コンテンツにスキップ

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

フィードバック

このページは役に立ちましたか?