ミニアプリログ収集¶

ミニアプリ Logs SDK は、Guance に業務ログを送信し、コンソール、ランタイム、ネットワークエラーを自動収集するためのものです。ログは browser_log ソースに書き込まれ、ログエクスプローラーで検索できます。MiniApp RUM SDK と併用すると、アプリ、セッション、ページ、ユーザー情報と関連付けることができます。

本記事では、SDK 1.0.6 の導入方法と動作について説明します。バージョン変更については SDK 更新ログを参照してください。

はじめに¶

1. インストールとインポート¶

npm によるインストールを推奨し、datafluxLogs エントリを使用します：

npm install @cloudcare/dataflux-rum-miniapp-logs

アプリのエントリで SDK をインポートし、業務ログとリクエストが発生する前に初期化を完了してください。ネイティブミニアプリ開発ツールを使用する場合は、ツールの要件に従って npm ビルドを実行してください。

const { datafluxLogs } = require('@cloudcare/dataflux-rum-miniapp-logs')

SDK ファイルをダウンロードして、ミニアプリプロジェクトに配置し、ローカルパスからインポートすることもできます。以下のパスは、ファイルの実際の場所に合わせて調整してください：

const { datafluxLogs } = require('./dataflux-rum-miniapp-logs.js')

SDK は利用可能な wx、my、swan、tt、uni リクエストインターフェースを自動的に選択し、それぞれ WeChat、Alipay、Baidu、Douyin、uni ホストに対応します。複数のインターフェースが同時に存在する場合は、上記の順序で選択されます。uni プロジェクトを使用する場合は、ミニアプリ側のコードでインポートと初期化を行ってください。デバイス、ネットワーク、ストレージ、ライフサイクルインターフェースが欠落している場合は、個別にフォールバックします。利用可能なリクエストインターフェースがない場合はログを収集せず、初期化に関するヒントを出力します。

SDK はミニアプリホスト上で動作し、インストールパッケージに engines.node の制限は設定されません。Node.js は開発段階のビルド、テスト、リリースツールにのみ使用され、そのバージョンは対応する開発依存関係の要件を満たす必要があります。

2. 初期化¶

いずれかの報告方法を選択し、アプリのライフサイクル内で一度だけ初期化します。報告アドレスはミニアプリからアクセス可能である必要があり、ターゲットプラットフォームの要件に従ってリクエストドメインを設定してください。

DataKitパブリック DataWay

アクセス可能な DataKit アドレスを設定します。datakitOrigin にはプロトコル、ドメイン名または IP、およびオプションのポートを指定し、/v1/write/logging を付けないでください。

datafluxLogs.init({
  datakitOrigin: 'https://datakit.example.com',
  applicationId: '<APPLICATION_ID>',
  service: 'miniapp',
  env: 'prod',
  version: '1.0.0'
})

applicationId はアプリを識別するために使用され、必要に応じて入力できます。DataKit のデプロイとネットワーク設定については DataKit ツール説明を参照してください。

Guance コンソールからサイトアドレスとクライアントトークンを取得し、site と clientToken を設定します。この方法では datakitOrigin を入力する必要はありません。

datafluxLogs.init({
  site: '<PUBLIC_DATAWAY_URL>',
  clientToken: '<CLIENT_TOKEN>',
  applicationId: '<APPLICATION_ID>',
  service: 'miniapp',
  env: 'prod',
  version: '1.0.0'
})

init() を繰り返し呼び出しても設定は更新されません。silentMultipleInit: true は重複初期化時のヒントを無効化するだけで、初期化結果は変わりません。

3. ログの送信と確認¶

初期化後、同じモジュールで datafluxLogs を使用します。他のページでは、前述の方法で同じ SDK モジュールをインポートできます。

datafluxLogs.logger.info('应用启动', { entry: 'home' })
datafluxLogs.logger.warn('库存不足', { product_id: 'product-123' })
datafluxLogs.logger.error('支付失败', { order_id: 'order-123' })

