Schemat zdarzeń i zapytania dotyczące App Analytics

Wykorzystaj to odniesienie do implementacji generatora zdarzeń lub pisania zapytań nad zdarzeniami App Analytics. Definiuje schemat w wersji 1, kodowanie protokołu OpenTelemetry Protocol (OTLP) oraz kroki przetwarzania potrzebne przed agregacją.

Dla przykładu pierwszego zdarzenia zobacz: Zacznij z analityką aplikacji. Panel nawigacyjny i jego dodatkowe dane dotyczące dostępu do aplikacji znajdziesz w artykule Czym jest App Analytics?.

Schemat zdarzeń

Każde zdarzenie to zapis dziennika OpenTelemetry przechowywany otel_logs w tabeli aplikacji w Unity Catalog. Użyj skonfigurowanej nazwy tabeli, w tym dowolnego prefiksu. Tabela zawiera także inne rekordy logów, więc wybieramy zdarzenia analityczne według wersji schematu i typu zdarzenia.

Przykłady ładunku

Wybierz typ zdarzenia, aby zobaczyć jego ładunek. Każdy przykład to jeden rekord logu OTLP, umieszczony resourceLogs[].scopeLogs[].logRecords[] podczas eksportu. Quickstart pokazuje ten wrapper żądań.

Poniższe identyfikatory i znacznik czasu są ilustracyjne. Generuj unikalny identyfikator dla każdego nowego zdarzenia i używaj jego rzeczywistego czasu wystąpienia. Przykłady pomijają opcjonalne session_id.

Działania

Zapisz zakończony raport eksportu. Opcjonalna właściwość format opisuje eksport bez zmiany nazwy zdarzenia.

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

widok strony

Nagraj wizytę w /reports. Typ zdarzenia i nazwa zdarzenia to oba .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

Zarejestruj pomiar największej ilości treści farby (LCP) wynoszący 1 800 milisekund. Ta wartość ma swoją kategorię 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" } }
  ]
}

Raporty dla tego samego pomiaru dzielą .web_vital.sample_id Każdy nowy raport ma swoje własne event.id. Zobacz zasady Web Vital.

Typowe pola

Poniższe pola logiczne mają zastosowanie w różnych typach zdarzeń. Ich nazwy atrybutów OTLP pojawiają się w powyższych przykładach.

session_id jest opcjonalny w schemacie zdarzeń. Metryki oparte na sesjach wykorzystują dokumenty, które je dostarczają. Nie tworz tożsamości ani nie używaj pustego ciągu do reprezentowania nieobecnej sesji.

Wymagane ciągi tekstów muszą być niepuste i nie mogą zawierać białych spacji, danych uwierzytelniających ani danych osobowych. Gdy dostępne jest opcjonalne pole, musi ono przestrzegać swoich zasad. Brak opcjonalnego atrybutu odczytuje się jako null w schemacie logicznym.

Typy zdarzeń

Uchwycona akcja opisuje to, co producent nagrał. Na przykład kliknięcie może zarejestrować intencję bez udowadniania, że operacja zakończyła się sukcesem.

Kodowanie OTLP i pola tabelowe

Atrybuty analityki wykorzystują databricks.app.analytics. przestrzeń nazw. Poniższa tabela odwzorowuje pola logiczne na OTLP i tablicę telemetrii:

Użyj następujących kodowań JSON OTLP:

• Znaczniki czasu: ciąg dziesiętny nanosekund Unix w timeUnixNano.
• Liczby całkowite: ciąg intValuedziesiętny, taki jak { "intValue": "1" }.
• Podwójne: Liczba doubleValue, taka jak { "doubleValue": 1.25 }.
• Smyczki: stringValue.
• Booleanie: boolValue.

Ustaw rekordy eventName logów na tę samą wartość co atrybut analityczny event_name . Instrumentacja scope.name identyfikuje producenta, ale nie jest selektorem dla rekordów analitycznych.

Tabela telemetryczna może zachować pojedynczy owijacz dla doubleValue wartości numerycznych, w tym zera. Odkoduj ten wrapper przed weryfikacją pól liczbowych. Zweryfikować typ oryginalnej wartości przed jej odrzuceniem zamiast akceptować ciąg wyglądający liczbowo jako liczbę.

Fizyczna kolumna date jest dostępna do przycinania podziałów. Nie jest częścią schematu zdarzeń logicznych.

Ograniczenia pola

Przed eksportem dezynfekuj pola. Walidacja i projekcja w zapytaniu nie usuwają surowych danych już zapisanych w tabeli telemetrycznej.

Nazwy i właściwości akcji

Nazwy akcji zawierają od 1 do 128 znaków. Zaczynają się od małej litery i używają małych liter, cyfr, kropek oraz podkreśleń. Kropki i podkreślenia oddzielają segmenty alfanumeryczne. Gramatyka to ^[a-z][a-z0-9]*([._][a-z0-9]+)*$.

