Schéma d’événements et requêtes d’App Analytics

Utilisez cette référence pour implémenter un producteur d’événements ou écrire des requêtes sur des événements App Analytics. Il définit la version 1 du schéma, son encodage OpenTelemetry Protocol (OTLP), ainsi que les étapes de traitement nécessaires avant l’agrégation.

Pour un exemple de premier événement, voir Commencer avec App Analytics. Pour le tableau de bord et ses données supplémentaires d’accès aux applications, voir Qu’est-ce que l’App Analytics ?

Schéma d’événement

Chaque événement est un enregistrement journal OpenTelemetry stocké dans la table de otel_logs l’application dans le catalogue Unity. Utilisez le nom de la table configurée, y compris n’importe quel préfixe. Le tableau contient également d’autres enregistrements de journal, donc sélectionnez les événements analytiques selon leur version de schéma et leur type d’événement.

Exemples de charge utile

Sélectionnez un type d’événement pour voir sa charge utile. Chaque exemple est un enregistrement OTLP log, placé lors resourceLogs[].scopeLogs[].logRecords[] de l’exportation. Le quickstart affiche ce wrapper de requête.

Les pièces d’identité et l’horodatage ci-dessous sont illustratives. Générez un identifiant unique pour chaque nouvel événement et utilisez son temps d’occurrence réel. Les exemples omet la fonction optionnelle session_id.

Action

Enregistrer une exportation de rapport complétée. La propriété optionnelle format décrit l’exportation sans changer le nom de l’événement.

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

mode Page

Enregistrez une visite à /reports. Le type d’événement et le nom de l’événement sont tous deux 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

Enregistrez une mesure de la plus grande peinture contente (LCP) de 1 800 millisecondes. Cette valeur a une good note.

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

Les rapports pour la même mesure partagent un web_vital.sample_id. Chaque nouveau rapport a son propre event.id. Voir les règles Web Vital.

Champs communs

Les champs logiques suivants s’appliquent à tous les types d’événements. Leurs noms d’attributs OTLP apparaissent dans les exemples ci-dessus.

session_id est optionnel dans le schéma d’événement. Les métriques basées sur les sessions utilisent les enregistrements qui les fournissent. Ne fabriquez pas d’identité ni n’utilisez une chaîne vide pour représenter une session absente.

Les chaînes obligatoires doivent être non vides et ne doivent pas contenir d’espaces blancs, d’identifiants ou de données personnelles. Lorsqu’un champ optionnel est présent, il doit se conformer à ses règles de champ. Un attribut optionnel absent se lit comme nul dans le schéma logique.

Types d’événements

Une action capturée décrit ce que le producteur a enregistré. Par exemple, un clic peut enregistrer une intention sans prouver que l’opération a réussi.

Encodage OTLP et champs de table

Les attributs analytiques utilisent cet databricks.app.analytics. espace de noms. Le tableau suivant associe les champs logiques à OTLP et à la table de télémétrie :

Utilisez les codages JSON OTLP suivants :

• Horodatages : Une chaîne décimale de nanosecondes Unix dans timeUnixNano.
• Entiers : Une chaîne intValuedécimale , telle que { "intValue": "1" }.
• Doubles : Un numérique doubleValue, tel que { "doubleValue": 1.25 }.
• Cordes : stringValue.
• Booléens : boolValue.

Fixez les enregistrements eventName de journal à la même valeur que l’attribut analytique event_name . L’instrumentation scope.name identifie le producteur, mais n’est pas un sélectionneur pour les enregistrements analytiques.

La table de télémétrie peut conserver un wrapper à champ unique doubleValue pour les valeurs numériques, y compris zéro. Décodez cet enveloppe avant de valider les champs numériques. Validez le type de la valeur originale avant de la lancer, plutôt que d’accepter une chaîne numérique comme un nombre.

La colonne physique date est disponible pour l’élagage de la partition. Ce n’est pas une partie du schéma des événements logiques.

Contraintes de champ

Désinfectez les champs avant l’exportation. La validation et la projection dans une requête ne suppriment pas les données brutes déjà stockées dans la table de télémétrie.

Noms et propriétés d’actions

Les noms des actions contiennent de 1 à 128 caractères. Ils commencent par une lettre minuscule et utilisent des lettres minuscules, des chiffres, des points et des soulignements. Points et soulignent des segments alphanumériques séparés. La grammaire est ^[a-z][a-z0-9]*([._][a-z0-9]+)*$.

