その他の言語にOpenTelemetryを導入する
MackerelはOpenTelemetryの仕組み (計装)を利用してデータを取得しています。
このページではドキュメントでは紹介していない言語を使ってデータをMackerelに送信する方法を解説します。
OpenTelemetry SDK
OpenTelemetryには多数のSDKがあり、多くの言語やフレームワークに対応しています。全てについてのドキュメントを書くことはできませんが、設定内容は共通しています。
このページでは言語共通の設定について解説します。
また、OpenTelemtryのSDKは共通部分がかなり多いため、別の言語の計装方法を解説したページも参考になります。
例えば、以下のページです。
Collectorを使用するべきか
データをMackerelに送信する際に、SDKから直接送信するだけではなく、Collectorを使うこともできます。
Collectorを使うかどうかを決める際は以下のページを参考にしてください。
導入方法
SDKの導入は以下のステップになります。
SDKの検索
アプリケーション内での設定
エラーを補足
独自の計装の追加 (任意)
1. SDKの検索
導入したい言語をOpenTelemtry公式のRegistryから検索します。
以下のページでLanguage
を対象言語に、 Type
を Instrumentation に設定すると対象言語のSDKが検索できます。
2. アプリケーション内での設定
アプリケーション内でSDKを実行する際には、エンドポイントなどの設定が必要になります。以下の項目を設定します。
エンドポイント
SDKからデータを直接Mackerelに送信する場合は、Mackerelのエンドポイント (https://otlp-vaxila.mackerelio.com/v1/traces)
Collectorを利用する場合は、Collectorのエンドポイント (http://localhost:4318/v1/traces など)
送信時のヘッダー
SDKからデータをMackerelに直接送信する場合、以下のヘッダーが必要です。
Accept
:*/*
Mackerel-Api-Key
: Mackerelで発行された書き込み権限のあるAPIキー
Collectorを利用する場合、ヘッダーは必要ありません。
Resource
最低限、以下を設定しておくといいでしょう。
サービス名 (
service.name
)サービスのバージョン (
service.version
)環境名 (
deployment.environment
)
3. エラーの補足
残念ながら、エラーが発生した場合に自動でエラー情報を追加しないSDKもあります。
そのため、エラーが発生したときにエラーメッセージやスタックトレースをSpanに追加するようコードを変更する必要があることがあります。
使用しているSDKがエラーを補足しているかどうかは、エラーが発生したトレースの Events
にエラー内容が書かれているかで判断できます。
エラーを補足している場合、以下のように events
の中にエラー内容やスタックトレースが追加されます。
{
"name": "GET awesome/path",
"context": {
"trace_id": "0xb999451d4eba88ae77c77f829c2d6350",
"span_id": "0x5fca4b11492b6856",
},
"attributes": {...},
"events": [
{
"name": "exception",
"timestamp": "2001-02-03T04:05:06.000000Z",
"attributes": {
"exception.type": "AwesomeException",
"exception.message": "Error happened",
"exception.stacktrace": "Traceback (most recent call last):\n File \"/usr/local/lib/python3.11/site-packages/opentelemetry/trace/__init__.py\", line 573, in use_span\n...",
}
}
],
...
}
エラーを補足していない場合、フレームワークのエラーハンドリング部分など、エラーを補足している場所でOpenTelemetryのイベント(Event)を追加する必要があります。
具体的には、recordException
や recordError
といった関数がSDKに用意されているので、それを呼び出します。
すると、以下の属性を保持したEventがSpanに追加されます。
exception.type
エラー種別
java.net.ConnectException
exception.message
エラーメッセージ
Can't convert 'int' object to str implicitly…
exception.stacktrace
スタックトレース
Exception in thread "main" java.lang.RuntimeException: Test exception\n at ...
Mackerelはこれらの属性を利用してエラー内容を把握し、グルーピングしています。
4. 独自の計装の追加 (任意)
独自のSpanを追加することで、任意の範囲を計装することができます。
計装することで、変数の値や処理時間を記録することができます。
各言語に必ず用意されているはずです。
最終更新