Thousandeyes

---
name: thousandeyes
description: "Expert coverage of Cisco ThousandEyes synthetic monitoring and internet intelligence platform: Cloud/Enterprise/Endpoint agent types, test types, path visualization, Internet Insights outage detection, Cisco SD-WAN integration, BGP monitoring, and API automation. Use for \"ThousandEyes\", \"path visualization\", \"Internet Insights\", \"Cloud Agent\", \"Enterprise Agent\", \"Endpoint Agent\", \"synthetic monitoring\", \"ThousandEyes test\". Do NOT use for cross-vendor comparison, platform selection, or category-wide architecture -- use the `network-monitoring` skill."
license: MIT
---

# ThousandEyes

This skill covers Cisco ThousandEyes, the synthetic monitoring and internet intelligence platform. Areas of expertise include:

- Cloud Agent, Enterprise Agent, and Endpoint Agent deployment and management
- All test types (HTTP, Page Load, Web Transaction, DNS, BGP, Network, API, Voice)
- Path Visualization for end-to-end hop-by-hop network analysis
- Internet Insights for macro-level outage detection across ISPs, CDNs, and cloud providers
- Cisco SD-WAN integration (IOS XE embedded agents, overlay/underlay visibility)
- Cisco XDR integration for network context in security operations
- Alert rules, dashboards, and sharing
- ThousandEyes API for automation and data export

## How to Approach Tasks

1. **Classify** the request:
   - **Test design** -- Select appropriate test types, agent placement, frequency
   - **Troubleshooting** -- Analyze path visualization, identify degradation source (your network, ISP, destination)
   - **Architecture** -- Load `references/architecture.md` for agent types, test internals, Internet Insights
   - **Deployment** -- Agent installation (Cloud, Enterprise, Endpoint), Cisco SD-WAN integration
   - **Automation** -- REST API for test management, data extraction, alert configuration

2. **Identify the monitoring goal** -- External application monitoring, internal network visibility, ISP performance, SaaS availability, or WAN quality.

3. **Load context** -- Read the reference file for deep knowledge.

4. **Analyze** -- Apply ThousandEyes-specific reasoning. Distinguish between what ThousandEyes measures (external paths, synthetic transactions) vs. what an NMS measures (device health, SNMP).

5. **Recommend** -- Provide specific test configurations, agent placement strategy, and analysis guidance.

## Agent Types

### Cloud Agents
- Deployed and managed by Cisco ThousandEyes in 1,057+ globally distributed vantage points across 271 cities
- Hosted in Tier 1/2/3 ISPs, broadband providers, cloud regions
- No customer infrastructure required
- **Use cases**: Monitor SaaS applications from customer geographies, test website reachability from diverse ISPs, BGP route visibility from global vantage points
- Cannot test internal-only applications (no access to private networks)

### Enterprise Agents
- Customer-deployed probes on:
  - Linux VMs (Ubuntu, RHEL, CentOS)
  - Docker containers
  - Cisco IOS XE routers (native ThousandEyes integration)
  - Physical appliances
- Placed at data centers, branch offices, cloud VPCs/VNets
- **Use cases**: Internal application monitoring, LAN performance, cross-site path analysis, SD-WAN overlay/underlay visibility
- **Cisco SD-WAN integration**: Native on IOS XE routers; no separate deployment; monitors both overlay and underlay paths

### Endpoint Agents
- Lightweight browser-based agents on employee laptops/desktops
- Capture real user experience data: WiFi quality, VPN performance, application response times
- Activated by scheduled tests or browser extension triggers
- **Privacy controls**: Configurable data collection windows (business hours only)
- **Use cases**: Remote worker experience monitoring, WiFi troubleshooting, VPN performance baselining

## Test Types

| Test Type | Layer | What It Measures | Agent Types |
|---|---|---|---|
| HTTP Server | L7 | Availability, response code, time, cert validity | Cloud, Enterprise |
| Page Load | L7 | Full browser page load (Chromium) including all resources | Cloud, Enterprise |
| Web Transaction | L7 | Multi-step scripted browser journeys (Selenium-like) | Cloud, Enterprise |
| DNS Server | L7 | Resolution time, answer correctness, DNSSEC | Cloud, Enterprise |
| DNS Trace | L7 | Full recursive resolution path tracing | Cloud, Enterprise |
| BGP | L3 | Route reachability, prefix visibility, path changes | Cloud (BGP monitors) |
| Network (ICMP) | L3 | Latency, jitter, packet loss | Cloud, Enterprise |
| Network (TCP) | L4 | TCP connection time, path analysis | Cloud, Enterprise |
| API | L7 | REST API endpoint testing with response assertions | Cloud, Enterprise |
| Voice (RTP) | L4/L7 | MOS score, jitter, packet loss for VoIP | Enterprise |

### Test Design Best Practices
- **Frequency**: Critical services at 1-2 minute intervals; standard at 5-15 minutes
- **Multiple agents per test**: Use 3+ agents for external tests to distinguish local vs. widespread issues
- **Combine test types**: HTTP Server (availability) + Network (path) for correlated analysis
- **BGP monitoring**: Add BGP tests for any service with public IP prefixes
- **DNS tests**: Always include DNS tests alongside HTTP; DNS failures are a top root cause

## Path Visualization

End-to-end network path mapping:

- Visualizes every network hop from agent to destination including ISP routers
- **Hop-level metrics**: Per-hop latency, packet loss, MPLS labels
- **BGP route overlay**: Correlates BGP path data with traceroute-derived forwarding path
- **SD-WAN visibility**: For Enterprise Agents on Cisco SD-WAN, shows both overlay tunnel and underlying WAN path
- **Historical comparison**: Compare paths across time to detect changes correlating with degradation

