App Analytics händelseschema och frågor

Använd denna referens för att implementera en event producer eller skriva frågor över App Analytics-händelser. Den definierar schemaversion 1, dess OpenTelemetry Protocol (OTLP)-kodning och de bearbetningssteg som krävs före aggregering.

För ett exempel från första händelsen, se Kom igång med App Analytics. För instrumentpanelen och dess ytterligare appåtkomstdata, se Vad är appanalys?.

Händelseschema

Varje händelse är en OpenTelemetri-loggpost som lagras i appens otel_logs tabell i Unity Catalog. Använd det konfigurerade tabellnamnet, inklusive vilket prefix som helst. Tabellen innehåller också andra loggposter, så välj analyshändelser efter schemaversion och händelsetyp.

Nyttolastexempel

Välj en händelsetyp för att se dess nyttolast. Varje exempel är en OTLP-loggpost, som läggs till resourceLogs[].scopeLogs[].logRecords[] vid export. Quickstart visar den önskemålswrappern.

ID:n och tidsstämpeln nedan är illustrativa. Generera ett unikt ID för varje ny händelse och använd dess faktiska förekomsttid. Exemplen utelämnar det valfria session_id.

Action

Registrera en färdig rapportexport. Den valfria format egenskapen beskriver exporten utan att ändra händelsenamnet.

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

sidvy

Spela in ett besök på /reports. Evenemangstypen och evenemangets namn är båda 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

Registrera en Största Contentful Paint (LCP)-mätning på 1 800 millisekunder. Detta värde har en good bedömning.

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

Rapporter för samma mätning delar en web_vital.sample_id. Varje ny rapport har sin egen event.id. Se Web Vital-regler.

Vanliga fält

Följande logiska fält gäller över alla händelsetyper. Deras OTLP-attributnamn förekommer i exemplen ovan.

session_id är valfritt i händelseschemat. Sessionsbaserade mätvärden använder de poster som tillhandahåller dem. Fabricera inte en identitet eller använd en tom sträng för att representera en frånvarande session.

Nödvändiga strängar måste vara icke-tomma och får inte innehålla tomt mellanslag, uppgifter eller personuppgifter. När ett valfritt fält finns måste det följa sina fältregler. Ett frånvarande valfritt attribut läses som null i det logiska schemat.

Händelsetyper

En fångad handling beskriver vad producenten spelade in. Till exempel kan ett klick registrera avsikt utan att bevisa att operationen lyckades.

OTLP-kodning och tabellfält

Analytiska attribut använder databricks.app.analytics. namnrymden. Följande tabell avbildar de logiska fälten till OTLP och telemetritabellen:

Använd följande OTLP JSON-kodningar:

• Tidsstämplar: En decimalsträng av Unix-nanosekunder i timeUnixNano.
• Heltal: En decimalsträng intValue, såsom { "intValue": "1" }.
• Dubblar: En numerisk doubleValue, såsom { "doubleValue": 1.25 }.
• Strängar: stringValue.
• Booleans: boolValue.

Sätt loggposterna eventName till samma värde som analytics-attributet event_name . Instrumenteringen scope.name identifierar producenten, men är inte en selector för analysposter.

Telemetritabellen kan behålla en enkelfältsomslag doubleValue för numeriska värden, inklusive noll. Avkoda den wrappern innan du validerar numeriska fält. Validera originalvärdets typ innan du kastar det, istället för att acceptera en numeriskt liknande sträng som ett tal.

Den fysiska date kolumnen finns tillgänglig för beskärning av partitioner. Det är inte en del av det logiska händelseschemat.

Fältbegränsningar

Sanera fälten innan export. Validering och projektion i en fråga tar inte bort rådata som redan lagrats i telemetritabellen.

Handlingsnamn och egenskaper

Handlingsnamn innehåller 1 till 128 tecken. De börjar med en liten bokstav och använder gemener, siffror, prickar och understreck. Prickar och understreck är separata alfanumeriska segment. Grammatiken är ^[a-z][a-z0-9]*([._][a-z0-9]+)*$.

