Esquema de eventos e consultas de App Analytics

Use esta referência para implementar um produtor de eventos ou escrever consultas sobre eventos de App Analytics. Define a versão 1 do esquema, a codificação do Protocolo OpenTelemetry (OTLP) e os passos de processamento necessários antes da agregação.

Para um exemplo de primeiro evento, veja Comece com App Analytics. Para o painel e os seus dados adicionais de acesso à aplicação, consulte O que é App Analytics?.

Esquema de eventos

Cada evento é um registo de registo OpenTelemetry armazenado na tabela da otel_logs aplicação no Unity Catalog. Use o nome da tabela configurada, incluindo qualquer prefixo. A tabela também contém outros registos de registo, por isso seleciona eventos analíticos pela versão do esquema e tipo de evento.

Exemplos de Payload

Selecione um tipo de evento para ver a sua carga útil. Cada exemplo é um registo de registo OTLP, colocado quando resourceLogs[].scopeLogs[].logRecords[] exportado. O quickstart mostra esse invólucro de pedido.

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

Action

Registar uma exportação de relatório concluído. 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" } }
  ]
}

Vista de página

Regista uma visita a /reports. O tipo de evento 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

Registar uma maior medição de tinta contenida (LCP) de 1.800 milissegundos. Este 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 medição partilham um web_vital.sample_id. Cada novo relatório tem o seu event.idpróprio . Consulte as regras Web Vital.

Campos comuns

Os seguintes campos lógicos aplicam-se a todos os tipos de eventos. Os seus nomes de atributos OTLP aparecem nos exemplos acima.

session_id é opcional no esquema de eventos. Métricas baseadas em sessões utilizam os registos 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, deve cumprir as suas regras de campo. Um atributo opcional ausente lê-se como nulo no esquema lógico.

Tipos de eventos

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

Codificação OTLP e campos de tabela

Os atributos analíticos utilizam o databricks.app.analytics. namespace. A tabela seguinte mapeia os campos lógicos para OTLP e para a tabela de telemetria:

Use as seguintes codificações JSON OTLP:

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

Defina os registos eventName de registo para o mesmo valor que o atributo de análise event_name . A instrumentação scope.name identifica o produtor, mas não é um seletor para registos analíticos.

A tabela de telemetria pode manter um wrapper de doubleValue campo único para valores numéricos, incluindo zero. Descifre esse wrapper antes de validar os campos numéricos. Valide o tipo do valor original antes de o lançar, em vez de aceitar uma cadeia 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 os campos antes da exportação. Validação e projeção numa 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 entre 1 e 128 caracteres. Começam com uma letra minúscula e usam letras minúsculas, dígitos, pontos e sublinhats. Pontos e sublinhas, segmentos alfanuméricos separados. A gramática é ^[a-z][a-z0-9]*([._][a-z0-9]+)*$.

Use nomes estáveis em vez de IDs incorporados, endereços de email ou texto introduzido pelo utilizador. 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 espaços de nomes reservados ou segmentos sensíveis, incluindo analytics, identity, session, urltelemetry, user, , users, passwordstackpasswdemailsecrettokenapi_keycredentialprivate_keyiphtmlusernamedomselectorcookieauthorizationstacktracetextselectorsinputou .referrer Estas restrições aplicam-se também 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.

As projeções de consulta ometem propriedades que não cumprem estas restrições. Os produtores continuam responsáveis pelo significado dos valores que enviam. As verificações sintáticas sozinhas não conseguem estabelecer que um valor é não pessoal.

Caminhos das páginas

A page_path começa com / e contém o caminho de aplicação do betão. Remova cadeias e fragmentos de consulta e higienize segmentos de caminho sensíveis. Não envie credenciais, dados pessoais ou texto inserido pelo utilizador num caminho.

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

Sessions

Uma sessão de análise pertence a um contexto de navegador de topo. Quando um produtor fornece um ID de sessão, mantém-no estável durante a navegação do lado do cliente e recarregamentos, e renova-o 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 utilizadores, endereços de email, endereços IP, IDs de pedido, IDs de trabalho ou tokens de acesso. Os eventos de backend preservam a sessão de origem quando uma está disponível. Os eventos repetidos preservam o tempo original da sessão e do evento.

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

Regras Web Vital

Os eventos Web Vital acrescentam 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 seguinte define as unidades e os limiares:

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

Uma amostra pode produzir múltiplos relatórios. Web Vitals descrevem a navegação de documentos. Uma alteração 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

Registos de processo na seguinte ordem:

1. Selecione versões de esquema suportadas e tipos de eventos. Para este esquema, selecione versão 1 e action, page_view, ou web_vital.
2. Descodifique os atributos tipados e requer valores válidos event_id, event_name, e occurred_at .
3. Validar campos de tipo de evento, nomes, unidades, classificações e restrições de campo. Exclua registos com campos obrigatórios inválidos e dados opcionais permitidos apenas por projetos.
4. Detetar IDs de eventos conflitantes e desduplicar entregas idênticas.
5. Selecione o intervalo de análise e quaisquer filtros de caminho ou evento.
6. Para os Web Vitais, reduza os relatórios repetidos para um relatório 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 cumpre o esquema de eventos.

Deduplicação e redução de amostras

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

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

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

Após a deduplicação e seleção do intervalo de análise, mantém-se o relatório mais recente por web_vital_sample_id. A ordem reporta por occurred_at, rompendo laços com event_id, ambos descendentes. Calcule os percentis após esta redução.

Definições de métricas

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.

Este esquema não define a identidade do utilizador, o dispositivo, o navegador ou as dimensões geográficas. As superfícies de produto podem mostrar métricas adicionais de outras fontes. Em particular, os visualizadores únicos do dashboard não são calculados contando sessões de análise.

Exemplo: calcular Web Vital p75 a partir de eventos validados

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

Prepara a entrada

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

• Uma linha por entrega que passe validação, antes da deduplicação ou filtragem por intervalo temporal.
• 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.

Define a entrada da aplicação que estás a analisar. Incluir entregas retidas de todos os tipos de eventos suportados para que seja detetada a reutilização de um ID de evento entre tipos. 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

Substitui <catalog>.<schema>.<validated-events-view> pela tua vista de entrada. Definir :start_time e :end_time como parâmetros de carimbo temporal 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 devolve o valor observado no posto solicitado em vez de uma aproximação. A consulta exclui IDs de eventos conflitantes antes de selecionar o intervalo temporal. 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. Relançamentos idênticos não aumentam esse número de amostras. Um ID de evento com conteúdo normalizado conflitante não contribui para nenhum registo.

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 os seus tipos, significados, escopo de identificadores ou semântica de sessão requer uma mudança significativa de versão. Alterações à deduplicação, redução de amostras ou semântica de tipo de evento também exigem uma nova versão principal.

Os consumidores ignoram versões e tipos de eventos não suportados em vez de os interpretar como ações.

Recursos adicionais

• O que é App Analytics?
• Comece com App Analytics
• Configurar telemetria para aplicações Databricks