OpenTelemetry Go（LoongSuite）¶

LoongSuite Go は、OpenTelemetry ベースの Go コンパイル時自動インストルメンテーションツールです。ビジネスコードを変更する必要はなく、従来の go build を otel go build に置き換えるだけで、コンパイル時にサポート対象のフレームワークやコンポーネントに OpenTelemetry SDK とインストルメンテーションロジックを注入します。

本記事では、DataKit の OpenTelemetry コレクターを使用して、LoongSuite が OTLP 経由で報告する Trace と Metric を受信し、Guance に転送します。

Go ソースコード -- otel go build --> インストルメントされた Go バイナリ -- OTLP --> DataKit --> Guance

!!! note

LoongSuite の「ゼロコード」は、ビジネスコードの変更が不要であることを意味しますが、再構築が不要であることを意味するわけではありません。インストルメンテーションはコンパイル時に行われるため、既に生成された Go バイナリに LoongSuite を後付することはできません。`otel go build` を使用して再コンパイルし、新しいバイナリをデプロイする必要があります。

事前準備¶

• DataKit がインストールされ、対象の Guance ワークスペースに接続されていること。
• Go アプリケーションから DataKit へのネットワークが到達可能であること：OTLP/HTTP は DataKit HTTP ポート 9529、OTLP/gRPC はデフォルトで 4317 を使用します。
• アプリケーションが標準の go build で正常にコンパイルできること。
• Go のバージョン、OS、アーキテクチャが LoongSuite の互換性要件を満たしていること。
• アプリケーションが使用するフレームワークまたはコンポーネントが LoongSuite のサポートリストに含まれていること。

本記事では、Linux AMD64 ホストを例とし、Kubernetes デプロイメントは含みません。

一、OpenTelemetry コレクターを有効にする¶

DataKit インストールディレクトリの conf.d/opentelemetry に移動します。コレクター設定がまだない場合は、サンプルファイルをコピーします。

cd /usr/local/datakit/conf.d/opentelemetry
sudo cp opentelemetry.conf.sample opentelemetry.conf

opentelemetry.conf に最低限以下の受信設定が含まれていることを確認します。

[[inputs.opentelemetry]]
  # カスタム属性をタグとして保持する場合は、ここにホワイトリストを追加します。
  # 属性名のドットはアンダースコアに変換されます（例: team.name -> team_name）。
  customer_tags = ["team", "project"]

  [inputs.opentelemetry.http]
    http_status_ok = 200
    trace_api = "/otel/v1/traces"
    metric_api = "/otel/v1/metrics"

  [inputs.opentelemetry.grpc]
    addr = "127.0.0.1:4317"
    max_payload = 16777216

上記の設定により、以下の受信アドレスが有効になります。

アプリケーションと DataKit が同一ホスト上にない場合は、実際のデプロイに応じて DataKit の HTTP リスニングアドレス、ファイアウォール、その他のネットワークアクセス制御を調整する必要があります。OTLP/gRPC を使用する場合は、addr をアプリケーションがアクセス可能なリスニングアドレス（例：0.0.0.0:4317）に変更してください。OTLP 受信ポートを直接パブリックネットワークに公開しないでください。

DataKit を再起動して設定を反映させます。

sudo datakit service restart

DataKit の HTTP サービスが到達可能かどうかを確認します。

curl http://127.0.0.1:9529/v1/ping

二、アプリケーションを OpenTelemetry に接続する¶

LoongSuite のインストール¶

LoongSuite 公式 GitHub Release から Linux AMD64 実行可能ファイルをダウンロードします。

sudo curl -fL \
  https://github.com/alibaba/loongsuite-go/releases/latest/download/otel-linux-amd64 \
  -o /usr/local/bin/otel
sudo chmod +x /usr/local/bin/otel

ARM64 ホストの場合は、ファイル名を otel-linux-arm64 に置き換えてください。その他の OS やアーキテクチャについては、LoongSuite Releases から対応するファイルを選択してください。

ツールが実行可能であることを確認します。

otel version
go version

本番環境では、明確なバージョン番号を含む Release ダウンロードアドレスを使用して LoongSuite のバージョンを固定し、アップグレード前に互換性、リリースノートを確認し、コンパイルとトレーシングの回帰テストを実行することを推奨します。

インストルメンテーション前の確認¶

まず、元のコマンドでプロジェクトが正常にコンパイルできることを確認します。

