コンテンツにスキップ

OpenTelemetry

OpenTelemetry は、Trace、Metric、Log などのテレメトリデータを生成、収集、転送するためのオープンスタンダードです。OpenTelemetry を使用することで、統一されたデータモデルと OTLP プロトコルを用いて、さまざまな言語、フレームワーク、実行環境のアプリケーションを観測できます。

OpenTelemetry エコシステムのサポート

Guanceは、OpenTelemetry 公式の Vendors リストに登録されています。公式の記載によると、Guanceは商用の可観測性ベンダーであり、Native OTLP をサポートし、OpenTelemetry のテレメトリデータをネイティブに受信できます。Guanceを使用することで、ユーザーは OpenTelemetry が生成する Trace、Metric、Log データを統一的に表示・分析し、さらにインフラストラクチャ、アプリケーションパフォーマンス、ユーザーアクセスなどのデータと組み合わせて相関分析を行うことができます。

本ドキュメントでは、アプリケーションの OpenTelemetry データを DataKit に送信し、DataKit から Guance に報告する方法を説明します。

アプリケーション + OpenTelemetry インストルメンテーション -> OTLP -> DataKit -> Guance

接続方式の選択

言語エコシステムとアプリケーション改革の要件に応じて、Zero-code Instrumentation または SDK Instrumentation を選択します。

接続方式 対象言語 動作方式 適用シナリオ
Zero-code Instrumentation Java、Python、PHP、Node.js、.NET、Go エージェント、ランタイムフック、拡張機能、起動パラメータ、またはコンパイル時のインストルメンテーションを介して、サポート対象のフレームワークとコンポーネントにテレメトリデータを自動的に作成します。 ビジネスコードの変更を最小限に抑え、一般的な 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 otelc を使用してコンパイル時に OpenTelemetry SDK 初期化とコンポーネントインストルメンテーションロジックを自動注入。 OpenTelemetry Go（otelc）
Go LoongSuite を介して go build コンパイル中に OpenTelemetry SDK とインストルメンテーションロジックを注入。 OpenTelemetry Go（LoongSuite）

SDK Instrumentation

言語 インストルメンテーション方式 導入ドキュメント
Go OpenTelemetry Go SDK、OTLP Exporter、コンテキストプロパゲーターを初期化し、使用するフレームワークやコンポーネントにインストルメンテーションライブラリをインストール。 OpenTelemetry Go SDK

導入フロー

言語によって具体的なインストールコマンドや起動パラメータは異なりますが、全体の導入フローは共通です。

  1. DataKit OpenTelemetry コレクターを有効にする：OTLP/HTTP または OTLP/gRPC 受信エンドポイントを設定し、DataKit を再起動してネットワーク到達性を確認します。
  2. アプリケーションに OpenTelemetry インストルメンテーションを有効にする：言語に応じてエージェント、拡張機能、自動インストルメンテーションモジュール、または SDK をインストールします。
  3. データ報告パラメータを設定する：サービス名、リソース属性、OTLP プロトコル、DataKit アドレス、サンプリング、およびシグナルスイッチを設定します。
  4. アプリケーションを再起動してアクセスする：実際のリクエストを生成し、Trace と Metric データをトリガーします。
  5. データを検証する：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 ベースアドレスを使用する場合は、次のように設定できます。

export OTEL_EXPORTER_OTLP_ENDPOINT="http://<DataKit-IP>:9529/otel"

標準の 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 アプリケーションバージョンを識別します。 リリースバージョン、ビルドバージョン、または Commit ID を使用し、異なるバージョンのパフォーマンスを比較できるようにします。
OTEL_RESOURCE_ATTRIBUTES リソース属性を一括設定します。 低カーディナリティで機密情報を含まない属性のみを配置します。
OTEL_PROPAGATORS クロスサービスコンテキスト伝播形式を制御します。 デフォルトでは tracecontext,baggage を優先し、コールチェーン上のサービス間で互換性を維持します。
サンプリング戦略 収集量とオーバーヘッドを制御します。 導入検証フェーズではフルサンプリングが可能ですが、本番環境ではトラフィック、ストレージ、トラブルシューティングの要件に応じて調整します。

カスタムリソース属性を Guance でタグとして保持する必要がある場合は、DataKit の customer_tags ホワイトリストに追加する必要があります。属性名の . は _ に変換されます。例：team.name は team_name に変換されます。

データの検証

導入が完了したら、まずアプリケーションインターフェースにアクセスしてリクエストを生成し、以下の確認を行います。

  1. curl http://<DataKit-IP>:9529/v1/ping を実行し、アプリケーションが DataKit にアクセスできることを確認します。
  2. アプリケーションの起動ログを確認し、エージェント、拡張、または SDK がロードされ、OTLP Exporter のエラーがないことを確認します。
  3. Guance のアプリケーションパフォーマンスモニタリング（APM）で、service.name に基づいてサービスとトレースを確認します。
  4. Metric は通常、周期ごとにエクスポートされるため、少なくとも1周期待ってからクエリします。
  5. データが見つからない場合は、DataKit コレクター設定、アプリケーションから DataKit へのネットワーク、OTLP プロトコル、報告アドレスを順に確認します。

フィードバック

このページは役に立ちましたか？