App Analytics Ereignisschema und Abfragen

Verwenden Sie diese Referenz, um einen Event Producer zu implementieren oder Abfragen über App-Analytics-Events zu schreiben. Es definiert Schema-Version 1, deren OpenTelemetry Protocol (OTLP)-Codierung und die Verarbeitungsschritte, die vor der Aggregation erforderlich sind.

Ein Beispiel für ein Erstereignis siehe Get Start with App Analytics. Für das Dashboard und die zusätzlichen App-Zugriffsdaten siehe Was ist App Analytics?.

Ereignisschema

Jedes Ereignis ist ein OpenTelemetriy-Protokolleintrag, der in der otel_logs App-Tabelle im Unity-Katalog gespeichert ist. Verwenden Sie den konfigurierten Tabellennamen, einschließlich eines beliebigen Präfixes. Die Tabelle enthält außerdem weitere Protokolleinträge, daher wählen Sie Analyseereignisse nach Schema-Version und Ereignistyp aus.

Nutzlastbeispiele

Wählen Sie einen Ereignistyp, um deren Nutzlast zu sehen. Jedes Beispiel ist ein OTLP-Protokoll, der beim Export eingefügt resourceLogs[].scopeLogs[].logRecords[] wird. Der Quickstart zeigt diesen Request-Wrapper an.

Die untenstehenden IDs und der Zeitstempel sind anschaulich. Generiere für jedes neue Ereignis eine eindeutige ID und verwende dessen tatsächliche Erscheinungszeit. Die Beispiele lassen das optionale session_id.

Action

Erfassen Sie den Export eines abgeschlossenen Berichts. Die optionale format Eigenschaft beschreibt den Export, ohne den Ereignisnamen zu ändern.

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

Seitenansicht

Nimm einen Besuch bei /reportsauf. Der Veranstaltungstyp und der Name des Events sind beides.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

Zeichnen Sie eine Messung der größten Contentful Paint (LCP) von 1.800 Millisekunden auf. Dieser Wert hat eine Bewertung 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" } }
  ]
}

Berichte für dieselbe Messung teilen sich ein web_vital.sample_id. Jeder neue Bericht hat seinen eigenen event.id. Siehe Web Vital Regeln.

Allgemeine Felder

Die folgenden logischen Felder gelten für alle Ereignistypen. Ihre OTLP-Attributnamen erscheinen in den obigen Beispielen.

session_id im Ereignisschema optional ist. Sitzungsbasierte Kennzahlen verwenden die Datensätze, die sie liefern. Erfinde keine Identität und benutze keinen leeren String, um eine abwesende Sitzung darzustellen.

Erforderliche Zeichenketten dürfen nicht leer sein und dürfen keine Leerzeichen, keine Zugangsdaten oder personenbezogene Daten enthalten. Wenn ein optionales Feld vorhanden ist, muss es seinen Feldregeln entsprechen. Ein fehlendes optionales Attribut liest sich im logischen Schema als null.

Ereignistypen

Eine aufgenommene Aktion beschreibt, was der Produzent aufgenommen hat. Zum Beispiel kann ein Klick die Absicht aufzeichnen, ohne zu beweisen, dass die Operation erfolgreich war.

OTLP-Codierung und Tabellenfelder

Analytische Attribute verwenden den Namensraum databricks.app.analytics. . Die folgende Tabelle bildet die logischen Felder auf OTLP und die Telemetrietabelle zu:

Verwenden Sie die folgenden OTLP-JSON-Kodierungen:

• Zeitstempel: Eine Dezimalkette von Unix-Nanosekunden in timeUnixNano.
• Ganze Zahlen: Eine Dezimalzeichenkette intValue, wie { "intValue": "1" }.
• Doubles: Eine numerische doubleValue, wie .{ "doubleValue": 1.25 }
• Streicher: stringValue.
• Booleans: boolValue.

Setze die Protokolleinträge eventName auf denselben Wert wie das Analytics-Attribut event_name . Die Instrumentierung scope.name identifiziert den Produzenten, ist aber kein Selektor für Analysedatensätze.

