zdx-diagnose-deeptrace

What this skill does

# ZDX: Deep Trace Diagnostics

## Keywords

deep trace, diagnostics session, cloud path, web probe, network path, packet loss, latency, jitter, health metrics, top processes, events, troubleshoot network, hop analysis, DNS time, TCP connect, SSL handshake, device health, CPU, memory, diagnostics, deeptrace

## Overview

Perform deep trace diagnostics on a user's device to capture detailed network path data, web probe performance, device health metrics, and event timelines. Deep traces are the most powerful troubleshooting tool in ZDX — they provide granular, time-series data that standard application scores and metrics cannot.

**Use this skill when:** An administrator needs to investigate network connectivity issues, isolate packet loss or latency on specific network hops, analyze device-level performance during an incident, or start a new diagnostics session to capture evidence of an intermittent problem.

**ZDX Diagnostics alignment:** This skill covers the full diagnostics workflow — starting sessions (Deep Tracing), evaluating session information (In Progress / History), and analyzing session results (web probes, cloud paths, health, events).

---

## Data Presentation Requirements

**All tables are rendered by the HTML template, not by hand.** Do not author `<table>`, `<thead>`, `<tbody>`, `<tr>`, `<th>`, or `<td>` markup in your reply or in the report. You produce a JSON payload (see *Data Payload Contract*) and the template at `./templates/report.html.template` turns it into the styled, sortable, exportable tables shown in `./example/report.example.html`.

After each table, provide:

1. **Detailed analysis** explaining what the metrics reveal about the user's connectivity
2. **Root cause identification** mapped to the specific layer (device, network, DNS, application, configuration)
3. **Next steps / resolution** with specific, actionable recommendations

Use color-coded status indicators:

- Green/Good: Metrics within normal range (latency < 50ms, packet loss 0%, healthy CPU/memory)
- Yellow/Degraded: Metrics approaching thresholds (latency 50-150ms, packet loss 1-5%, moderate resource usage)
- Red/Critical: Metrics exceeding thresholds (latency > 150ms, packet loss > 5%, resource exhaustion)

## ⚠ HTML OUTPUT — READ THIS BEFORE PRODUCING ANY HTML

There is exactly one acceptable way to produce the HTML output:

1. **Read the template from disk** — do NOT inline a copy in your response. The template lives next to this SKILL.md inside the skill's package, at:

   ```text
   ./templates/report.html.template
   ```

   The `./` prefix is intentional: this path is **relative to the skill folder** (the directory containing this SKILL.md), **never** an absolute path. Most agents that load skills from an uploaded `.zip` extract the package into a working directory and expose its contents via that relative path — read the file by joining the skill's own root directory with `./templates/report.html.template`. Do not rewrite this to an absolute path that points at the author's machine.

2. **Build a single JSON object** (`__ZDX_DATA__` payload) shaped exactly as documented in the *Data Payload Contract* section below. Aggregate the responses from the ZDX MCP tool calls (Steps 1–8 of the *Workflow*) into that object.

3. **Replace** the literal token `__ZDX_DATA__` (which appears once, inside `<script type="application/json" id="zdx-data">__ZDX_DATA__</script>`) with the JSON object. Do not edit any other part of the template.

4. **Write** the result to disk as `deep_trace_diagnosis_<YYYYMMDD-HHMMSS>.html` next to the .docx, and give the user a `computer://` link to it.

This template already provides: Zscaler header with logo · sticky top bar · scope summary bar · KPI cards with severity-coded top borders · per-table search + filter chips · sortable color-coded tables · per-table CSV export · light/dark theme toggle · top-right language dropdown (EN / ES / PT / FR / JA) · printable PDF view · localStorage prefs · Analysis / Root Cause / Remediation block.

**If you find yourself writing `<html>`, `<style>`, or `<table>` in a code-block destined for the user, stop. Read the template instead.**

A populated reference rendering ships with this skill at `./example/report.example.html` (relative to the skill folder). Open it in a browser to preview the exact layout and depth expected.

### Data Payload Contract

The full `__ZDX_DATA__` payload is one JSON object. Every field below is **required** unless marked optional. This skill emits **five tables**: web probe metrics, cloud path topology, device health, top processes, and events timeline.

```json
{
  "generated_at": "<ISO 8601 timestamp>",
  "scope_en": "Free-form description in English",
  "scope_es": "...in Spanish (optional, falls back to scope_en)",
  "scope_pt": "...in Portuguese (optional)",
  "scope_fr": "...in French (optional)",
  "scope_ja": "...in Japanese (optional)",
  "kpis": {
    "user": "<user name or email>",
    "device": "<device hostname>",
    "session": "<session name or id>",
    "status": "Completed | In Progress | Failed",
    "duration": "<e.g. '14m'>",
    "rootCauseLayer": "Device | Local Network | ISP | Zscaler | Application | DNS | —"
  },
  "tables": {
    "probes": [
      {
        "severity": "critical | warning | good",
        "metric": "DNS | TCP | SSL | HTTP Response",
        "value": "<measured value, e.g. '186ms'>",
        "threshold": "<expected value, e.g. '<50ms'>",
        "status": "Good | Degraded | Critical"
      }
    ],
    "path": [
      {
        "severity": "critical | warning | good",
        "hop": "<int>",
        "host": "<IP or hostname>",
        "latency": "<int, ms>",
        "loss": "<float, %>",
        "jitter": "<int, ms>",
        "status": "Good | Degraded | Critical"
      }
    ],
    "health": [
      {
        "severity": "critical | warning | good",
        "metric": "CPU | Memory | Disk I/O | Network",
        "value": "<e.g. '92%'>",
        "status": "Good | Degraded | Critical"
      }
    ],
    "processes": [
      {
        "severity": "critical | warning | good | neutral",
        "name": "<process name>",
        "cpu": "<float, %>",
        "memory": "<float, %>"
      }
    ],
    "events": [
      {
        "severity": "critical | warning | good | info",
        "timestamp": "<ISO 8601>",
        "type": "Zscaler | Hardware | Software | Network",
        "description": "<event description>"
      }
    ]
  },
  "analysis": {
    "summary": "...",
    "rootCause": "...",
    "remediation": [
      { "priority": "Immediate | Investigate | Monitor | Communicate", "action": "..." }
    ]
  }
}
```

Map each row's `severity` from `status` (or threshold delta for probes/path/health): `Good` → `good`, `Degraded` → `warning`, `Critical` → `critical`.

## Output Artifacts — MANDATORY

You MUST generate BOTH files below. Both are REQUIRED output for every deep trace diagnosis.

### 1. Word Document (.docx) — REQUIRED

Write a Word document to disk named `deep_trace_diagnosis_<YYYYMMDD-HHMMSS>.docx` containing:

- Session summary (name, type, user, device, status, start/end time, duration)
- Web probe metrics breakdown (DNS, TCP, SSL, HTTP response times)
- Cloud path topology with per-hop latency, packet loss, and jitter analysis
- Device health assessment (CPU, memory, disk I/O, network utilization)
- Top processes consuming resources during the trace
- Event correlation timeline (Zscaler, hardware, software, network changes)
- Root cause analysis mapped to the affected layer
- Prioritized remediation actions

### 2. Interactive HTML Web Page (.html) — REQUIRED

Generated by the template-substitution flow described in the **HTML OUTPUT** section above. Filename: `deep_trace_diagnosis_<YYYYMMDD-HHMMSS>.html`. Do not hand-author HTML or CSS — the template ships everything the report needs.

---

## Workflow

### Step 1: Find the User's Device

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

Note the `devic