Zdx Diagnose Deeptrace

zdx_list_devices(search="<username_or_email>")```text
Note the `device_id`. If multiple devices, ask the user which one.
---
### Step 2: Check Existing Deep Trace Sessions
```textzdx_list_device_deep_traces(device_id="<device_id>")```text
Review the sessions:
- **In Progress**: The session is still collecting data. Note the expected end time.- **Completed**: Proceed to analysis (Step 4).- **No sessions found**: Offer to start a new one (Step 3).
The sessions list shows: Name, Session Type, User, Device, Created Time, Start Time, Status, Application, Created By, Duration (for in-progress), and End Time (for completed).
---
### Step 3: Start a New Diagnostics Session (Write Operation)
Requires `--enable-write-tools`. Only if no suitable trace exists.
First, discover the probe IDs for the target application:
```textzdx_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):
```textzdx_start_deeptrace(  device_id="<device_id>",  session_name="Diag-<user>-<date>",  app_id=<app_id>,  web_probe_id=<web_probe_id>,  cloudpath_probe_id=<cloudpath_probe_id>,  session_length_minutes=15,  probe_device=True)```text
**Session duration guidance:**
- **5 minutes**: Quick verification of an intermittent issue- **15 minutes**: Standard diagnostics session (recommended)- **30 minutes**: Extended capture for hard-to-reproduce problems- **60 minutes**: Long-running capture for periodic issues
**Configuration options (from ZDX Admin Portal):**
- **Device Probing**: When enabled, collects device-level CPU, memory, disk, network stats- **Application**: Target a specific monitored application or add a special URL- **Web Probe**: DNS, TCP, SSL, HTTP response times- **Cloud Path Probe**: Hop-by-hop latency, packet loss, jitter with optional thresholds
After starting, inform the user of the expected completion time and wait.
---
### Step 4: Get Trace Summary
```textzdx_get_device_deep_trace(device_id="<device_id>", trace_id="<trace_id>")```text
Review the trace status, start/end times, and high-level findings.
---
### Step 5: Analyze Web Probe Metrics
```textzdx_get_deeptrace_webprobe_metrics(device_id="<device_id>", trace_id="<trace_id>")```text
**Key metrics and thresholds:**
| Metric | Normal | Degraded | Critical | Indicates ||--------|--------|----------|----------|-----------|| DNS resolution | < 50ms | 50-150ms | > 150ms | DNS server performance || TCP connect | < 100ms | 100-300ms | > 300ms | Network reachability || SSL handshake | < 150ms | 150-500ms | > 500ms | TLS negotiation issues || HTTP response | < 500ms | 500-2000ms | > 2000ms | Application server health |
**Diagnosis patterns:**
- High DNS only → DNS server or resolution issue- High TCP + SSL → Network path congestion- High HTTP only → Application server overload- All high → Major network or infrastructure event
---
### Step 6: Analyze Cloud Path
```textzdx_get_deeptrace_cloudpath(device_id="<device_id>", trace_id="<trace_id>")```text
View the full hop-by-hop network path. Identify:
- Hops with abnormally high latency (compared to previous hop)- Hops where packet loss begins- Whether the issue is in the local network, ISP, or cloud segment
```textzdx_get_deeptrace_cloudpath_metrics(device_id="<device_id>", trace_id="<trace_id>")```text
Check per-hop latency trends, packet loss percentage, and jitter over the trace duration.
**Cloud path interpretation:**
- Latency spike at hop 1-3 → Local network / WiFi issue- Latency spike at mid-path → ISP backbone issue- Latency spike at final hops → Cloud provider or application datacenter issue- Packet loss at a specific hop → Congested or misconfigured router/firewall
---
### Step 7: Analyze Device Health
```textzdx_get_deeptrace_health_metrics(device_id="<device_id>", trace_id="<trace_id>")```text
Check device resource utilization during the trace:
- **CPU > 80%**: Device may be throttling network operations- **Memory > 90%**: System under memory pressure, swapping- **Disk I/O high**: Background operations competing for resources- **Network throughput low**: Interface saturation or driver issues
```textzdx_list_deeptrace_top_processes(device_id="<device_id>", trace_id="<trace_id>")```text
Identify resource-heavy processes. Common culprits:
- Backup software consuming bandwidth- Security scans consuming CPU- Browser with many tabs consuming memory- VPN clients conflicting with Zscaler
---
### Step 8: Review Events Timeline
```textzdx_get_deeptrace_events(device_id="<device_id>", trace_id="<trace_id>")```text
Review all events that occurred during the trace window:
| Event Type | Examples | Impact ||------------|----------|--------|| **Zscaler** | Policy changes, tunnel reconnections, service edge switches | May cause temporary connectivity drops || **Hardware** | Driver updates, hardware failures, display changes | May impact network adapter performance || **Software** | OS updates, app installations, crashes | May compete for resources or change behavior || **Network** | Interface changes, WiFi roaming, VPN connect/disconnect | Directly impacts connectivity |
**Correlation technique:** Overlay event timestamps with metric degradation windows. If a Zscaler tunnel reconnection at 10:15 AM coincides with a 30-second spike in TCP connect time, the tunnel reconnection is the likely cause.
---
### Step 9: Present Diagnosis
**Root cause layer identification:**
| Layer | Evidence | Action ||-------|----------|--------|| **Device** | High CPU/memory + resource-heavy processes | Optimize device, close unnecessary apps || **Local Network** | Packet loss on hops 1-3 + WiFi events | Check WiFi AP, switch, local routing || **ISP** | Latency spike mid-path + no device issues | Contact ISP with hop data as evidence || **Zscaler** | Tunnel events + correlated metric spikes | Check service edge health, PAC file || **Application** | High HTTP response + clean network path | Escalate to app team with ZDX evidence || **DNS** | High DNS time + normal TCP/SSL | Check DNS resolver, consider DNS proxy |
Use the table above to pick the dominant **root cause layer**, then assemble the `__ZDX_DATA__` payload defined in the *Data Payload Contract* and render it through `./templates/report.html.template` (see the **HTML OUTPUT** section). The template already produces the five tables (probes, path, health, processes, events), KPI cards, color coding, search/sort, and CSV export — do **not** hand-author any HTML here.
Write the `analysis` block before rendering:
- **`analysis.summary`** (3–5 sentences): which layer is the bottleneck, the strongest piece of evidence (single number / hop), and whether this is a one-off or part of a recurring pattern.- **`analysis.rootCause`** (2–4 sentences): map the layer to the evidence row that proves it (e.g., *"hop 4 (203.0.113.10) shows 187 ms latency and 6% packet loss — every downstream metric is degraded from that hop on, isolating the issue to the ISP segment, not the device or Zscaler edge"*).- **`analysis.remediation`** (3–5 items): each `priority` uses the same buckets as the other skills (`Immediate`, `Investigate`, `Monitor`, `Communicate`).
---
### Step 10: Cleanup (Optional Write Operation)
If the diagnostics session is no longer needed:
```textzdx_delete_deeptrace(device_id="<device_id>", trace_id="<trace_id>")```text
This is a **destructive operation**. Always confirm with the user before deleting.
---
## Edge Cases
### Session Still In Progress
```textDiagnostics session "<session_name>" is still collecting data.Started: <start_time>Expected completion: <end_time> (approximately <remaining> minutes)
Partial data may be available. Wait for completion for the most accurate analysis.```text
### No Application Configured
If the user wants to trace an app that isn't monitored:
```textThe application is not configured for ZDX monitoring.You can start a deep trace with a special application URL:
zdx_start_deeptrace(  device_id="<device_id>",  session_name="Custom-App-Trace",  app_url="https://example.com",  session_length_minutes=15)```text
### Device Has Active Session
A device can only have one active diagnostics session at a time:
```textDevice already has an active diagnostics session:  Session: <session_name>  Status: In Progress  Started: <start_time>
Wait for the current session to complete, or delete it first (requires write tools):  zdx_delete_deeptrace(device_id="<device_id>", trace_id="<trace_id>")```text
---
## Quick Reference
**Primary workflow:** Find Device → Check Traces → Start/Analyze → Web Probes → Cloud Path → Health → Processes → Events → Diagnosis
**Read-only tools:**
- `zdx_list_device_deep_traces(device_id)` — list all trace sessions- `zdx_get_device_deep_trace(device_id, trace_id)` — trace summary- `zdx_get_deeptrace_webprobe_metrics(device_id, trace_id)` — DNS, TCP, SSL, HTTP times- `zdx_get_deeptrace_cloudpath(device_id, trace_id)` — hop-by-hop network path- `zdx_get_deeptrace_cloudpath_metrics(device_id, trace_id)` — per-hop latency, loss, jitter- `zdx_get_deeptrace_health_metrics(device_id, trace_id)` — CPU, memory, disk, network- `zdx_list_deeptrace_top_processes(device_id, trace_id)` — resource-heavy processes- `zdx_get_deeptrace_events(device_id, trace_id)` — event timeline
**Probe discovery tools (call before starting a deep trace):**
- `zdx_get_web_probes(device_id, app_id)` — get web_probe_id for the app- `zdx_list_cloudpath_probes(device_id, app_id)` — get cloudpath_probe_id for the app
**Write tools (require `--enable-write-tools`):**
- `zdx_start_deeptrace(device_id, session_name, app_id, web_probe_id, cloudpath_probe_id, ...)` — start a diagnostics session- `zdx_delete_deeptrace(device_id, trace_id)` — delete a trace session
**Related skills:**
- [Troubleshoot User Experience](../troubleshoot-user-experience/) — for ZDX score and metric analysis- [Investigate Alerts](../investigate-alerts/) — for alert-driven investigation- [Compare Location Experience](../compare-location-experience/) — for site-by-site comparison