App Analytics gebeurtenisschema en queries

Gebruik deze referentie om een event producer te implementeren of queries te schrijven over App Analytics-events. Het definieert schemaversie 1, de OpenTelemetry Protocol (OTLP)-codering en de verwerkingsstappen die nodig zijn vóór aggregatie.

Voor een voorbeeld van een eerste gebeurtenis, zie Begin met App Analytics. Voor het dashboard en de aanvullende app-toegangsgegevens, zie Wat is App Analytics?.

Gebeurtenisschema

Elk event is een OpenTelemetrie-logrecord dat is opgeslagen in de otel_logs tabel van de app in Unity Catalog. Gebruik de geconfigureerde tabelnaam, inclusief elk prefix. De tabel bevat ook andere logboekrecords, dus selecteer analytics-evenementen op basis van hun schemaversie en gebeurtenistype.

Voorbeelden van payloads

Selecteer een gebeurtenistype om de payload te bekijken. Elk voorbeeld is één OTLP-logrecord, geplaatst resourceLogs[].scopeLogs[].logRecords[] bij export. De quickstart toont die request wrapper.

De ID's en tijdstempel hieronder zijn illustratief. Genereer een unieke ID voor elk nieuw evenement en gebruik de werkelijke tijd van het optreden. De voorbeelden laten de optionele session_idweg .

Action

Registreer een voltooid rapportexport. De optionele format eigenschap beschrijft de export zonder de gebeurtenisnaam te wijzigen.

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

paginaweergave

Neem een bezoek aan /reportsop. Het type evenement en de naam van het evenement zijn beide 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

Registreer een Grootste Contentful Paint (LCP) meting van 1.800 milliseconden. Deze waarde heeft een good beoordeling.

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

Rapporten voor dezelfde meting delen een web_vital.sample_id. Elk nieuw rapport heeft zijn eigen event.id. Zie Web Vital-regels.

Algemene velden

De volgende logische velden zijn van toepassing op alle gebeurtenistypen. Hun OTLP-attribuutnamen verschijnen in de bovenstaande voorbeelden.

session_id is optioneel in het eventschema. Sessiegebaseerde metrics gebruiken de gegevens die het aanleveren. Verzin geen identiteit of gebruik geen lege string om een afwezige sessie weer te geven.

Vereiste strings mogen niet-leeg zijn en mogen geen witruimte, inloggegevens of persoonlijke gegevens bevatten. Wanneer er een optioneel veld aanwezig is, moet het voldoen aan de veldregels. Een afwezig optioneel attribuut leest als null in het logische schema.

Gebeurtenistypen

Een vastgelegde actie beschrijft wat de producent heeft opgenomen. Een klik kan bijvoorbeeld intentie vastleggen zonder te bewijzen dat de operatie is geslaagd.

OTLP-codering en tabelvelden

Analytics-attributen gebruiken de databricks.app.analytics. naamruimte. De volgende tabel beeldt de logische velden af aan OTLP en de telemetrietabel:

Gebruik de volgende OTLP JSON-coderingen:

• Tijdstempels: Een decimale reeks Unix-nanoseconden in timeUnixNano.
• Gehele getallen: Een decimale snaar intValue, zoals { "intValue": "1" }.
• Dubbelen: Een numeriek doubleValue, zoals { "doubleValue": 1.25 }.
• Snaren: stringValue.
• Booleans: boolValue.

Stel de logrecords eventName in op dezelfde waarde als het analytics-attribuut event_name . De instrumentatie scope.name identificeert de producent, maar is geen selector voor analysegegevens.

De telemetrietabel kan een single-field doubleValue wrapper behouden voor numerieke waarden, inclusief nul. Decodeer die wrapper voordat je numerieke velden valideert. Valideer het type van de oorspronkelijke waarde voordat je deze uitspreekt, in plaats van een numeriek uitziende string als getal te accepteren.

De fysieke date kolom is beschikbaar voor het snoeien van partities. Het maakt geen deel uit van het logische gebeurtenisschema.

Veldbeperkingen

Smit velden voordat je exporteert. Validatie en projectie in een query verwijderen geen ruwe data die al in de telemetrietabel is opgeslagen.

Actienamen en eigenschappen

Actienamen bevatten 1 tot 128 tekens. Ze beginnen met een kleine letter en gebruiken kleine letters, cijfers, stippen en onderstrepen. Puntjes en onderstreepjes onderscheiden alfanumerieke segmenten. De grammatica is ^[a-z][a-z0-9]*([._][a-z0-9]+)*$.

