Esquema de eventos y consultas de App Analytics

Importante

Esta característica se encuentra en versión preliminar privada. Para probarlo, póngase en contacto con su contacto de Azure Databricks.

Utiliza esta referencia para implementar un productor de eventos o escribir consultas sobre eventos de App Analytics. Define la versión 1 del esquema, su codificación con el Protocolo OpenTelemetry (OTLP) y los pasos de procesamiento necesarios antes de la agregación.

Para un ejemplo de primer evento, véase Empezar con App Analytics. Para el panel de control y sus datos adicionales de acceso a la app, consulta ¿Qué es App Analytics?.

Esquema del evento

Cada evento es un registro de registro de OpenTelemetry almacenado en la tabla de otel_logs la aplicación en el Catálogo de Unity. Utiliza el nombre de la tabla configurada, incluyendo cualquier prefijo. La tabla también contiene otros registros de registro, así que selecciona los eventos analíticos por su versión de esquema y tipo de evento.

Ejemplos de carga útil

Selecciona un tipo de evento para ver su carga útil. Cada ejemplo es un registro OTLP, colocado al resourceLogs[].scopeLogs[].logRecords[] exportarlo. El inicio rápido muestra ese envoltorio de solicitudes.

Los identificadores y la marca de tiempo que aparecen a continuación son ilustrativos. Genera un ID único para cada nuevo evento y utiliza su tiempo real de ocurrencia. Los ejemplos omiten el opcional session_id.

Action

Registrar una exportación de informe completado. La propiedad opcional format describe la exportación sin cambiar el nombre del evento.

{
  "timeUnixNano": "1790164800000000000",
  "eventName": "report_exported",
  "attributes": [
    { "key": "databricks.app.analytics.schema.version", "value": { "intValue": "1" } },
    { "key": "databricks.app.analytics.event.id", "value": { "stringValue": "d6c34165-7f4a-467c-b671-50ae495bcb14" } },
    { "key": "databricks.app.analytics.event.type", "value": { "stringValue": "action" } },
    { "key": "databricks.app.analytics.event.name", "value": { "stringValue": "report_exported" } },
    { "key": "databricks.app.analytics.properties.format", "value": { "stringValue": "csv" } }
  ]
}

vista de página

Graba una visita a /reports. El tipo y el nombre del evento son ambos page_view.

{
  "timeUnixNano": "1790164800000000000",
  "eventName": "page_view",
  "attributes": [
    { "key": "databricks.app.analytics.schema.version", "value": { "intValue": "1" } },
    { "key": "databricks.app.analytics.event.id", "value": { "stringValue": "caafc8e3-5f19-4f22-934b-09d1f8bf8e63" } },
    { "key": "databricks.app.analytics.event.type", "value": { "stringValue": "page_view" } },
    { "key": "databricks.app.analytics.event.name", "value": { "stringValue": "page_view" } },
    { "key": "databricks.app.analytics.page.path", "value": { "stringValue": "/reports" } }
  ]
}

Web Vital

Registra una medición de Mayor Pintura Contenida (LCP) de 1.800 milisegundos. Este valor tiene una good valoración.

{
  "timeUnixNano": "1790164800000000000",
  "eventName": "lcp",
  "attributes": [
    { "key": "databricks.app.analytics.schema.version", "value": { "intValue": "1" } },
    { "key": "databricks.app.analytics.event.id", "value": { "stringValue": "a23eecb7-b6c1-47c8-92ab-e2856f6ac804" } },
    { "key": "databricks.app.analytics.event.type", "value": { "stringValue": "web_vital" } },
    { "key": "databricks.app.analytics.event.name", "value": { "stringValue": "lcp" } },
    { "key": "databricks.app.analytics.page.path", "value": { "stringValue": "/reports" } },
    { "key": "databricks.app.analytics.web_vital.value", "value": { "doubleValue": 1800 } },
    { "key": "databricks.app.analytics.web_vital.unit", "value": { "stringValue": "ms" } },
    { "key": "databricks.app.analytics.web_vital.delta", "value": { "doubleValue": 1800 } },
    {
      "key": "databricks.app.analytics.web_vital.sample_id",
      "value": { "stringValue": "30990ea0-3ec1-4a93-98b9-7c9abfe0e2d8" }
    },
    { "key": "databricks.app.analytics.web_vital.rating", "value": { "stringValue": "good" } }
  ]
}