ログはバッチで送信され、デフォルトでは 30 秒ごとに送信を試行します。バッチしきい値に達した場合やアプリがバックグラウンドに移行した場合も送信がトリガーされます。ログエクスプローラーを開き、ソース browser_log、service、ログ本文、カスタムフィールドで検索してください。

設定¶

初期化パラメータ¶

パラメータ	型	デフォルト値	説明
`datakitOrigin`	String	—	DataKit の報告アドレス。DataKit を使用する場合は `datakitUrl` との少なくともいずれかを指定し、このパラメータが優先されます。
`datakitUrl`	String	—	`datakitOrigin` の互換エイリアス。
`site`	String	—	パブリック DataWay の報告アドレス。パブリック DataWay を使用する場合に必須です。
`clientToken`	String	—	パブリック DataWay のクライアントトークン。`site` と組み合わせて使用し、空にすることはできません。
`applicationId`	String	—	Logs を単独で使用する場合のアプリ ID で、`app_id` に対応します。RUM と関連付ける場合は、ログが発生した時点の RUM アプリコンテキストを使用します。
`service`	String	`miniapp`	ログが属するサービス名。
`env`	String	空文字列	アプリの実行環境。例: `prod`、`pre`、`local`。
`version`	String	空文字列	業務アプリのバージョン番号。SDK パッケージのバージョンとは異なります。
`sampleRate`	Number	`100`	HTTP ログ報告のセッションサンプリングレート。`0`–`100` の範囲で指定します。`0` は報告なし、`100` は全量報告を意味します。
`forwardErrorsToLogs`	Boolean	`true`	コンソール、ランタイム、ネットワークエラーを自動収集するかどうか。`false` に設定しても手動ログ API には影響しません。
`rumIntakeUrls`	String[]	`[]`	オプション。自動ネットワークエラー収集から追加で除外する完全な RUM アップロード URL。RUM と Logs で異なる収集アドレスを使用する場合に指定します。
`silentMultipleInit`	Boolean	`false`	重複初期化時のヒントを無効化するかどうか。初期化結果は変わりません。

選択した報告方法で必要なアドレスとトークン以外のパラメータはすべてオプションです。サンプリングは SDK 初期化時に決定され、同じ実行インスタンス内ではその結果が使用されます。ログごとに独立してランダムサンプリングされるわけではありません。

1.0.6 以降、未実装の初期化オプション tags、trackInteractions、allowedTracingOrigins、traceId128Bit、traceType は削除されました。カスタムフィールドはコンテキスト API を使用し、インタラクションとトレース収集は RUM SDK で設定します。

使用方法¶

ログレベル¶

デフォルトの Logger は datafluxLogs.logger で、デフォルトレベルは debug、デフォルトでは HTTP で報告されます。対応するメソッドを直接呼び出せます：

メソッド	ログの `status`	使用例
`logger.debug(message, context)`	`debug`	デバッグ情報。
`logger.info(message, context)`	`info`	業務イベントや実行情報。
`logger.warn(message, context)`	`warning`	回復可能な例外や業務アラート。
`logger.error(message, context)`	`error`	業務の失敗やエラー。
`logger.critical(message, context)`	`critical`	重大なエラー。

message は文字列、context はオプションのフィールドオブジェクトです。log(message, context, status) を使用してレベルを明示的に指定することもできます。status を省略した場合は info になります。warn() に対応するステータス値は warning であることに注意してください：

datafluxLogs.logger.log('库存不足', { product_id: 'product-123' }, 'warning')

setLevel() を使用して最低レベルを設定すると、そのレベルより低いログは出力されません。レベルの順序は debug → info → warning → error → critical です：

datafluxLogs.logger.setLevel('warning')

カスタム Logger¶

業務モジュールごとに Logger を作成し、レベル、出力方法、永続コンテキストをそれぞれ設定できます：

