App Analyticsイベントスキーマとクエリ

Important

この機能は、プライベートプレビュー段階にあります。試すには、Azure Databricks の連絡先にお問い合わせください。

このリファレンスを使ってイベントプロデューサーを実装したり、App Analyticsイベントに関するクエリを作成したりできます。スキーマバージョン1、OpenTelemetry Protocol(OTLP)エンコーディング、集約前の処理ステップを定義しています。

最初のイベント例としては、「App Analyticsで始める」をご覧ください。ダッシュボードおよびそれに関連する追加のアプリアクセスデータについては、「 App Analyticsとは何か?」をご覧ください。

イベントスキーマ

各イベントは、Unity Catalogのアプリの otel_logs テーブルに保存されたOpenTelemetryのログレコードです。設定済みのテーブル名(任意のプレフィックスも含む)を使ってください。テーブルには他のログレコードも含まれているので、分析イベントはスキーマのバージョンやイベントタイプで選択できます。

ペイロードの例

イベントタイプを選択してペイロードを確認します。各例は1つのOTLPログレコードで、エクスポート時に resourceLogs[].scopeLogs[].logRecords[] に入れられます。クイックスタートにはそのリクエストラッパーが表示されます。

以下のIDとタイムスタンプはその例を示しています。各新しいイベントごとにユニークなIDを作成し、その実際の発生時刻を使用します。例ではオプション session_idが省略されています。

Action

完了したレポートのエクスポートを記録します。オプションの format プロパティはイベント名を変えずにエクスポートを記述します。

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

ページビュー

/reportsへの訪問を記録してください。イベントの種類と名称はどちらも 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" } }
  ]
}

ウェブバイタル

最大量の含有量塗料(LCP)測定を1,800ミリ秒記録してください。この値は 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" } }
  ]
}

同じ測定値のレポートは同じで、同じ web_vital.sample_idを共有します。新しい報告書にはそれぞれ独自の event.idがあります。ウェブバイタルルールを参照してください。

共通フィールド

以下の論理フィールドはイベントタイプに共通して適用されます。上記の例にこれらのOTLP属性名が現れます。

フィールド	タイプ	Requirement	Description
`schema_version`	`INT`	必須	メジャー契約版。 `1` を使用してください。
`event_id`	`STRING`	必須	グローバルに一意で不透明な識別子。イベントを再挑戦する際は保存してください。
`event_type`	`STRING`	必須	`action`、`page_view` または `web_vital`
`event_name`	`STRING`	必須	イベントタイプ内の低濃度名。
`occurred_at`	`TIMESTAMP`	必須	摂取した時ではなく、出来事が起きた時のことです。
`session_id`	`STRING`	Optional	分析活動ウィンドウの不透明な識別子。それは個人を特定するものではありません。
`page_path`	`STRING`	Optional	`/orders/42`のような、サニティ化された具体的なアプリパス。
`properties`	Object	Optional	アプリケーション定義のスカラー特性。

session_id イベントスキーマではオプションです。セッションベースのメトリクスは、それを提供するレコードを使用します。アイデンティティを作り上げたり、空の文字列で不在のセッションを表現したりしないでください。

必要な文字列は空でなければならず、空白、認証情報、個人データを含んではいけません。オプションフィールドが存在する場合、そのフィールドルールに準拠しなければなりません。任意の属性が欠けている場合は論理スキーマ上でnullとして読み取られます。

イベントの種類

イベントの種類	イベント名	追加フィールド
`action`	アプリケーションで定義された名前、例えば `report_exported`。	オプションプロパティはアクションを記述します。
`page_view`	`page_view`	オプションの `page_path` は訪問ルートを識別します。
`web_vital`	`lcp`、`inp`、`cls`、`fcp`、または `ttfb`	Web Vital Rulesで定義された Web Vital フィールド。

キャプチャされたアクションは、プロデューサーが記録した内容を表します。例えば、クリックは操作の成功を証明せずに意図を記録できます。

OTLPの符号化と表フィールド

アナリティクス属性は databricks.app.analytics. 名前空間を使用します。以下の表は論理フィールドをOTLPおよびテレメトリーテーブルにマッピングしています:

論理体	OTLPの出典	`otel_logs` 出典
`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>`	対応するキーは `attributes`。
`web_vital_<field>`	`databricks.app.analytics.web_vital.<field>`	対応するキーは `attributes`。

以下のOTLPのJSONエンコーディングを使用します:

タイムスタンプ:Unixのナノ秒単位の小数列 timeUnixNano。
整数:{ "intValue": "1" }のような小数列intValue。
ダブル:{ "doubleValue": 1.25 }のような数値のdoubleValue。
弦楽器: stringValue。
ブール値: boolValue。

ログレコードの eventName を分析 event_name 属性と同じ値に設定してください。計測 scope.name は生産者を識別しますが、分析記録の選択器ではありません。

テレメトリーテーブルは、ゼロを含む数値に対して単一フィールドの doubleValue ラッパーを保持することができます。数値フィールドを検証する前にラッパーをデコードしてください。数値に見える文字列を数字として受け入れるのではなく、元の値の型を検証してキャストしてください。

物理的な date カラムはパーティション剪定に利用可能です。それは論理的なイベントスキーマの一部ではありません。

場の制約

輸出前にフィールドを消毒してください。クエリでの検証や投影は、テレメトリーテーブルにすでに保存されている生データを削除するものではありません。

アクション名とプロパティ

アクション名は1文字から128文字まであります。これらは小文字で始まり、小文字、数字、点、アンダースコアを使用します。点と下線は英数字の区間を別々に示します。文法はとても ^[a-z][a-z0-9]*([._][a-z0-9]+)*$。

IDやメールアドレス、ユーザーが入力したテキストを埋め込む代わりに、安定名を使いましょう。物件にさまざまな詳細を入れましょう。例えば、各フォーマットごとに異なるアクション名ではなく、formatプロパティを持つreport_exportedを使うことなどです。

プロパティキーも同じ文法に従います。予約された名前空間やセンシティブセグメントは使わないでください。 analytics、 identity、 session、 telemetry、 url、 user、 users、 email、 password、 passwd、 secret、 token、 authorization、 cookie、 username、 ip、 credential、 api_key、 private_key、 html、 dom、 selector、 selectors、 stack、 stacktrace、 text、 input、または referrerなどです。これらの制限はアクション名にも適用されます。

プロパティにはスカラー文字列、有限数、ブール値などが含まれます。配列、入れ子オブジェクト、null値、認証情報、個人データは許可されていません。

Limit	Value
事象ごとの性質	50
プロパティキー長	128 文字
文字列値長	1,024 文字

クエリ射影はこれらの制約を満たさない性質を省略します。生産者は、自分たちが送る価値観の意味に責任を持ち続けます。統語チェックだけでは値が非個人的であることを証明することはできません。

ページパス

page_pathは/で始まり、具体的な適用経路を含みます。クエリ文字列やフラグメントを削除し、機密パスセグメントをサニタイズします。認証情報、個人情報、ユーザーが入力したテキストをパスに送らないでください。

無効なパスはクエリの投影から省略されます。パスのないページビューは有効ですが、ルートレベルの集約には寄与しません。

Sessions

分析セッションはトップレベルのブラウザコンテキストに属します。プロデューサーがセッションIDを提供した場合は、クライアント側のナビゲーションやリロードで安定させ、30分後に記録された分析イベントなしで更新してください。

セッションIDは不透明でなければならず、ユーザーID、メールアドレス、IPアドレス、リクエストID、ジョブID、アクセストークンから派生してはなりません。バックエンドイベントは、利用可能な発生セッションを保持します。再プレイイベントは元のセッションとイベント時間を保持します。

セッションは活動のウィンドウを測定するものであって、特定の人物を測定するものではありません。製品内のビューワー指標は別個のアプリアクセスデータを利用できます。

ウェブ重要ルール

Web Vital Eventsには以下の項目が追加されます。値とデルタをOTLP doubleValue 属性としてエンコードし、残りのフィールドを stringValue 属性としてエンコードします。アクションやページビューには、Webバイタル固有のフィールドは不要でなければなりません。

