export-debugger

エクスポートのデバッグ

目的

特定のユーザーが外部プラットフォームにエクスポートされたかどうか、その理由を診断します。エクスポートパイプライン全体を追跡します：セグメントへの所属 -> ジョブのステータス -> フローの状態 -> 静穏時間帯 -> エクスポートログ。読み取り専用の診断です。

環境

認証済みの API アクセスが必要です。認証情報の解決方法については、../references/auth.md を参照してください。

入力

• ユーザーの識別情報（フィールド + 値。例：email [email protected]）
• エクスポート先：ジョブ ID、ジョブ名、プラットフォーム名、またはフロー名
• テーブル（デフォルト：user）

診断フロー

ステップ 1：エクスポートジョブを特定する

ユーザーがジョブ ID を指定した場合は、その ID を直接取得します。それ以外の場合は、該当するジョブを検索します：

# List all jobs to find the export
curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/job" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

名前、ワークフローの種類、またはプラットフォームで照合します。ジョブの config フィールドから segment_id を抽出します。これは、ジョブがエクスポートする元のセグメントです。

ユーザーがフローに言及した場合は、そのフローを取得し、エクスポートのステップを追跡します：

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/flow/ui/${FLOW_ID}" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

type_hint: "work_export" のステップを見つけ、その work_id を取得してエクスポートジョブを特定します。

ステップ 2：ユーザーがセグメントに属しているか確認する

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/api/entity/user/${FIELD}/${VALUE}?segments=true&allsegments=true" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

確認事項：ユーザーはエクスポートジョブの対象セグメントに含まれていますか？

• はい -> ステップ 3 に進みます（ジョブはユーザーをエクスポートするはずです）
• いいえ -> これが原因である可能性が高いです。profile-investigator skill を使用して、ユーザーがセグメントに含まれていない理由を説明します。

ステップ 3：ジョブのステータスを確認する

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/job/${JOB_ID}" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

ステータス	診断
runnable	ジョブはアクティブです。エクスポートの詳細をログで確認してください
sleeping	ジョブは実行の合間です。sleep_until を確認してください。静穏時間帯またはスケジュールされた遅延中の可能性があります
paused	ジョブは一時停止中です。ユーザーまたはシステムによって一時停止されており、エクスポートは停止しています
fault	ジョブにエラーがあります。エラーの詳細をログで確認してください
failed	ジョブは最終的に失敗しました。根本原因をログで確認してください
killed	ジョブは手動で停止されました

ステップ 4：静穏時間帯を確認する

ジョブに静穏時間帯の設定がある場合、現在その時間帯が有効かどうかを計算します：

ジョブのレスポンスで、次のフィールドを確認します：

• quiet_time_of_day -- 例："2:00pm"
• quiet_timezone -- 例："America/Los_Angeles"
• quiet_period -- 静穏時間帯の時間数。例：4

3 つすべてが設定されている場合、次のように計算します：

Quiet window: quiet_time_of_day to (quiet_time_of_day + quiet_period hours)
              in the configured timezone

Example: 2:00pm - 6:00pm America/Los_Angeles

現在時刻が静穏時間帯に該当する場合、ジョブはスリープ中であり、時間帯が終了するまでエクスポートされません。ジョブのレスポンスで sleep_until を確認して確かめます。

drop_events_during_quiet_window が true の場合、静穏時間帯に到着したイベントはキューに追加されず、完全に破棄されます。

ステップ 5：フローの状態を確認する（フロー経由のエクスポートの場合）

フロー経由でエクスポートがトリガーされる場合、ユーザーがどのステップにいるかを確認します：

ステップ 2 のエンティティレスポンスには flows_step_slugs が含まれています：

{
  "flows_step_slugs": {
    "flow_id-1": "welcome_email_step"
  }
}

フローのステップ一覧と照合して、次の点を確認します：

• ユーザーはエクスポートのステップに到達していますか？（まだ遅延中、またはそれ以前のステップにいる可能性があります）
• ユーザーはエクスポートに到達する前にフローを離脱しましたか？
• ユーザーはエクスポートにつながらない条件分岐にいますか？

ステップ 6：ジョブのログを確認する

デバッグ時は必ず include_errors=true を使用して、エラーの詳細をすべて取得します：

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/job/${JOB_ID}/logs?include_errors=true" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

次の項目を確認します：

• エクスポート件数：ログコンテキスト内の added、omitted、removed
• エラー：レート制限、認証エラー、宛先プラットフォームからの API エラー
• タイムスタンプ：ジョブが最後に正常実行された時刻
• ユーザー単位のエラー：プラットフォームによっては、ユーザーごとの失敗が報告されます（例：無効なメールアドレス形式）

出力形式

## Export Debug Report

### User: [email protected]
### Destination: Facebook Custom Audiences (job: "fb_export_high_value")

### Diagnostic Results

1. SEGMENT MEMBERSHIP: PASS
   User IS in segment "High Value Customers" (id: seg123)

2. JOB STATUS: PASS
   Job is "runnable" -- actively processing

3. QUIET WINDOW: FAIL
   Job is currently in quiet window (2:00pm - 6:00pm PT)
   Will resume at: 6:00pm PT (2026-03-19T01:00:00Z)
   drop_events_during_quiet_window: false (events are queued)

4. FLOW STATE: N/A
   Export is not flow-based

5. JOB LOGS: INFO
   Last export: 2026-03-19 09:45:00 UTC
   Added: 145, Omitted: 3, Removed: 12
   No errors in recent logs

### Diagnosis
The user IS in the export segment and the job is active, but the job
is currently in its quiet window (2:00pm-6:00pm PT). The user should
be exported when the job resumes at 6:00pm PT. Events are being
queued, not dropped.

一般的な診断

症状	考えられる原因	解決方法
ユーザーがセグメントに含まれていない	FilterQL の条件を満たしていない	profile-investigator を使って、どの条件が満たされていないか確認します
ジョブが一時停止中	手動で一時停止されたか、自動で一時停止された	ジョブを再開します
ジョブがエラー状態	認証の期限切れ、レート制限、API エラー	ログを確認し、認証を修正するか、レート制限がリセットされるまで待ちます
ジョブがスリープ中	静穏時間帯、またはスケジュールされた遅延	静穏時間帯が終了するまで待ちます
ユーザーが誤ったフローステップにいる	遅延ステップ、または条件分岐	フローの構造とタイミングを確認します
ユーザーをエクスポートしたが表示されない	プラットフォームとの同期遅延	プラットフォーム側を確認します。反映に数分から数時間かかる場合があります
ログに「省略」と表示される	エクスポート設定によってユーザーがフィルタリングされた	セグメント以外の追加フィルターがジョブ設定にないか確認します

エラー処理

• ジョブが見つからない：ジョブの一覧を表示し、適切なジョブを特定できるようユーザーをサポートします
• ユーザーが見つからない：別の識別フィールドを試します
• 同じプラットフォーム向けのエクスポートジョブが複数ある：すべて表示し、ユーザーに選択してもらいます
• ログがない：ジョブが新しいか、ログの保存期間が過ぎている可能性があります

依存関係

• 構成要素：job-manager skill、entity-lookup skill、segment-manager skill、flow-manager skill
• 関連：profile-investigator skill（セグメントへの所属状況の診断用）
• 参照：../references/auth.md、../references/api-client.md