Trace 設定¶
この記事では、HarmonyOS Trace の初期化設定と分散型トレーシングについて説明します。
サンプリングフィールドの移行(
ft_sdk >= 0.1.18):setTraceSamplingRateは 0~100 の浮動小数点パーセントを使用します。旧setSamplingRateは 0~1 の単位を維持し、移行時には値を 100 倍します。新しいフィールドは明示的に設定された場合にのみ旧フィールドより優先され、不正な値は例外をスローし、以前の有効な値は変更されません。このバージョンより前では引き続き旧メソッドを使用します。非推奨は削除を意味せず、旧メソッドは元の単位と動作を維持します。
初期化設定¶
import { FTSDK, FTTraceConfig, TraceType } from '@guancecloud/ft_sdk/Index';
const traceConfig = new FTTraceConfig()
.setTraceSamplingRate(80)
.setTraceType(TraceType.DDTRACE)
.setEnableAutoTrace(true)
.setEnableLinkRUMData(true);
FTSDK.installTraceConfig(traceConfig);
| メソッド名 | 型 | 必須 | 説明 |
|---|---|---|---|
setTraceSamplingRate |
number |
いいえ | サンプリングレートを設定します。値の範囲は [0,100] で、0 はサンプリングしないこと、100 はすべてサンプリングすることを示します。デフォルト値は 100 で、小数をサポートします。ft_sdk 0.1.18 以降でサポートされます |
setSamplingRate |
number |
いいえ | 非推奨の互換 API です。値の範囲は [0,1] で、デフォルト値は 1 です。setTraceSamplingRate を使用してください |
setTraceType |
TraceType |
いいえ | 分散型トレーシングのタイプです。デフォルトは DDTRACE です |
setEnableLinkRUMData |
boolean |
いいえ | RUM データと関連付けるかどうか。デフォルトは false です |
setEnableAutoTrace |
boolean |
いいえ | 自動 HTTP Trace を有効にするかどうか。デフォルトは false です |
setTraceHeaderHandler |
FTTraceHeaderHandler |
いいえ | グローバルな Trace Header ジェネレーターを設定し、リクエストの Trace Header をカスタマイズするために使用します。getTraceContext(request) を通じて headers、traceId、spanId を一度に返すと、SDK は同一の Trace コンテキストでリクエスト Header の注入と RUM Resource の関連付けを行います。例についてはカスタム Traceを参照してください |
自動トレース¶
setEnableAutoTrace(true) を有効にすると、SDK は RCP Session または HTTP/Axios 経由で SDK インターセプターが設定されたリクエストに Trace Headers を自動的に注入します。
import { rcp } from '@kit.RemoteCommunicationKit';
import { createFTRCPTrackConfig } from '@guancecloud/ft_sdk/Index';
const session = rcp.createSession(createFTRCPTrackConfig({
baseAddress: 'https://api.example.com'
}));
const request = new rcp.Request('/data', 'GET');
const response = await session.fetch(request);
Trace Header の手動取得¶
ビジネスで他のネットワークフレームワークを使用する場合は、Trace Header を手動で取得してリクエストに追加できます。
Trace Header の手動取得は、リクエスト Header の生成と追加のみを行います。RUM Resource を生成して報告する必要がある場合は、SDK が提供する NetworkKit/RCP/Axios インターセプターを使用するか、RUM Resource 関連 API を自身で呼び出して start/stop/addResource を実行してください。
import { FTTraceManager } from '@guancecloud/ft_sdk/Index';
import http from '@ohos.net.http';
const url = 'https://api.example.com/data';
const resourceId = 'unique-resource-id';
const traceHeaders: Record<string, string> = FTTraceManager.getInstance().getTraceHeader(resourceId, url);
const httpRequest = http.createHttp();
const response = await httpRequest.request(url, {
method: http.RequestMethod.GET,
header: traceHeaders
});
NetworkKit/RCP/Axios による TraceHeader のカスタマイズ¶
FTTraceConfig.setEnableAutoTrace(true) を有効にすると、SDK は NetworkKit/RCP/Axios インターセプターチェーンで Trace Header を自動的に注入します。同時に FTTraceConfig.setTraceHeaderHandler(...) を設定した場合、SDK は Trace Header の生成時にカスタム Handler を呼び出し、Handler が返す headers、traceId、spanId を使用して今回のリクエストの Header 注入と RUM Resource の関連付けを行います。
getTraceContext(request) 方式で Trace Header をカスタマイズすると、リクエストの Header、traceId、spanId を一度に返すことができ、リクエスト Header と RUM Resource の関連付けが同じ Trace コンテキストを使用することを保証できます。
import {
FTSDK,
FTTraceConfig,
FTTraceManager,
FTTraceHeaderHandler,
FTTraceRequestContext,
FTTraceContext,
TraceType
} from '@guancecloud/ft_sdk/Index';
class CustomTraceHeaderHandler implements FTTraceHeaderHandler {
getTraceContext(request: FTTraceRequestContext): FTTraceContext {
const traceContext = FTTraceManager.getInstance().getTraceContextDirect(request.url);
traceContext.traceId = this.getHeaderValue(request.headers, 'x-existing-trace-id');
traceContext.spanId = this.getHeaderValue(request.headers, 'x-existing-span-id');
return traceContext;
}
private getHeaderValue(headers: Record<string, string>, key: string): string {
const directValue = headers[key];
if (directValue !== undefined) {
return directValue;
}
const normalizedKey = key.toLowerCase();
const headerKeys = Object.keys(headers);
for (let i = 0; i < headerKeys.length; i++) {
const headerKey = headerKeys[i];
if (headerKey.toLowerCase() === normalizedKey) {
return headers[headerKey];
}
}
return '';
}
}
import { FTSDK, FTTraceConfig, TraceType } from '@guancecloud/ft_sdk/Index';
const traceConfig = new FTTraceConfig()
.setEnableAutoTrace(true)
.setTraceType(TraceType.TRACEPARENT)
.setTraceHeaderHandler(new CustomTraceHeaderHandler());
FTSDK.installTraceConfig(traceConfig);
Trace タイプ¶
| Trace タイプ | プロトコル | 主な Headers |
|---|---|---|
DDTRACE |
DataDog Trace | x-datadog-trace-id、x-datadog-parent-id、x-datadog-origin、x-datadog-sampling-priority |
ZIPKIN_MULTI_HEADER |
Zipkin Multi-Header | X-B3-TraceId、X-B3-SpanId、X-B3-ParentSpanId、X-B3-Sampled |
ZIPKIN_SINGLE_HEADER |
Zipkin Single-Header | b3 |
JAEGER |
Jaeger | uber-trace-id |
TRACEPARENT |
W3C Trace Context | traceparent、tracestate |
SKYWALKING |
SkyWalking | sw8 |