Używaj nazw stabilnych zamiast osadzania identyfikatorów, adresów e-mail czy tekstów wprowadzanych przez użytkownika. Umieść różne szczegóły w nieruchomościach. Na przykład, używaj report_exported z właściwością format zamiast innej nazwy akcji dla każdego formatu.

Klucze własności podążają tą samą gramatyką. Nie używaj zarezerwowanych przestrzeni nazw ani wrażliwych segmentów, w tym analytics, identity, session, telemetry, emailstackpasswordpasswdusersuserurlsecrettokenapi_keycredentialprivate_keyiphtmlusernamedomselectorcookieauthorizationstacktracetextselectorsinputlub .referrer Te ograniczenia dotyczą także nazw akcji.

Właściwości mogą zawierać ciągi skalarne, liczby skończone oraz wartości boole'owe. Tablice, zagnieżdżone obiekty, wartości null, dane uwierzytelniające i dane osobowe nie są dozwolone.

Projekcje zapytań pomijają właściwości, które nie spełniają tych ograniczeń. Producenci pozostają odpowiedzialni za znaczenie przesłanych wartości. Same testy składniowe nie są w stanie ustalić, że wartość jest nieosobowa.

Ścieżki stron

A page_path zaczyna się od / i zawiera konkretną ścieżkę aplikacji. Usuń ciągi zapytań i fragmenty oraz oczyścić wrażliwe segmenty ścieżek. Nie wysyłaj danych danych, danych osobowych ani tekstów wpisanych przez użytkownika w ścieżce.

Nieprawidłowa ścieżka jest pomijana w projekcji zapytania. Wyświetlenie strony bez ścieżki pozostaje ważne, ale nie przyczynia się do agregacji na poziomie tras.

Sessions

Sesja analityczna należy do kontekstu przeglądarki na najwyższym poziomie. Gdy producent dostarcza identyfikator sesji, utrzymuj go stabilną w nawigacji po stronie klienta i podczas wczytywania, a następnie odnawiaj po 30 minutach bez rejestracji zdarzenia analitycznego.

Identyfikatory sesji muszą być nieprzejrzyste i nie mogą pochodzić z tożsamości użytkowników, adresów e-mail, adresów IP, identyfikatorów żądań, identyfikatorów zadań ani tokenów dostępu. Zdarzenia backendowe zachowują sesję początkową, gdy jest dostępna. Powtórzone wydarzenia zachowują oryginalny czas sesji i wydarzenia.

Sesja mierzy okno aktywności, a nie unikalną osobę. Metryki przeglądarki w produkcie mogą korzystać z oddzielnych danych dostępu do aplikacji.

Zasady internetowe

Web Vital events dodaje następujące pola. Zakoduj wartość i delta jako atrybuty OTLP doubleValue , a pozostałe pola jako stringValue atrybuty. Pola specyficzne dla Web Vital muszą być nieobecne w akcjach i odsłonach stron.

Poniższa tabela definiuje jednostki i progi:

LCP, INP i CLS to kluczowe parametry sieciowe. FCP i TTFB dostarczają dodatkowych pomiarów wydajności. Wartość znajduje się na lub poniżej good progu dobra, poor powyżej progu biednych i needs_improvement pomiędzy nimi. Niedopasowana jednostka lub ocena sprawia, że rekord jest nieważny.

Próbka może wygenerować wiele raportów. Web Vitals opisuje nawigację po dokumentach. Zmiana trasy po stronie klienta może wygenerować widok strony bez tworzenia nowej próbki Web Vital. Serwer może przesłać pomiar przeglądarkowy, ale czasy serwera nie zastępują tego pomiaru.

Kolejność walidacji

Rejestry procesów w następującej kolejności:

1. Wybierz obsługiwane wersje schematu i typy zdarzeń. Dla tego schematu należy wybrać wersję 1 i action, page_view, lub web_vital.
2. Dekoduj typowe atrybuty i wymagaj poprawnych event_id, event_name, oraz occurred_at wartości.
3. Walidacja pól, nazwy, jednostki, oceny i ograniczenia pól typu zdarzenia. Wyklucz rekordy z nieprawidłowymi polami wymaganymi i projekty zezwalają tylko na dane opcjonalne.
4. Wykrywanie konfliktowych identyfikatorów zdarzeń i deduplikowanie identycznych dostaw.
5. Wybierz interwał analizy oraz dowolne filtry ścieżek lub zdarzeń.
6. W przypadku Web Vitals ogranicz powtarzające się zgłoszenia do jednego raportu na próbkę.
7. Agreguj powstałe zdarzenia lub próbki.

Trzymaj walidację oddzielnie od diagnostyki spożycia. Znalezienie wiersza w otel_logs nie oznacza, że jest on zgodny ze schematem zdarzeń.

Deduplikacja i redukcja próbki

