OpenTelemetry¶
OpenTelemetry は、Trace、Metric、Log などのテレメトリデータを生成、収集、転送するためのオープンスタンダードです。OpenTelemetry を使用すると、統一されたデータモデルと OTLP プロトコルを通じて、異なる言語、フレームワーク、およびランタイム環境のアプリケーションを観測できます。
OpenTelemetry エコシステムのサポート¶
Guance は、OpenTelemetry 公式の Vendors リストに掲載されています。公式の記載によると、Guance は商用のオブザーバビリティベンダーであり、Native OTLP をサポートしており、OpenTelemetry テレメトリデータをネイティブに受信できます。Guance を使用すると、ユーザーは OpenTelemetry が生成する Trace、Metric、Log データを統一的に表示および分析し、インフラストラクチャ、アプリケーションパフォーマンス、ユーザーアクセスなどのデータを組み合わせた関連分析を行うことができます。
このドキュメントでは、アプリケーションの OpenTelemetry データを DataKit に送信し、DataKit から Guance にレポートする方法を説明します。
導入方式の選択¶
言語のエコシステムとアプリケーションの改修要件に応じて、Zero-code Instrumentation または SDK Instrumentation を選択します。
| 導入方式 | 対応言語 | 動作方式 | 適用シナリオ |
|---|---|---|---|
| Zero-code Instrumentation | Java、Python、PHP、Node.js、.NET、Go | Agent、ランタイムフック、拡張、起動パラメータ、またはコンパイル時のインストルメンテーションにより、サポート対象のフレームワークやコンポーネントに対して自動的にテレメトリデータを作成します。 | ビジネスコードの変更を最小限に抑え、一般的な Web、HTTP、データベース、メッセージキューの呼び出しを迅速に収集したい場合。 |
| SDK Instrumentation | Go | アプリケーション内で OpenTelemetry SDK を初期化し、フレームワークのインストルメンテーションライブラリまたは API を使用してテレメトリデータを作成します。 | Provider、Exporter、サンプリング、リソース属性、ビジネススパンを明示的に制御する必要がある場合。 |
Zero-code は、ビジネスロジックを変更する必要がない、またはほとんど変更する必要がないことを意味しますが、コンポーネントのインストール、レポートパラメータの設定、アプリケーションの再起動が不要というわけではありません。自動インストルメンテーションは、サポート対象のフレームワークとコンポーネントのみをカバーします。ビジネス内部の重要な操作は、OpenTelemetry API を使用してカスタムスパン、メトリクス、属性を追加で作成できます。
Zero-code Instrumentation¶
| 言語 | インストルメンテーション方式 | 導入ドキュメント |
|---|---|---|
| Java | JVM -javaagent で OpenTelemetry Java Agent をロードします。 |
OpenTelemetry Java；Java 拡張 |
| Python | opentelemetry-instrument でアプリケーションを起動し、対応するインストルメンテーションパッケージをロードします。 |
OpenTelemetry Python |
| PHP | OpenTelemetry PHP 拡張でランタイムフックを提供し、Composer インストルメンテーションパッケージでフレームワークの呼び出しを収集します。 | OpenTelemetry PHP |
| Node.js | NODE_OPTIONS で OpenTelemetry 自動インストルメンテーションモジュールをプリロードします。 |
OpenTelemetry Node.js |
| .NET | CLR Profiler と Startup Hook で OpenTelemetry .NET Automatic Instrumentation をロードします。 | OpenTelemetry .NET |
| Go | LoongSuite を使用して go build コンパイル時に OpenTelemetry SDK とインストルメンテーションロジックを注入します。 |
OpenTelemetry Go（LoongSuite） |
SDK Instrumentation¶
| 言語 | インストルメンテーション方式 | 導入ドキュメント |
|---|---|---|
| Go | OpenTelemetry Go SDK、OTLP Exporter、コンテキストプロパゲータを初期化し、使用するフレームワークやコンポーネントのインストルメンテーションライブラリをインストールします。 | OpenTelemetry Go SDK |
導入フロー¶
言語によって具体的なインストールコマンドや起動パラメータは異なりますが、全体的な導入フローは統一されています。
- DataKit OpenTelemetry コレクターを有効にする：OTLP/HTTP または OTLP/gRPC の受信エンドポイントを設定し、DataKit を再起動してネットワーク接続を確認します。
- アプリケーションで OpenTelemetry インストルメンテーションを有効にする：言語に応じて Agent、拡張、自動インストルメンテーションモジュール、または SDK をインストールします。
- データレポートパラメータを設定する：サービス名、リソース属性、OTLP プロトコル、DataKit アドレス、サンプリング、およびシグナルのオン/オフを設定します。
- アプリケーションを再起動してアクセスする：実際のリクエストを生成し、Trace と Metric データをトリガーします。
- データを検証する：Guance でサービス、トレース、メトリクスを確認し、アプリケーションおよび DataKit のログを確認してレポートエラーをトラブルシューティングします。
DataKit OTLP 受信アドレス¶
このドキュメントのホスト導入例では、以下のアドレスを使用します。<DataKit-IP> は、アプリケーションがアクセス可能な DataKit のアドレスに置き換えてください。
| プロトコル | シグナル | 受信アドレス |
|---|---|---|
| OTLP/HTTP + Protobuf | Trace | http://<DataKit-IP>:9529/otel/v1/traces |
| OTLP/HTTP + Protobuf | Metric | http://<DataKit-IP>:9529/otel/v1/metrics |
| OTLP/HTTP + Protobuf | Log | http://<DataKit-IP>:9529/otel/v1/logs |
| OTLP/gRPC | Trace、Metric、Log | http://<DataKit-IP>:4317 |
汎用の OTLP/HTTP ベースアドレスを使用する場合は、次のように設定できます。
標準の OTLP 環境変数をサポートする Exporter は、シグナルに応じて自動的に /v1/traces、/v1/metrics、または /v1/logs を追加します。OTEL_EXPORTER_OTLP_TRACES_ENDPOINT などのシグナル専用アドレスを使用する場合は、/otel/v1/traces を含む完全なアドレスを入力する必要があります。
OTLP/gRPC アドレスには /v1/traces などの HTTP パスを追加できません。アプリケーションと DataKit が同じホストにない場合は、DataKit のリスニングアドレス、ファイアウォール、またはその他のネットワークアクセス制御も調整する必要があります。OTLP 受信ポートをパブリックネットワークに直接公開しないでください。
完全な DataKit パラメータの説明については、OpenTelemetry コレクター を参照してください。
統一パラメータの推奨事項¶
どの言語を使用する場合でも、以下のリソース属性と伝播パラメータを統一して計画することをお勧めします。
| パラメータまたは属性 | 役割 | 推奨事項 |
|---|---|---|
service.name |
サービスを識別し、APM サービスの所属を決定するコアフィールドです。 | 安定した一意のサービス名を使用し、Pod やプロセス ID などの動的な値は使用しないでください。 |
deployment.environment.name |
デプロイ環境を識別します。 | dev、test、staging、prod などの統一された値を使用します。 |
service.version |
アプリケーションバージョンを識別します。 | リリースバージョン、ビルドバージョン、またはコミット ID を使用して、異なるバージョンのパフォーマンスを比較できるようにします。 |
OTEL_RESOURCE_ATTRIBUTES |
リソース属性を一括設定します。 | 低カーディナリティで機密情報を含まない属性のみを配置します。 |
OTEL_PROPAGATORS |
サービス間のコンテキスト伝播形式を制御します。 | デフォルトでは tracecontext,baggage を優先し、呼び出しチェーン上のサービス間で互換性を維持します。 |
| サンプリング戦略 | 収集量とオーバーヘッドを制御します。 | 導入検証段階ではフルサンプリングが可能ですが、本番環境ではトラフィック、ストレージ、トラブルシューティングのニーズに応じて調整します。 |
カスタムリソース属性を Guance でタグとして保持するには、DataKit の customer_tags ホワイトリストに追加する必要があります。属性名の . は _ に変換されます。例：team.name は team_name に変換されます。
データの検証¶
導入が完了したら、まずアプリケーションのインターフェースにアクセスしてリクエストを生成し、次に以下のチェックを実行します。
curl http://<DataKit-IP>:9529/v1/pingを実行して、アプリケーションが DataKit にアクセスできることを確認します。- アプリケーションの起動ログを確認し、Agent、拡張、または SDK がロードされ、OTLP Exporter のエラーがないことを確認します。
- Guance のアプリケーションパフォーマンスモニタリング (APM) で、
service.nameを使用してサービスとトレースを検索します。 - Metric は通常、定期的にエクスポートされるため、少なくとも 1 エクスポートサイクル待ってからクエリを実行します。
- データが見つからない場合は、DataKit コレクターの設定、アプリケーションから DataKit へのネットワーク、OTLP プロトコル、およびレポートアドレスを順に確認します。