Schema degli eventi e query di App Analytics

Usa questo riferimento per implementare un event producer o scrivere query su eventi App Analytics. Definisce lo schema versione 1, la codifica del suo OpenTelemetry Protocol (OTLP) e i passaggi di elaborazione necessari prima dell'aggregazione.

Per un esempio di primo evento, vedi Inizia con App Analytics. Per la dashboard e i suoi dati aggiuntivi di accesso alle app, vedi Cos'è App Analytics?.

Schema eventi

Ogni evento è un registro di registro OpenTelemetry memorizzato nella tabella dell'app otel_logs nel Unity Catalog. Usa il nome della tabella configurata, incluso qualsiasi prefisso. La tabella contiene anche altri record di log, quindi seleziona gli eventi di analisi in base alla versione dello schema e al tipo di evento.

Esempi di payload

Seleziona un tipo di evento per vedere il suo payload. Ogni esempio è un registro OTLP, inserito resourceLogs[].scopeLogs[].logRecords[] al momento dell'esportazione. Il quickstart mostra quell'involucro delle richieste.

I documenti e l'ora di riferimento qui sotto sono esemplari. Genera un ID unico per ogni nuovo evento e usa il suo tempo effettivo di verificazione. Gli esempi omettono l'opzionale session_id.

Action

Registra un'esportazione del report completato. La proprietà opzionale format descrive l'esportazione senza cambiare il nome dell'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" } }
  ]
}

visualizzazione pagina

Registra una visita a /reports. Il tipo e il nome dell'evento sono entrambi 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 misura di Largest Contentful Paint (LCP) di 1.800 millisecondi. Questo valore ha una good classificazione.

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

I rapporti per la stessa misura condividono un web_vital.sample_id. Ogni nuovo rapporto ha i propri event.id. Vedi le regole Web Vital.

Campi comuni

I seguenti campi logici si applicano a tutti i tipi di eventi. I nomi degli attributi OTLP compaiono negli esempi sopra.

session_id è opzionale nello schema degli eventi. Le metriche basate su sessioni utilizzano i record che le forniscono in regola. Non inventare un'identità né usare una stringa vuota per rappresentare una sessione assente.

Le stringhe richieste devono essere non vuote e non devono contenere spazi bianchi, credenziali o dati personali. Quando è presente un campo opzionale, deve conformarsi alle regole del campo. Un attributo opzionale assente si legge come nullo nello schema logico.

Tipi di evento

Un'azione catturata descrive ciò che il produttore ha registrato. Ad esempio, un clic può registrare l'intento senza dimostrare che l'operazione abbia avuto successo.

Codifica OTLP e campi di tabella

Gli attributi Analytics utilizzano il databricks.app.analytics. namespace. La tabella seguente mappa i campi logici a OTLP e alla tabella di telemetria:

Usa le seguenti codifiche JSON OTLP:

• Timestamps: una stringa decimale di nanosecondi Unix in timeUnixNano.
• Interi: Una stringa intValuedecimale , come { "intValue": "1" }.
• Raddoppi: Un numerico doubleValue, come { "doubleValue": 1.25 }.
• Corde: stringValue.
• Booleani: boolValue.

Imposta i record eventName dei log allo stesso valore dell'attributo analytics event_name . La strumentazione scope.name identifica il produttore, ma non è un selezionatore per i record di analisi.

La tabella di telemetria può mantenere un wrapper a campo singolo doubleValue per valori numerici, incluso zero. Decodifica quel wrapper prima di validare i campi numerici. Valida il tipo del valore originale prima di lanciarlo, invece di accettare una stringa numerica come numero.

La colonna fisica date è disponibile per la potatura delle partizioni. Non fa parte dello schema degli eventi logici.

Vincoli di campo

Sterilizza i campi prima dell'esportazione. La validazione e la proiezione in una query non rimuovono i dati grezzi già memorizzati nella tabella di telemetria.

Nomi e proprietà delle azioni

I nomi delle azioni contengono da 1 a 128 caratteri. Iniziano con una lettera minuscola e usano lettere minuscole, cifre, punti e sottoline. Punti e sottolineamenti separati in segmenti alfanumerici. La grammatica è ^[a-z][a-z0-9]*([._][a-z0-9]+)*$.

