diagnose-deeptrace

name	diagnose-deeptrace
disable-model-invocation	true
argument-hint	<username_or_email> [application_name] [action: analyze|start|cleanup]
description	Run a ZDX deep trace diagnostics session — start, analyze, or clean up deep traces for a user's device.

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

After starting, inform the user of the expected completion time.

## Step 5: Analyze Deep Trace Results

For a completed trace, collect all diagnostics data:

### 5a. Trace Summary

```text
zdx_get_device_deep_trace(device_id="<device_id>", trace_id="<trace_id>")
```text

### 5b. Web Probe Metrics

```text
zdx_get_deeptrace_webprobe_metrics(device_id="<device_id>", trace_id="<trace_id>")
```text

Check DNS resolution, TCP connect, SSL handshake, and HTTP response times. These indicate where application connectivity bottlenecks exist.

### 5c. Cloud Path Topology

```text
zdx_get_deeptrace_cloudpath(device_id="<device_id>", trace_id="<trace_id>")
```text

View the full hop-by-hop network path from the user's device to the application. Identify hops with high latency or that are unreachable.

### 5d. Cloud Path Metrics

```text
zdx_get_deeptrace_cloudpath_metrics(device_id="<device_id>", trace_id="<trace_id>")
```text

Check per-hop latency, packet loss percentage, and jitter. Spikes on specific hops isolate the network segment causing degradation.

### 5e. Device Health Metrics

```text
zdx_get_deeptrace_health_metrics(device_id="<device_id>", trace_id="<trace_id>")
```text

Check CPU utilization, memory usage, disk I/O, and network interface throughput. High resource usage indicates device-side performance problems.

### 5f. Top Processes

```text
zdx_list_deeptrace_top_processes(device_id="<device_id>", trace_id="<trace_id>")
```text

Identify processes consuming the most CPU and memory during the trace. Resource-heavy processes can explain device-level degradation.

### 5g. Events Timeline

```text
zdx_get_deeptrace_events(device_id="<device_id>", trace_id="<trace_id>")
```text

Review events that occurred during the trace window:

- **Zscaler events**: Policy changes, tunnel reconnections
- **Hardware events**: Driver changes, hardware failures
- **Software events**: Updates, installations, crashes
- **Network events**: Interface changes, connectivity drops

Correlate event timestamps with metric degradation to identify root cause.

## Step 6: Cleanup (if action=cleanup)

Requires `--enable-write-tools`.

```text
zdx_delete_deeptrace(device_id="<device_id>", trace_id="<trace_id>")
```text

This is a destructive operation. Confirm with the user before proceeding.

## Step 7: Present Diagnosis

**ALWAYS present data in HTML tables** using `<table>`, `<thead>`, `<tbody>`, `<tr>`, `<th>`, `<td>` tags with inline styling. Use color-coded rows: green for healthy, yellow for degraded, red for critical.

Include:

1. **Session summary table** (session name, type, user, device, status, start/end time, duration)
2. **Web probe metrics table** (DNS time, TCP connect, SSL handshake, HTTP response — each with value, threshold, and status)
3. **Cloud path table** (hop number, IP/hostname, latency, packet loss, jitter — color-coded by severity)
4. **Device health table** (CPU, memory, disk, network — with values and health status)
5. **Top processes table** (process name, CPU %, memory %, status)
6. **Events timeline** (timestamp, event type, description, correlated impact)
7. **Root cause analysis**: Identify the layer where the issue exists:
   - **Device**: High CPU/memory, resource-heavy processes
   - **Network**: Packet loss or latency on specific hops
   - **DNS**: Slow resolution affecting all applications
   - **Application**: High server response time with clean network path
   - **Configuration**: Correlated Zscaler policy or connector changes
8. **Remediation actions** prioritized by confidence level

## Step 8: Generate Downloadable Artifacts — MANDATORY

**You MUST create BOTH files. Do NOT skip the HTML page.**

1. **Word document** (`deep_trace_diagnosis_<date>.docx`): Session summary, all metrics tables, cloud path analysis, device health assessment, event correlation, root cause analysis, and prioritized remediation steps.

2. **Interactive HTML page** (`deep_trace_diagnosis_<date>.html`): Use the complete HTML template from the `zdx-diagnose-deeptrace` skill. The file must be fully functional with working search bar, sortable columns, filter dropdowns, color-coded rows, summary dashboard, and CSV export button. All CSS and JavaScript inline — no external dependencies. Populate the `<tbody>` with data from all deep trace metrics.

**Write both files to disk and provide the file paths to the user.**