Trace 設定¶
Trace 初期化設定¶
| メソッド名 | 型 | 必須 | 説明 |
|---|---|---|---|
| setTraceSamplingRate | Float | いいえ | サンプリング比率。範囲は [0,100]、デフォルトは 100。小数にも対応しており、例えば 0.1 は 0.1% を表します。0 は収集しないこと、100 は全量収集することを示します。新しいフィールドを明示的に設定した場合は、設定順序に関係なく旧フィールドより優先されます。ft-sdk >= 1.7.6 で対応しています。 |
| setSamplingRate | Float | いいえ | ft-sdk 1.7.6 以降は非推奨ですが、互換性のため残されています。 サンプリングレートを設定します。範囲は [0,1] で、0 は収集しないこと、1 は全量収集することを示します。デフォルト値は 1 です。 |
| setTraceType | TraceType | いいえ | 分散型トレーシングのタイプを設定します。デフォルトは DDTrace で、現在は Zipkin、Jaeger、DDTrace、Skywalking (8.0+)、TraceParent (W3C) に対応しています。OpenTelemetry を接続し、対応するトレースタイプを選択する場合は、サポートされているタイプと agent の関連設定を必ず確認してください。 |
| setEnableLinkRUMData | Boolean | いいえ | RUM データと関連付けるかどうか。デフォルトは false です。 |
| setEnableAutoTrace | Boolean | いいえ | 自動 HTTP Trace を有効にするかどうかを設定します。デフォルトは false です。自動計装は ft-plugin に依存し、OkHttp に対応しています。ft-sdk >= 1.7.6-alpha03 と ft-plugin >= 1.3.9-alpha01 を組み合わせ、URLConnection Resource の収集を有効にしている場合は、HttpURLConnection / HttpsURLConnection にも対応します。詳しくは URLConnection Trace を参照してください。 |
| setOkHttpTraceHeaderHandler | Callback | いいえ | ASM でグローバルな FTTraceInterceptor.HeaderHandler を設定します。デフォルトでは設定されず、ft-sdk 1.6.8 以上で対応しています。ft-sdk 1.6.17 以降は、getTraceContext(Request) のオーバーライドを優先してサポートしており、Header、traceId、spanId を一度に返すことができます。例は カスタム Trace を参照してください。 |
HttpURLConnection / HttpsURLConnection Trace¶
ft-sdk >= 1.7.6-alpha03 と ft-plugin >= 1.3.9-alpha01 を組み合わせる場合、先に URLConnection 自動収集 に従って setEnableTraceUserResource(true) と setEnableHttpURLConnectionResource(true) を有効にし、その後 FTTraceConfig.setEnableAutoTrace(true) で Trace Header の注入を有効にします。Trace スイッチだけを有効にしても URLConnection のラップは有効になりません。また、Resource URL フィルタリングによって、そのパスでの Trace 注入も除外されます。
伝搬形式とサンプリング決定は、FTTraceConfig の Trace タイプとサンプリングレート設定に従います。setEnableLinkRUMData(true) を有効にすると、正常に注入された trace_id / span_id が対応する Resource に関連付けられます。上記の Trace 初期化例は、RUM 設定と組み合わせて使用できます。
URLConnection は、選択した伝搬形式の既存 Trace Header を置き換えます。リクエストが他の SDK や JS レイヤーで既にトレース情報を注入されている場合は、重複して有効にしないでください。Resource の Trace 情報がサーバー側で受信した Header と一致しなくなるおそれがあります。setOkHttpTraceHeaderHandler は OkHttp に対してのみ機能し、URLConnection の Trace Header のカスタマイズには使用されません。
Tracer ネットワーク分散型トレーシング¶
FTTraceConfig で enableAutoTrace を有効にするとトレースデータが自動的に追加されます。また、FTTraceManager を手動で使用して HTTP リクエストに Propagation Header を追加することもできます。以下に例を示します。
String url = "https://request.url";
String uuid = "uuid";
// トレースヘッダー情報を取得
Map<String, String> headers = FTTraceManager.get().getTraceHeader(uuid, url);
OkHttpClient client = new OkHttpClient.Builder().addInterceptor(chain -> {
Request original = chain.request();
Request.Builder requestBuilder = original.newBuilder();
// リクエストにトレースヘッダー情報を追加
for (String key : headers.keySet()) {
requestBuilder.header(key, headers.get(key));
}
Request request = requestBuilder.build();
Response response = chain.proceed(request);
if (response != null) {
Map<String, String> requestHeaderMap = new HashMap<>();
Map<String, String> responseHeaderMap = new HashMap<>();
for (Pair<String, String> header : response.request().headers()) {
requestHeaderMap.put(header.first, header.second);
}
for (Pair<String, String> header : response.headers()) {
responseHeaderMap.put(header.first, header.second);
}
}
return response;
}).build();
Request.Builder builder = new Request.Builder().url(url).method(RequestMethod.GET.name(), null);
client.newCall(builder.build()).execute();
val url = "https://request.url"
val uuid = "uuid"
// トレースヘッダー情報を取得
val headers = FTTraceManager.get().getTraceHeader(uuid, url)
val client: OkHttpClient = OkHttpClient.Builder().addInterceptor { chain ->
val original = chain.request()
val requestBuilder = original.newBuilder()
// リクエストにトレースヘッダー情報を追加
for (key in headers.keys) {
requestBuilder.header(key!!, headers[key]!!)
}
val request = requestBuilder.build()
val response = chain.proceed(request)
if (response != null) {
val requestHeaderMap = HashMap<String, String>()
val responseHeaderMap = HashMap<String, String>()
request.headers.forEach {
requestHeaderMap[it.first] = it.second
}
response.headers.forEach {
responseHeaderMap[it.first] = it.second
}
}
response
}.build()
val builder: Request.Builder = Request.Builder().url(url).method(RequestMethod.GET.name, null)
client.newCall(builder.build()).execute()
OkHttp Interceptor による Resource と TraceHeader のカスタマイズ¶
Resource¶
FTRUMConfig.setEnableTraceUserResource(true) または FTRUMConfig.setOkHttpResourceContentHandler(...) を有効にすると、OkHttp のカスタム Interceptor が優先的に読み込まれます。
new OkHttpClient.Builder()
.addInterceptor(new FTTraceInterceptor())
.addInterceptor(new FTResourceInterceptor(new FTResourceInterceptor.ContentHandlerHelper() {
@Override
public void onRequest(Request request, HashMap<String, Object> extraData) {
String contentType = request.header("Content-Type");
extraData.put("df_request_header", request.headers().toString());
if ("application/json".equals(contentType) ||
"application/x-www-form-urlencoded".equals(contentType) ||
"application/xml".equals(contentType)) {
extraData.put("df_request_body", request.body());
}
}
@Override
public void onResponse(Response response, HashMap<String, Object> extraData) throws IOException {
String contentType = response.header("Content-Type");
extraData.put("df_response_header", response.headers().toString());
if ("application/json".equals(contentType) ||
"application/xml".equals(contentType)) {
// body の一部をコピーして読み取り、大規模データ処理の消費を回避
ResponseBody body = response.peekBody(33554432);
extraData.put("df_response_body", body.string());
}
}
@Override
public void onException(Exception e, HashMap<String, Object> extraData) {
}
}))
.eventListenerFactory(new FTResourceEventListener.FTFactory())
.build();
OkHttpClient.Builder()
.addInterceptor(FTTraceInterceptor())
.addInterceptor(FTResourceInterceptor(object : FTResourceInterceptor.ContentHandlerHelper {
override fun onRequest(request: Request, extraData: HashMap<String, Any>) {
val contentType = request.header("Content-Type")
extraData["df_request_header"] = request.headers().toString()
if ("application/json" == contentType ||
"application/x-www-form-urlencoded" == contentType ||
"application/xml" == contentType) {
extraData["df_request_body"] = request.body()
}
}
override fun onResponse(response: Response, extraData: HashMap<String, Any>) {
val contentType = response.header("Content-Type")
extraData["df_response_header"] = response.headers().toString()
if ("application/json" == contentType ||
"application/xml" == contentType) {
// レスポンスボディの一部をコピーして大規模データの消費を回避
val body = response.peekBody(33554432)
extraData["df_response_body"] = body.string()
}
}
override fun onException(e: Exception, extraData: HashMap<String, Any>) {
// 例外を処理
}
}))
.eventListenerFactory(FTResourceEventListener.FTFactory())
.build()
TraceHeader¶
FTTraceConfig.setEnableAutoTrace(true) または FTTraceConfig.setOkHttpTraceHeaderHandler(...) を有効にすると、OkHttp のカスタム Interceptor が優先的に読み込まれます。以下では W3C Trace Context を例に説明します。
ft-sdk < 1.4.1 の場合は、
FTTraceConfig.setEnableAutoTrace(false)を設定してオフにする必要があります。 ft-sdk > 1.6.7 では、カスタム Trace Header と RUM データの関連付けに対応しています。 ft-sdk >= 1.6.17 でgetTraceContext(Request)が追加され、リクエスト Header、traceId、spanIdを一度に返せます。この方式を優先して使用することを推奨します。
推奨する方式:getTraceContext(Request) を使用¶
new OkHttpClient.Builder()
.addInterceptor(new FTTraceInterceptor(new FTTraceInterceptor.HeaderHandler() {
@Override
public TraceContext getTraceContext(Request request) {
HashMap<String, String> headers = FTTraceManager.get()
.getTraceHeader(request.url().toString());
return TraceContext.Simple.fromTraceType(headers);
}
}))
.addInterceptor(new FTResourceInterceptor())
.eventListenerFactory(new FTResourceEventListener.FTFactory())
.build();
OkHttpClient.Builder()
.addInterceptor(
FTTraceInterceptor(object : FTTraceInterceptor.HeaderHandler() {
override fun getTraceContext(request: Request): TraceContext? {
val headers = FTTraceManager.get().getTraceHeader(request.url.toString())
return TraceContext.Simple.fromTraceType(headers)
}
})
)
.addInterceptor(FTResourceInterceptor())
.eventListenerFactory(FTResourceEventListener.FTFactory())
.build()
旧方式との互換:getTraceHeader / getTraceID / getSpanID を個別に実装¶
new OkHttpClient.Builder()
.addInterceptor(new FTTraceInterceptor(new FTTraceInterceptor.HeaderHandler() {
private String[] splits;
@Override
public HashMap<String, String> getTraceHeader(Request request) {
HashMap<String, String> map = new HashMap<>();
String headerString = FTTraceManager.get()
.getTraceHeader(request.url().toString())
// ヘッダーから propagation header を取得
.get(FTTraceHandler.W3C_TRACEPARENT_KEY);
splits = headerString.split("-");
map.put(W3C_TRACEPARENT_KEY, headerString);
return map;
}
@Override
public String getSpanID() {
if (splits != null) {
return splits[2];
}
return null;
}
@Override
public String getTraceID() {
if (splits != null) {
return splits[1];
}
return null;
}
}))
.addInterceptor(new FTResourceInterceptor())
.eventListenerFactory(new FTResourceEventListener.FTFactory())
.build();
OkHttpClient.Builder()
.addInterceptor(
FTTraceInterceptor(object : FTTraceInterceptor.HeaderHandler {
private var splits: Array<String>? = null
override fun getTraceHeader(request: Request): HashMap<String, String> {
val map = HashMap<String, String>()
val headerString = FTTraceManager.get()
.getTraceHeader(request.url.toString())
// ヘッダーから propagation header を取得
.get(FTTraceHandler.W3C_TRACEPARENT_KEY)
splits = headerString?.split("-")?.toTypedArray()
headerString?.let {
map[W3C_TRACEPARENT_KEY] = it
}
return map
}
override fun getSpanID(): String? {
return splits?.getOrNull(2)
}
override fun getTraceID(): String? {
return splits?.getOrNull(1)
}
})
)
.addInterceptor(FTResourceInterceptor())
.eventListenerFactory(FTResourceEventListener.FTFactory())
.build()
OkHttp で ResourceID を追加¶
OkHttp の Request に uuid を追加します。同じリクエストが高頻度で並行実行されるシナリオでは、有効にすることを推奨します。ft-plugin 1.3.5 以上、ft-sdk 1.6.10 以上で FTSDKConfig.setEnableOkhttpRequestTag(true) を有効にすると、Request に ResourceID を自動的に追加できます。