Använd stabila namn istället för att bädda in ID:n, e-postadresser eller användarinmatad text. Lägg till olika detaljer i fastigheterna. Till exempel, använd report_exported med en format egenskap istället för ett annat åtgärdsnamn för varje format.

Egenskaperycklar följer samma grammatik. Använd inte reserverade namnrymder eller känsliga segment, inklusive analytics, identity, , telemetrysession, url, userstackpasswdpasswordemailuserssecrettokenapi_keycredentialprivate_keyiphtmlusernamedomselectorcookieauthorizationstacktracetextselectorsinputeller .referrer Dessa begränsningar gäller även för åtgärdsnamn.

Egenskaper kan innehålla skalärsträngar, ändliga tal och booleanska värden. Arrayer, nästlade objekt, nullvärden, legitimationsuppgifter och personuppgifter är inte tillåtna.

Frågeprojektioner utelämnar egenskaper som inte uppfyller dessa begränsningar. Producenter är fortfarande ansvariga för innebörden av de värden de sänder. Syntaktiska kontroller kan inte ensamma fastställa att ett värde är icke-personligt.

Sidvägar

A page_path börjar med / och innehåller den konkreta appliceringsvägen. Ta bort frågesträngar och fragment, och sanera känsliga vägsegment. Skicka inte inloggningsuppgifter, personuppgifter eller användarinmatad text i en sökväg.

En ogiltig väg utelämnas från frågeprojektionen. En sidvisning utan sökväg förblir giltig, men bidrar inte till ruttnivåaggregeringar.

Sessions

En analyssession tillhör en webbläsarkontext på toppnivå. När en producent tillhandahåller ett sessions-ID, håll det stabilt över klientsidans navigering och omladdningar, och förnya det efter 30 minuter utan en inspelad analyshändelse.

Sessions-ID:n måste vara ogenomskinliga och får inte härstamma från användaridentiteter, e-postadresser, IP-adresser, förfrågnings-ID:n, jobb-ID:n eller åtkomsttoken. Backend-händelser bevarar den ursprungliga sessionen när en sådan är tillgänglig. Omspelade evenemang bevarar sin ursprungliga session och evenemangstid.

En session mäter ett aktivitetsfönster, inte en unik person. Tittarmått i produkten kan använda separata appåtkomstdata.

Web Vital-regler

Webb Vitala händelser lägger till följande fält. Koda värde och delta som OTLP-attribut doubleValue , och de återstående fälten som stringValue attribut. Webbplatsspecifika fält för vitala ändamål måste saknas vid åtgärder och sidvisningar.

Följande tabell definierar enheter och tröskelvärden:

LCP, INP och CLS är Core Web Vitals. FCP och TTFB tillhandahåller ytterligare prestandamätningar. Ett värde är good på eller under den goda tröskeln, poor över den dåliga tröskeln och needs_improvement mellan dem. En oöverensstämmande enhet eller betyg gör posten ogiltig.

Ett urval kan ge flera rapporter. Web Vitals beskriver dokumentnavigering. En kundsidans ruttändring kan skapa en sidvisning utan att skapa ett nytt Web Vital-exempel. En server kan vidarebefordra en webbläsarmätning, men servertider är inte en ersättning för den mätningen.

Valideringsordning

Processa poster i följande ordning:

1. Välj stödda schemaversioner och händelsetyper. För detta schema, välj version 1 och action, page_view, eller web_vital.
2. Avkoda de typade attributen och kräver giltiga event_id, event_name, och occurred_at värden.
3. Validera händelsetypfält, namn, enheter, betyg och fältbegränsningar. Exkludera poster med ogiltiga obligatoriska fält och projektdata är endast tillåten valfri data.
4. Upptäck motstridiga händelse-ID:n och deduplicera identiska leveranser.
5. Välj analysintervallet och eventuella väg- eller händelsefilter.
6. För Web Vitals, minska upprepade rapporter till en rapport per urval.
7. Aggregera de resulterande händelserna eller proverna.

Håll validering åtskild från intagsdiagnostik. Att hitta en rad i otel_logs fastställer inte att den följer händelseschemat.

Deduplicering och provreduktion

Identiska leveranser av en händelse räknas som en händelse. Om en event_id återanvänds för annat logiskt händelseinnehåll, uteslut varje post i den konfliktuppsättningen och rapportera konflikten som ett datakvalitetsfel. Välj inte en godtycklig leverans från setet.