Utilisez des noms d’écurie au lieu d’intégrer des identifiants, des adresses e-mail ou des textes saisis par l’utilisateur. Mettez des détails différents dans les propriétés. Par exemple, utilisez report_exported avec une format propriété plutôt qu’un nom d’action différent pour chaque format.

Les clés de propriété suivent la même grammaire. N’utilisez pas d’espaces de noms réservés ni de segments sensibles, y compris analytics, identity, sessiontelemetry, url, user, , emailusers, cookiestackpasswordpasswdsecretapi_keycredentialprivate_keyiphtmlusernamedomselectorauthorizationtokenstacktracetextselectorsinputou .referrer Ces restrictions s’appliquent également aux noms d’actions.

Les propriétés peuvent contenir des chaînes scalaires, des nombres finis et des booléens. Les tableaux, objets imbriqués, valeurs nulles, identifiants et données personnelles ne sont pas autorisés.

Les projections de requête omet des propriétés qui ne respectent pas ces contraintes. Les producteurs restent responsables du sens des valeurs qu’ils transmettent. Les contrôles syntaxiques seuls ne peuvent pas établir qu’une valeur est non personnelle.

Chemins de page

A commence par / et contient le chemin d’application page_path concret. Supprimez les chaînes de requêtes et les fragments, et aseptisez les segments de chemin sensibles. N’envoyez pas d’identifiants, de données personnelles ou de texte saisi par l’utilisateur dans un chemin.

Un chemin invalide est omis de la projection de requête. Une vue de page sans chemin reste valide, mais ne contribue pas aux agrégations au niveau de la route.

Sessions

Une session d’analyse appartient au contexte d’un navigateur de haut niveau. Lorsqu’un producteur fournit un ID de session, maintenez-le stable lors de la navigation côté client et des rechargements, puis renouvelez-le après 30 minutes sans événement d’analyse enregistré.

Les identifiants de session doivent être opaques et ne doivent pas provenir d’identités d’utilisateurs, d’adresses e-mail, d’adresses IP, d’identifiants de requête, d’identifiants de travail ou de jetons d’accès. Les événements backend conservent la session d’origine lorsqu’une est disponible. Les événements rejoués conservent leur session et leur temps d’événement d’origine.

Une session mesure une fenêtre d’activité, pas une personne unique. Les métriques de visualisation dans le produit peuvent utiliser des données d’accès à l’application séparées.

Web Vital règne

Les événements Web Vital ajoutent les champs suivants. Encodez la valeur et le delta comme attributs OTLP doubleValue , et les champs restants comme stringValue attributs. Les champs spécifiques à Web Vital doivent être absents sur les actions et les pages vues.

Le tableau suivant définit les unités et les seuils :

LCP, INP et CLS sont des signes vitaux Web de base. FCP et TTFB fournissent des mesures de performance supplémentaires. Une valeur est good au seuil de Bon ou en dessous, poor au-dessus du seuil de Pauvre, et needs_improvement entre les deux. Une unité ou une classification inadéquate rend le dossier invalide.

Un échantillon peut produire plusieurs rapports. Les signes vitaux Web décrivent la navigation dans les documents. Un changement de route côté client peut produire une page vue sans produire un nouvel échantillon Web Vital. Un serveur peut transmettre une mesure de navigateur, mais les timings du serveur ne remplaçant pas cette mesure.

Ordre de validation

Dossiers de processus dans l’ordre suivant :

1. Sélectionnez les versions de schéma prises en charge et les types d’événements. Pour ce schéma, sélectionnez version 1 et action, page_view, ou web_vital.
2. Décodez les attributs typés et nécessitent des valeurs valides event_id, event_name, et occurred_at .
3. Validez les champs de type d’événement, les noms, les unités, les notes et les contraintes de champ. Excluez les enregistrements avec des champs requis invalides et les données optionnelles autorisées uniquement par projet.
4. Détecter les identifiants d’événements conflictuels et dédupliquer les livraisons identiques.
5. Sélectionnez l’intervalle d’analyse et tout filtre de chemin ou d’événement.
6. Pour les constantes Web Vitals, réduisez les signalements répétés à un seul rapport par échantillon.
7. Agrégez les événements ou échantillons résultants.

Séparez la validation des diagnostics d’ingestion. Trouver une ligne dans otel_logs ne prouve pas qu’elle correspond au schéma d’événement.

Déduplication et réduction d’échantillon

