ddtrace よく使うパラメータの使い方¶
著者：刘锐
前提条件¶
-
DataKit ddtrace コレクター を有効にする
-
起動コマンド
java -javaagent:D:/ddtrace/dd-java-agent-guance.jar \
-Ddd.service.name=ddtrace-server \
-Ddd.agent.port=9529 \
-jar springboot-ddtrace-server.jar
パラメータの使用¶
query パラメータを有効にする¶
query パラメータを有効にすると、現在のリクエストにどのようなパラメータが含まれているかをユーザーが直感的に確認でき、実際の操作フローをより正確に再現できます。デフォルトは false で、有効になっていません。
ただし、query パラメータを有効にしても URL 上のパラメータのみが収集され、リクエストボディ内のパラメータは現在サポートされていません。
リモート収集リンクの設定¶
dd.agent.host のデフォルト値は localhost であるため、デフォルトではローカルの DataKit に送信されます。
リモートの DataKit に送信する場合は、dd.agent.host を設定する必要があります。
Tag を追加する 2 つの方法¶
ddtrace では Tag を追加する方法が 2 つあり、効果は同じです。ただし、dd.tags の方法を使用することを推奨します。
1. dd.trace.span.tags¶
すべてのスパンに projectName:observable-demo を追加する例：
2. dd.tags¶
上記 2 つの方法はいずれも Tag を生成でき、効果は同じで、meta 内にデータが表示されます。
もし dd.tags でマークした Tag を Guance のタグとして使用したい場合は、ddtrace.conf で customer_tags を設定する必要があります。
[[inputs.ddtrace]]
endpoints = ["/v0.3/traces", "/v0.4/traces", "/v0.5/traces"]
customer_tags = ["projectName","user_name"]
効果は以下の通りです：
データベースインスタンス名の表示¶
データベースの名前を表示します。デフォルトではデータベースの種類が表示されます。データベース名を表示する場合は、値を TRUE に設定します。
上記のデモではデータベースを読み込んでいないため、この効果を得るには、データベースを導入したアプリケーションを選択してパラメータを追加してください。
効果は以下の通りです：
クラスまたはメソッドへの Trace 注入¶
ddtrace はメソッドに Trace を注入することをサポートしています。デフォルトでは、ddtrace はすべての API エンドポイントに動的に Trace を注入します。
非 API のクラス（メソッド）— 重要なクラスやメソッドを重点的にマークしたい場合は、dd.trace.methods パラメータで設定できます。
- Environment Variable: DD_TRACE_METHODS
- Default: null
- Example: package.ClassName[method1,method2,...];AnonymousClass$1[call];package.ClassName[*]
List of class/interface and methods to trace. Similar to adding @Trace, but without changing code. - Note: The wildcard method support ([*]) does not accommodate constructors, getters, setters, synthetic, toString, equals, hashcode, or finalizer method calls
例えば、com.zy.observable.ddtrace.service.TestService クラスの getDemo メソッドに Trace を追加する必要がある場合。
コードの一部：
@Autowired
private TestService testService;
@GetMapping("/gateway")
@ResponseBody
public String gateway(String tag) {
String userId = "user-" + System.currentTimeMillis();
MDC.put(ConstantsUtils.MDC_USER_ID, userId);
logger.info("this is tag");
sleep();
testService.getDemo();
httpTemplate.getForEntity(apiUrl + "/resource", String.class).getBody();
httpTemplate.getForEntity(apiUrl + "/auth", String.class).getBody();
if (client) {
httpTemplate.getForEntity("http://"+extraHost+":8081/client", String.class).getBody();
}
return httpTemplate.getForEntity(apiUrl + "/billing?tag=" + tag, String.class).getBody();
}
dd.trace.methods パラメータを追加しない場合、11 個のスパンが報告され、効果は以下の通りです：
ヘッダーによるカスタムビジネスタグ¶
主にヘッダーを使用して、非侵襲的な方法でビジネスタグをトレースに注入し、対応するビジネスの実行状況を追跡できます。Key:value 形式で設定し、key は元のヘッダーのパラメータ名、value は key のリネームです。key は省略可能です。
リクエスト
トレース効果：
Baggage: Tag を無限に伝搬させる¶
環境変数: DD_TRACE_HEADER_BAGGAGE
デフォルト値: null
サンプル: CASE-insensitive-Header:my-baggage-name,User-ID:userId,My-Header-And-Baggage-Name
例：
-Dd.trace.header.tags は伝搬機能を実装しません。Baggage はヘッダーのタグを無限に伝搬させることができます。
トレース効果：
デバッグモードの有効化¶
デバッグモードを有効にすると、システムは ddtrace 関連のログを出力し、ddtrace 関連の問題のトラブルシューティングに役立ちます。
デフォルトではデバッグログは stdout に出力されます。ファイルに出力する場合は、以下のパラメータと組み合わせる必要があります。
注意
-Dd.trace.debug=true は ddtrace のデバッグログを有効にするためのものであり、アプリケーションのデバッグログを有効にするものではありません。
traceId の 128 ビット有効化¶
traceId はデフォルトで 64 ビット（long 型）です。opentelemetry （traceId は 128 ビット）との互換性を向上させるために、手動で 128 ビットを有効にできます。
Trace 情報の出力¶
研究開発関連の作業を行う場合、Trace レポートのデータ構造を理解することが必要です。デフォルトでは、Trace 情報は DDAgentWriter を介してリモートの可観測性プラットフォームに報告されます。コンソールに情報を出力する場合は、以下のパラメータを設定します。
複数設定することもできます。
サービス名によるミドルウェア名の置き換えを有効にする¶
デフォルトでは、トレース情報はミドルウェア名ごとにグループ化されて表示されます。そのため、アプリケーションがミドルウェアのみからトレース情報を生成する場合、現在のミドルウェアが属するアプリケーションを上位に遡ることができません。パラメータを調整することで、グローバルタグの service name をミドルウェアの service として使用できます。以下のパラメータで設定します。
起動パラメータでの注入
環境変数での注入も可能です。
上記2つの方法のいずれかを選択してください。
最終的な効果として、ミドルウェアのサービス名は表示されなくなります（つまり、アプリケーションのサービス名がミドルウェアの名前を置き換えます）。スパンの他のタグやデータは影響を受けません。
置き換え前の効果
置き換え後の効果
伝搬設定¶
ddtrace は以下の伝搬をサポートしています。伝搬の種類は大文字小文字を区別しません。
- Datadog：デフォルトの伝搬
- B3：B3 伝搬は、ヘッダー "b3" および "x-b3-" で始まるヘッダーの仕様です。これらのヘッダーは、サービス間のトレースコンテキスト伝搬に使用されます。B3 には以下の2つの方法があります。
- B3SINGLE（B3_SINGLE_HEADER）：ヘッダーキーは
b3 - B3（B3MULTI）：ヘッダーキーは
x-b3-
- B3SINGLE（B3_SINGLE_HEADER）：ヘッダーキーは
- haystack
- tracecontext：デフォルトの伝搬
- xray：AWS 伝搬
または環境変数で設定
ddtrace 1.9.0 より前は以下を使用
または注意：複数の伝搬を設定できます。複数の伝搬はカンマ(,)で区切ります。伝搬の種類は大文字小文字を区別しません。
伝搬に関する詳細は、リンクトレース伝搬（Propagate）メカニズムとユースケース を参照してください。
レスポンスでの TraceId 返却¶
この項目は追加設定は不要です。リクエストの応答が完了した後、キーが guance_trace_id のヘッダーが追加されます。
version >= 1.25.1-guance
ヘッダータグ¶
リクエストとレスポンスのすべてのヘッダーをトレースタグに追加します。リクエストヘッダーのタグ名は request_header、レスポンスヘッダーのタグ名は response_header です。以下の2つの方法のいずれかで有効にします。
- 起動コマンド
-Dd.trace.headers.enabled：デフォルト値は false（有効になっていません）。
- 環境変数
DD_TRACE_HEADERS_ENABLED
| コンポーネント | ddtrace バージョン |
|---|---|
| javax.servlet | >=1.25 |
| jakarta.servlet | >=1.42.9 |
リクエストボディタグ¶
リクエストボディをトレースタグに追加します。現在は POST リクエストのみサポートしており、Context-Type が application/json または application/json;charset=UTF-8 である必要があります。
- 起動コマンド
-Dd.trace.request.body.enabled：デフォルト値は false（有効になっていません）。
- 環境変数
DD_TRACE_REQUEST_BODY_ENABLED
以下のリクエストを実行する場合
curl -X POST -H 'Content-Type: application/json' -d '{"username":"joy","age":18}' http://localhost:8090/jsonStr
| コンポーネント | ddtrace バージョン |
|---|---|
| javax.servlet | >=1.25 |
| jakarta.servlet | >=1.42.9 |
レスポンスボディタグ¶
レスポンスボディの内容をトレースタグに追加します。application/json および text/plain タイプのデータをサポートします。
- 起動コマンド
-Dd.trace.response.body.enabled：デフォルト値は false（有効になっていません）。
- 環境変数
DD_TRACE_RESPONSE_BODY_ENABLED
レスポンスボディを読み取ると Java メモリを消費するため、レスポンスボディが大きいリクエスト（ファイルダウンロード API など）にはブラックリストを設定して OOM を防止することを推奨します。ブラックリストに登録された URL はレスポンスボディの解析を行いません。
ブラックリストの設定は以下の通りです。
- パラメータ方式
-Dd.trace.response.body.blacklist.urls="/auth,/download/file"
- 環境変数方式
DD_TRACE_RESPONSE_BODY_BLACKLIST_URLS
| コンポーネント | ddtrace バージョン |
|---|---|
| javax.servlet | >=1.42 |
| jakarta.servlet | >=1.42.9 |