Los informes para la misma medición comparten un web_vital.sample_id. Cada nuevo informe tiene su propio event.id. Consulta las reglas Web Vital.

Campos comunes

Los siguientes campos lógicos se aplican a todos los tipos de eventos. Sus nombres de atributos OTLP aparecen en los ejemplos anteriores.

Campo	Tipo	Requirement	Descripción
`schema_version`	`INT`	Obligatorio	Versión de contrato importante. Utilice `1`.
`event_id`	`STRING`	Obligatorio	Identificador opaco y único a nivel mundial. Conserva la prueba al volver a intentar un evento.
`event_type`	`STRING`	Obligatorio	`action`, `page_view`, o `web_vital`.
`event_name`	`STRING`	Obligatorio	Un nombre de baja cardinalidad dentro del tipo de evento.
`occurred_at`	`TIMESTAMP`	Obligatorio	Cuando ocurrió el evento, no cuando fue ingerido.
`session_id`	`STRING`	Optional	Un identificador opaco para una ventana de actividad analítica. No identifica a una persona.
`page_path`	`STRING`	Optional	Un camino de aplicación concreto y saneado, como `/orders/42`.
`properties`	Objeto	Optional	Propiedades escalares definidas por la aplicación.

session_id es opcional en el esquema de eventos. Las métricas basadas en sesiones utilizan los registros que las suministran. No fabriques una identidad ni uses una cadena vacía para representar una sesión ausente.

Las cadenas requeridas deben no estar vacías y no deben contener espacios en blanco, credenciales ni datos personales. Cuando hay un campo opcional, debe ajustarse a sus reglas de campo. Un atributo opcional ausente se lee como nulo en el esquema lógico.

Tipos de evento

Tipo de evento	Nombre del evento	Campos adicionales
`action`	Un nombre definido por la aplicación, como `report_exported`.	Las propiedades opcionales describen la acción.
`page_view`	`page_view`	Una opción `page_path` identifica la ruta visitada.
`web_vital`	`lcp`, `inp`, `cls`, `fcp` o `ttfb`	Los campos Web Vital definidos en Web Vital se regírano.

Una acción capturada describe lo que el productor grabó. Por ejemplo, un clic puede registrar la intención sin demostrar que la operación ha tenido éxito.

Codificación OTLP y campos de tabla

Los atributos de Analytics utilizan el databricks.app.analytics. espacio de nombres. La siguiente tabla asigna los campos lógicos a OTLP y a la tabla de telemetría:

Campo lógico	Fuente OTLP	`otel_logs` Fuente
`occurred_at`	`timeUnixNano`	`time`
`schema_version`	`databricks.app.analytics.schema.version`	`attributes:["databricks.app.analytics.schema.version"]`
`event_id`	`databricks.app.analytics.event.id`	`attributes:["databricks.app.analytics.event.id"]`
`event_type`	`databricks.app.analytics.event.type`	`attributes:["databricks.app.analytics.event.type"]`
`event_name`	`databricks.app.analytics.event.name`	`attributes:["databricks.app.analytics.event.name"]`
`session_id`	`databricks.app.analytics.session.id`	`attributes:["databricks.app.analytics.session.id"]`
`page_path`	`databricks.app.analytics.page.path`	`attributes:["databricks.app.analytics.page.path"]`
`properties.<key>`	`databricks.app.analytics.properties.<key>`	La clave correspondiente en `attributes`.
`web_vital_<field>`	`databricks.app.analytics.web_vital.<field>`	La clave correspondiente en `attributes`.

Utiliza las siguientes codificaciones JSON OTLP:

Marcas de tiempo: Una cadena decimal de nanosegundos Unix en timeUnixNano.
Enteros: Una cadena intValuedecimal , como { "intValue": "1" }.
Dobles: Un numérico doubleValue, como { "doubleValue": 1.25 }.
Cuerdas: stringValue.
Booleanos: boolValue.

Establece los registros eventName de registro al mismo valor que el atributo de analítica event_name . La instrumentación scope.name identifica al productor, pero no es un selector para registros analíticos.

