@opentelemetry/api編

概要

trace: Span, Tracer, TracerProvider の管理

metrics: Meter, Counter, Histogram, Gauge の管理

context: 非同期処理を跨いだコンテキストの維持

propagation: HTTP ヘッダ等へのコンテキスト inject/extract

diag: OpenTelemetry 自体のデバッグログ

複数の npm パッケージが同じ API インスタンスを共有可能

バージョン互換性チェック付き

code:ts

type OTelGlobal = {

};

code:md

globalThis (グローバルオブジェクト)

│

│

└── { version, trace, metrics, context, propagation, diag }

│

└── 各 API の Provider インスタンス

型レベルの工夫

code:ts

/**

* Symbol used to make BaggageEntryMetadata an opaque type

*/

export const baggageEntryMetadataSymbol = Symbol('BaggageEntryMetadata');

// 直接作れない

const meta: BaggageEntryMetadata = { toString: () => "foo" };

// エラー: Property '__TYPE__' is missing

// 専用関数でのみ作成可能

const meta = baggageEntryMetadataFromString("foo");

安全にAPIを扱える仕組み

SDKが存在しない場合はNOOP_CONTEXT_MANAGERが登録されることで、実際のアプリケーションの動作に影響を与えないような仕組みになっています。

code:ts

private _getContextManager(): ContextManager {

return getGlobal(API_NAME) || NOOP_CONTEXT_MANAGER;

}

code:ts

// trace

const NOOP_TRACER = new NoopTracer();

// metrics

const NOOP_METER_PROVIDER = new NoopMeterProvider();

// propagation

const NOOP_TEXT_MAP_PROPAGATOR = new NoopTextMapPropagator();

TraceAPI等の内部ではProxyTracer / ProxyTracerProviderにより、SDK が後から登録されても、既に取得した Tracer が動作する仕組みになっています。SDK未登録時はNoopTracerにフォールバックします。

code:md

1. アプリ起動時にtracer = trace.getTracer('my-app') を取得

→ ProxyTracerが返る（まだ SDK なし）

2. 後から SDK を登録: trace.setGlobalTracerProvider(provider)

→ ProxyTracerProviderにdelegateがセットされる

3. tracer.startSpan()を呼ぶ

→ ProxyTracerがdelegateから本物のTracerを取得して使用

Experimental

デフォルトでは下記のようなExceptionハンドリングの関数があり、例外時に呼び出されるようになっています。

code:ts

const defaultOnException = (e: Error, span: Span) => {

span.recordException(e);

span.setStatus({

code: SpanStatusCode.ERROR,

});

};

まとめ