Die Telemetrietabelle kann für numerische Werte, einschließlich Null, einen Einzelfeld-Wrapper doubleValue beibehalten. Entschlüsseln Sie diesen Wrapper, bevor Sie numerische Felder validieren. Überprüfen Sie den Typ des ursprünglichen Wertes, bevor Sie ihn casten, anstatt eine numerisch aussehende Zeichenkette als Zahl zu akzeptieren.

Die physische date Spalte steht für das Ausschneiden von Partitionen zur Verfügung. Es ist nicht Teil des logischen Ereignisschemas.

Feldbeschränkungen

Desinfizieren Sie die Felder vor dem Export. Validierung und Projektion in einer Abfrage entfernen keine bereits in der Telemetrietabelle gespeicherten Rohdaten.

Aktionsnamen und Eigenschaften

Aktionsnamen enthalten 1 bis 128 Zeichen. Sie beginnen mit einem Kleinbuchstaben und verwenden Kleinbuchstaben, Ziffern, Punkte und Unterstrichen. Punkte und Unterstreichungen unterstreichen getrennte alphanumerische Segmente. Die Grammatik ist ^[a-z][a-z0-9]*([._][a-z0-9]+)*$.

Verwenden Sie stabile Namen statt Einbettungen von IDs, E-Mail-Adressen oder vom Benutzer eingegebenen Text. Fügen Sie verschiedene Details in die Immobilien ein. Zum Beispiel verwenden report_exported Sie mit einer Eigenschaft format statt eines anderen Aktionsnamens für jedes Format.

Eigenschaftsschlüssel folgen derselben Grammatik. Verwenden Sie keine reservierten Namensräume oder sensiblen Segmente, einschließlich analytics, identity, session, urlstackpasswordemailpasswdusersusertelemetrysecrettokenapi_keycredentialprivate_keyiphtmlusernamedomselectorcookieauthorizationstacktracetextselectorsinput, oder .referrer Diese Einschränkungen gelten auch für Aktionsnamen.

Eigenschaften können skalare Strings, endliche Zahlen und Boolesche Werte enthalten. Arrays, verschachtelte Objekte, Nullwerte, Zugangsdaten und persönliche Daten sind nicht erlaubt.

Abfrageprojektionen lassen Eigenschaften weg, die diese Einschränkungen nicht erfüllen. Produzenten bleiben für die Bedeutung der von ihnen gesendeten Werte verantwortlich. Syntaktische Prüfungen allein können nicht feststellen, dass ein Wert nicht persönlich ist.

Seitenpfade

A beginnt mit / und enthält den Betonauftragspfadpage_path. Entferne Abfragestrings und Fragmente und bereinige sensible Pfadsegmente. Senden Sie keine Zugangsdaten, persönliche Daten oder vom Nutzer eingegebenen Text in einen Pfad.

Ein ungültiger Pfad wird aus der Abfrageprojektion weggelassen. Eine Seitenansicht ohne Pfad bleibt gültig, trägt aber nicht zu Routen-Ebene-Aggregationen bei.

Sitzungen

Eine Analysesitzung gehört zu einem Top-Level-Browserkontext. Wenn ein Produzent eine Session-ID bereitstellt, halten Sie sie stabil über clientseitige Navigation und Neuladen hinweg und erneuern Sie sie nach 30 Minuten ohne aufgezeichnetes Analyseereignis.

Sitzungs-IDs müssen undurchsichtig sein und dürfen nicht von Benutzeridentitäten, E-Mail-Adressen, IP-Adressen, Anfrage-IDs, Job-IDs oder Zugriffstoken abgeleitet werden. Backend-Ereignisse bewahren die ursprüngliche Sitzung, wenn eine verfügbar ist. Wiederholte Ereignisse behalten ihre ursprüngliche Sitzung und Ereigniszeit.

