diagnose-deeptrace

Deep Trace Diagnostics Session

Perform deep trace diagnostics for: $ARGUMENTS

Step 1: Parse Input

Extract:

• Username or email (required)
• Application name (optional — if not provided, the session covers all monitored apps)
• Action (default: analyze)
  • analyze — Check existing traces and analyze results
  • start — Start a new diagnostics session (requires write tools)
  • cleanup — Delete completed/stale traces (requires write tools)

Step 2: Find the User's Device

zdx_list_devices(search="<username>")
```text

Note the `device_id`. If multiple devices, ask the user which one.

## Step 3: Check Existing Deep Traces

```text
zdx_list_device_deep_traces(device_id="<device_id>")
```text

Review existing sessions:

- **In Progress** sessions: Wait for completion or analyze partial data
- **Completed** sessions: Proceed to analysis
- **No sessions**: Offer to start a new one (requires write tools)

## Step 4: Start a New Session (if action=start)

Requires `--enable-write-tools`.

A diagnostics session can include Deep Tracing, Hi-Fi Cloud Path, Bandwidth Testing, or Packet Capture Probing. Through the MCP tools, we support Deep Tracing sessions.

First, discover the probe IDs for the target application:

```text
zdx_get_web_probes(device_id="<device_id>", app_id="<app_id>")
zdx_list_cloudpath_probes(device_id="<device_id>", app_id="<app_id>")
```text

Then start the deep trace with all required IDs (all IDs must be integers):

```text
zdx_start_deeptrace(
  device_id="<device_id>",
  session_name="Diag-<user>-<date>",
  app_id=<app_id>,                 (integer, from zdx_list_applications)
  web_probe_id=<probe_id>,         (integer, from zdx_get_web_probes)
  cloudpath_probe_id=<probe_id>,   (integer, from zdx_list_cloudpath_probes)
  session_length_minutes=15,       (5, 15, 30, or 60 minutes)
  probe_device=True                (collect device-level statistics)
)
```text

Configuration guidance:

- **5 minutes**: Quick check for intermittent issues
- **15 minutes**: Standard diagnostics session (recommended default)
- **30 minutes**: Extended capture for hard-to-reproduce issues
- **60 minutes**: Long-running capture for periodic/scheduled issues