Gebruik stabiele namen in plaats van het inbedden van ID's, e-mailadressen of door de gebruiker ingevoerde tekst. Zet verschillende details in de woningen. report_exported Gebruik bijvoorbeeld met een format eigenschap in plaats van een andere actienaam voor elk formaat.

Eigenschapssleutels volgen dezelfde grammatica. Gebruik geen gereserveerde naamruimtes of gevoelige segmenten, waaronder analytics, identity, session, , telemetry, userstackpasswordpasswdemailusersurlsecrettokenapi_keycredentialprivate_keyiphtmlusernamedomselectorcookieauthorizationstacktracetextselectorsinput, of .referrer Deze beperkingen gelden ook voor actienamen.

Eigenschappen kunnen scalairstrings, eindige getallen en booleanen bevatten. Arrays, geneste objecten, null-waarden, inloggegevens en persoonlijke gegevens zijn niet toegestaan.

Queryprojecties laten eigenschappen weg die niet aan deze beperkingen voldoen. Producenten blijven verantwoordelijk voor de betekenis van de waarden die ze sturen. Syntactische checks alleen kunnen niet vaststellen dat een waarde niet-persoonlijk is.

Paginapaden

A page_path begint met / en bevat het betonaanbrengingspad. Verwijder querystrings en fragmenten, en saneer gevoelige padsegmenten. Stuur geen inloggegevens, persoonlijke gegevens of door de gebruiker ingevoerde tekst in een pad.

Een ongeldig pad wordt weggelaten uit de queryprojectie. Een paginaweergave zonder pad blijft geldig, maar draagt niet bij aan route-niveau aggregaties.

Sessions

Een analysesessie behoort tot een topniveau browsercontext. Wanneer een producer een sessie-ID aanlevert, houd deze stabiel over client-side navigatie en herlaad, en verleng deze na 30 minuten zonder een geregistreerd analyse-event.

Sessie-ID's moeten ondoorzichtig zijn en mogen niet afkomstig zijn van gebruikersidentiteiten, e-mailadressen, IP-adressen, verzoek-ID's, job-ID's of toegangstokens. Backend-events behouden de oorspronkelijke sessie wanneer die beschikbaar is. Herhalde evenementen behouden hun oorspronkelijke sessie en evenementtijd.

Een sessie meet een activiteitsvenster, niet een uniek persoon. Viewer-metrics in het product kunnen aparte app-toegangsdata gebruiken.

Web Vital-regels

Web Vitale gebeurtenissen voegen de volgende velden toe. Codeer waarde en delta als OTLP-attributen doubleValue , en de overige velden als stringValue attributen. Web Vital-specifieke velden moeten ontbreken bij acties en paginaweergaven.

De volgende tabel definieert de eenheden en drempels:

LCP, INP en CLS zijn Core Web Vitals. FCP en TTFB bieden aanvullende prestatiemetingen. Een waarde ligt good op of onder de Goede drempel, poor boven de Slechte drempel, en needs_improvement tussen hen in. Een niet-overeenkomende eenheid of beoordeling maakt het record ongeldig.

Een steekproef kan meerdere rapporten opleveren. Web Vitals beschrijven documentnavigatie. Een wijziging aan de client-side route kan een paginaweergave opleveren zonder een nieuw Web Vital-voorbeeld te genereren. Een server kan een browsermeting doorsturen, maar servertimings zijn geen vervanging voor die meting.

Validatievolgorde

Verwerk records in de volgende volgorde:

1. Selecteer ondersteunde schema-versies en gebeurtenistypen. Voor dit schema selecteert u versie 1 en action, page_view, of web_vital.
2. Decodeer de getypeerde attributen en vereist geldige event_id, event_name, en occurred_at waarden.
3. Valideer gebeurtenistypevelden, namen, eenheden, beoordelingen en veldbeperkingen. Sluit records uit met ongeldige vereiste velden en project-only optionele data.
4. Detecteer conflicterende gebeurtenis-ID's en dedupliceer identieke leveringen.
5. Selecteer het analyse-interval en eventuele pad- of gebeurtenisfilters.
6. Voor Web Vitals verminder herhaalde meldingen tot één rapport per steekproef.
7. Verzamel de resulterende gebeurtenissen of monsters.

Houd validatie gescheiden van innamediagnostiek. Het vinden van een rij in otel_logs bewijst niet dat deze voldoet aan het gebeurtenisschema.

Deduplicatie en monsterreductie

Identieke leveringen van een evenement tellen als één gebeurtenis. Als een event_id wordt hergebruikt voor andere logische gebeurtenisinhoud, sluit dan elk record uit die conflictset uit en rapporteer het conflict als een datakwaliteitsprobleem. Kies geen willekeurige levering uit de set.

