Esquema e queries de eventos do App Analytics
Visualização
Esse recurso está na Prévia privada. Para experimentar, fale com o seu contato no Databricks.
Use esta referência para implementar um produtor de eventos ou escrever query sobre eventos do App analítica. Ele define a versão 1 do esquema, sua codificação OTLP (OpenTelemetry Protocol) e os passos de processamento necessários antes da agregação.
Para ver um exemplo de primeiro evento, consulte Get started with App Analytics. Para ver o painel e seus dados adicionais de acesso ao aplicativo, consulte What is App Analytics?.
Esquema de eventos
Cada evento é um registro de log do OpenTelemetry armazenado na tabela otel_logs do aplicativo no Unity Catalog. Use o nome de tabela configurado, incluindo qualquer prefixo. A tabela também contém outros registros de log, portanto, selecione eventos de analítica por sua versão de esquema e tipo de evento.
Exemplos de payload
Selecione um tipo de evento para ver seu payload. Cada exemplo é um registro de Log OTLP, colocado em resourceLogs[].scopeLogs[].logRecords[] quando exportado. O início rápido mostra esse wrapper de solicitação.
Os IDs e o Timestamp abaixo são ilustrativos. Gere um ID exclusivo para cada novo evento e use seu horário de ocorrência real. Os exemplos omiten o opcional session_id.
- Action
- Page view
- Web Vital
Registrar uma exportação de relatório concluída. 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" } }
]
}
Grave 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" } }
]
}
Registre uma medição de Largest Contentful Paint (LCP) de 1.800 milissegundos. Este valor tem uma classificação good.
{
"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 compartilham um web_vital.sample_id. Cada novo relatório tem seu próprio event.id. Consulte Web Vital rules.
Campos comuns
Os seguintes campos lógicos se aplicam a todos os tipos de eventos. Seus nomes de atributos OTLP aparecem nos exemplos acima.
campo | Tipo | Requisito | Descrição |
|---|---|---|---|
|
| Obrigatório | Versão principal do contrato. Use |
|
| Obrigatório | Identificador opaco e globalmente exclusivo. Preserve-o ao tentar novamente um evento. |
|
| Obrigatório |
|
|
| Obrigatório | Um nome de cardinalidade baixa no tipo de evento. |
|
| Obrigatório | Quando o evento ocorreu, e não quando foi ingerido. |
|
| Opcional | Um identificador opaco para uma janela de atividade de analítica. Ele não identifica uma pessoa. |
|
| Opcional | Um caminho de aplicativo concreto sanitizado, como |
| Objeto | Opcional | Propriedades escalares definidas pelo aplicativo. |
session_id é opcional no esquema de eventos. As métricas baseadas em sessão usam os registros que as fornecem. Não crie uma identidade nem use uma string vazia para representar uma sessão ausente.
As strings obrigatórias não devem estar vazias e não devem conter espaços em branco, credenciais ou dados pessoais. Quando um campo opcional estiver presente, ele deverá estar em conformidade com suas regras de campo. Um atributo opcional ausente é lido como nulo no esquema lógico.
Tipos de evento
Tipo de evento | Nome do evento | Campos adicionais |
|---|---|---|
| Um nome definido pelo aplicativo, como | As propriedades opcionais descrevem a ação. |
|
| Um |
|
| The Web Vital fields defined in Web Vital rules. |
Uma ação capturada descreve o que o produtor registrou. 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
Os atributos de analítica usam o namespace databricks.app.analytics.. A tabela a seguir mapeia os campos lógicos para o OTLP e a tabela de telemetria:
Campo lógico | Origem OTLP |
|
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| The corresponding key in |
|
| The corresponding key in |
Use as seguintes codificações JSON do OTLP:
- Timestamps: Uma string decimal de nanossegundos Unix em
timeUnixNano. - Integers: uma string decimal
intValue, como{ "intValue": "1" }. - Duplicados: um
doubleValuenumérico, como{ "doubleValue": 1.25 }. - Strings:
stringValue. - Booleanos:
boolValue.
Defina o eventName do registro de log com o mesmo valor do atributo event_name de analítica. A instrumentação scope.name identifica o produtor, mas não é um seletor para registros de analítica.
A tabela de telemetria pode reter um wrapper de doubleValue de campo único para valores numéricos, incluindo zero. Decodifique esse wrapper antes de validar os campos numéricos. Valide o tipo do valor original antes de convertê-lo, em vez de aceitar uma string com aparência numérica como um número.
A coluna física date está disponível para remoção de partições. Não faz parte do esquema de eventos lógico.
Restrições de campo
Sanitizar campos antes da exportação. A validação e a projeção em uma query não removem os dados brutos já armazenados na tabela de telemetria.
Nomes e propriedades de ações
Os nomes de ações contêm de 1 a 128 caracteres. Eles começam com uma letra minúscula e usam letras minúsculas, dígitos, pontos e underscores. Pontos e underscores separam segmentos alfanuméricos. A gramática é ^[a-z][a-z0-9]*([._][a-z0-9]+)*$.
Use nomes estáveis em vez de incorporar IDs, endereços de email ou texto inserido pelo usuário. Coloque detalhes variáveis nas propriedades. Por exemplo, use report_exported com uma propriedade format em vez de um nome de ação diferente para cada formato.
As keys de propriedade seguem a mesma gramática. Não use namespaces reservados ou segmentos confidenciais, incluindo analytics, identity, session, telemetry, url, user, users, email, password, passwd, secret, token, authorization, cookie, username, ip, credential, api_key, private_key, html, dom, selector, selectors, stack, stacktrace, text, input ou referrer. Essas restrições também se aplicam a nomes de ações.
As propriedades podem conter strings escalares, números finitos e booleanos. Matrizes, objetos aninhados, valores nulos, credenciais e dados pessoais não são permitidos.
Limite | Valor |
|---|---|
Propriedades por evento | 50 |
Comprimento da key da propriedade | 128 caracteres |
Comprimento do valor da string | 1.024 caracteres |
As projeções de query omitem propriedades que não atendem a essas restrições. Os produtores continuam responsáveis pelo significado dos valores que enviam. Verificações sintáticas isoladas não podem determinar que um valor não é pessoal.
Caminhos de página
A page_path begins with / and contains the concrete application path. Remove query strings and fragments, and sanitize sensitive path segments. Don't send credentials, personal data, or user-entered text in a path.
Um caminho inválido é omitido da projeção da query. Um page view sem um caminho permanece válido, mas não contribui para agregações em nível de rota.
Sessões
Uma sessão de analítica pertence a um contexto de navegador de nível superior. Quando um produtor fornece um ID de sessão, mantenha-o estável durante a navegação e os recarregamentos no lado do cliente e renove-o após 30 minutos sem um evento de analítica gravado.
As IDs de sessão devem ser opacas e não devem ser derivadas de identidades de usuário, endereços de email, endereços IP, IDs de solicitação, IDs de job, IDs de usuário ou access tokens. Os eventos do backend preservam a sessão de origem quando uma está disponível. Os eventos reproduzidos preservam sua sessão e seu tempo do evento originais.
Uma sessão mede uma janela de atividade, não uma pessoa única. As métricas de visualizadores no produto podem usar dados de acesso ao aplicativo separados.
Regras de Web Vital
Os eventos do Web Vital adicionam os seguintes campos. Codifique o valor e o delta como atributos OTLP doubleValue e os campos restantes como atributos stringValue. Os campos específicos do Web Vital devem estar ausentes em ações e visualizações de página.
campo | Requisito | Descrição |
|---|---|---|
| Obrigatório | Valor cumulativo finito e não negativo para a amostra. |
| Obrigatório |
|
| Obrigatório | Finite, nonnegative change since the previous report. |
| Obrigatório | Globally unique identifier shared by reports for one sample. |
| Obrigatório |
|
| Opcional |
|
A tabela a seguir define as unidades e os limites:
Métrica | Nome | Unidade | Bom | Fraco |
|---|---|---|---|---|
| Largest Contentful Paint (LCP) |
| ≤ 2.500 | > 4.000 |
| Interaction to Next Paint (INP) |
| ≤ 200 | > 500 |
| Cumulative Layout Shift (CLS) |
| ≤ 0,1 | > 0,25 |
| First Contentful Paint (FCP) |
| ≤ 1.800 | > 3.000 |
| Tempo até o primeiro byte (TTFB) |
| ≤ 800 | > 1.800 |
LCP, INP e CLS são Core Web Vitals. FCP e TTFB fornecem medições de desempenho adicionais. Um valor é good no limite Bom ou abaixo dele, poor acima do limite Ruim e needs_improvement entre eles. Uma unidade ou classificação incompatível torna o registro inválido.
Uma amostra pode produzir vários relatórios. Web Vitals descrevem a navegação de documentos. Uma alteração de rota no lado do cliente pode produzir uma exibição de página sem produzir uma nova amostra do Web Vital. Um servidor pode encaminhar uma medição de navegador, mas as temporizações de servidor não substituem essa medição.
Ordem de validação
Processe os registros na seguinte ordem:
- Selecione as versões de esquema e os tipos de evento compatíveis. Para este esquema, selecione a versão
1eaction,page_viewouweb_vital. - Decodifique os atributos tipados e exija valores de
event_id,event_nameeoccurred_atválidos. - Valide campos, nomes, unidades, classificações e restrições de campo de tipo de evento. Exclua registros com campos obrigatórios inválidos e projete apenas os dados opcionais permitidos.
- Detectar IDs de eventos conflitantes e desduplicar entregas idênticas.
- Selecione o intervalo de análise e quaisquer filtros de caminho ou evento.
- Para o Web Vitals, reduza relatórios repetidos a um relatório por amostra.
- Agregue os eventos ou as amostras resultantes.
Mantenha a validação separada dos diagnósticos de ingestão. Encontrar uma linha em otel_logs não estabelece que ela esteja em conformidade com o esquema de eventos.
Deduplicação e redução de amostra
Identical deliveries of an event count as one event. Se um event_id for reutilizado para conteúdo de evento lógico diferente, exclua todos os registros desse conjunto de conflitos e relate o conflito como um problema de qualidade de dados. Don't choose an arbitrary delivery from the set.
Comparar conteúdo lógico normalizado, incluindo campos e propriedades opcionais. Use uma representação determinística de propriedades para que a ordenação de chaves não crie falsos conflitos. Os metadados de transporte não fazem parte do conteúdo do evento lógico. As novas tentativas preservam o Timestamp original do evento.
Verifique a identidade em todas as entregas retidas para cada ID de evento candidato antes de aplicar o intervalo de tempo de análise. Filtrar entregas brutas primeiro pode ocultar conteúdo conflitante fora desse intervalo.
After deduplication and selection of the análise interval, retain the latest report per web_vital_sample_id. Ordene os relatórios por occurred_at, desempatando com event_id, ambos em ordem decrescente. Calculate percentiles after this reduction.
Definições de métricas
Os intervalos de tempo incluem start_time e excluem end_time. Os intervalos de tempo usam o Tempo Universal Coordenado (UTC).
Métrica | Definição |
|---|---|
Page views | Number of deduplicated |
Sessões | Número de valores de |
Ações monitoradas | Number of deduplicated |
Páginas por sessão | Visualizações de página divididas por sessões. Nenhum valor quando a contagem de sessões for zero. |
Principais ações | Ações agrupadas por |
Principais páginas | Visualizações de página agrupadas por |
Web Vital p75 | Percentil 75 de rank mais próximo após a desduplicação de eventos e a redução de amostras. |
Tamanho da amostra do Web Vital | Número de amostras distintas após a redução. |
Último evento | Maior |
Para N amostras ordenadas, o p75 de rank mais próximo usa o valor na posição ceil(0.75 × N), com indexação baseada em um. Considere menos de 30 amostras do Web Vital como evidência indicativa, e não conclusiva, de uma tendência.
Este esquema não define dimensões de identidade de usuário, dispositivo, navegador ou geografia. As superfícies de produto podem exibir métricas adicionais de outras fontes. Em particular, os visualizadores únicos do painel não são computados contando sessões de analítica.
Exemplo: calcular a Web Vital p75 a partir de eventos validados
The following query demonstrates collision exclusion, deduplication, sample reduction, and exact percentile calculation. It consumes a normalized dataset, not the raw otel_logs table.
Prepare the input
Crie uma view de entrada no seu próprio pipeline de processamento que aplique os passos de 1 a 3 da Ordem de validação. A view deve conter os seguintes dados:
- Uma linha por entrega que passa pela validação, antes da desduplicação ou da filtragem por intervalo de tempo.
- Os campos lógicos digitados, incluindo
event_id,occurred_at,event_type,event_name,web_vital_valueeweb_vital_sample_id. - Uma string
logical_contentnão nula contendo uma representação determinística de todos os campos e propriedades de eventos normalizados. Represente campos opcionais ausentes de forma consistente e preserve o horário original do evento.
Defina o escopo da entrada para o aplicativo que você está analisando. Inclua entregas retidas de todos os tipos de evento compatíveis para que a reutilização de uma ID de evento entre tipos seja detectada. A entrada deve impor todos os campos obrigatórios, tipos numéricos e intervalos, unidades, classificações e restrições de tipo de evento descritos acima.
Esta view de entrada não é criada habilitando a telemetria do aplicativo. Este é um pré-requisito fornecido pelo seu pipeline de processamento. Converter alguns atributos brutos não substitui este passo de validação.
Aggregate the validated input
Substitua <catalog>.<schema>.<validated-events-view> por sua view de entrada. Defina :start_time e :end_time como parâmetros Timestamp no editor de 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 na classificação solicitada em vez de uma aproximação. A query exclui IDs de eventos conflitantes antes de selecionar o intervalo de tempo. Rastreie separadamente os IDs cujos content_count excedem um como erros de qualidade de dados.
Por exemplo, três amostras de LCP reduzidas 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.
Controle de versão
schema_version identifica a versão principal do contrato independentemente das versões do pacote do produtor.
Adicionar campos opcionais ou nomes de ação definidos pelo aplicativo é compatível com versões anteriores. A remoção de campos obrigatórios ou a alteração de seus tipos, significados, escopo de identificador ou semântica de sessão requer uma mudança de versão principal. Alterações na desduplicação, redução de amostra 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 compatíveis em vez de interpretá-los como ações.