lynx-trace-record

1. ワークフローの例

記録プロセスでは、trace_record CLI ツールを使用する必要があります。操作の順序は非常に重要です。

Step 1. 接続済みクライアントを一覧表示する：

まず、接続済みのクライアントをすべて一覧表示して、クライアント ID を取得します。これにより、トレースするアプリを特定できます。

• 接続済みクライアントが複数ある場合は、トレースするクライアント ID をユーザーに指定してもらいます。その後、この ID を --client パラメーターに指定してトレースします。
• 接続済みクライアントが 1 つだけの場合は、--client パラメーターを省略できます。
• クライアントが見つからない場合は、デバイスを USB で接続し、デバッグアプリを開くようユーザーに促します。

  node <path_to_the_skill>/scripts/trace_record.bundle.cjs list-clients
  

Step 2. 記録を開始する：

デバイスでページをビルドまたは開く前に、開始コマンドを実行します。これにより、ページの最初のフレーム全体を確実に記録できます。Step 1 で取得したクライアント ID を --client パラメーターに指定します。

node <path_to_the_skill>/scripts/trace_record.bundle.cjs start --client <client-id>

開始時のオプションパラメーターは、ユーザーの自然言語によるリクエストに基づいて設定できます：

ユーザーの意図	CLI パラメーター	トレース設定フィールド	デフォルト
特定のトレースカテゴリのみを含める	--include-categories <categories>	includedCategories	*
特定のトレースカテゴリを除外する	--exclude-categories <categories>	excludedCategories	*
メモリデータの収集を有効にする	--enable-memory-trace	enableMemoryTrace	false
自動ガベージコレクションを無効にする	--no-force-gc	forceGC	true
「shared-group」VM のヒープスナップショットを自動的に取得する	--enable-auto-heap-snapshot	enableAutoHeapSnapshot	false
特定の「shared-group」VM のヒープスナップショットのみを自動取得する	--shared-group-id <id>	sharedGroupId	空の文字列
quickjs や v8 などの JS プロファイルタイプを指定する	--js-profile-type <type>	JSProfileType	空の文字列（JS プロファイルは無効）
JS プロファイルの間隔を指定する（例：100）	--js-profile-interval <interval>	JSProfileInterval	JSProfileType が空でなく、間隔が <= 0 の場合は 100、それ以外は -1

ユーザーが自然言語でリクエストした場合は、その内容を対応する start フラグに変換します。たとえば、ユーザーが「trace_record でトレースを記録し、メモリデータの収集を有効にして、'xxx' という名前の VM のヒープスナップショットを自動的に取得して」と言った場合は、次を実行します：

node <path_to_the_skill>/scripts/trace_record.bundle.cjs start --client <client-id> --enable-memory-trace --enable-auto-heap-snapshot --shared-group-id xxx

一般的なトレースカテゴリは lynx、vitals、javascript、jsb、devtool です。特定のイベントカテゴリのみを含めるようユーザーから求められた場合は、--include-categories にカンマ区切りのリストを渡します。たとえば、「录制trace时只允许以下类型的事件js，jsb」は --include-categories lynx,jsb に対応します。ユーザーが「录制trace时允许所有事件」と求めた場合は、--include-categories を渡しません。デフォルトの includedCategories: ['*'] により、すべてのイベントが記録されます。

特定のイベントカテゴリを除外するようユーザーから求められた場合は、--exclude-categories にカンマ区切りのリストを渡します。たとえば、「录制trace时关闭devtool事件和vitals事件」は --exclude-categories devtool,vitals に対応します。

「v8 JS profile で記録して」のように、特定の JS エンジンプロファイルタイプを使用するようユーザーから求められた場合は、--js-profile-type v8 を追加します。JS プロファイルの収集を求められていない場合は、--js-profile-type を渡しません。デフォルトの空の文字列では、JS プロファイルの収集は無効になります。

「JS profile interval 100 で記録して」のように、特定の JS プロファイル間隔を使用するようユーザーから求められた場合は、--js-profile-interval 100 を追加します。たとえば、「v8 JS profile と interval 100 で記録して」は --js-profile-type v8 --js-profile-interval 100 に対応します。

Step 3. ページをビルドして開く

開発サーバーを起動します。ページが自動で開かない場合は、対象のページを手動で開きます。

  pnpm run dev

Step 4. 操作を実行する

インタラクション（スクロール、クリック、データ更新など）をデバッグする場合は、ここでデバイス上で操作を実行します。

Step 5. 記録を停止してストリームハンドルを取得する

トレースの記録を停止します。CLI は stream フィールドを含む JSON レスポンスを出力します（これがストリームハンドルです）。Step 1 と同じクライアント ID を --client パラメーターに指定します。

node <path_to_the_skill>/scripts/trace_record.bundle.cjs end --client <client-id>

ステップ 6. トレースデータの読み取りと保存

ステップ 5 で取得したストリームハンドルを使用して、トレースファイルをダウンロードし、ローカルマシンに保存します。ステップ 1 と同じクライアント ID を指定して、--client パラメーターを使用してください。

node <path_to_the_skill>/scripts/trace_record.bundle.cjs readData --client <client-id> --stream <stream-handle> --output ./my-trace.pftrace

2. よくあるエラーのトラブルシューティング

「トレース機能を有効にするには、アプリを再起動してください」

enable_debug_mode がオフでした。CLI は自動的に有効にしようとしました。解決方法：デバイス上のアプリを強制終了して再起動し、ステップ 1 から再度記録してください。

「現在のバージョンではトレース機能はサポートされていません」

Lynx の開発版を使用していることを確認してください。詳しくは、こちらをご覧ください：https://lynxjs.org/guide/start/integrate-lynx-dev-version.html

「トレースが開始されていません。先にトレースを開始してください」

end と readData を実行する前に、start を実行する必要があります。