export-debugger（导出调试器）

Export Debugger

Purpose

Diagnoses why a specific user was or wasn't exported to an external platform. Traces through the full export pipeline: segment membership -> job status -> flow state -> quiet windows -> export logs. Read-only diagnostic.

Environment

• LYTICS_API_TOKEN -- API authentication token
• LYTICS_API_URL -- Base URL (default: https://api.lytics.io)

Inputs

• User identity (field + value, e.g., email user@example.com)
• Export destination: job ID, job name, platform name, or flow name
• Table (default: user)

Diagnostic Flow

Step 1: Identify the Export Job

If the user provides a job ID, fetch it directly. Otherwise, find the relevant job:

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

Match by name, workflow type, or platform. Extract the segment_id from the job's config field -- this is the segment the job exports from.

If the user mentions a flow, fetch it and trace to the export step:

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

Find steps with type_hint: "work_export" and get their work_id to identify the export job.

Step 2: Check User's Segment Membership

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

Check: Is the user in the export job's target segment?

• YES -> proceed to Step 3 (job should be exporting them)
• NO -> this is likely the reason. Use profile-investigator skill to explain why they're not in the segment.

Step 3: Check Job Status

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

Step 4: Check Quiet Window

If the job has quiet window settings, calculate whether it's currently active:

From the job response, check these fields:

• quiet_time_of_day -- e.g., "2:00pm"
• quiet_timezone -- e.g., "America/Los_Angeles"
• quiet_period -- hours of quiet, e.g., 4

If all three are set, calculate:

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

If the current time falls within the quiet window, the job is sleeping and won't export until the window ends. Check sleep_until in the job response to confirm.

If drop_events_during_quiet_window is true, events arriving during quiet time are permanently dropped, not queued.

Step 5: Check Flow State (if flow-based export)

If the export is triggered through a flow, check which step the user is at:

The entity response from Step 2 includes flows_step_slugs:

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

Cross-reference with the flow's step list to determine:

• Has the user reached the export step yet? (may still be in a delay or earlier step)
• Did the user exit the flow before reaching the export?
• Is the user in a conditional branch that doesn't lead to the export?

Step 6: Check Job Logs

Always use include_errors=true when debugging to get full error details:

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

Look for:

• Export counts: added, omitted, removed in the log context
• Errors: Rate limits, auth failures, API errors from the destination platform
• Timestamps: When the job last ran successfully
• User-level errors: Some platforms report per-user failures (e.g., invalid email format)

Output Format

## Export Debug Report

### User: user@example.com
### 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.

Common Diagnoses

Error Handling

• Job not found: List jobs and help user identify the right one
• User not found: Try alternative identity fields
• Multiple export jobs for same platform: Show all, ask user to pick
• No logs available: Job may be new or logs may have aged out

Dependencies

• Composes: job-manager skill, entity-lookup skill, segment-manager skill, flow-manager skill
• Related: profile-investigator skill (for segment membership diagnosis)
• References: ../references/api-client.md