Esquema de eventos e consultas de App Analytics

Use essa referência para implementar um produtor de eventos ou escrever consultas sobre eventos de App Analytics. Ele define a versão 1 do esquema, sua codificação do OpenTelemetry Protocol (OTLP) e as etapas de processamento necessárias antes da agregação.

Para um exemplo de primeiro evento, veja Comece com App Analytics. Para o painel e seus dados adicionais de acesso ao app, veja O que é App Analytics?.

Esquema de eventos

Cada evento é um registro de log do OpenTelemetry armazenado na tabela do otel_logs app no Unity Catalog. Use o nome da tabela configurada, incluindo qualquer prefixo. A tabela também contém outros registros de log, então selecione eventos analíticos pela versão do esquema e tipo de evento.

Exemplos de payload

Selecione um tipo de evento para ver sua carga útil. Cada exemplo é um registro de log OTLP, colocado em resourceLogs[].scopeLogs[].logRecords[] quando exportado. O quickstart mostra esse envelope de pedido.

Os documentos e o carimbo de data abaixo são ilustrativos. Gerar um ID único para cada novo evento e usar seu tempo real de ocorrência. Os exemplos omitem o opcional session_id.

Action

Registre uma exportação de relatório completo. A propriedade opcional format descreve a exportação sem alterar o nome do 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" } }
  ]
}

Exibição de página

Registre uma visita a /reports. O tipo e o nome do evento são 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

Registre uma maior medição de tinta contenente (LCP) de 1.800 milissegundos. Esse valor tem uma good classificação.

{
  "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" } }
  ]
}

Relatórios para a mesma medida compartilham um web_vital.sample_id. Cada novo relatório tem seu próprio event.id. Veja as regras Web Vital.

Campos comuns

Os seguintes campos lógicos se aplicam entre os tipos de evento. Seus nomes de atributos OTLP aparecem nos exemplos acima.

session_id é opcional no esquema de eventos. Métricas baseadas em sessões usam os registros que as fornecem. Não fabrique uma identidade nem use uma sequência vazia para representar uma sessão ausente.

As strings exigidas devem ser não vazias e não devem conter espaços em branco, credenciais ou dados pessoais. Quando um campo opcional está presente, ele deve estar em conformidade com suas regras de campo. Um atributo opcional ausente é lido como nulo no esquema lógico.

Tipos de evento

Uma ação capturada descreve o que o produtor gravou. Por exemplo, um clique pode registrar a intenção sem provar que a operação foi bem-sucedida.

Codificação OTLP e campos de tabela

Atributos de Analytics usam o databricks.app.analytics. namespace. A tabela a seguir mapeia os campos lógicos para OTLP e a tabela de telemetria:

Use as seguintes codificações JSON OTLP:

• Timestamps: Uma sequência decimal de nanosegundos Unix em timeUnixNano.
• Inteiros: Uma cadeia intValuedecimal , como { "intValue": "1" }.
• Dobra: Um numérico doubleValue, como { "doubleValue": 1.25 }.
• Cordas: stringValue.
• Booleanos: boolValue.

Defina os registros eventName de log para o mesmo valor do atributo de analytics event_name . A instrumentação scope.name identifica o produtor, mas não é um seletor para registros analíticos.

A tabela de telemetria pode reter um wrapper de campo doubleValue único para valores numéricos, incluindo zero. Decode esse wrapper antes de validar os campos numéricos. Valide o tipo do valor original antes de lançá-lo, em vez de aceitar uma string numérica como número.

A coluna física date está disponível para poda de partições. Não faz parte do esquema lógico de eventos.

Restrições de campo

Sanitize campos antes da exportação. Validação e projeção em uma consulta não removem dados brutos já armazenados na tabela de telemetria.

Nomes e propriedades das ações

Os nomes das ações contêm de 1 a 128 caracteres. Elas começam com uma letra minúscula e usam letras minúsculas, dígitos, pontos e sublinhados. Pontos e sublinhados são segmentos alfanuméricos separados. A gramática é ^[a-z][a-z0-9]*([._][a-z0-9]+)*$.