go build ./...

プロジェクトがすでに OpenTelemetry Go API、SDK、または Contrib インストルメンテーションライブラリに直接依存している場合は、これらの依存関係が現在の LoongSuite バージョンの要件と一致しているかどうかを確認する必要があります。

go list -m all | grep 'go.opentelemetry.io'

LoongSuite はアプリケーションに SDK 初期化ロジックを注入し、OpenTelemetry 自体にもインストルメンテーションを施します。プロジェクト内に互換性のない OpenTelemetry 依存関係や重複する SDK 初期化ロジックが存在する場合、コンパイルエラー、Span の重複、またはコンテキストの中断が発生する可能性があります。このようなプロジェクトでは、まず公式の互換性テーブルに従って依存関係のバージョンを統一してください。アプリケーションで SDK を自ら制御する必要がある場合は、代わりに OpenTelemetry Go SDK を使用することをお勧めします。

LoongSuite を使用したコンパイル¶

Go プロジェクトディレクトリに移動し、元のビルドコマンドの前に otel を追加します。

otel go build -o ./bin/order-service ./cmd/order-service

その他の一般的なビルド方法についても、元の go build パラメータを保持します。例：

otel go build
otel go build -trimpath -ldflags="-s -w" -o ./bin/order-service ./cmd/order-service

LoongSuite によるコンパイルは、前処理、インストルメンテーション、依存関係処理のフェーズが追加されるため、初回のビルドは通常の go build よりも著しく遅くなります。再利用可能な Go ビルドキャッシュを設定して、以降のビルド時間を短縮できます。

otel set -gocache=/var/tmp/loongsuite-go-cache

環境変数を使用して、CI や単発のビルド用にキャッシュを指定することもできます。

export OTELTOOL_GO_CACHE="/var/tmp/loongsuite-go-cache"
otel go build -o ./bin/order-service ./cmd/order-service

!!! warning

以降のリリースプロセスでは、`otel go build` で生成されたバイナリをデプロイする必要があります。通常の `go build` で成果物を上書きすると、実行時に LoongSuite の自動インストルメンテーションは含まれません。

OTLP/HTTP を設定して起動する¶

以下の例では、OTLP/HTTP + Protobuf を使用して Trace と Metric をローカルの DataKit に報告します。汎用 endpoint を http://127.0.0.1:9529/otel に設定すると、Exporter はそれぞれ /v1/traces と /v1/metrics を追加し、最終的に DataKit の /otel/v1/* 受信パスに対応します。

export OTEL_SERVICE_NAME="order-service"
export OTEL_RESOURCE_ATTRIBUTES="deployment.environment.name=prod,service.version=1.0.0,team=backend"

export OTEL_TRACES_EXPORTER="otlp"
export OTEL_METRICS_EXPORTER="otlp"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://127.0.0.1:9529/otel"
export OTEL_EXPORTER_OTLP_INSECURE="true"

# 1.0 は全量サンプリングを意味します。接続検証フェーズでのみ使用することを推奨します。
export OTEL_TRACE_SAMPLER="1.0"

./bin/order-service

実行時パラメータは、コンパイルホスト上だけでなく、インストルメント後のバイナリが実際に実行される環境で設定する必要があります。起動後、サポート対象のフレームワークが提供するインターフェースをリクエストし、データベース、HTTP クライアント、またはメッセージキューへの呼び出しをトリガーして、検証可能な Span と Metric を生成します。

OTLP/gRPC の使用¶

OTLP/gRPC に変更する場合は、プロトコルと endpoint を置き換えます。gRPC アドレスには /v1/traces などの HTTP パスを追加しないでください。

export OTEL_EXPORTER_OTLP_PROTOCOL="grpc"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://127.0.0.1:4317"
export OTEL_EXPORTER_OTLP_INSECURE="true"

三、データ報告パラメータ¶

LoongSuite はコンパイル時に OpenTelemetry SDK の初期化ロジックを注入します。インストルメント後のアプリケーションは、実行時に環境変数を使用して Exporter、endpoint、サンプリング、リソース属性を調整できます。

リソースと Exporter のパラメータ¶

汎用 HTTP endpoint を使用する場合は http://<DataKit-IP>:9529/otel を入力します。シグナル専用 endpoint を使用する場合は、/otel/v1/traces または /otel/v1/metrics を含む完全なパスを入力する必要があります。DataKit の OTLP/HTTP 収集は Protobuf のみをサポートします。http/json は設定しないでください。