const paymentLogger = datafluxLogs.createLogger('payment', {
  level: 'info',
  handler: 'http',
  context: { module: 'payment' }
})

paymentLogger.info('创建订单', { order_id: 'order-123' })

createLogger(name, configuration) は作成された Logger を返します。その後、getLogger(name) で取得できます。作成されていない名前の場合は undefined を返します。configuration 内の level、handler、context は省略可能で、デフォルトはそれぞれ debug、http、空オブジェクトです。

setHandler() を使用して出力方法を切り替えます：

`handler`	動作
`http`	SDK のバッチでログを報告します。
`console`	`console.log` を呼び出して、レベル、本文、Logger/単一ログのコンテキストを出力します。HTTP 報告は行われません。
`silent`	この Logger のログを出力しません。

const paymentLogger = datafluxLogs.getLogger('payment')
if (paymentLogger) {
  paymentLogger.setHandler('console')
}

自動収集されたエラーはデフォルトの Logger で出力されるため、datafluxLogs.logger のレベルや出力方法を変更すると、自動エラーログにも影響します。名前付き Logger の設定はその Logger にのみ適用されます。

カスタムフィールド¶

カスタムフィールドは、グローバルコンテキスト、Logger コンテキスト、単一ログコンテキストのいずれかに配置できます。HTTP 報告時、同じ名前のカスタムフィールドはグローバル → Logger → 単一ログの順に上書きされます。

グローバルコンテキストは、すべての Logger の HTTP ログに適用されます：

datafluxLogs.setLoggerGlobalContext({ tenant: 'example' })
datafluxLogs.addLoggerGlobalContext('region', 'cn')
const globalContext = datafluxLogs.getLoggerGlobalContext()
datafluxLogs.removeLoggerGlobalContext('region')

Logger コンテキストは、対応する Logger にのみ適用されます：

datafluxLogs.logger.setContext({ team: 'payments' })
datafluxLogs.logger.addContext('channel', 'miniapp')
datafluxLogs.logger.removeContext('channel')

setLoggerGlobalContext() と setContext() は、対応するコンテキスト全体を置き換えます。add...Context() はフィールドを追加または置き換え、remove...Context() はフィールドを削除します。グローバルコンテキストの取得は独立したスナップショットを返すため、返されたオブジェクトを変更しても SDK 内部に保存されたデータは変更されません。

単一ログコンテキストは、この呼び出しのみに適用されます：

datafluxLogs.logger.info('支付完成', {
  order_id: 'order-123',
  amount: 0,
  paid: true,
  customer: { id: 'customer-123' },
  items: ['product-123']
})

フィールドはスカラー、オブジェクト、配列に対応しています。0、false などの有効な値は保持されます。オブジェクトと配列は報告時に JSON 文字列にシリアライズされ、BigInt は正確な十進数の文字列として送信されます。通常の業務フィールドはコンテキストのルートレベルに直接配置でき、tags: { ... } 形式にも対応しています。ここでの tags も最終的にはカスタムログフィールドとして送信されます。

コンテキストは独立したスナップショットを採用しています。toJSON(key) を持つオブジェクトは、元のインスタンス上で実際のフィールド名に従ってシリアライズが実行され、その結果が保存されるため、プライベートフィールドを持つマスキング処理にも対応します。通常のフィールドでマスキングに失敗した場合はエラープレースホルダー値が使用され、マスキング前の元オブジェクトにはフォールバックしません。

HTTP ログのルートコンテキストとネストされた tags は辞書形式の結果のみを受け付けます。無効な結果は無視され、有効な永続フィールドが保持されます。永続コンテキストを設定する際、ルートのマスキング処理が失敗した場合や非辞書を返した場合は、空の辞書にリセットされます。単一ログは永続コンテキストを変更しません。