Use nomes estáveis em vez de embedding IDs, endereços de e-mail ou texto inserido pelo usuário. Coloque detalhes variados nas propriedades. Por exemplo, use report_exported com uma format propriedade em vez de um nome de ação diferente para cada formato.

As chaves de propriedade seguem a mesma gramática. Não use namespaces reservados ou segmentos sensíveis, incluindo analytics, identity, telemetrysession, url, user, users, email, authorizationpasswdpasswordsecrettokenprivate_keyapi_keyhtmlcredentialdomipselectorselectorsusernamecookiestacktracetextstackinputou .referrer Essas restrições também se aplicam aos nomes das ações.

As propriedades podem conter cadeias escalares, números finitos e booleanos. Arrays, objetos aninhados, valores nulos, credenciais e dados pessoais não são permitidos.

Projeções de consulta omitem propriedades que não atendem a essas restrições. Os produtores continuam responsáveis pelo significado dos valores que enviam. Só checagens sintáticas não conseguem estabelecer que um valor é não pessoal.

Caminhos de página

A page_path começa com / e contém o caminho de aplicação do concreto. Remova strings e fragmentos de consulta, e limpe segmentos de caminho sensíveis. Não envie credenciais, dados pessoais ou texto digitado pelo usuário em um caminho.

Um caminho inválido é omitido da projeção da consulta. Uma visualização de página sem caminho permanece válida, mas não contribui para agregações em nível de rota.

Sessions

Uma sessão de análise pertence ao contexto de um navegador de nível superior. Quando um produtor fornece um ID de sessão, mantenha-o estável durante a navegação do lado do cliente e as recargas, e renove após 30 minutos sem um evento analítico gravado.

Os IDs de sessão devem ser opacos e não devem derivar de identidades de usuários, endereços de e-mail, endereços IP, IDs de requisição, IDs de trabalho ou tokens de acesso. Eventos backend preservam a sessão de origem quando uma está disponível. Eventos rejogados preservam seu tempo original de sessão e evento.

Uma sessão mede uma janela de atividade, não uma pessoa única. Métricas de visualização no produto podem usar dados separados de acesso ao app.

Web Vital

Eventos Essenciais na Web adicionam os seguintes campos. Codificar valor e delta como atributos OTLP doubleValue , e os campos restantes como stringValue atributos. Campos específicos do Web Vital devem estar ausentes nas ações e visualizações de página.

A tabela a seguir define as unidades e limiares:

LCP, INP e CLS são os Core Web Vitals. FCP e TTFB fornecem medições adicionais de desempenho. Um valor está good no limite de Bom ou abaixo, poor acima do limite de Pobre e needs_improvement entre eles. Uma unidade ou classificação incompatível torna o registro inválido.

Uma amostra pode gerar múltiplos relatórios. Web Vitals descrevem a navegação de documentos. Uma mudança de rota do lado do cliente pode gerar uma visualização de página sem gerar um novo exemplo Web Vital. Um servidor pode encaminhar uma medição do navegador, mas os tempos do servidor não substituem essa medição.

Ordem de validação

Registros de processo na seguinte ordem:

1. Selecione versões de esquema suportadas e tipos de eventos. Para esse esquema, selecione versão 1 e action, page_view, ou web_vital.
2. Decodifica os atributos tipados e requer valores válidos event_id, event_name, e occurred_at .
3. Valide campos, nomes, unidades, classificações e restrições de campo por tipo de evento. Exclua registros com campos exigidos inválidos e apenas dados opcionais permitidos por projetos.
4. Detectar IDs de eventos conflitantes e deduplicar entregas idênticas.
5. Selecione o intervalo de análise e quaisquer filtros de caminho ou evento.
6. Para Web Vitals, reduza os relatos repetidos para um relato por amostra.
7. Agregue os eventos ou amostras resultantes.

Mantenha a validação separada dos diagnósticos de ingestão. Encontrar uma linha em otel_logs não estabelece que ela está conforme o esquema de eventos.

Deduplicação e redução de amostras

Entregas idênticas de um evento contam como um evento. Se an event_id for reutilizado para conteúdo lógico diferente de eventos, exclua todos os registros desse conjunto de conflitos e reporte o conflito como um problema de qualidade dos dados. Não escolha uma entrega arbitrária do set.

