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)も同時に有効にすることを推奨します - ログ量が多い場合は、サンプリングレートとレベルフィルタリングによってレポート量を制御できます