@opentelemetry/core編

概要

This package provides default implementations of the OpenTelemetry API for trace and metrics. It's intended for use both on the server and in the browser.

かっこいいですね。サーバーおよびブラウザどちらでも使えるトレースとメトリクスのデフォルト実装が入っているようです。

主な実装は以下の通りです：

Propagators: W3C Trace Context / W3C Baggage 準拠の伝搬実装

Time utilities: HrTime（高精度時間）の変換・計算

Attributes: 属性値のバリデーション・サニタイズ

Error handling: グローバルエラーハンドラ

Platform abstraction: Node.js/Browser両対応の環境抽象化

Utils: タイムアウト、マージ、コールバック制御など

Built-in Propagators

Readmeでは3つのPropagatorsが提供されていると書いています。

W3CTraceContextPropagator Propagator

Composite Propagator

Baggage Propagator

実際にドキュメントにもあるようにプラットフォームによってはOpenTelemetryではout-of-the-boxとして事前にPropagatorが事前構成され、デフォルトでこれらのPropagatorが設定されているべきであると書いてあります。

Platforms such as ASP.NET may pre-configure out-of-the-box propagators. If pre-configured, Propagators SHOULD default to a composite Propagator containing the W3C Trace Context Propagator and the Baggage Propagator specified in the Baggage API. These platforms MUST also allow pre-configured propagators to be disabled or overridden.

W3CTraceContextPropagator Propagator

inject

code:ts

const traceParent = `${VERSION}-${spanContext.traceId}-${

spanContext.spanId

}-0${Number(spanContext.traceFlags || TraceFlags.NONE).toString(16)}`;

extract

SpanContextから取得したTraceparent Headerがパースできない場合は例外を返さず元のContextをそのまま返すようになっています。(MUST NOT throw an exception)

parseをする関数に面白いことが書いてあります。

W3C仕様にバージョニングルールがあるそうです。

with future versions. If there are more parts, we only reject it if it's using version 00

code:md

traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01

─┬ ────────────────┬─────────────── ────────┬─────── ─┬

│ │ │ │

version(00) trace-id(32桁hex) parent-id(16桁) flags

code:ts

const TRACE_PARENT_REGEX = new RegExp(

);

拡張できるだけで現状の実装では無視されているのでparse結果からは除外されています。

CompositePropagator

複数のPropagatorを1つにまとめて使うためのものです。

code:ts

const propagator = new CompositePropagator({

propagators: [

new W3CTraceContextPropagator(), // traceparent, tracestate

new W3CBaggagePropagator(), // baggage

new B3Propagator(), // x-b3-* ヘッダー

],

});

Baggage Propagator

サービス間で任意のキー/バリューペアを伝搬するための仕組みです。トレースIDやSpanIDとは別に、ビジネスロジックで使うデータを渡せます。

code:md

baggage: key1=value1,key2=value2;metadata,key3=value3

─────┬───── ──────────┬──────── ─────┬─────

│ │ │

エントリ1 エントリ2 エントリ3

(メタデータ付き)

inject

code:ts

export function getKeyPairs(baggage: Baggage): string[] {

// include opaque metadata if provided

// NOTE: we intentionally don't URI-encode the metadata - that responsibility falls on the metadata implementation

if (value.metadata !== undefined) {

entry += BAGGAGE_PROPERTIES_SEPARATOR + value.metadata.toString();

}

return entry;

});

}

ヘッダーに載せるためにkeyparがシリアライズされます。

code:ts

export function serializeKeyPairs(keyPairs: string[]): string {

return keyPairs.reduce((hValue: string, current: string) => {

const value = `${hValue}${

hValue !== '' ? BAGGAGE_ITEMS_SEPARATOR : ''

}${current}`;

return value.length > BAGGAGE_MAX_TOTAL_LENGTH ? hValue : value;

}, '');

}

code:md

reduce処理:

"" + "a=1" = "a=1" (5文字 < 8192) → OK

"a=1" + ",b=2" = "a=1,b=2" (9文字 < 8192) → OK

"a=1,b=2" + ",c=3" = "a=1,b=2,c=3" (13文字 < 8192) → OK

...

"a=1,b=2,..." + ",huge=..." = 8300文字 > 8192 → 追加せず前の状態を返す

extract

extract側でも同様にkeypairとmetadataをデコードしパースしています。

AnchoredClockに関して

システム時刻が変更されると、Spanの開始時刻より終了時刻が前になる可能性があるのでそれに対応するために、モノトニック時計が使われます。

BindOnceFuture

シャットダウン処理等のPromise処理を一度のみ行うような設計になっています。(2回目以降は同じ結果のPromiseが返る)

まとめ

coreの実装を見ていきました、Built inのPropagatorの他に他のパッケージで使えるutil関数などたくさん定義されていました。