Skip to content
Catalyst SD-WAN APIs

Python Monitoring Examples

The monitoring package provides a registry of reusable monitoring cases and a single command-line runner.

Available Cases

Section titled “Available Cases”
Case Category Purpose
system-status Real-time Current CPU, uptime, and system status
interfaces Real-time Current interface state, counters, and errors
tunnel-traffic Real-time Current tunnel counters for one device
bfd-state Bulk state BFD state across the fabric
applications Statistics DPI utilization by application family
sites Statistics Network availability grouped by site
circuits Statistics Link availability grouped by system IP and color

Run Monitoring Cases

Section titled “Run Monitoring Cases”

Use system_ip from .env for device-specific cases, or override it with --device-id:

Terminal window
uv run -m monitoring.run_cases --insecure system-status
uv run -m monitoring.run_cases --insecure interfaces --device-id 10.0.0.20
uv run -m monitoring.run_cases --insecure tunnel-traffic
uv run -m monitoring.run_cases --insecure bfd-state --count 500

Historical aggregation cases accept a time window:

Terminal window
uv run -m monitoring.run_cases --insecure applications --hours 24
uv run -m monitoring.run_cases --insecure sites --hours 24
uv run -m monitoring.run_cases --insecure circuits --hours 24

If an active lab has sparse DPI history, widen --hours carefully. You can run every registered case once with all, but remember that this includes device real-time calls:

Terminal window
uv run -m monitoring.run_cases --insecure all --hours 24

AppRoute Examples

Section titled “AppRoute Examples”

The specialized AppRoute module exposes application mappings, stored path statistics, and live path measurements:

Terminal window
uv run -m monitoring.approute --insecure applications
uv run -m monitoring.approute --insecure fields
uv run -m monitoring.approute --insecure statistics 10.0.0.20 10.0.0.21 --hours 6

Use uv run -m monitoring.approute realtime --help to see the device, remote-system-IP, and color arguments required for a live path query.

Add a Monitoring Case

Section titled “Add a Monitoring Case”

Add reusable query builders and one MonitoringCase entry to monitoring/cases.py:

MonitoringCase(
    "interface-traffic",
    "Interface traffic",
    "Aggregate received traffic by interface.",
    lambda client, options: client.post(
        "/statistics/interface/aggregation",
        payload=interface_query(options.hours),
    ),
    (
        ("Interface", ("interface", "ifname")),
        ("RX octets", ("rx_octets", "rx-octets")),
    ),
    uses_hours=True,
),

The runner creates the subcommand automatically. Set requires_device=True to add --device-id, uses_hours=True to add --hours, and empty_hint to explain an empty result.

Test the New Case

Section titled “Test the New Case”

Add a focused test to tests/test_monitoring_cases.py, then run:

Terminal window
uv run --with ruff ruff format .
uv run --with ruff ruff check .
uv run python -m unittest discover -s tests -v

Monitoring Guidance

Section titled “Monitoring Guidance”

Real-time APIs query devices directly and are intended for targeted troubleshooting. Use statistics queries for continuous monitoring and historical analysis. Review the Monitoring API Best Practices and the full Common Monitoring Use Cases before choosing a polling interval.