Usa nomi di stable invece di inserire ID, indirizzi email o testi inseriti dagli utenti. Inserisci dettagli diversi nelle proprietà. Ad esempio, usa report_exported con una format proprietà invece di un nome di azione diverso per ogni formato.

Le chiavi di proprietà seguono la stessa grammatica. Non usare namespace riservati o segmenti sensibili, inclusi analytics, , telemetrystacktraceipusernamecookiecredentialauthorizationtokensecretapi_keypasswdpasswordprivate_keyselectorsselectorstackdomtextinputsessionuserreferrerurlusersemailhtmlidentity Queste restrizioni si applicano anche ai nomi delle azioni.

Le proprietà possono contenere stringhe scalari, numeri finiti e booleani. Array, oggetti annidati, valori nulli, credenziali e dati personali non sono permessi.

Le proiezioni delle query omettono proprietà che non soddisfano questi vincoli. I produttori rimangono responsabili del significato dei valori che inviano. I controlli sintattici da soli non possono stabilire che un valore sia non personale.

Percorsi delle pagine

A page_path inizia con / e contiene il percorso di applicazione concreto. Rimuovere stringhe di query e frammenti e sanificare i segmenti di percorso sensibili. Non inviare credenziali, dati personali o testo inserito dall'utente in un percorso.

Un percorso non valido viene omesso dalla proiezione della query. Una visualizzazione di pagina senza percorso rimane valida, ma non contribuisce alle aggregazioni a livello di percorso.

Sessioni

Una sessione di analisi appartiene al contesto di un browser di alto livello. Quando un produttore fornisce un ID di sessione, mantieni la stabilità durante la navigazione lato client e i ricaricamenti, e rinnovala dopo 30 minuti senza un evento di analisi registrato.

Gli ID di sessione devono essere opachi e non devono derivare da identità utente, indirizzi email, indirizzi IP, ID di richiesta, ID di lavoro o token di accesso. Gli eventi backend preservano la sessione di origine quando è disponibile. Gli eventi rigiocati conservano la loro sessione originale e il tempo degli eventi.

Una sessione misura una finestra di attività, non una persona unica. Le metriche di visualizzazione nel prodotto possono utilizzare dati separati per l'accesso all'app.

Regole Web Vital

Gli eventi Web Vital aggiungono i seguenti campi. Codifica valore e delta come attributi OTLP doubleValue , e i campi rimanenti come stringValue attributi. I campi specifici di Web Vital devono essere assenti nelle azioni e nelle visualizzazioni di pagina.

La tabella seguente definisce le unità e le soglie:

LCP, INP e CLS sono i Core Web Vitals. FCP e TTFB forniscono ulteriori misurazioni di prestazione. Un valore è good a o sotto la soglia del Buono, poor sopra la soglia del Povero e needs_improvement tra di esse. Un'unità o una valutazione discorrispondenti rende il record invalido.

Un campione può produrre più rapporti. I parametri vitali web descrivono la navigazione nei documenti. Un cambiamento di percorso lato client può produrre una visualizzazione pagina senza produrre un nuovo esempio Web Vital. Un server può inoltrare una misurazione del browser, ma i tempi del server non sostituiscono quella misurazione.

Ordine di validazione

Registri di processo nel seguente ordine:

1. Seleziona le versioni di schema supportate e i tipi di eventi. Per questo schema, si selezionano versione 1 e action, page_view, o web_vital.
2. Decodifica gli attributi tipizzati e richiede valori validi event_id, event_name, e occurred_at .
3. Validare campi, nomi, unità, valutazioni e vincoli di campo per tipo di evento. Escludi i record con campi richiesti non validi e dati opzionali solo per il progetto permessi.
4. Rilevare ID di eventi in conflitto e deduplicare consegne identiche.
5. Seleziona l'intervallo di analisi e qualsiasi filtro di percorso o eventi.
6. Per i parametri vitali web, riduci i report ripetuti a un solo report per campione.
7. Aggregare gli eventi o campioni risultanti.

Mantieni la validazione separata dalla diagnostica dell'ingestione. Trovare una riga in otel_logs non stabilisce che sia conforme allo schema degli eventi.

Deduplicazione e riduzione del campione

Consegne identiche di un evento contano come un solo evento. Se un è event_id riutilizzato per contenuti logici diversi di eventi, escludere ogni record in quel set di conflitti e segnalare il conflitto come un problema di qualità dei dati. Non scegliere una consegna arbitraria dal set.