Des livraisons identiques d’un événement comptent comme un seul événement. Si an event_id est réutilisé pour différents contenus d’événements logiques, excluez tous les enregistrements de cet ensemble de conflits et signalez le conflit comme un problème de qualité des données. Ne choisissez pas une livraison arbitraire du plateau.

Comparez le contenu logique normalisé, y compris les champs et propriétés optionnels. Utilisez une représentation déterministe des propriétés afin que l’ordre des clés ne crée pas de faux conflits. Les métadonnées de transport ne font pas partie du contenu logique des événements. Les essais conservent l’horodatage de l’événement original.

Vérifiez l’identité entre les livraisons conservées pour chaque ID d’événement candidat avant d’appliquer la plage de temps d’analyse. Filtrer d’abord les livraisons brutes peut masquer le contenu conflictuel en dehors de cette fourchette.

Après la déduplication et la sélection de l’intervalle d’analyse, conserver le dernier rapport par web_vital_sample_id. L’ordre rapporte par occurred_at, rompant les liens avec event_id, tous deux en descente. Calculez les percentiles après cette réduction.

Définitions de métriques

Les intervalles de temps incluent start_time et excluent end_time. Les intervalles temporels utilisent le temps universel coordonné (UTC).

Pour les N échantillons ordonnés, le rang le plus proche p75 utilise la valeur en position ceil(0.75 × N), avec indexation basée sur un. Considérez moins de 30 échantillons Web Vital comme des preuves indicatives plutôt que concluantes d’une tendance.

Ce schéma ne définit pas l’identité de l’utilisateur, l’appareil, le navigateur ou les dimensions géographiques. Les surfaces produit peuvent afficher des métriques supplémentaires provenant d’autres sources. En particulier, les visualiseurs uniques du tableau de bord ne sont pas calculés en comptant les sessions d’analyse.

Exemple : calculer Web Vital p75 à partir d’événements validés

La requête suivante montre l’exclusion des collisions, la déduplication, la réduction d’échantillon et le calcul exact du percentile. Il consomme un ensemble de données normalisé, pas la table brute otel_logs .

Préparez l’entrée

Créez une vue d’entrée dans votre propre pipeline de traitement qui applique les étapes 1 à 3 de l’ordre de validation. La vue doit contenir les données suivantes :

• Une ligne par livraison qui passe la validation, avant la déduplication ou le filtrage par plage de temps.
• Les champs logiques typés, incluant event_id, occurred_at, event_type, event_name, web_vital_value, et web_vital_sample_id.
• Une chaîne non nulle logical_content contenant une représentation déterministe de tous les champs et propriétés d’événements normalisés. Représenter les champs optionnels absents de manière cohérente et préserver le temps d’événement initial.

Analysez l’entrée de l’application que vous analysez. Inclure les livraisons conservées de tous les types d’événements pris en charge afin que la réutilisation d’un identifiant d’événement entre types soit détectée. L’entrée doit respecter tous les champs requis, types numériques et plages, unités, évaluations et contraintes de type d’événement décrites ci-dessus.

Agréger l’entrée validée

Remplacez-le <catalog>.<schema>.<validated-events-view> par votre vue d’entrée. Définissez :start_time et :end_time comme paramètres horodatages dans l’éditeur 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 retourne la valeur observée au rang demandé plutôt qu’une approximation. La requête exclut les identifiants d’événements conflictuels avant de sélectionner la plage de temps. Suivez les identifiants qui content_count dépassent un séparément en tant qu’erreurs de qualité des données.

Par exemple, trois échantillons de LCP réduits avec des valeurs de 100, 200 et 300 millisecondes produisent sample_size = 3 et p75 = 300. Des relivraisons identiques n’augmentent pas ce nombre d’échantillons. Un identifiant d’événement avec un contenu normalisé conflictuel ne contribue à aucun enregistrement.

Versioning

schema_version identifie la version principale sous contrat indépendamment des versions du package produit.

L’ajout de champs optionnels ou de noms d’actions définis par l’application est rétrocompatible. Supprimer les champs requis ou modifier leurs types, significations, portée d’identification ou sémantique de session nécessite un changement majeur de version. Les modifications de la déduplication, de la réduction d’échantillonnage ou de la sémantique des types d’événements nécessitent également une nouvelle version majeure.

Les consommateurs ignorent les versions et types d’événements non pris en charge au lieu de les interpréter comme des actions.

Ressources additionnelles

• Qu’est-ce que l’App Analytics ?
• Commencez avec l’App Analytics
• Configurez la télémétrie pour les applications Databricks