opentelemetry-instrumentation

Coralogix 向け OpenTelemetry SDK インストルメンテーション

このスキルを使用するタイミング

ユースケース	対応方法
言語を選択する／どこから始めるかを決める	まず language-selector.md を読み込みます。言語、シグナル、モード、エクスポート経路を選ぶための判断ツリーが記載されています
特定の言語向けにセットアップを生成する	SDK を確認してから、該当する言語リファレンスを読み込みます：java.md、python.md、nodejs.md、dotnet.md、go.md
OTLP エンドポイント、リージョン、または認証を設定する	coralogix-endpoints.md を読み込みます。リージョン別ドメイン、OTLP のホストとポート、認証ヘッダー形式について説明しています
ユーザー向けの回答を完成させる	output-templates.md を読み込みます。前提条件、コード、検証手順を含むチェックリスト形式が記載されています
SDK のトレース、メトリクス、またはログが見つからない問題を診断する	troubleshooting.md を読み込みます。SDK 側の障害について、症状と根本原因を対応させた表が記載されています

読み込み順：language-selector.md → 言語リファレンス → coralogix-endpoints.md → output-templates.md（必ず最後に読み込みます）。デバッグ時に限り、troubleshooting.md を読み込みます。

回答ルール

回答する前に（エージェントモード）：

• 必ず最初に list_references() を呼び出し、その後、関連ファイルに対して read_reference(...) を呼び出してください（言語セレクター＋対象言語＋エンドポイント。デバッグ時のみトラブルシューティングも追加します）。参照資料が正確性に影響する可能性がある場合、記憶だけを頼りに回答しないでください。
• ユーザー向けの回答には、output-templates.md の構成とチェックリストを使用してください。独自の説明は最小限に抑え、すぐに実行できる内容にしてください。

生成する回答には、必ず以下を含めてください。

• 必須環境変数（名前のみ） — 「コピーして貼り付け」て使えるセットアップには、次の変数を含めてください。 OTEL_EXPORTER_OTLP_ENDPOINT、OTEL_EXPORTER_OTLP_HEADERS、OTEL_SERVICE_NAME、OTEL_RESOURCE_ATTRIBUTES （シグナル／プロトコルを選択する場合は、OTEL_*_EXPORTER／OTEL_EXPORTER_OTLP_*_PROTOCOL も追加します）。言語ごとの正確なエンドポイント形式と Python の %20 環境変数ルールについては、coralogix-endpoints.md を参照してください。

• 必須のリソース属性 — service.name（APM カタログ／トランザクション）、cx.application.name + cx.subsystem.name（ルーティング、TCO、APM のグループ化）、telemetry.sdk.language（自動設定されるため、削除しないでください）。いずれかが欠けると、APM の機能が気づかれないまま低下します。k8s／ホストの追加属性については、各言語リファレンスで説明しています。

• テレメトリーの品質。 カーディナリティの低いスパン名、機密データの不使用、上限を設けたメトリクス属性、トレース／スパン ID を含む構造化された単一行ログ、シグナルの検証手順を徹底してください。user_id、tenant_id、request_id、session_id など、ユーザー単位の値をメトリクスのラベルとして承認しないでください。カーディナリティに上限がなくなり、メトリクスストレージが急増します。

• ダイレクトルーティングとコレクター経由のルーティングに関するルール： 開発／テスト環境、単純な単一サービスの本番環境、またはコレクターインフラストラクチャがない場合は、デフォルトでダイレクト OTLPを使用します。Pod／名前空間のエンリッチメント（k8sattributes）、テールサンプリング、複数サービスで共有するキー管理、またはバッファー付きの再試行／ファイル永続化が必要な Kubernetes ワークロードでは、デフォルトでコレクター経由を使用します。デプロイ環境が不明な場合は、language-selector.md のトレードオフ表を使って両方の選択肢を示してください。

• コレクター設定は対象外です。 opentelemetry-collector を案内してください。パイプラインやプロセッサーに関する質問に対し、一部だけ回答しないでください。

高リスクの注意事項（推測しないでください）

このリストは短く保ち、ユーザーの症状が該当する場合にのみ使用してください。詳細については、各言語のリファレンスを参照してください。

• Java エージェント： opentelemetry-javaagent.jar + JAVA_TOOL_OPTIONS="-javaagent:/path/to/opentelemetry-javaagent.jar"。
• Java/.NET の gRPC エンドポイント： 完全な URI https://ingress.<region>.coralogix.com:443 が必要です（URI の解析では host:port のみの形式は使用できません）。
• Python の認証ヘッダー： 環境変数では %20 が必要です（Authorization=Bearer%20<KEY>）。プログラムで指定するヘッダーには、小文字のキーとリテラルのスペースを含むタプルのシーケンスを使用します（("authorization", f"Bearer {token}")）。
• Node.js の HTTP/proto： エクスポーターの url には /v1/traces を含める必要があります（https://ingress.<region>.coralogix.com:443/v1/traces）。gRPC では不要です。
• Go の gRPC： credentials.NewTLS(nil) と、WithEndpoint で https:// を付けないエンドポイント ingress.<region>.coralogix.com:443 を使用します。
• Go のメトリクスのカーディナリティ： sdk/metric のカーディナリティ上限はデフォルトで 2000 です。無制限の系列が意図的に必要な場合にのみ WithCardinalityLimit(0) を使用してください。上限に達すると otel.metric.overflow=true が設定されます。
• .NET OTLP のディスク再試行： OTEL_DOTNET_EXPERIMENTAL_OTLP_RETRY=disk を使用する場合、現在は OTEL_DOTNET_EXPERIMENTAL_OTLP_DISK_RETRY_DIRECTORY_PATH も必要です。暗黙的な一時ディレクトリへのフォールバックに依存しないでください。
• トランザクション： CoralogixTransactionSampler が必要です（Node.js：@coralogix/opentelemetry）。バンドルされた NODE_OPTIONS による自動計装はトランザクションをサポートしません。
• 短時間で終了する Python スクリプト： SimpleSpanProcessor と BatchSpanProcessor の違いに注意してください。メトリクスには PeriodicExportingMetricReader のフラッシュ／待機が必要です。
• .NET Framework の受信伝搬： OpenTelemetry.Instrumentation.AspNet + AddAspNetInstrumentation()。

ワークフロー

• 新規セットアップ： language-selector.md → 言語リファレンス + coralogix-endpoints.md → output-templates.md を使って生成します。
• コードレビュー： 言語リファレンス → output-templates.md のレビュー用チェックリスト。
• デバッグ： まず troubleshooting.md を参照してください。SDK 側の原因が確認された場合にのみ、言語リファレンスに進んでください。

制限事項

• OTel Collector / OTTL — opentelemetry-collector または opentelemetry-ottl を使用してください。
• Lambda / サーバーレス — Coralogix の Lambda レイヤーのドキュメントを参照してください。Payload Too Large の OTLP エラーは Lambda レイヤーに関するものであり、SDK に関するものではありません。
• PHP、eBPF 自動計装 — 対象外です。
• Coralogix プラットフォームの内部機能（データルーティング、インデックスポリシー、APM UI の設定）— プラットフォームに関するトピックです。

非推奨のネイティブ SDK

Coralogix のネイティブ SDK は 2026 年 6 月 30 日に EOL となります。OTel に誘導し、レガシーパッケージ向けの設定は提供しないでください。

上流のリファレンス

Coralogix の OTel 計装：Java · Python · Node.js · .NET · Go

Coralogix の OTel ドキュメント · OpenTelemetry 公式ドキュメント