La tabla de telemetría puede conservar un envoltorio de un solo campo doubleValue para valores numéricos, incluyendo cero. Descifra ese envolvente antes de validar los campos numéricos. Valida el tipo del valor original antes de lanzarlo, en lugar de aceptar una cadena numérica como número.

La columna física date está disponible para la poda de particiones. No forma parte del esquema lógico de eventos.

Restricciones de campo

Desinfecta los campos antes de exportar. La validación y la proyección en una consulta no eliminan los datos en bruto ya almacenados en la tabla de telemetría.

Nombres y propiedades de acciones

Los nombres de las acciones contienen de 1 a 128 caracteres. Comienzan con una letra minúscula y utilizan letras minúsculas, dígitos, puntos y guiones bajos. Puntos y subrayos en segmentos alfanuméricos separados. La gramática es ^[a-z][a-z0-9]*([._][a-z0-9]+)*$.

Utiliza nombres estables en lugar de incrustar IDs, direcciones de correo electrónico o texto introducido por el usuario. Pon distintos detalles en las propiedades. Por ejemplo, úsalo report_exported con una format propiedad en lugar de un nombre de acción diferente para cada formato.

Las claves de propiedades siguen la misma gramática. No uses espacios de nombres reservados ni segmentos sensibles, incluyendo analytics, identity, session, urltelemetry, user, , users, passwordstackpasswdemailsecrettokenapi_keycredentialprivate_keyiphtmlusernamedomselectorcookieauthorizationstacktracetextselectorsinputo .referrer Estas restricciones también se aplican a los nombres de las acciones.

Las propiedades pueden contener cadenas escalares, números finitos y booleanos. No se permiten arrays, objetos anidados, valores nulos, credenciales ni datos personales.

Limit	Value
Propiedades por evento	50
Longitud de la clave de propiedad	128 caracteres
Longitud del valor de la cuerda	1024 caracteres

Las proyecciones de consulta omiten propiedades que no cumplen estas restricciones. Los productores siguen siendo responsables del significado de los valores que envían. Las comprobaciones sintácticas por sí solas no pueden establecer que un valor sea no personal.

Rutas de página

A page_path comienza con / y contiene el camino concreto de aplicación. Elimina cadenas de consulta y fragmentos, y limpia los segmentos de ruta sensibles. No envíes credenciales, datos personales ni texto introducido por el usuario en una ruta.

Un camino inválido se omite de la proyección de consulta. Una vista de página sin ruta sigue siendo válida, pero no contribuye a agregaciones a nivel de ruta.

Sessions

Una sesión de análisis pertenece al contexto de un navegador de primer nivel. Cuando un productor proporciona un ID de sesión, mantenlo estable durante la navegación y recarga del cliente, y renuévalo tras 30 minutos sin un evento analítico grabado.

Los IDs de sesión deben ser opacos y no deben derivar de identidades de usuario, direcciones de correo electrónico, direcciones IP, IDs de solicitud, IDs de trabajo o tokens de acceso. Los eventos de backend conservan la sesión de origen cuando hay una disponible. Los eventos repetidos conservan su sesión original y su tiempo de evento.

Una sesión mide una ventana de actividad, no una persona única. Las métricas de espectadores en el producto pueden usar datos de acceso a aplicaciones separados.

Reglas Web Vital

Los eventos web Vital añaden los siguientes campos. Codifica valor y delta como atributos OTLP doubleValue , y los campos restantes como stringValue atributos. Los campos específicos de Web Vital deben estar ausentes en las acciones y vistas de página.

Campo	Requirement	Descripción
`web_vital_value`	Obligatorio	Valor acumulativo finito y no negativo para la muestra.
`web_vital_unit`	Obligatorio	`ms` o `score`, determinado por la métrica.
`web_vital_delta`	Obligatorio	Cambio finito y no negativo desde el informe anterior.
`web_vital_sample_id`	Obligatorio	Identificador globalmente único compartido por los informes para una muestra.
`web_vital_rating`	Obligatorio	`good`, `needs_improvement`, o `poor`, derivado de los umbrales de valor y métrica.
`web_vital_navigation_type`	Optional	`navigate`, `reload`, `back_forward`, `back_forward_cache`, `prerender`o `restore`.

La siguiente tabla define las unidades y umbrales:

Métrica	Nombre	Unidad	Bueno	Deficiente
`lcp`	Pintura con contenido más grande (LCP)	`ms`	≤ 2.500	> 4,000
`inp`	Interacción con la siguiente pintura (INP)	`ms`	≤ 200	> 500
`cls`	Desplazamiento de diseño acumulativo (CLS)	`score`	≤ 0,1	> 0.25
`fcp`	Primera pintura contenida (FCP)	`ms`	≤ 1.800	> 3,000
`ttfb`	Tiempo hasta el primer byte (TTFB)	`ms`	≤ 800	> 1,800

LCP, INP y CLS son Core Web Vitals. FCP y TTFB proporcionan mediciones adicionales de rendimiento. Un valor está good en o por debajo del umbral de Bueno, poor por encima del umbral de Pobre y needs_improvement entre ambos. Una unidad o calificación desajustada hace que el registro sea inválido.

Una muestra puede producir varios informes. Web Vitals describe la navegación de documentos. Un cambio de ruta del lado del cliente puede producir una vista de página sin necesidad de crear una nueva muestra de Web Vital. Un servidor puede reenviar una medición del navegador, pero los tiempos de servidor no sustituyen esa medición.

Orden de validación

Registros de proceso en el siguiente orden:

Selecciona las versiones de esquema compatibles y los tipos de eventos. Para este esquema, selecciona versión 1 y action, page_view, o web_vital.
Decodifica los atributos tipados y requiere valores válidos event_id, event_name, y occurred_at .
Validar los campos, nombres, unidades, valoraciones y restricciones de campo por tipo de evento. Excluye registros con campos requeridos inválidos y solo permite el proyecto datos opcionales.
Detectar IDs de eventos en conflicto y deduplicar entregas idénticas.
Selecciona el intervalo de análisis y cualquier filtro de camino o evento.
Para los signos vitales web, reduce los informes repetidos a un solo informe por muestra.
Agrega los eventos o muestras resultantes.

Mantén la validación separada del diagnóstico de ingestión. Encontrar una fila en otel_logs no establece que se ajuste al esquema de eventos.

Deduplicación y reducción de muestras

Las entregas idénticas de un evento cuentan como un solo evento. Si se reutiliza event_id para contenido de eventos lógicos diferentes, excluye todos los registros de ese conjunto de conflictos y reporta el conflicto como un problema de calidad de datos. No elijas una entrega arbitraria del set.

Compara el contenido lógico normalizado, incluyendo campos y propiedades opcionales. Utiliza una representación determinista de las propiedades para que el orden de claves no genere falsos conflictos. Los metadatos de transporte no forman parte del contenido lógico del evento. Los reintentos conservan la marca de tiempo del evento original.

Comprueba la identidad entre las entregas retenidas de cada ID de evento candidato antes de aplicar el rango de tiempo de análisis. Filtrar primero las entregas en bruto puede ocultar contenido contradictorio fuera de ese rango.

Tras la deduplicación y selección del intervalo de análisis, conservar el informe más reciente por web_vital_sample_id. Informes de orden por occurred_at, rompiendo lazos con event_id, ambos descendentes. Calcula los percentiles después de esta reducción.

Definiciones de métricas

Los intervalos de tiempo incluyen start_time y excluyen end_time. Los cubos de tiempo utilizan Tiempo Universal Coordinado (UTC).

Métrica	Definición
Vistas de página	Número de eventos deduplicados `page_view` .
Sessions	Número de valores distintos y no nulos `session_id` entre los eventos analíticos seleccionados.
Acciones rastreadas	Número de eventos deduplicados `action` .
Páginas por sesión	Vistas de página divididas por sesiones. No hay valor cuando el recuento de sesiones es cero.
Principales acciones	Acciones agrupadas por `event_name`.
Páginas principales	Vistas de página agrupadas por `page_path`, excluyendo rutas que faltan.
Web Vital p75	Posición más cercana en percentil 75 tras la deduplicación de eventos y reducción muestral.
Tamaño de muestra de Web Vital	Número de muestras distintas tras la reducción.
Último evento	El mejor `occurred_at` entre los eventos analíticos seleccionados.

Para N muestras ordenadas, el rango más cercano p75 utiliza el valor en la posición ceil(0.75 × N), con indexación basada en uno. Considera menos de 30 muestras de Web Vital como evidencia indicativa y no concluyente de una tendencia.

