Zerobus Ingest の OpenTelemetry テーブル参照
このページでは、Zerobus Ingest OTLPで使用されるOpenTelemetry(OTLP)テーブルスキーマとデータマッピングに関する参考情報を提供します。
テーブルスキーマ
OTLPデータが到着すると、Zerobus IngestはネストされたOTLP/scope/record階層の各レコードをフラットな非正規化行に変換します。 リソース属性と計測範囲情報は各行に直接埋め込まれているため、結合することなくデータを即座にクエリできます。
すべての属性フィールド (Logs の場合は attributes、 resource.attributes、 instrumentation_scope.attributes、 body、 メトリクスの場合は metadata) は、 VARIANT 列として格納されます。VARIANT は、 Delta Lake の半構造化データ型であり、元の型を保持しながら JSON データを格納します。各 OTLP 値型がどのように格納されるかについては、 Attribute values を参照してください。
各レコードには、Databricks固有のフィールドが追加されています。
フィールド | 説明 | ソース |
|---|---|---|
| 一意の識別と時間順ソートのための、システム生成ID。 | 時間に基づいて生成されます |
| Unixエポックからのマイクロ秒単位のタイムスタンプ。 |
|
| 日付パーティション列は、効率的な時間範囲フィルタリングに使用されます。 | 由来 |
| OTelセマンティック規約で定義されているサービス名による効率的なフィルタリングのための最上位列。 | から抽出 |
数値の精度と符号付き型
Deltaの型は、次の点でOTLPの型と異なります:
- 整数メトリクス値は 2^53 を超えると精度が失われます。
Gauge、Sum、およびExemplarのデータポイントで、値がas_int(64ビット整数)としてレポートされるものは、 Zerobus Ingest がすべてのメトリクス値を単一の浮動小数点数カラムに格納するため、DOUBLEに変換されます。DOUBLEは 2^53 (約9000兆)までの整数を正確に表現するため、それより大きいas_int値は変換後に正確な精度を失います。これは、累積バイト数やリクエストの合計など、非常に大きな累積カウンターで主に問題となります。 - 符号なしOTLPフィールドは符号付きとして格納されます。
INTとBIGINTはDeltaでは常に符号付きですが、OTLPでは一部の数値フィールドが符号なし (uint32、uint64、fixed64) または非常に大きな固定幅カウンターとして定義されています。*_time_unix_nano、flags、dropped_attributes_countなどのフィールドは、符号付きのINTまたはBIGINT列にそのまま格納されます。符号付き最大値 (INTの場合はi32::MAX、BIGINTの場合はi64::MAX) を超える値は、エラーにならずに負の数にラップされます。
スキーママッピング
Zerobus Ingestは、以下に説明するように、OTLPデータをDeltaテーブルの列にマッピングします。
非正規化
OTLPプロトコルでは、テレメトリデータは次のようにネストされます。
ResourceSpans (or ResourceLogs, ResourceMetrics)
└── Resource (attributes, schema_url)
└── ScopeSpans (or ScopeLogs, ScopeMetrics)
└── InstrumentationScope (name, version, attributes)
└── Span (or LogRecord, Metric)
Zerobus Ingestはこの階層構造を平坦化し、各行に完全なコンテキストが含まれるようにします。
resourceリソース属性(VARIANT)とdropped_attributes_countを含む構造体。resource_schema_url: 囲んでいる ResourceSpans、ResourceLogs、または ResourceMetrics のスキーマ URL。instrumentation_scope: スコープ名、バージョン、属性 (VARIANTとして)、およびdropped_attributes_countを含む構造体。span_schema_url/log_schema_url/metric_schema_url: 囲んでいる ScopeSpans、ScopeLogs、または ScopeMetrics のスキーマ URL。
メトリクスデータポイント
各メトリクスのデータポイントは、独自の行として格納されます。メトリクスのname、description、unit、およびmetadataが各行で繰り返され、データポイントのstart_time_unix_nanoおよびtime_unix_nanoは同じ名前のトップレベル列に格納されます。
metric_type はgauge、sum、histogram、exponential_histogram、またはsummaryです。データポイントはその名前の構造体列に格納され、他の4つの構造体列はNULLです。
属性値
属性値と Logs本体は OTLP AnyValue 値であり、次のように保存されます。
OTLP値タイプ | 保存形式 |
|---|---|
| String |
| Boolean |
| Integer |
| Double型。 |
| Array |
| オブジェクト |
| 小文字の16進数エンコード文字列。たとえば、バイト |
同じテキストを保持するstring_valueとbytes_valueを区別することはできません。元のバイト列を取得するには、unhexを使用してデコードします。たとえばunhex(attributes:['payload']::string)。
同じキーが属性リストまたはkvlist_value内に複数回出現した場合、最後のリターン値が格納されます。
IDエンコーディング
trace_id``span_id 、 parent_span_idは小文字の16進数エンコードされた文字列として格納されます。
trace_id: 32文字の16進数文字列(16バイト)span_idおよびparent_span_id: 16文字の16進文字列 (8バイト)
IDの長さが誤っているか、すべての文字がゼロである場合、そのIDは無効です。スパン自体のtrace_idとspan_idについては、拒否されたレコードを参照してください。その他の欠落しているIDおよび無効なIDは、次のように処理されます。
- 欠落または無効な
parent_span_idはNULLとして格納されるため、スパンはルートスパンとして格納されます。 - Logsレコードの
trace_idまたはspan_idが欠落しているか無効な場合はNULLとして保存され、Logsレコードが取り込まれます。 - スパンLinkとエグザンプラーの
trace_idとspan_idは、検証せず、受信したままの状態で16進数エンコードされて保存されます。
列挙型エンコーディング
kind``status.code、severity_number は、OTLP仕様で定義されているように、その文字列名として格納されます。例えば SPAN_KIND_SERVER、STATUS_CODE_OK、SEVERITY_NUMBER_INFO です。OTLP仕様で定義されていない値は、その番号として格納されます。例えば 42 です。
aggregation_temporality AGGREGATION_TEMPORALITY_ プレフィックスなしで、 DELTA または CUMULATIVE として保存されます。
拒否されたレコード
Zerobus Ingestは、次のチェックのいずれかに失敗したレコードを拒否します。拒否されたレコードの報告方法については、 部分的な成功を参照してください。
次の場合、スパンは拒否されます:
trace_idまたはspan_idが欠落しているか、 無効です。start_time_unix_nanoが見つかりません。
メトリクスデータポイントは、以下の場合に拒否されます。
- そのメトリクスには
nameがないか、OTLP 仕様で定義されていないaggregation_temporality値があります。メトリクスのデータポイントがすべて拒否されます。 time_unix_nanoが欠落しているか、 0です。- ゲージまたは合計データポイントに値がありません。
- ヒストグラムのデータポイントには
explicit_boundsはありますがbucket_countsがありません。またはbucket_countsの数がexplicit_boundsの数に 1 を足したものではないか、bucket_countsの合計がcountになっていません。 - 指数ヒストグラムのデータポイントには、正のバケットカウント、負のバケットカウント、および合計が
countにならないzero_countが含まれています。 - ヒストグラム、指数ヒストグラム、または要約データポイントの
countが 0 で、sumが 0 以外になっています。
NO_RECORDED_VALUEフラグが設定されているデータポイントは、値、count、sum、およびバケットチェックをスキップします。
Logsレコードは、コンテンツが理由で拒否されることはありません。Logsレコードの欠落または無効な ID がどのように格納されるかについては、ID エンコーディングを参照してください。
次のステップ
- OpenTelemetry (OTLP) クライアントを設定してデータをUnity Catalogに送信する: OpenTelemetry SDKまたは Collector を設定してトレース、ログ、およびメトリクスを Zerobus Ingest に送信する。
- OpenTelemetry データのクエリ: テレメトリデータを探索するための SQL クエリの例。
- Zerobus Ingestのエラー処理:一般的なエラーとエラーコードのトラブルシューティング。
- Zerobus Ingest クォータ:Zerobus Ingest の throughput および保持制限を確認します。