Eine Sitzung misst ein Aktivitätsfenster, nicht eine einzelne Person. Viewer-Metriken im Produkt können separate App-Zugriffsdaten verwenden.

Web-Vital-Regeln

Web Vital Events fügen die folgenden Felder hinzu. Kodieren Sie Wert und Delta als OTLP-Attribute doubleValue und die übrigen Felder als stringValue Attribute. Web-Vital-spezifische Felder müssen bei Aktionen und Seitenaufrufen fehlen.

Die folgende Tabelle definiert die Einheiten und Schwellenwerte:

LCP, INP und CLS sind Core Web Vitals. FCP und TTFB bieten zusätzliche Leistungsmessungen. Ein Wert liegt good auf oder unter der Gut-Schwelle, poor oberhalb der Schlecht-Schwelle und needs_improvement zwischen ihnen. Eine unpassende Einheit oder Bewertung macht den Eintrag ungültig.

Eine Stichprobe kann mehrere Berichte erzeugen. Web Vitals beschreiben die Dokumentnavigation. Eine Client-seitige Routenänderung kann eine Seitenansicht erzeugen, ohne eine neue Web Vital-Probe zu erstellen. Ein Server kann eine Browsermessung weiterleiten, aber Server-Timings ersetzen diese Messung nicht.

Validierungsreihenfolge

Verarbeiten Sie Datensätze in folgender Reihenfolge:

1. Wählen Sie unterstützte Schema-Versionen und Ereignistypen aus. Für dieses Schema wählen Sie Version 1 und action, page_view, oder web_vital.
2. Entschlüsseln Sie die typisierten Attribute und benötigen gültige event_id, event_name, und occurred_at Werte.
3. Validiere Ereignistyp-Felder, Namen, Einheiten, Bewertungen und Feldbeschränkungen. Schließen Sie Datensätze mit ungültig erforderlichen Feldern aus und projektiert nur optionale Daten.
4. Erkennen Sie widersprüchliche Ereignis-IDs und deduplizieren Sie identische Lieferungen.
5. Wählen Sie das Analyseintervall und beliebige Pfad- oder Ereignisfilter aus.
6. Für Web Vitals reduzieren Sie wiederholte Meldungen auf einen Bericht pro Stichprobe.
7. Aggregieren Sie die resultierenden Ereignisse oder Stichproben.

Halte die Validierung von Aufnahmediagnostiken getrennt. Das Finden einer Zeile in otel_logs stellt nicht fest, dass sie dem Ereignisschema entspricht.

Deduplizierung und Probenreduktion

Identische Zustellungen eines Ereignisses zählen als ein Ereignis. Wenn ein event_id für andere logische Ereignisinhalte wiederverwendet wird, schließen Sie jeden Datensatz aus diesem Konfliktsatz aus und melden Sie den Konflikt als Datenqualitätsproblem. Wähle keine willkürliche Lieferung aus dem Set.

Vergleichen Sie normalisierte logische Inhalte, einschließlich optionaler Felder und Eigenschaften. Verwenden Sie eine deterministische Darstellung von Eigenschaften, damit die Schlüsselordnung keine falschen Konflikte erzeugt. Transportmetadaten sind kein Teil des Inhalts des logischen Ereignisses. Wiederholte Versuche bewahren den ursprünglichen Ereigniszeitstempel.

Überprüfen Sie die Identität der gespeicherten Lieferungen für jede Kandidaten-Ereignis-ID, bevor Sie den Analysezeitraum anwenden. Das Filtern von Rohlieferungen zuerst kann widersprüchliche Inhalte außerhalb dieses Bereichs verbergen.

Nach der Deduplizierung und Auswahl des Analyseintervalls wird der neueste Bericht gemäß web_vital_sample_idbeibehalten. Die Ordnung meldet sich von occurred_at, bricht die Verbindung zu event_id, beide absteigend. Berechnen Sie die Perzentile nach dieser Reduktion.

Metrikdefinitionen

Zeitintervalle beinhalten start_time und schließen end_time. Zeitbehälter verwenden Coordinated Universal Time (UTC).