Vergelijk genormaliseerde logische inhoud, inclusief optionele velden en eigenschappen. Gebruik een deterministische representatie van eigenschappen zodat sleutelordening geen valse conflicten veroorzaakt. Transportmetadata maakt geen deel uit van de inhoud van de logische gebeurtenis. Herpogingen behouden de oorspronkelijke gebeurtenistijdstempel.

Controleer de identiteit van de behouden leveringen voor elke kandidaat gebeurtenis-ID voordat je de analyseperiode toepast. Het eerst filteren van ruwe leveringen kan conflicterende inhoud buiten dat bereik verbergen.

Na deduplicatie en het selecteren van het analyseinterval, bewaar het laatste rapport per web_vital_sample_id. Order rapporteert door occurred_at, verbreekt de banden met event_id, beide dalend. Bereken percentielen na deze reductie.

Metriekdefinities

Tijdintervallen omvatten start_time en sluiten end_timeuit. Tijdemmers gebruiken Gecoördineerde Universele Tijd (UTC).

Voor N geordende steekproeven gebruikt de dichtstbijzijnde rank p75 de waarde op positie ceil(0.75 × N), met één-gebaseerde indexering. Behandel minder dan 30 Web Vital-monsters als indicatief in plaats van sluitend bewijs van een trend.

Dit schema definieert geen gebruikersidentiteit, apparaat, browser of geografische dimensies. Productoppervlakken kunnen aanvullende metrics van andere bronnen weergeven. In het bijzonder worden de unieke viewers van het dashboard niet berekend door analysesessies te tellen.

Voorbeeld: bereken Web Vital p75 uit gevalideerde gebeurtenissen

De volgende query toont botsingsuitsluiting, deduplicatie, steekproefreductie en exacte percentielberekening. Het verbruikt een genormaliseerde dataset, niet de ruwe otel_logs tabel.

Bereid de input voor

Maak een inputweergave aan in je eigen verwerkingspijplijn die stappen 1 tot en met 3 van de validatievolgorde toepast. De weergave moet de volgende gegevens bevatten:

• Eén rij per levering die validatie doorstaat, vóór deduplicatie of tijdsintervalfiltering.
• De getypeerde logische velden, waaronder event_id, occurred_at, , event_typeevent_name, , web_vital_valueen web_vital_sample_id.
• Een niet-nulstring logical_content die een deterministische representatie bevat van alle genormaliseerde gebeurtenisvelden en eigenschappen. Vertegenwoordig afwezige optionele velden consistent en behoud de oorspronkelijke gebeurtenistijd.

Beperk de input naar de app die je analyseert. Includeer behouden leveringen van alle ondersteunde gebeurtenistypes zodat hergebruik van een gebeurtenis-ID tussen types wordt gedetecteerd. De invoer moet alle vereiste velden, numerieke types en bereiken, eenheden, beoordelingen en gebeurtenistypebeperkingen zoals hierboven beschreven, afdwingen.

Aggregeer de gevalideerde invoer

Vervang <catalog>.<schema>.<validated-events-view> door je inputweergave. Stel :start_time en :end_time in als tijdstempelparameters in de SQL-editor.

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 geeft de waargenomen waarde terug op de gevraagde rang in plaats van een benadering. De zoekopdracht sluit conflicterende gebeurtenis-ID's uit voordat het tijdsbereik wordt geselecteerd. Volg IDs waarvan de content_count ene afzonderlijk overschrijdt als datakwaliteitsfouten.

Bijvoorbeeld, drie gereduceerde LCP-monsters met waarden van 100, 200 en 300 milliseconden produceren sample_size = 3 en p75 = 300. Identieke herleveringen verhogen dat aantal monsters niet. Een event ID met conflicterende genormaliseerde inhoud levert geen record.

Versioning

schema_version identificeert de belangrijkste contractversie onafhankelijk van de producer package-versies.

Het toevoegen van optionele velden of applicatiegedefinieerde actienamen is achterwaarts compatibel. Het verwijderen van vereiste velden of het wijzigen van hun types, betekenissen, identifierscope of sessiesemantiek vereist een grote versiewijziging. Wijzigingen in deduplicatie, samplereductie of gebeurtenistype-semantiek vereisen ook een nieuwe grote versie.

Consumenten negeren niet-ondersteunde versies en gebeurtenistypes in plaats van ze te interpreteren als acties.

Aanvullende bronnen

• Wat is App Analytics?
• Begin met App Analytics
• Configure telemetry for Databricks Apps