Identyczne dostawy wydarzenia liczą się jako jedno wydarzenie. Jeśli an event_id jest używany ponownie do innej logycznej zawartości zdarzeń, wyklucz każdy rekord z tego zestawu konfliktów i zgłoś konflikt jako problem z jakością danych. Nie wybieraj dowolnej dostawy z zestawu.

Porównaj znormalizowaną zawartość logiczną, w tym opcjonalne pola i właściwości. Użyj deterministycznej reprezentacji właściwości, aby kolejność kluczy nie powodowała fałszywych konfliktów. Metadane transportowe nie są częścią treści zdarzeń logicznych. Próby zachowują oryginalną datę czasu zdarzenia.

Sprawdź tożsamość w zachowanych dostawach dla każdego ID zdarzenia kandydata przed zastosowaniem przedziału czasowego analizy. Filtrowanie surowych dostaw może ukryć sprzeczne treści poza tym zakresem.

Po deduplikacji i wyborze przedziału analizy zachowaj najnowszy raport dla .web_vital_sample_id Raporty porządkowe przez occurred_at, przerywając remisy z event_id, oba schodzące. Po tym spadku oblicz percentyle.

Definicje metryk

Przedziały czasowe obejmują start_time i wykluczają end_time. Kubełki czasowe wykorzystują Skoordynowany Uniwersalny Czas (UTC).

Dla N uporządkowanych próbek, najbliższy rang p75 wykorzystuje wartość na pozycji ceil(0.75 × N), z indeksowaniem opartym na jedynce. Traktuj mniej niż 30 próbek Web Vital jako wyznaczające, a nie jednoznaczne dowody na trend.

Ten schemat nie definiuje tożsamości użytkownika, urządzenia, przeglądarki ani wymiarów geograficznych. Powierzchnie produktu mogą wyświetlać dodatkowe metryki z innych źródeł. W szczególności unikalni odbiorcy panelu nie są obliczani przez liczenie sesji analitycznych.

Przykład: oblicz Web Vital p75 na podstawie zweryfikowanych zdarzeń

Poniższe zapytanie demonstruje wykluczenie kolizji, deduplikację, redukcję próby oraz dokładne obliczenia percentyla. Zużywa znormalizowany zbiór danych, a nie surową otel_logs tabelę.

Przygotuj dane wejściowe

Stwórz widok wejściowy w swoim własnym potoku przetwarzania, który stosuje kroki 1 do 3 kolejności walidacji. Widok musi zawierać następujące dane:

• Jeden wiersz na każdą dostawę, który przechodzi weryfikację, przed deduplikacją lub filtrowaniem w zakresie czasu.
• Typowe pola logiczne, w tym event_id, occurred_at, event_type, event_name, web_vital_value, oraz .web_vital_sample_id
• Ciąg niebędący logical_content zerowym zawierający deterministyczną reprezentację wszystkich znormalizowanych pól zdarzeń i właściwości. Reprezentuj nieobecne pola opcjonalne konsekwentnie i zachowuj oryginalny czas zdarzenia.

Określ zakres danych wejściowych do aplikacji, którą analizujesz. Uwzględnić zachowane dostawy wszystkich obsługiwanych typów zdarzeń, aby wykryć ponowne użycie identyfikatora zdarzenia między typami. Dane wejściowe muszą wymuszać wszystkie wymagane pola, typy liczb i zakresy, jednostki, oceny oraz ograniczenia typu zdarzenia opisane powyżej.

Zagreguj zweryfikowane dane wejściowe

Zamień <catalog>.<schema>.<validated-events-view> na widok wejściowy. Ustaw :start_time i :end_time jako parametry znaczników czasu w edytorze 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 zwraca obserwowaną wartość na żądanym ranku zamiast przybliżenia. Zapytanie wyklucza sprzeczne identyfikatory zdarzeń przed wyborem zakresu czasu. Osobno śledź ID, które przewyższają content_count jeden, jako błędy jakości danych.

Na przykład trzy zredukowane próbki LCP o wartościach 100, 200 i 300 milisekund dają sample_size = 3 i p75 = 300. Identyczne ponowne dostawy nie zwiększają tej liczby próbek. ID zdarzenia z konfliktową normalizacją treści nie dostarcza żadnego zapisu.

Versioning

schema_version identyfikuje główną wersję kontraktową niezależnie od wersji pakietów producenta.

Dodawanie opcjonalnych pól lub nazw akcji definiowanych przez aplikację jest kompatybilne wstecz. Usunięcie wymaganych pól lub zmiana ich typów, znaczeń, zakresu identyfikatorów czy semantyki sesji wymaga poważnej zmiany wersji. Zmiany w deduplikacji, redukcji próbki lub semantyce typu zdarzenia również wymagają nowej wersji głównej.

Konsumenci ignorują nieobsługiwane wersje i typy zdarzeń zamiast interpretować je jako akcje.

Dodatkowe zasoby

• Czym jest App Analytics?
• Zacznij z analityką aplikacji
• Configure telemetry for Databricks Apps