Este esquema no define la identidad del usuario, el dispositivo, el navegador ni las dimensiones geográficas. Las superficies de producto pueden mostrar métricas adicionales de otras fuentes. En particular, los espectadores únicos del panel de control no se calculan contando las sesiones de análisis.

Ejemplo: calcular Web Vital p75 a partir de eventos validados

La siguiente consulta demuestra la exclusión de colisiones, la deduplicación, la reducción muestral y el cálculo exacto del percentil. Consume un conjunto de datos normalizado, no la tabla en bruto otel_logs .

Prepara la entrada

Crea una vista de entrada en tu propia canalización de procesamiento que aplique los pasos 1 a 3 del orden de validación. La vista debe contener los siguientes datos:

Una fila por entrega que pasa la validación, antes de la deduplicación o el filtrado por intervalo de tiempo.
Los campos lógicos tipados, incluyendo event_id, occurred_at, event_type, event_name, web_vital_value, y web_vital_sample_id.
Una cadena no nula logical_content que contiene una representación determinista de todos los campos y propiedades de eventos normalizados. Representa los campos opcionales ausentes de forma consistente y conserva el tiempo original del evento.

Analiza la entrada de la app que estás analizando. Incluir entregas retenidas de todos los tipos de eventos soportados para que se detecte la reutilización de un ID de evento entre tipos. La entrada debe hacer cumplir todos los campos, tipos y rangos numéricos requeridos, unidades, valoraciones y restricciones de tipo de evento descritas anteriormente.

Importante

Esta vista de entrada no se crea activando la telemetría de la app. Es un requisito previo que proporciona tu pipeline de procesamiento. Lanzar unos pocos atributos en bruto no sustituye este paso de validación.

Agrega la entrada validada

Sustituye <catalog>.<schema>.<validated-events-view> por tu vista de entrada. Establece :start_time y :end_time como parámetros de marca temporal en el editor SQL.

WITH event_id_quality AS (
  SELECT event_id, COUNT(DISTINCT logical_content) AS content_count
  FROM <catalog>.<schema>.<validated-events-view>
  GROUP BY event_id
),
deduplicated AS (
  SELECT events.*
  FROM <catalog>.<schema>.<validated-events-view> AS events
  JOIN event_id_quality AS quality USING (event_id)
  WHERE quality.content_count = 1
  QUALIFY ROW_NUMBER() OVER (
    PARTITION BY event_id ORDER BY occurred_at
  ) = 1
),
samples AS (
  SELECT *
  FROM deduplicated
  WHERE event_type = 'web_vital'
    AND occurred_at >= :start_time
    AND occurred_at < :end_time
  QUALIFY ROW_NUMBER() OVER (
    PARTITION BY web_vital_sample_id ORDER BY occurred_at DESC, event_id DESC
  ) = 1
)
SELECT
  event_name,
  COUNT(*) AS sample_size,
  PERCENTILE_DISC(0.75) WITHIN GROUP (ORDER BY web_vital_value) AS p75
FROM samples
GROUP BY event_name
ORDER BY event_name;

PERCENTILE_DISC devuelve el valor observado en el rango solicitado en lugar de una aproximación. La consulta excluye los IDs de eventos en conflicto antes de seleccionar el rango de tiempo. Rastrea los IDs que content_count excedan uno por separado como errores de calidad de datos.

Por ejemplo, tres muestras reducidas de LCP con valores de 100, 200 y 300 milisegundos producen sample_size = 3 y p75 = 300. Las reasignaciones idénticas no aumentan ese recuento de muestras. Un ID de evento con contenido normalizado en conflicto no aporta ningún registro.

Versioning

schema_version identifica la versión principal del contrato independientemente de las versiones del paquete para productores.

Añadir campos opcionales o nombres de acciones definidos por la aplicación es compatible hacia atrás. Eliminar campos requeridos o cambiar sus tipos, significados, alcance de identificadores o semántica de sesión requiere un cambio importante de versión. Los cambios en la deduplicación, reducción de muestras o semántica de tipo evento también requieren una nueva versión principal.

Los consumidores ignoran versiones y tipos de eventos no soportados en lugar de interpretarlos como acciones.

Recursos adicionales

Comentarios

¿Le ha resultado útil esta página?

Se actualizó por última vez el 2026-09-30