Jämför normaliserat logiskt innehåll, inklusive valfria fält och egenskaper. Använd en deterministisk representation av egenskaper så att nyckelordningen inte skapar falska konflikter. Transportmetadata ingår inte i det logiska händelseinnehållet. Omprövningar bevarar den ursprungliga händelsens tidsstämpel.

Kontrollera identiteten över de behållna leveranserna för varje kandidat händelse-ID innan analystidsintervallet tillämpas. Att filtrera råa leveranser först kan dölja motstridigt innehåll utanför det intervallet.

Efter deduplicering och val av analysintervall, behåll den senaste rapporten per web_vital_sample_id. Ordningen rapporterar med occurred_at, bryter banden med event_id, båda nedåtgående. Beräkna percentiler efter denna minskning.

Måttdefinitioner

Tidsintervall inkluderar start_time och exkluderar end_time. Tidshinkar använder Coordinated Universal Time (UTC).

För N ordnade prover använder närmaste rank p75 värdet på position ceil(0.75 × N), med enbaserad indexering. Behandla färre än 30 Web Vital-prover som indikativa snarare än avgörande bevis på en trend.

Detta schema definierar inte användaridentitet, enhet, webbläsare eller geografiska dimensioner. Produktytor kan visa ytterligare mätvärden från andra källor. Särskilt beräknas inte dashboardens unika visningar genom att räkna analyssessioner.

Exempel: beräkna Web Vital p75 från validerade händelser

Följande fråga visar kollisionsexkludering, deduplicering, stickprovsreduktion och exakt percentilberäkning. Den använder en normaliserad datamängd, inte den råa otel_logs tabellen.

Förbered indata

Skapa en inmatningsvy i din egen bearbetningspipeline som tillämpar steg 1 till 3 i valideringsordningen. Vyn måste innehålla följande data:

• En rad per leverans som klarar valideringen, innan deduplicering eller tidsintervallfiltrering.
• De typade logiska fälten, inklusive event_id, occurred_at, , event_type, web_vital_valueevent_name, , och web_vital_sample_id.
• En icke-nullsträng logical_content som innehåller en deterministisk representation av alla normaliserade händelsefält och egenskaper. Representera avsaknade valfria fält konsekvent och bevara den ursprungliga händelsetiden.

Begränsa inputen till appen du analyserar. Inkludera behållna leveranser av alla stödda händelsetyper så att återanvändning av ett händelse-ID mellan olika typer kan upptäckas. Indata måste upprätthålla alla nödvändiga fält, numeriska typer och intervall, enheter, betyg och händelsetypbegränsningar som beskrivs ovan.

Aggregera den validerade indatan

Ersätt <catalog>.<schema>.<validated-events-view> med din inmatningsvy. Sätt :start_time och :end_time som tidsstämpelparametrar i SQL-editorn.

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 returnerar det observerade värdet vid den begärda rangen istället för en approximation. Frågan utesluter motstridiga händelse-ID:n innan tidsintervallet väljs. Spåra ID:n vars content_count överstiger ett separat som datakvalitetsfel.

Till exempel ger tre reducerade LCP-prover med värden 100, 200 och 300 millisekunder och sample_size = 3p75 = 300. Identiska återleveranser ökar inte det antalet prov. Ett händelse-ID med motstridigt normaliserat innehåll bidrar inte med någon post.

Versioning

schema_version identifierar huvudkontraktsversionen oberoende av producentpaketversionerna.

Att lägga till valfria fält eller applikationsdefinierade handlingsnamn är bakåtkompatibelt. Att ta bort nödvändiga fält eller ändra deras typer, betydelser, identifieraromfängd eller sessionsemantik kräver en större versionsförändring. Ändringar i deduplicering, sample-reduktion eller händelsetypsemantik kräver också en ny större version.

Konsumenter ignorerar icke-stödda versioner och händelsetyper istället för att tolka dem som åtgärder.

Ytterligare resurser

• Vad är App Analytics?
• Kom igång med App Analytics
• Konfigurera telemetri för Databricks Apps