Für N geordnete Stichproben verwendet der nächstrangige p75 den Wert an Position ceil(0.75 × N), mit einbasierter Indexierung. Betrachten Sie weniger als 30 Web Vital-Proben als Hinweis und nicht als schlüssige Belege für einen Trend.

Dieses Schema definiert weder Benutzeridentität, Gerät, Browser noch geografische Dimensionen. Produktoberflächen können zusätzliche Kennzahlen aus anderen Quellen anzeigen. Insbesondere werden die eindeutigen Viewer des Dashboards nicht durch das Zählen von Analysesitzungen berechnet.

Beispiel: Berechnen Sie Web Vital p75 aus validierten Ereignissen

Die folgende Abfrage zeigt Kollisionsausschluss, Deduplizierung, Stichprobenreduktion und exakte Perzentilberechnung. Es verbraucht einen normalisierten Datensatz, nicht die Rohtabelle otel_logs .

Bereite die Eingabe vor.

Erstellen Sie eine Eingabeansicht in Ihrer eigenen Verarbeitungspipeline, die die Schritte 1 bis 3 der Validierungsreihenfolge anwendet. Die Ansicht muss folgende Daten enthalten:

• Eine Zeile pro Lieferung, die die Validierung besteht, bevor Deduplizierung oder Zeitbereichsfilterung durchgeführt wird.
• Die typisierten logischen Felder, darunter , , , event_nameevent_type, web_vital_value, und web_vital_sample_id. occurred_atevent_id
• Eine nicht-nulle logical_content Zeichenkette, die eine deterministische Darstellung aller normalisierten Ereignisfelder und Eigenschaften enthält. Stellen Sie abwesende optionale Felder konsistent dar und bewahren Sie die ursprüngliche Ereigniszeit.

Scopen Sie die Eingaben auf die App, die Sie analysieren. Beziehen Sie aufbewahrte Lieferungen aller unterstützten Ereignistypen ein, sodass die Wiederverwendung einer Ereignis-ID über verschiedene Typen hinweg erkannt wird. Die Eingabe muss alle oben beschriebenen erforderlichen Felder, numerische Typen und Bereiche, Einheiten, Bewertungen und Ereignistyp-Einschränkungen durchsetzen.

Aggregieren Sie die validierten Eingaben

Ersetze <catalog>.<schema>.<validated-events-view> sie durch deine Eingabeansicht. Setze :start_time und :end_time als Zeitstempelparameter im 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 gibt den beobachteten Wert beim gewünschten Rang zurück, anstatt eine Näherung. Die Abfrage schließt widersprüchliche Ereignis-IDs aus, bevor der Zeitbereich ausgewählt wird. Tracke IDs, deren content_count eine übersteigt, separat als Datenqualitätsfehler.

Zum Beispiel erzeugen sample_size = 3 drei reduzierte LCP-Proben mit den Werten 100, 200 und 300 Millisekunden und p75 = 300. Identische Nachlieferungen erhöhen diese Probenzahl nicht. Eine Ereignis-ID mit widersprüchlichen normalisierten Inhalten trägt keinen Datensatz bei.

Versionsverwaltung

schema_version identifiziert die Hauptvertragsversion unabhängig von den Herstellerpaketversionen.

Das Hinzufügen optionaler Felder oder anwendungsdefinierter Aktionsnamen ist abwärtskompatibel. Das Entfernen erforderlicher Felder oder das Ändern ihrer Typen, Bedeutungen, Identifikationsbereiche oder Sitzungssemantik erfordert eine grundlegende Versionsänderung. Änderungen an Deduplizierung, Sample-Reduktion oder Ereignistyp-Semantik erfordern ebenfalls eine neue Hauptversion.

Verbraucher ignorieren nicht unterstützte Versionen und Ereignistypen, anstatt sie als Aktionen zu interpretieren.

Weitere Ressourcen

• Was ist App Analytics?
• Fang mit App Analytics an
• Configure telemetry for Databricks Apps