フィールド	Requirement	Description
`web_vital_value`	必須	サンプルの有限で負のない累積価値。
`web_vital_unit`	必須	`ms` または計量によって決まるもの `score`。
`web_vital_delta`	必須	前回の報告からは有限でマイナスではない変化です。
`web_vital_sample_id`	必須	1つのサンプルに対して、レポートで共有されるグローバルな一意識別子。
`web_vital_rating`	必須	`good`、 `needs_improvement`、または `poor`は、値とメトリックの閾値から導き出されます。
`web_vital_navigation_type`	Optional	`navigate`、 `reload`、 `back_forward`、 `back_forward_cache`、 `prerender`、または `restore`。

以下の表は単位と閾値を定義しています:

Metric	Name	単位	よし	悪い
`lcp`	最大のコンテンツフルペイント (LCP)	`ms`	≤ 2,500	> 4,000
`inp`	次のペイントへの相互作用 (INP)	`ms`	≤ 200	> 500
`cls`	累積レイアウトシフト (CLS)	`score`	≤ 0.1	> 0.25
`fcp`	ファースト・コンテントフル・ペイント(FCP)	`ms`	≤ 1,800	> 3,000
`ttfb`	最初のバイトまでの時間(TTFB)	`ms`	≤ 800	> 1,800

LCP、INP、CLSはコアウェブバイタルです。 FCPとTTFBは追加の性能測定を提供します。値は「良い」閾値以下、poor「貧」閾値以上、その間needs_improvementgoodします。単位や評価が不一致すると記録は無効になります。

サンプルは複数のレポートを作成することができます。ウェブバイタルはドキュメントのナビゲーションを説明します。クライアント側のルート変更は、新しいWeb Vitalサンプルを生成せずにページビューを生成できます。サーバーはブラウザの測定値を転送できますが、サーバーのタイミングはその測定の代わりにはなりません。

検証順序

プロセスレコードは以下の順に以下の通りです:

サポートされるスキーマバージョンとイベントタイプを選択します。このスキーマでは、バージョン 1 と action、 page_view、または web_vitalを選択します。
型付けられた属性をデコードし、有効な event_id、 event_name、 occurred_at の値が必要です。
イベントタイプのフィールド、名前、単位、評価、フィールド制約を検証します。無効な必須欄やプロジェクトのみ許可された任意のデータを含むレコードを除外します。
競合するイベントIDを検出し、同一の配信を重複化しません。
解析区間と任意の経路またはイベントフィルターを選択します。
ウェブバイタルについては、繰り返し報告をサンプルごとに1回に減らしましょう。
得られた出来事やサンプルを集約します。

検証は摂取診断とは分けて行ってください。 otel_logsの行を見つけたからといって、それがイベントスキーマに合致しているとは限りません。

重複除去とサンプル削減

同じイベントの配信は1つのイベントとしてカウントされます。 event_idが異なる論理イベントコンテンツに再利用された場合、その競合セット内のすべてのレコードを除外し、その競合をデータ品質の問題として報告します。セットから適当な配達品を選ばないでください。

オプションフィールドやプロパティを含む正規化された論理コンテンツを比較します。キーの順序が誤った競合を生じないように、プロパティの決定論的な表現を用いましょう。トランスポートメタデータは論理イベントコンテンツの一部ではありません。リトライは元のイベントタイムスタンプを保持します。

分析時間範囲を適用する前に、各候補イベントIDのリテイムドリデリー全体で識別を確認してください。生の配信を先にフィルタリングすることで、その範囲外の矛盾するコンテンツを隠すことができます。

重複除去と分析間隔の選択後、 web_vital_sample_idごとの最新レポートを保持してください。 occurred_atごとに命令報告を行い、event_idとの関係を断ち、両者とも降りていく。この減少後のパーセンタイルを計算してください。

測定基準の定義

時間間隔は start_time と除外 end_timeが含まれます。タイムバケットは協調ユニバーサル時(UTC)を使用しています。

Metric	Definition
ページビュー	重複 `page_view` のイベント数。
Sessions	選択された分析イベントの中に異なる、nullでない `session_id` 値の数。
追跡行動	重複 `action` のイベント数。
セッションあたりのページ数	ページビューはセッション数で分けられます。セッション数がゼロの場合は価値がありません。
上位のアクション	アクションは `event_name`ごとにまとめられています。
トップページ	ページビューは `page_path`ごとにグループ化されており、抜けたパスは除外されます。
ウェブバイタル p75	事象の重複除去およびサンプル削減後の最も近い75パーセンタイル。
ウェブバイタルサンプルサイズ	還元後のサンプル数。
最新の出来事	選ばれた分析イベントの中で最も優れた `occurred_at` 。

