zscaler/zscaler-mcp-server/analyze-application-health

ZDX: Analyze Application Health

Keywords

application health, zdx score, application performance, app monitoring, degraded apps, poor score, application analytics, score trend, page fetch time, dns time, availability, impacted users, application overview

Overview

Perform an organization-wide analysis of application health using ZDX. This skill retrieves all monitored applications, identifies those with degraded or poor scores, drills into metric-level details to find the bottleneck, and lists the most impacted users. It answers the "big picture" question: How are our applications performing right now?

Use this skill when: An administrator wants a health overview of monitored applications, needs to identify which apps are underperforming, or wants to compare application performance across locations or departments.

ZDX Copilot alignment: This skill covers the Analytics category -- "Show me the number of applications impacted by alerts", "What is John Doe's ZDX Score for the Zoom application in the last 4 hours?"

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 data means in plain language
2. Root cause identification for degraded or poor applications
3. Next steps / resolution with specific, actionable recommendations prioritized by impact

Use color-coded status indicators in tables:

• Green/Good: scores 66-100, metrics within normal range
• Yellow/Okay: scores 34-65, metrics approaching thresholds
• Red/Poor: scores 0-33, metrics exceeding thresholds

⚠ 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.

1. 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–5 of the Workflow) into that object.

1. 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.

1. Write the result to disk as application_health_report_<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.

{
  "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": {
    "total": "<int>",
    "good": "<int>",
    "okay": "<int>",
    "poor": "<int>",
    "mostImpacted": "<app name or '—'>"
  },
  "tables": {
    "apps": [
      {
        "severity": "critical | warning | good",
        "name": "<application name>",
        "score": "<0-100>",
        "status": "Good | Okay | Poor",
        "pft": "<page fetch time, e.g. '1.2s'>",
        "dns": "<dns time, e.g. '18ms'>",
        "availability": "<percentage, e.g. '99%'>",
        "impactedUsers": "<int or summary string>",
        "bottleneck": "DNS | PFT | Availability | None"
      }
    ]
  },
  "analysis": {
    "summary": "...",
    "rootCause": "...",
    "remediation": [
      { "priority": "Immediate | Investigate | Monitor | Communicate", "action": "..." }
    ]
  }
}

Map each row's severity from status: Good → good, Okay → warning, Poor → critical.

Output Artifacts — MANDATORY

You MUST generate BOTH files below. Both are REQUIRED output for every application health analysis.

1. Word Document (.docx) — REQUIRED

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

• Executive summary with overall health posture (healthy/degraded/poor counts)
• Application health table (app name, score, status, PFT, DNS, availability, impacted users, bottleneck)
• Per-application deep dive for degraded/poor apps with metric trends
• Root cause analysis per degraded application
• User impact breakdown by location and department
• Prioritized remediation actions

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

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

Workflow

Step 1: List All Monitored Applications

Retrieve the full list of applications monitored by ZDX.

zdx_list_applications()

Optionally filter by location, department, or geolocation:

zdx_list_applications(
  location_id=["<location_id>"],
  department_id=["<department_id>"],
  since=4
)

Categorize results by score:

• Good (66-100): Healthy, no action needed
• Okay (34-65): Degraded, investigate further
• Poor (0-33): Critical, immediate attention

Step 2: Investigate Degraded Applications

For each application with a degraded or poor score, get the score trend to understand if this is a new or ongoing issue.

zdx_get_application_score_trend(
  app_id="<app_id>",
  since=24
)

Interpret the trend:

• Sudden drop: Likely an incident (server, network, or ISP issue)
• Gradual decline: Resource exhaustion, growing user base, or config drift
• Intermittent spikes: Unstable network path or periodic load spikes

Get application details for additional context:

zdx_get_application(app_id="<app_id>")

Step 3: Drill Into Metrics

For each degraded application, check individual metrics to isolate the bottleneck.

Page Fetch Time (overall web performance):

zdx_get_application_metric(
  app_id="<app_id>",
  metric_name="pft"
)

DNS Resolution Time:

zdx_get_application_metric(
  app_id="<app_id>",
  metric_name="dns"
)

Availability:

zdx_get_application_metric(
  app_id="<app_id>",
  metric_name="availability"
)

Metric interpretation guide:

Bottleneck mapping:

• High pft + normal dns + high availability → Server or CDN slow
• High pft + high dns + high availability → DNS resolution issues
• Low availability → Application or network unreachable

Step 4: Identify Impacted Users

For each degraded application, list the impacted users.

Users with poor scores:

zdx_list_application_users(
  app_id="<app_id>",
  score_bucket="poor"
)

Users with okay scores (borderline):

zdx_list_application_users(
  app_id="<app_id>",
  score_bucket="okay"
)

Filter by location to scope the impact:

zdx_list_application_users(
  app_id="<app_id>",
  score_bucket="poor",
  location_id=["<location_id>"]
)

For a specific user, get detailed experience data:

zdx_get_application_user(
  app_id="<app_id>",
  user_id="<user_id>"
)

Step 5: Cross-Reference with Alerts

Check if any active alerts correlate with the degraded applications.

zdx_list_alerts(since=24)

For relevant alerts:

zdx_get_alert(alert_id="<alert_id>")
zdx_list_alert_affected_devices(alert_id="<alert_id>")

Step 6: Present Application Health Report

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 application table, KPI cards, color coding, search/sort, and CSV export — do not hand-author any HTML or markdown table here.

What you DO write is the analysis block inside the payload. Do not skip it. This is what makes the report useful:

• `analysis.summary` (3–5 sentences): overall health posture — how many apps are good vs. okay vs. poor, the dominant bottleneck pattern across degraded apps, and whether this is a localized or organization-wide degradation.
• `analysis.rootCause` (1–3 sentences per degraded app): state the primary bottleneck metric and what it indicates (e.g., "Microsoft 365 PFT at 12.4s indicates server-side or CDN latency, not DNS or network"). Quote the numbers from the metric calls in Steps 2–3.
• `analysis.remediation` (4–6 items): label each with a priority bucket and a concrete action.

Filtering Strategies

By Location

Useful for investigating office-specific issues.

zdx_list_applications(location_id=["<location_id>"])
zdx_get_application_score_trend(app_id="<app_id>", location_id=["<location_id>"])
zdx_get_application_metric(app_id="<app_id>", metric_name="pft", location_id=["<location_id>"])

By Department

Useful for understanding impact on specific business units.

zdx_list_applications(department_id=["<dept_id>"])
zdx_list_application_users(app_id="<app_id>", department_id=["<dept_id>"])

By Geolocation

Useful for regional analysis.

zdx_list_applications(geo_id=["<geo_id>"])

By Time Window

Adjust since (hours) for different investigation windows: