コンテンツにスキップ

Log 設定

このページでは HarmonyOS Log の初期化設定について説明します。

サンプリングフィールドの移行(ft_sdk >= 0.1.18):setLogSamplingRate は 0~100 の浮動小数点パーセントを使用します。旧 setSamplingRate は 0~1 の単位を維持するため、移行時は値を 100 倍してください。新しいフィールドは明示的に設定された場合にのみ旧フィールドより優先されます。不正な値は例外をスローし、それ以前の有効な値は変更されません。このバージョンより前では引き続き旧メソッドを使用します。非推奨は削除を意味せず、旧メソッドは元の単位と動作を維持します。

初期化設定

import { FTSDK, FTLoggerConfig, Status } from '@guancecloud/ft_sdk/Index';

const logConfig = new FTLoggerConfig()
  .setLogSamplingRate(100)
  .setEnableCustomLog(true)
  .setEnableConsoleLog(true, '[business]')
  .setLogLevelFilters([
    Status.ERROR,
    Status.WARN,
    Status.INFO,
    Status.DEBUG
  ])
  .setEnableLinkRumData(true)
  .addGlobalContext('log_source', 'business')
  .setLogCacheLimitCount(10000);

FTSDK.installLogConfig(logConfig);
メソッド名 型 必須 説明
setLogSamplingRate number いいえ ログの収集率を設定します。値の範囲は [0,100] で、0 は収集しない、100 はすべて収集することを意味します。デフォルト値は 100 で、小数をサポートします。ft_sdk 0.1.18 以降でサポートされます
setSamplingRate number いいえ 非推奨の互換 API です。値の範囲は [0,1]、デフォルト値は 1 です。setLogSamplingRate に置き換えてください
setEnableCustomLog boolean いいえ カスタムログを有効にするかどうか。デフォルトは false
setPrintCustomLogToConsole boolean いいえ FTLogger.logBackground(...) のカスタムログを同時に HiLog に出力するかどうか。デフォルトは false。setEnableCustomLog(true) と SDK の setDebug(true) を有効にする必要があり、出力は setSdkLogLevel(...) で制御されます。詳細はカスタムログを HiLog に出力を参照してください
setEnableConsoleLog enable: boolean, prefix?: string いいえ コンソールログをレポートするかどうか。この設定は Hvigor Plugin に依存し、デフォルトは false。console.log、debug、info、warn、error、trace、および @ohos.hilog または @kit.PerformanceAnalysisKit からインポートした hilog.debug、info、warn、error、fatal をサポートします。ログレベルの対応関係は次のとおりです:log、info -> info、debug、trace -> debug、warn -> warn、error -> error、fatal -> fatal。prefix には通常のメッセージプレフィックス、または { で始まる DataKit 収集ルールを指定できます。詳細はコンソールログのフィルタリングを参照してください。この機能には ft-sdk 0.1.17 以降と @cloudcare/hvigor-ohos-plugin 0.1.1 以降が必要です
setEnableLinkRumData boolean いいえ RUM データを関連付けるかどうか。デフォルトは false
setLogLevelFilters Array<Status \| string \| { name: string }> いいえ ログレベルのフィルタリング。指定可能な値:ERROR、WARN、INFO、DEBUG
addGlobalContext Dictionary いいえ Log のグローバルプロパティを追加します。key,value をサポートします。追加ルールはこちらを参照してください
addGlobalContext key: string, value: object いいえ Log のグローバルプロパティを追加します。追加ルールはこちらを参照してください
setLogCacheLimitCount number いいえ ログデータのキャッシュ数上限。デフォルトは 5000、最小値は 1000
setLogCacheDiscardStrategy LogCacheDiscard いいえ ログが上限に達した後のログ破棄ルールを設定します。デフォルトは LogCacheDiscard.DISCARD です。DISCARD は追加データを破棄し、DISCARD_OLDEST は古いデータを破棄します

コンソールログのフィルタリング

setEnableConsoleLog(true, prefix) の第 2 引数は、自動収集される console.* と hilog.* のログをフィルタリングするために使用します:

  • 通常の文字列を渡した場合は互換動作を維持し、メッセージがその文字列で始まるログのみを収集します。渡さない場合はフィルタリングしません。
  • 最初の非空白文字が { の文字列を渡した場合は、DataKit ルール構文に従って許可ルールとして処理します。ルールに一致したログは SDK のキューに入り、一致しないログはキューに入る前に破棄されます。複数のルールブロックの間は「OR」の関係です。

ルールでは message、log_source(console または hilog)を使用できます。hilog では tag と domain も使用できます。ログレベルは引き続き setLogLevelFilters(...) で個別に制御されます。

const logConfig = new FTLoggerConfig().setEnableConsoleLog(true,
  "{ log_source = 'hilog' and tag = 'Network' and message match ['^HTTP'] }");

Logger ログ出力

FTLogger を使用してカスタムログをレポートする前に、setEnableCustomLog(true) を有効にする必要があります。1 件のログ内容は最大 30 KB で、超過分は切り捨てられます。

使用方法

/**
 * 単一のカスタムログをレポートします。
 *
 * @param content ログ内容。
 * @param status ログレベル。`Status` またはレベル文字列を指定できます。
 * @param property 追加プロパティ(オプション)。
 * @param isSilence サイレント処理するかどうか(オプション)。
 */
FTLogger.logBackground(
  content: string,
  status: Status | string,
  property?: Map<string, object>,
  isSilence?: boolean
): void

コード例

import { FTLogger, Status } from '@guancecloud/ft_sdk/Index';

// 単一のログをアップロードします。
FTLogger.logBackground('登录成功', Status.INFO);

// 追加プロパティを渡します。
const property = new Map<string, object>();
property.set('user_id', new String('user-001'));
FTLogger.logBackground('支付完成', Status.INFO, property);

ログレベル

メソッド名 説明
Status.TRACE トレース
Status.DEBUG デバッグ
Status.INFO 情報
Status.WARN 警告
Status.ERROR エラー
Status.FATAL 致命的

使用上の推奨事項

  • setLogLevelFilters(...) は FTLogger のビジネス Log のレポートレベルを制御し、SDK 内部診断ログの setSdkLogLevel(...) とは互いに独立しています
  • setEnableConsoleLog(...) と setEnableCustomLog(...) は互いに独立しています。前者は console.* と hilog.* のログを自動収集するためのもので、Hvigor Plugin のインストールと設定が必要です。後者は FTLogger でカスタムログを手動レポートするためのもので、プラグインのインストールは不要です
  • デバッグ段階では、setEnableCustomLog(true)、setDebug(true)、および SDK デバッグログ を組み合わせて収集経路を検証できます
  • ログをユーザー行動、ページ、リソースのデータと関連付けて分析したい場合は、setEnableLinkRumData(true) も同時に有効にすることを推奨します
  • ログ量が多い場合は、サンプリングレートとレベルフィルタリングによってレポート量を制御できます

フィードバック

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