サンプリングと Metric のパラメータ¶

!!! warning

LoongSuite が現在使用するサンプリング変数は `OTEL_TRACE_SAMPLER` であり、OpenTelemetry SDK で一般的な `OTEL_TRACES_SAMPLER`、`OTEL_TRACES_SAMPLER_ARG` とは異なります。インストールされている LoongSuite のバージョンの [SDK 設定説明](https://github.com/alibaba/loongsuite-go/blob/main/docs/user/sdk-config.md){:target="_blank"} を参照してください。

本番環境では、トラフィック、データ予算、およびトラブルシューティングの要件に応じてサンプリングレートを調整してください。上下流のサービス間で互換性のある W3C Trace Context 伝播を維持し、サービス間の呼び出しでチェーンが切断されないようにする必要があります。

LoongSuite ビルドパラメータ¶

以下の変数は LoongSuite コンパイルツールのみを制御し、インストルメント後のバイナリのデータ報告は制御しません。

例えば、一時的に詳細なコンパイルログを出力する場合：

export OTELTOOL_DEBUG="true"
export OTELTOOL_VERBOSE="true"
otel go build -o ./bin/order-service ./cmd/order-service

トラブルシューティングが完了したら、ログ量を減らすために Debug と Verbose をオフにしてください。

フィールドマッピング¶

LoongSuite によって報告された OTLP Span Attributes は、DataKit OpenTelemetry コレクターによってトレースフィールドに変換されます。一般的なマッピングは次のとおりです。

LoongSuite によって報告されたその他の Attributes をタグとして昇格させるには、DataKit の opentelemetry.conf で customer_tags を設定します。customer_tags は正規表現をサポートしており、一致した属性名の . は _ に変換されます。

[[inputs.opentelemetry]]
  customer_tags = [
    "reg:^db\\.query\\.parameter\\.",
    "reg:^kratos\\.service\\.meta\\.",
    "reg:^gen_ai\\.other_input\\.",
    "reg:^gen_ai\\.other_output\\.",
  ]

ユーザー ID、注文番号などの高カーディナリティ値をタグとして一括で昇格させたり、パスワード、トークン、データベースの完全な接続文字列などの機密情報を報告したりしないでください。

接続の検証¶

1. otel go build を使用してコンパイルし、新しいバイナリを起動します。
2. サポート対象の Web フレームワークによって処理されるインターフェースをリクエストし、データベース、HTTP クライアント、またはメッセージキューへの呼び出しをトリガーします。
3. OTLP/HTTP を使用して報告する場合、DataKit ホストで受信ログを確認します。

sudo tail -f /usr/local/datakit/log/gin.log | grep '/otel/v1/'

/otel/v1/traces または /otel/v1/metrics への POST リクエストが表示され、応答コードが 200 の場合、DataKit がデータを受信したことを意味します。次に、Guance の「APM > トレース」に移動し、service:order-service で検索します。Metric は、少なくとも 1 つのエクスポートサイクルが経過した後にクエリします。

データがない場合は、以下の項目を順に確認してください。

• デプロイされているのが otel go build で生成された新しいバイナリであるかどうか。
• OTEL_SERVICE_NAME、Exporter、プロトコル、endpoint が実際の実行プロセスで設定されているかどうか。
• アプリケーションが使用するフレームワークとそのバージョンが LoongSuite のサポートリストに含まれているかどうか。
• LoongSuite とプロジェクトの既存の OpenTelemetry 依存関係との互換性。
• DataKit OpenTelemetry コレクターが有効化され、再起動されて反映されているかどうか。
• アプリケーションから DataKit へのネットワークとポートが到達可能かどうか。

通常の go build は成功するが otel go build が失敗する場合は、一時的に OTELTOOL_DEBUG=true と OTELTOOL_VERBOSE=true を有効にして、失敗したインストルメンテーションルールを特定します。必要に応じて、otel set -disable=<rule-name> で問題のあるルールを一時的に無効にし、LoongSuite Issues にフィードバックを送信してください。

参考¶

• LoongSuite Go
• LoongSuite がサポートするフレームワークとコンポーネント
• LoongSuite SDK 設定
• LoongSuite ビルドツール設定
• OpenTelemetry Go ゼロコードインストルメンテーション
• DataKit OpenTelemetry コレクター