Compare o conteúdo lógico normalizado, incluindo campos opcionais e propriedades. Use uma representação determinística das propriedades para que a ordenação de chaves não crie conflitos falsos. Metadados de transporte não fazem parte do conteúdo lógico do evento. As tentativas mantêm o carimbo de tempo original do evento.

Verifique a identidade entre as entregas retidas para cada ID de evento candidato antes de aplicar a faixa de tempo da análise. Filtrar as entregas brutas primeiro pode esconder conteúdo conflitante fora dessa faixa.

Após a deduplicação e seleção do intervalo de análise, mantenha o relatório mais recente por web_vital_sample_id. A ordem relata por occurred_at, rompendo laços com event_id, ambos descendentes. Calcule percentis após essa redução.

Definições de Métrica

Intervalos de tempo incluem start_time e excluem end_time. Os baldes de tempo utilizam o Tempo Universal Coordenado (UTC).

Para N amostras ordenadas, o posto mais próximo p75 usa o valor na posição ceil(0.75 × N), com indexação baseada em um. Trate menos de 30 amostras do Web Vital como evidência indicativa, e não conclusiva, de uma tendência.

Esse esquema não define a identidade do usuário, dispositivos, navegador ou dimensões geográficas. Superfícies de produto podem exibir métricas adicionais de outras fontes. Em particular, os visualizadores únicos do painel não são calculados contando sessões de análise.

Exemplo: calcular Web Vital p75 a partir de eventos validados

A consulta a seguir demonstra exclusão de colisão, deduplicação, redução amostral e cálculo exato do percentil. Ele consome um conjunto de dados normalizado, não a tabela bruta otel_logs .

Prepare a entrada

Crie uma visualização de entrada no seu próprio pipeline de processamento que aplique os passos 1 a 3 da ordem de validação. A visualização deve conter os seguintes dados:

• Uma linha por entrega que passa pela validação, antes da deduplicação ou filtragem por intervalo de tempo.
• Os campos lógicos tipados, incluindo event_id, occurred_at, event_type, event_name, web_vital_value, e web_vital_sample_id.
• Uma cadeia não nula logical_content contendo uma representação determinística de todos os campos e propriedades de eventos normalizados. Represente os campos opcionais ausentes de forma consistente e preserve o tempo original do evento.

Escope a entrada do app que você está analisando. Incluir entregas retidas de todos os tipos de eventos suportados para que a reutilização de um ID de evento entre os tipos seja detectada. A entrada deve cumprir todos os campos exigidos, tipos e intervalos numéricos, unidades, classificações e restrições de tipo de evento descritas acima.

Agregar a entrada validada

Substitua <catalog>.<schema>.<validated-events-view> pela sua visão de entrada. Defina :start_time e :end_time como parâmetros de carimbo de data no 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 retorna o valor observado no posto solicitado em vez de uma aproximação. A consulta exclui IDs de eventos conflitantes antes de selecionar o intervalo de tempo. Rastreie IDs que content_count excedam um separadamente como erros de qualidade de dados.

Por exemplo, três amostras reduzidas de LCP com valores de 100, 200 e 300 milissegundos produzem sample_size = 3 e p75 = 300. Reentregas idênticas não aumentam essa contagem de amostras. Um ID de evento com conteúdo normalizado conflitante não contribui com nenhum registro.

Versioning

schema_version identifica a versão principal do contrato independentemente das versões do pacote do produtor.

Adicionar campos opcionais ou nomes de ações definidos pela aplicação é compatível com versões anteriores. Remover campos obrigatórios ou alterar seus tipos, significados, escopo de identificador ou semântica de sessão requer uma mudança significativa de versão. Mudanças na deduplicação, redução de amostras ou semântica de tipo evento também exigem uma nova versão principal.

Os consumidores ignoram versões e tipos de eventos não suportados em vez de interpretá-los como ações.

Recursos adicionais

• O que é App Analytics?
• Comece com App Analytics
• Configurar telemetria para aplicativos Databricks