otel-go

Go における OpenTelemetry

Go サービスにおける OpenTelemetry の仕組みを調べるためのエントリーポイントです。タスクに応じて、以下のリファレンスを参照してください。各リファレンスは単独で利用できます。

リファレンス

ファイル	参照する場面
references/declarative-setup.md	otelconf と YAML による SDK の設定：プロバイダー、プロパゲーター、シャットダウン、環境変数の置換。
references/api.md	インポートパス、グローバル API へのアクセス、トレーサー／メーター／ロガーの使い方、属性、プロパゲーション、ログブリッジ（zap、slog）を調べるとき。
references/instrumentation-libraries.md	contrib ライブラリ（otelhttp、otelgrpc、データベース、AWS、メッセージキュー、プロパゲーター、リソース検出器）の選定や接続、および semconv に準拠した手動計装の実装。
references/performance.md	サンプリング、バッチプロセッサー、メトリクスリーダー、エクスポーターの圧縮／再試行、属性の割り当て、ログの Enabled() による早期終了、グレースフルシャットダウンの調整。
references/breaking-changes.md	最近の SDK／contrib リリースにおける非推奨の呼び出し、名前が変更されたセマンティック規約、削除された API について、既存コードを監査するとき。
references/compile-time-instrumentation.md	otelc を使ったゼロコードのコンパイル時計装：使用方法（otelc go build、ツール依存関係、toolexec による置き換え）、サブコマンド、サポート対象ライブラリ、ルールの参照元／優先順位、otel.instrumentation.go によるバージョン固定。

アップグレードのレビューでは、必ず安全なローカル検証手順（go mod tidy -diff、 go build ./...、go test ./...）で締めくくってください。エクスポーターの URL や再試行の変更は、デプロイ先のエンドポイントではなく、使い捨てのローカルレシーバーに対してテストしてください。

モジュールのバージョン管理 — 依存関係を追加する前にお読みください

opentelemetry-go は、個別にバージョン管理されるモジュールグループに分かれています。各グループで同じバージョン番号を共有しているわけではありません。そうだと仮定することは、ビルドの失敗やバージョンの頻繁な変更が起きる最も一般的な原因です。

モジュールグループ	モジュールの例	バージョン系列
安定版（トレース、メトリクス、ログの API／SDK）	go.opentelemetry.io/otel、otel/sdk、otel/trace、otel/metric、otel/log、otel/sdk/log、OTLP トレース／メトリクスエクスポーター	v1.x（例：v1.47.0。ログ API／SDK は v1.47.0 で加わりました）
ログエクスポーターとテストヘルパー	otel/exporters/otlp/otlplog/otlploghttp、.../otlploggrpc、otel/exporters/stdout/stdoutlog、otel/log/logtest、otel/sdk/log/logtest	v0.x（独立した、より小さいバージョン系列。例：v0.23.0）
contrib 計装	contrib/instrumentation/net/http/otelhttp、.../otelgrpc	v0.x（独立したバージョン系列。例：v0.72.0）
contrib ログブリッジ	contrib/bridges/otelslog、otelzap、otellogrus、otellogr	v0.x

落とし穴： すべてのモジュールをコアのバージョンに固定すると（例：go get go.opentelemetry.io/otel/exporters/otlp/otlplog/[email protected]）、失敗します。ログエクスポーター、ログテストヘルパー、ブリッジの各モジュールには v1.x のタグがありません。各 @vX を手作業で選んで何度も見直すのは、避けるべきバージョン変更の繰り返しです。

代わりに、次のようにしてください — 各モジュールを @latest で追加し、Go に互換性のある組み合わせを解決させます。

go get go.opentelemetry.io/otel@latest go.opentelemetry.io/otel/sdk@latest
# logs (API/SDK are v1.x; log exporters stay on a v0.x line — do NOT force the core version):
go get go.opentelemetry.io/otel/log@latest go.opentelemetry.io/otel/sdk/log@latest \
       go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploghttp@latest
# contrib (instrumentation and bridges each resolve to their own v0.x line):
go get go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp@latest \
       go.opentelemetry.io/contrib/bridges/otelslog@latest
go mod tidy && go build ./...

正確なバージョンが必要な場合は、各モジュールグループ固有のソースからタグを取得してください（以下を参照）。あるグループのバージョンから別のグループのバージョンを推測してはいけません。

信頼できる情報源

YAML スキーマの詳細については、otel-declarative-config スキルに記載されている上流の情報源を取得してください。 Go 固有の情報については、以下を参照してください。

情報	取得方法
最新の go.opentelemetry.io/otel コアリリース	gh api repos/open-telemetry/opentelemetry-go/releases/latest -q '.tag_name'
最新の go.opentelemetry.io/contrib リリース	gh api repos/open-telemetry/opentelemetry-go-contrib/releases/latest -q '.tag_name'
最新の otelconf モジュールタグ	以下の表にある、バージョン順に並べ替えるタグコマンド
最新の Go semconv パッケージ	選択したコアリリースの CHANGELOG で Add the go.opentelemetry.io/otel/semconv/ を検索してください。上流の semantic-conventions リリースからパッケージの提供状況を推測しないでください。オフラインの場合：otel v1.47.0 の semconv/v1.43.0（2026-10-25 に確認。記録：otel-semantic-conventions スキルの references/sdk-semconv-packages.md）。
otel-go CHANGELOG	WebFetch https://raw.githubusercontent.com/open-telemetry/opentelemetry-go/main/CHANGELOG.md
otel-go-contrib CHANGELOG	WebFetch https://raw.githubusercontent.com/open-telemetry/opentelemetry-go-contrib/main/CHANGELOG.md

gh api repos/open-telemetry/opentelemetry-go-contrib/git/matching-refs/tags/otelconf -q '.[].ref' | sort -V | tail -1

相互参照

• スキーマレベルの情報：otel-declarative-config スキル（言語に依存しない YAML スキーマの情報源）。
• 言語間での SDK バージョンの選択：otel-sdk-versions スキル。
• セマンティック規約の検索：otel-semantic-conventions スキル。