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 ダウンロード URL を使用して 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 コレクター