Confronta il contenuto logico normalizzato, inclusi campi e proprietà opzionali. Usa una rappresentazione deterministica delle proprietà in modo che l'ordinamento delle chiavi non crei conflitti false. I metadati di trasporto non fanno parte del contenuto logico degli eventi. I ritentativi conservano il timestamp originale dell'evento.

Controlla l'identità tra le consegne conservate per ogni ID evento candidato prima di applicare l'intervallo temporale di analisi. Filtrare prima le consegne grezze può nascondere contenuti contrastanti al di fuori di quel intervallo.

Dopo la deduplicazione e la selezione dell'intervallo di analisi, conservare il report più recente per web_vital_sample_id. Riferimenti d'ordine da occurred_at, interrompendo i legami con event_id, entrambi in discesa. Calcola i percentili dopo questa riduzione.

Definizioni di metrica

Gli intervalli di tempo includono start_time ed escludono end_time. I compartimenti temporali utilizzano il Tempo Universale Coordinato (UTC).

Per N i campioni ordinati, il rango più vicino p75 usa il valore in posizione ceil(0.75 × N), con indicizzazione basata su uno. Considera meno di 30 campioni di Web Vital come prova indicativa piuttosto che conclusiva di una tendenza.

Questo schema non definisce l'identità dell'utente, il dispositivo, il browser o le dimensioni geografiche. Le superfici di prodotto possono mostrare metriche aggiuntive provenienti da altre fonti. In particolare, i visualizzatori unici della dashboard non vengono calcolati contando le sessioni di analisi.

Esempio: calcolare Web Vital p75 da eventi validati

La seguente query dimostra l'esclusione delle collisioni, la deduplicazione, la riduzione del campione e il calcolo esatto del percentile. Consuma un dataset normalizzato, non la tabella grezza otel_logs .

Prepara l'input

Crea una vista di input nella tua pipeline di elaborazione che applichi i passaggi da 1 a 3 dell'ordine di validazione. La vista deve contenere i seguenti dati:

• Una riga per ogni consegna che supera la validazione, prima della deduplicazione o del filtraggio per intervallo temporale.
• I campi logici tipati, inclusi event_id, occurred_at, event_type, event_name, web_vital_value, e web_vital_sample_id.
• Una stringa non nulla logical_content contenente una rappresentazione deterministica di tutti i campi e proprietà di eventi normalizzati. Rappresentare i campi opzionali assenti in modo coerente e preservare il tempo originale dell'evento.

Analizza l'input dell'app che stai analizzando. Includere le consegne conservate di tutti i tipi di eventi supportati in modo che venga rilevato il riutilizzo di un ID evento tra i tipi. L'input deve far rispettare tutti i campi richiesti, i tipi numerici e gli intervalli, le unità, le valutazioni e i vincoli di tipo di evento descritti sopra.

Aggrega l'input validato

Sostituisci <catalog>.<schema>.<validated-events-view> con la tua vista di input. Imposta :start_time e :end_time come timestamp parametri nell'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 restituisce il valore osservato al rango richiesto invece di un'approssimazione. La query esclude gli ID degli eventi in conflitto prima di selezionare l'intervallo temporale. Monitorare gli ID che content_count superano uno separatamente come errori di qualità dei dati.

Ad esempio, tre campioni LCP ridotti con valori di 100, 200 e 300 millisecondi producono sample_size = 3 e p75 = 300. Riconsegne identiche non aumentano quel numero di campioni. Un ID evento con contenuti normalizzati in conflitto non contribuisce a nessun record.

Versioning

schema_version identifica la versione principale sotto contratto indipendentemente dalle versioni del produttore del pacchetto.

Aggiungere campi opzionali o nomi di azioni definiti dall'applicazione è retrocompatibile. Rimuovere i campi richiesti o modificare i loro tipi, significati, ambito dell'identificatore o semantica della sessione richiede una modifica importante della versione. Anche le modifiche alla deduplicazione, alla riduzione del campione o alla semantica dei tipi di evento richiedono una nuova versione principale.

I consumatori ignorano versioni e tipi di eventi non supportati invece di interpretarli come azioni.

Risorse aggiuntive

• Cos'è App Analytics?
• Inizia con App Analytics
• Configura la telemetria per le app Databricks