N順序付けられたサンプルの場合、最近ランクp75は位置ceil(0.75 × N)の値を使い、1ベースのインデックス付けを用います。 30件未満のWeb Vitalサンプルは、傾向の決定的な証拠ではなく指標的なものとして扱う。

このスキーマはユーザーのアイデンティティ、デバイス、ブラウザ、地理的次元を定義していません。製品表面は他のソースからの追加の指標を表示することができます。特に、ダッシュボードのユニークビューアは分析セッション数をカウントして計算されるわけではありません。

例:検証済みイベントからWeb Vital p75を計算します

以下のクエリは、衝突排除、重複除去、サンプル削減、そして正確なパーセンタイル計算を示しています。正規化されたデータセットを消費し、生の otel_logs テーブルを消費しません。

入力を準備してください

自分の処理パイプラインに入力ビューを作成し、検証順のステップ1から3までを適用します。ビューには以下のデータが含まれていなければなりません:

検証を通過した1行のデリバリーで、重複除去やタイムレンジフィルタリングの前に行を割り当てます。
event_id、occurred_at、event_type、、event_name、web_vital_value、web_vital_sample_idを含む型付き論理フィールドです。
すべての正規化されたイベントフィールドとプロパティの決定論的表現を含む非ヌル logical_content 文字列。欠如するオプションフィールドを一貫して表現し、元のイベント時間を保持します。

分析しているアプリの入力範囲を絞り込みます。すべてのサポートされているイベントタイプの保持された配信を含め、タイプ間でのイベントIDの再利用を検出します。入力は、上記のすべての必要フィールド、数値の種類や範囲、単位、評価、イベント型制約を強制しなければなりません。

Important

この入力ビューはアプリのテレメトリを有効にして作成されるものではありません。これはあなたの処理パイプラインが提供する前提条件です。いくつかの生の属性を付与するだけでは、この検証ステップの代わりにはなりません。

検証済みの入力を集約する

<catalog>.<schema>.<validated-events-view>入力ビューに置き換えてください。 SQLエディタで :start_time と :end_time をタイムスタンプパラメータとして設定します。

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 近似ではなく、要求されたランクで観測値を返します。クエリは時間範囲を選択する前に競合するイベントIDを除外します。 1を超える content_count IDは個別にデータ品質エラーとして追跡します。

例えば、100ミリ秒、200ミリ秒、300ミリ秒の縮小LCPサンプルを3つ組み合わせると、 sample_size = 3 と p75 = 300が得られます。同じ再配達でもサンプル数は増えません。正規化されたコンテンツが矛盾するイベントIDは記録を残しません。

Versioning

schema_version プロデューサーパッケージのバージョンとは独立してメジャー契約バージョンを識別します。

オプションフィールドやアプリケーション定義のアクション名の追加は後方互換性があります。必須フィールドの削除や型、意味、識別子のスコープ、セッションの意味の変更には大規模なバージョン変更が必要です。重複除去、サンプル削減、イベントタイプの意味論の変更も新たなメジャーバージョンを必要とします。

消費者はサポートされていないバージョンやイベントタイプを無視し、それらをアクションとして解釈しません。

その他のリソース

フィードバック

このページはお役に立ちましたか?

最終更新: 2026-09-30

App Analyticsイベントスキーマとクエリ

イベント スキーマ

ペイロードの例

Action

ページ ビュー

ウェブバイタル

共通フィールド

イベントの種類

OTLPの符号化と表フィールド

場の制約

アクション名とプロパティ

ページパス

Sessions

ウェブ重要ルール

検証順序

重複除去とサンプル削減

測定基準の定義

例:検証済みイベントからWeb Vital p75を計算します

入力を準備してください

検証済みの入力を集約する

Versioning

その他のリソース

フィードバック

その他のリソース

イベントスキーマ

ページビュー