業務フィールドは message、status、service などの標準フィールドと同じ名前を避けてください。同じ名前の業務データは business オブジェクトに配置できます。message と status はログ呼び出しのパラメータで決まり、type は SDK 内部のログタイプに固定されており、コンテキストで置き換えることはできません。

エラーの手動記録¶

logger.error() は本文とコンテキストを受け取ります。Error のスタックを記録する必要がある場合は、error.stack に明示的に配置します：

const error = new Error('支付接口超时')
datafluxLogs.logger.error(error.message, {
  order_id: 'order-123',
  error: { stack: error.stack }
})

手動で記録されたエラーは、デフォルトで error_source=logger として報告されます。単一ログに明示的に渡された error.source はデフォルトのソースを上書きできます。自動エラーは実際のソースが保持されます。

自動エラー収集¶

デフォルトで有効です。forwardErrorsToLogs: false で無効化できます。収集機能はホストが提供する API に依存します：

ソース	収集内容
コンソール	`console.error()` の本文と引数。`console.log()`、`info()`、`warn()` は自動収集されません。
ランタイム	ホストのエラーイベント、未処理の Promise 拒否、および対応するページ不存在・メモリ警告イベント。
ネットワーク	`request`、`downloadFile` のネットワーク失敗、および HTTP ステータスコードが `500` 以上のレスポンス。後述のコールバック範囲の制限を受けます。

ネットワークエラーの自動収集には、業務呼び出しで success、fail、complete のいずれかのコールバックが提供され、安全にコピーできる通常のパラメータオブジェクトが使用されている必要があります。凍結オブジェクト、プロトタイプが空の辞書、非列挙のデータプロパティ、Symbol メタデータ、リアクティブ Proxy の有効な値は保持できます。元のコールバックパラメータ、戻り値、例外、ネイティブの task/Promise は変更されません。

以下の場合、リクエスト完了ログは自動生成されません：

呼び出しがコールバックを一切提供しない場合。SDK はコールバックを注入せず、業務 Promise の読み取りやサブスクライブも行いません。元の戻りパターンと未処理の拒否イベントを保持するためです。
パラメータにアクセサまたは特殊なプロトタイプが含まれる場合。SDK は元のパラメータをホストに渡し、元の読み取り動作を保持します。
リクエストが Logs 自身または除外された RUM アップロードアドレスに属する場合。

HTTP 4xx はステータスコードのみでエラーログを生成しません。業務で捕捉済みの失敗は logger.error() で手動記録できます。未処理の拒否はホストのランタイムフックで引き続き収集できます。成功したリクエストと除外されたアップロードリクエストはレスポンス本文を読み取りません。

RUM との連携¶

Logs は単独で使用できます。ユーザーアクセスコンテキストを関連付ける必要がある場合は、MiniApp RUM 導入ドキュメントに従って RUM SDK を初期化します。RUM コンテキストが利用可能な場合、ログには対応するアプリ、セッション、ページ、アクション、ユーザー情報が付与されます。利用できない場合でも、独立したログを報告できます。

SDK はログが発生した時点の RUM コンテキストを取得します。遅延エラーの履歴情報が欠落または失効している場合は、対応するフィールドを省略し、現在のページで置き換えることはありません。RUM の関連付けがない場合、通常の即時ログには現在のページルートを付与できますが、RUM ページ ID が自動的に生成されることはありません。

Logs は自身のアップロードアドレスと、同じ収集アドレス配下の /v1/write/rum を自動的に除外します。RUM と Logs が異なるドメイン、ポート、プロキシパスを使用する場合は、オプションの rumIntakeUrls を設定して、アップロード失敗時に相互収集されるのを防ぎます：

datafluxLogs.init({
  datakitOrigin: 'https://logs.example.com',
  rumIntakeUrls: ['https://rum.example.com/v1/write/rum']
})

