Trace 設定¶

本ドキュメントでは、HarmonyOS Trace の初期化設定と分散型トレーシングについて説明します。

初期化設定¶

import { FTSDK, FTTraceConfig, TraceType } from '@guancecloud/ft_sdk/Index';

const traceConfig = new FTTraceConfig()
  .setSamplingRate(0.8)
  .setTraceType(TraceType.DDTRACE)
  .setEnableAutoTrace(true)
  .setEnableLinkRUMData(true);

FTSDK.installTraceConfig(traceConfig);

メソッド	型	必須	説明
`setSamplingRate`	`number`	いいえ	サンプリングレート。範囲は `[0,1]`、デフォルトは `1`
`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 コンテキストを使用してリクエストヘッダーのインジェクションと 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 を取得する場合は、リクエストヘッダーの生成と追加のみを行います。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 を使用して今回のリクエストのヘッダーインジェクションと RUM Resource の関連付けを行います。

getTraceContext(request) メソッドを使用して Trace Header をカスタマイズすると、リクエストの Header、traceId、spanId を一度に返すことができ、リクエストヘッダーと 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 タイプ	プロトコル	主要なヘッダー
`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`