Yoshi Yamaguchi

OpenTelemetryプロジェクトのパッケージレイアウト

この記事は英語の原文を日本語に翻訳したものです。原文: https://opentelemetry.io/docs/specs/otel/library-layout/

翻訳元: open-telemetry/opentelemetry-specification v1.60.0（コミット 29ae8c7）

このドキュメントは、OpenTelemetryプロジェクトの基本的なパッケージレイアウトの「見た目と使い勝手」を記述するためのものです。このパッケージレイアウトは意図的に汎用的なものであり、言語固有のパッケージ構造を強制しようとするものではありません。

APIパッケージ

以下は、OpenTelemetry APIパッケージの汎用的なパッケージ構造の提案です。

典型的なトップレベルのディレクトリレイアウトは次のとおりです。

api
   ├── context
   │   └── propagation
   ├── metrics
   ├── trace
   │   └── propagation
   ├── baggage
   │   └── propagation
   ├── internal
   └── logs

小文字、camelCase、snake_caseのいずれの名前を使うかは言語に依存します。

/api/context

このディレクトリは、プロセス内でのコンテキスト伝搬を提供するAPIを記述します。

/api/metrics

このディレクトリは、アプリケーションのメトリクスを記録するために使えるMetrics APIを記述します。

/api/baggage

このディレクトリは、コンテキスト伝搬とメトリクスイベントの属性を管理するために使えるBaggage APIを記述します。

/api/trace

Trace APIは、いくつかの主要なクラスから構成されます。

  • Tracerはすべての操作に使われます。Tracerの節を参照してください。
  • Spanは現在の操作の実行に関する情報を保持する、可変のオブジェクトです。Spanの節を参照してください。

/api/internal（オプション）

ユーザーに公開すべきでない、ライブラリのコンポーネントや実装です。言語にイディオマティックな内部コンポーネントのレイアウトがある場合は、その言語のイディオマティックなスタイルに従ってください。

/api/logs（将来的に）

TODO：ログの操作

SDKパッケージ

以下は、OpenTelemetry SDKパッケージの汎用的なパッケージ構造の提案です。

典型的なトップレベルのディレクトリレイアウトは次のとおりです。

sdk
   ├── context
   ├── metrics
   ├── resource
   ├── trace
   ├── baggage
   ├── internal
   └── logs

小文字、camelCase、snake_caseのいずれの名前を使うかは言語に依存します。

/sdk/context

このディレクトリは、api/contextに対するSDKの実装を記述します。

/sdk/metrics

このディレクトリは、api/metricsに対するSDKの実装を記述します。

/sdk/resource

resourceディレクトリは、主に統計情報やトレースが記録される対象のエンティティに関する情報を捕捉するResource型を定義します。例えば、Kubernetesのコンテナから公開されるメトリクスは、クラスタ、名前空間、Pod、コンテナ名を指定するリソースに結び付けられます。

/sdk/baggage

TODO

/sdk/trace

このディレクトリは、Tracing SDKの実装を記述します。

/sdk/internal（オプション）

ユーザーに公開すべきでない、ライブラリのコンポーネントや実装です。言語にイディオマティックな内部コンポーネントのレイアウトがある場合は、その言語のイディオマティックなスタイルに従ってください。

/sdk/logs（将来的に）

TODO：ログの操作