上記の設定は最初の init() に組み込んでください。初期化を繰り返さないでください。リストは完全な HTTP(S) URL のみを受け付け、初期化時にスナップショットが保存され、無効な項目は無視されます。比較時はプロトコル、ホスト名の大文字小文字、デフォルトポートを統一し、query/fragment を無視して、完全なパスとその大文字小文字を保持します。同じドメイン配下の他の業務パスは除外されません。

報告フィールド¶

logger.log() などのログ記録メソッドは void を返し、ログオブジェクトは返しません。SDK はデータを browser_log ソースに書き込みます。以下はログエクスプローラーでよく使用されるフィールドであり、固定のネストされた JSON 戻り構造ではありません。

フィールド	内容
`message`、`status`、`service`	本文、レベル、サービス名。
`sdk_name`、`sdk_version`	SDK 名とパッケージバージョン。
`app_id`、`env`、`version`	アプリ ID、実行環境、業務バージョン。
`session_id`	Logs のセッション識別子。RUM と関連付ける場合はそのセッション情報を使用します。
`view_id`、`view_name`、`view_referer`、`action_id`	利用可能なページ、参照元ページ、アクション情報。`view_name` はページルートに対応します。
`userid`、`user_name`、`user_email`	RUM コンテキストで利用可能なユーザー情報。
`platform`、`platform_version`、`app_framework_version`	ミニアプリホストの種類、ホストバージョン、基本ライブラリバージョン。
`device`、`model`、`device_uuid`、`os`、`os_version`、`network_type`	デバイスブランド、モデル、匿名インストール識別子、オペレーティングシステム、ネットワーク情報。
`error_source`、`error_type`、`error_stack`	エラーのソース、タイプ、スタック。実際のエラー内容に応じて提供されます。
`error_resource_url`、`error_resource_method`、`error_resource_status`	ネットワークエラーに対応するリクエストアドレス、メソッド、ステータスコード。
カスタムフィールド	例: `order_id`、`amount`、`paid`。書き込み時は有効な値を保持し、標準フィールドと同じ名前を避けてください。

platform はミニアプリホストを表し、オペレーティングシステムは os などの独立したフィールドを使用します。device_uuid は SDK が生成してローカルストレージに保存する匿名インストール識別子で、ホストの AppID やハードウェア ID ではありません。ストレージをクリアすると再生成され、ストレージが利用できない場合は現在の実行期間中のみ安定します。

報告タイミングと制限¶

動作	説明
周期送信	デフォルトでは 30 秒ごとにキャッシュされたログの送信を試行します。
バッチ送信	50 件または約 16 KiB のバッチしきい値に達すると、事前に送信します。
バックグラウンド送信	ホストが `onAppHide` をサポートしている場合、アプリがバックグラウンドに移行すると送信がトリガーされます。
単一ログサイズ	シリアライズ後の単一ログは 256 KiB 未満である必要があります。制限を超えたログは破棄されます。
エラー頻度制限	同じ SDK インスタンスは 1 分間のウィンドウ内で最大 3000 件の `status=error` ログを報告できます。超過すると頻度制限のヒントが 1 回記録され、ウィンドウがリセットされると復旧します。
送信失敗	ログはベストエフォートで配信されます。ローカルの永続キュー、失敗時の自動リトライ、配信保証は提供されません。

これらは SDK の組み込み送信動作であり、公開された初期化オプションではありません。大きなオブジェクトやレスポンス本文は単一ログのサイズを増加させるため、調査に必要な業務フィールドのみを記録することを推奨します。

よくある質問¶