### Interpreting Path Visualization
1. **Green nodes**: Normal latency/loss at this hop
2. **Yellow nodes**: Elevated latency or minor loss
3. **Red nodes**: Significant loss or latency at this hop
4. **Multiple paths**: ECMP or load balancing; different paths taken by different probes
5. **Path changes**: New hops appearing or disappearing; correlate with performance changes
6. **ISP identification**: Each hop annotated with owning ISP/organization (WHOIS data)

### Key Analysis Patterns
- **Loss at a single hop, no downstream impact**: ICMP rate-limiting (cosmetic, not a problem)
- **Loss at a hop with downstream impact**: Real congestion or failure at that hop
- **Latency increase at ISP boundary**: Peering or transit link congestion
- **Path change correlating with performance change**: Routing event caused degradation

## Internet Insights

Macro-level outage detection across the internet:

### How It Works
- Aggregates data from the entire ThousandEyes Cloud Agent network
- Detects correlated failures across multiple agents pointing to the same provider
- Distinguishes "your problem" from "the internet's problem"

### Coverage Packages
Licensed by provider type and geography:
- **Provider types**: ISP, CDN, DNS, IaaS, SECaaS, UCaaS
- **Geographies**: North America, EMEA, APAC, LATAM
- **Global Insights Bundle**: All packages in one license

### Outage Data
- Affected network prefixes
- Impacted providers and services
- Geographic scope
- Timeline (start, peak, resolution)
- Correlated with your own test data

### Use Cases
- Rapid triage: "Is it us or the internet?"
- SLA evidence for ISP performance issues
- Proactive notification before users report problems
- Historical outage data for ISP evaluation and selection

## Cisco SD-WAN Integration

### Embedded Agents
- ThousandEyes Enterprise Agent embedded in Cisco IOS XE SD-WAN routers
- No separate hardware or VM required
- Monitors from the branch/site perspective

### Overlay and Underlay Visibility
- **Overlay**: Application-level tests through SD-WAN tunnels (measures what users experience)
- **Underlay**: Network-level tests on WAN links (measures raw transport quality)
- Correlate overlay performance with underlay quality to identify WAN-caused app issues

### WAN Quality Metrics
- Per-link latency, jitter, packet loss
- Path visualization through SD-WAN fabric
- Integration with vManage for correlated SD-WAN + ThousandEyes dashboards

## Cisco XDR Integration

- ThousandEyes data feeds into Cisco XDR for network context enrichment
- **Secure Access Experience Insights**: Endpoint health, network stability, SaaS performance in unified XDR console
- Accelerates security triage with network path data alongside security event timelines

## Alerting

### Alert Rules
- **Threshold alerts**: Metric exceeds static value (response time > 500ms, loss > 5%)
- **Baseline alerts**: Deviation from learned normal (2x standard deviation)
- **Test-level alerts**: Apply to all agents in a test or specific agents
- **Agent-level alerts**: Alert only when specific agent(s) see the issue

### Notification Channels
- Email, PagerDuty, Slack, Microsoft Teams, ServiceNow, webhook
- API-driven alert integration with custom systems
- Alert suppression during maintenance windows

## API

### REST API
- Base URL: `https://api.thousandeyes.com/v7/`
- Authentication: Bearer token (OAuth2) or Basic Auth (email + API token)
- JSON response format

### Key Endpoints
```
GET /tests                  # List all tests
POST /tests/http-server     # Create HTTP Server test
GET /test-results/{testId}/network  # Network test results
GET /test-results/{testId}/path-vis # Path visualization data
GET /alerts                 # Active alerts
GET /agents                 # List agents (Cloud + Enterprise)
GET /internet-insights/outages  # Internet Insights outages
```

### Use Cases
- Automated test provisioning for new applications
- Data export to custom dashboards (Grafana, Power BI)
- Integration with CI/CD pipelines (test deployment health)
- Alert data aggregation into enterprise event management

## Dashboards and Sharing

- **Built-in dashboards**: Test-specific views with timeline, agent comparison, path visualization
- **Custom dashboards**: Drag-and-drop widgets; combine multiple tests on one view
- **Snapshot sharing**: Point-in-time snapshots shareable via URL (no login required for viewer)
- **Embedded widgets**: Embed ThousandEyes views in external dashboards or NOC displays
- **Reports**: Scheduled PDF/email reports for SLA tracking and trend analysis

## Common Pitfalls

1. **Testing from wrong agent type** -- Cloud Agents cannot reach internal applications. Use Enterprise Agents for internal monitoring.

2. **Too few agents per test** -- A single agent showing loss might be a local issue. Use 3+ agents to establish whether the problem is widespread.

3. **Ignoring DNS tests** -- DNS failures cause application outages but are invisible to HTTP-only tests. Always pair HTTP tests with DNS tests.

4. **Not using Internet Insights for triage** -- Before deep-diving into path visualization, check Internet Insights to rule out widespread ISP/CDN issues.

5. **Alert threshold too sensitive** -- Sub-second response time variations are normal. Set thresholds based on actual impact to users, not theoretical perfection.

6. **Path visualization ICMP rate-limiting** -- Some hops show loss that does not affect real traffic. Look for downstream impact, not isolated hop loss.

7. **SD-WAN overlay-only monitoring** -- Monitor both overlay AND underlay. Overlay tests show user experience; underlay tests show WAN quality.

## Reference Files

Load these when you need deep knowledge:

- `references/architecture.md` -- Agent types, test internals, path visualization, Internet Insights, Cisco integrations. Read for "how does X work" questions.