メインコンテンツまでスキップ

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固有のフィールドが追加されています。

フィールド

説明

ソース

record_id

一意の識別と時間順ソートのための、システム生成ID。

時間に基づいて生成されます

time

Unixエポックからのマイクロ秒単位のタイムスタンプ。

start_time_unix_nano(スパン)またはtime_unix_nano(Logs、メトリクス)から取得されたTimestamp(マイクロ秒単位)。time_unix_nanoのないLogsレコードの場合、observed_time_unix_nanoが使用されます。

date

日付パーティション列は、効率的な時間範囲フィルタリングに使用されます。

由来 time

service_name

OTelセマンティック規約で定義されているサービス名による効率的なフィルタリングのための最上位列。

から抽出 resource.attributes["service.name"]

フィールド

説明

ソース

record_id

一意の識別と時間順ソートのための、システム生成ID。

時間に基づいて生成されます

time

Unixエポックからのマイクロ秒単位のタイムスタンプ。

start_time_unix_nano(スパン)またはtime_unix_nano(Logs、メトリクス)から取得されたTimestamp(マイクロ秒単位)。time_unix_nanoのないLogsレコードの場合、observed_time_unix_nanoが使用されます。

date

日付パーティション列は、効率的な時間範囲フィルタリングに使用されます。

由来 time

service_name

OTelセマンティック規約で定義されているサービス名による効率的なフィルタリングのための最上位列。

から抽出 resource.attributes["service.name"]

数値の精度と符号付き型​

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_value

String

bool_value

Boolean

int_value

Integer

double_value

Double型。NaN、正の無限大、負の無限大は、文字列 "NaN"、"Infinity"、"-Infinity" として保存されます。

array_value

Array

kvlist_value

オブジェクト

bytes_value

小文字の16進数エンコード文字列。たとえば、バイト0x01 0xFFは"01ff"として格納されます。

OTLP値タイプ

保存形式

string_value

String

bool_value

Boolean

int_value

Integer

double_value

Double型。NaN、正の無限大、負の無限大は、文字列 "NaN"、"Infinity"、"-Infinity" として保存されます。

array_value

Array

kvlist_value

オブジェクト

bytes_value

小文字の16進数エンコード文字列。たとえば、バイト0x01 0xFFは"01ff"として格納されます。

同じテキストを保持する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 エンコーディングを参照してください。

次のステップ​