現象	確認方法
初期化してもログが出力されない	アドレスとトークン、リクエストドメイン、ネットワークを確認してください。SDK が業務呼び出し前に初期化されていること、`sampleRate` が `0` でないこと、Logger レベルが該当ログを許可していること、`handler` が `http` であることを確認します。周期送信を待つか、ホストがサポートしている場合はバックグラウンドに切り替えて送信をトリガーします。
コンソールには出力されるが、ログプラットフォームに記録されない	`handler: 'console'` を使用していないか確認してください。通常の `console.log()` は自動報告されません。
Promise リクエストが失敗してもネットワークログがない	コールバックなしの呼び出しではないか、エラーが業務で捕捉済みでないか確認してください。必要に応じて `logger.error()` を明示的に呼び出します。
エラーが RUM ページに関連付けられていない	RUM が初期化されているか、該当時点のコンテキストが存在するか確認してください。独立した Logs ログは RUM ページレコードを自動的に作成しません。
アップグレード後に設定項目で型エラーが発生する	初期化パラメータ表を確認して未実装のオプションを削除し、カスタムフィールドはコンテキスト API で追加してください。

SDK 更新ログ¶

1.0.6（2026-09-09）¶

機能と互換性¶

WeChat、Alipay、Baidu、Douyin、uni ホストの自動検出と、デバイス、ネットワーク、ストレージ、ライフサイクルインターフェースの互換処理を改善しました。オプションのインターフェースが利用できない場合は安全にフォールバックします。
Logs を単独で使用する場合、applicationId によるアプリ ID の報告をサポートしました。RUM と関連付ける場合は、ログが発生した時点のコンテキストを取得し、遅延エラーが現在のページやセッションに関連付けられるのを防ぎます。
独立した収集アドレスの RUM アップロードを除外するためのオプション rumIntakeUrls を追加しました。同じ収集アドレス配下の Logs/RUM アップロードは自動的に除外され、アップロード失敗後に相互収集されるのを防ぎます。
公開 TypeScript 宣言と配布パッケージの型エントリを追加しました。engines.node のインストール制限を削除し、SDK は実行時に Node.js に依存しません。リポジトリのビルド、テスト、リリースツールは引き続き各開発依存関係の Node.js 要件を満たす必要があります。

問題の修正¶

リクエストとダウンロードのインターセプトが元のパラメータ、業務コールバック、返された task/Promise、未処理の拒否イベントに与える影響を修正しました。リアクティブパラメータの有効な値を保持し、収集例外が業務呼び出しに影響しなくなります。成功したリクエストと除外されたアップロードリクエストはレスポンス本文を読み取りません。
コンテキストの改ざん、危険な属性のマージ、マスキング結果の誤った再利用を修正しました。元のオブジェクト上で実際のフィールド名に従って toJSON(key) を実行し、独立したスナップショットを保存します。プライベートフィールドのマスキング処理、オブジェクト、配列、BigInt をサポートします。
ルートコンテキストとネストされた tags が非辞書を返したりマスキングに失敗した際に、数字フィールドが生成されたり既存フィールドが失われる問題を修正しました。無効なコンテキストはマスキング前の元の値にフォールバックせず、単一ログは永続コンテキストを変更しません。
ランタイムエラーと未処理の拒否で、複数行の本文、元のスタック、ネットワーク診断フィールドが失われる問題を修正しました。手動エラーログのデフォルトソースが logger として正しく報告され、自動エラーは実際のソースが保持されます。
報告フィールドのエスケープ、Unicode バイト数のカウント、0/false などの有効な値の欠落、バッチの再入問題を修正しました。アプリがバックグラウンドに移行した際にログを即時フラッシュします。platform がホストを正しく表し、device_uuid はローカルに永続化された匿名インストール識別子を使用します。

アップグレードに関する注意¶

未実装の初期化オプション tags、trackInteractions、allowedTracingOrigins、traceId128Bit、traceType を削除しました。カスタムフィールドにはコンテキスト API を使用し、インタラクションとトレース収集は RUM SDK で設定します。
コールバックなしの呼び出し、およびアクセサや特殊なプロトタイプを含むリクエストパラメータは、ホストの元の動作を維持し、リクエスト完了ログを自動生成しません。業務で捕捉済みの失敗は logger.error() で手動記録でき、未処理の拒否は引き続きホストのランタイムフックで収集できます。