Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Important
Dieses Feature befindet sich in der privaten Vorschauphase. Wenden Sie sich an Ihren Azure Databricks-Kontakt, um es zu testen.
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.
| Feld | Typ | Anforderung | Description |
|---|---|---|---|
schema_version |
INT |
Erforderlich | Große Vertragsversion. Verwenden Sie 1. |
event_id |
STRING |
Erforderlich | Weltweit eindeutige, undurchsichtige Kennung. Bewahre es auf, wenn du ein Ereignis erneut versuchst. |
event_type |
STRING |
Erforderlich |
action, page_view oder web_vital. |
event_name |
STRING |
Erforderlich | Ein Name mit niedriger Kardinalität innerhalb des Ereignistyps. |
occurred_at |
TIMESTAMP |
Erforderlich | Wann das Ereignis stattfand, nicht als es verschluckt wurde. |
session_id |
STRING |
Fakultativ | Ein undurchsichtiger Identifikator für ein Analyseaktivitätsfenster. Es identifiziert keine Person. |
page_path |
STRING |
Fakultativ | Ein desinfizierter Beton-App-Weg, wie zum Beispiel /orders/42. |
properties |
Objekt | Fakultativ | Anwendungsdefinierte skalare Eigenschaften. |
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
| Ereignistyp | Ereignisname | Zusätzliche Felder |
|---|---|---|
action |
Ein anwendungsdefinierter Name, wie zum Beispiel report_exported. |
Optionale Eigenschaften beschreiben die Aktion. |
page_view |
page_view |
Eine optionale page_path Route identifiziert die besuchte Route. |
web_vital |
lcp, inp, cls, fcp oder ttfb |
Die Web Vital Felder sind in den Web Vital Regeln definiert. |
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:
| Logisches Feld | OTLP-Quelle |
otel_logs Quelle |
|---|---|---|
occurred_at |
timeUnixNano |
time |
schema_version |
databricks.app.analytics.schema.version |
attributes:["databricks.app.analytics.schema.version"] |
event_id |
databricks.app.analytics.event.id |
attributes:["databricks.app.analytics.event.id"] |
event_type |
databricks.app.analytics.event.type |
attributes:["databricks.app.analytics.event.type"] |
event_name |
databricks.app.analytics.event.name |
attributes:["databricks.app.analytics.event.name"] |
session_id |
databricks.app.analytics.session.id |
attributes:["databricks.app.analytics.session.id"] |
page_path |
databricks.app.analytics.page.path |
attributes:["databricks.app.analytics.page.path"] |
properties.<key> |
databricks.app.analytics.properties.<key> |
Der entsprechende Schlüssel in attributes. |
web_vital_<field> |
databricks.app.analytics.web_vital.<field> |
Der entsprechende Schlüssel in attributes. |
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.
| Limit | Wert |
|---|---|
| Immobilien pro Ereignis | 50 |
| Eigenschaftsschlüssellänge | 128 Zeichen |
| Zeichenwertlänge | 1.024 Zeichen |
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.
| Feld | Anforderung | Description |
|---|---|---|
web_vital_value |
Erforderlich | Endlicher, nichtnegativer kumulativer Wert für die Stichprobe. |
web_vital_unit |
Erforderlich |
ms oder score, bestimmt durch die Metrik. |
web_vital_delta |
Erforderlich | Endliche, nicht-negative Veränderung seit dem vorherigen Bericht. |
web_vital_sample_id |
Erforderlich | Weltweit eindeutige Identifikator, die von Berichten für eine Stichprobe geteilt wird. |
web_vital_rating |
Erforderlich |
good, needs_improvement, oder poor, abgeleitet aus dem Wert und den metrischen Schwellenwerten. |
web_vital_navigation_type |
Fakultativ |
navigate, reload, back_forward, back_forward_cache, , prerenderoder restore. |
Die folgende Tabelle definiert die Einheiten und Schwellenwerte:
| Metric | Name | Einheit | Gut | Schlecht |
|---|---|---|---|---|
lcp |
Größter inhaltsbehafteter Paint (LCP) | ms |
≤ 2.500 | > 4,000 |
inp |
Interaktion mit nächstem Paint (INP) | ms |
≤ 200 | > 500 |
cls |
Kumulative Layoutverschiebung (CLS) | score |
≤ 0.1 | > 0.25 |
fcp |
Erste Contentful Paint (FCP) | ms |
≤ 1.800 | > 3,000 |
ttfb |
Zeit zum ersten Byte (TTFB) | ms |
≤ 800 | > 1,800 |
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:
- Wählen Sie unterstützte Schema-Versionen und Ereignistypen aus. Für dieses Schema wählen Sie Version
1undaction,page_view, oderweb_vital. - Entschlüsseln Sie die typisierten Attribute und benötigen gültige
event_id,event_name, undoccurred_atWerte. - 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.
- Erkennen Sie widersprüchliche Ereignis-IDs und deduplizieren Sie identische Lieferungen.
- Wählen Sie das Analyseintervall und beliebige Pfad- oder Ereignisfilter aus.
- Für Web Vitals reduzieren Sie wiederholte Meldungen auf einen Bericht pro Stichprobe.
- 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).
| Metric | Definition |
|---|---|
| Seitenaufrufe | Anzahl der deduplizierten page_view Ereignisse. |
| Sitzungen | Anzahl der verschiedenen, nicht-nullen session_id Werte unter den ausgewählten Analyseereignissen. |
| Erfasste Aktionen | Anzahl der deduplizierten action Ereignisse. |
| Seiten pro Sitzung | Seitenaufrufe nach Sitzungen unterteilt. Kein Wert, wenn die Anzahl der Sitzungen null ist. |
| Wichtigste Aktionen | Aktionen gruppiert nach event_name. |
| Topseiten | Seitenaufrufe gruppiert nach page_path, ohne fehlende Pfade. |
| Web Vital S. 75 | Nächstplatzierter 75. Perzentil nach Event-Deduplizierung und Stichprobenreduktion. |
| Web Vital Stichprobengröße | Anzahl der unterschiedlichen Proben nach der Reduktion. |
| Neueste Veranstaltung | Am besten occurred_at unter den ausgewählten Analytics-Events. |
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, undweb_vital_sample_id.occurred_atevent_id - Eine nicht-nulle
logical_contentZeichenkette, 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.
Important
Diese Eingabeansicht wird nicht durch Aktivierung der App-Telemetrie erstellt. Sie ist eine Voraussetzung, die von Ihrer Verarbeitungspipeline bereitgestellt wird. Das Casten einiger roher Attribute ist kein Ersatz für diesen Validierungsschritt.
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.