version: "1.0.1" name: suzieq-observability description: "SuzieQ network observability — query current and historical network state, run validation assertions, get summary statistics, trace forwarding paths, and discover unique values across 20+ network tables. Use when investigating BGP/OSPF state, checking interface health, performing time-travel queries, validating network assertions, or tracing packet paths through the network via SuzieQ." license: Apache-2.0 user-invocable: true metadata: { "openclaw": { "requires": { "bins": ["python3"], "env": ["SUZIEQ_API_URL", "SUZIEQ_API_KEY"] } } }

SuzieQ Network Observability

Server & Configuration

• Server script: mcp-servers/suzieq-mcp/server.py
• Transport: stdio (JSON-RPC 2.0)
• Environment variables: SUZIEQ_API_URL, SUZIEQ_API_KEY
• Optional: SUZIEQ_VERIFY_SSL (default: true), SUZIEQ_TIMEOUT (default: 30s)

All 5 Available Tools

1. suzieq_show

Query detailed network state data from any SuzieQ table. Supports filtering by device, namespace, time range, and columns. Use for current or historical (time-travel) network state queries.

• table (string, required): SuzieQ table name (e.g., "bgp", "route", "interface")
• namespace (string): Filter by SuzieQ namespace
• hostname (string): Filter by device hostname
• columns (string): Comma-separated column names to return
• start_time (string): Start time for time-travel query (ISO 8601 or relative e.g., "1h", "2d")
• end_time (string): End time for time-travel query
• view (string): Data view: "latest", "all", or "changes"
• filters (string): Additional key=value pairs separated by ampersand

Use when: Querying current network state, investigating specific devices, performing time-travel queries for historical analysis.

2. suzieq_summarize

Get aggregated statistics and summary views of any SuzieQ network table. Returns counts, distributions, and per-device breakdowns.

• table (string, required): SuzieQ table name
• namespace (string): Filter by SuzieQ namespace
• hostname (string): Filter by device hostname
• start_time (string): Start time for historical summary
• end_time (string): End time for historical summary

Use when: Getting high-level network overview, distribution analysis, capacity planning.

3. suzieq_assert

Run validation assertions against network state. Checks conditions like "all BGP peers established" or "no interface errors".

• table (string, required): Must be one of: bgp, ospf, interface, evpnVni
• namespace (string): Filter by SuzieQ namespace
• hostname (string): Filter by device hostname

Use when: Validating network health, pre/post-change verification, compliance checks.

4. suzieq_unique

Get distinct values and their counts for a specific column in a SuzieQ table.

• table (string, required): SuzieQ table name
• column (string, required): Column name to get unique values for
• namespace (string): Filter by SuzieQ namespace
• hostname (string): Filter by device hostname

Use when: Understanding value distributions (unique VRFs, BGP states, interface types).

5. suzieq_path

Trace the forwarding path between two endpoints through the network.

• namespace (string, required): SuzieQ namespace
• source (string, required): Source IP address
• destination (string, required): Destination IP address
• vrf (string): VRF name (default: "default")

Use when: Troubleshooting connectivity, verifying forwarding paths, path analysis.

Workflow

1. Start with suzieq_show or suzieq_summarize to understand current network state
2. Use suzieq_assert to validate health (BGP established, OSPF full, interfaces up)
3. Use suzieq_unique to explore value distributions for specific columns
4. Use suzieq_path to trace forwarding paths between endpoints
5. Use start_time/end_time on show/summarize for time-travel historical analysis

Supported Tables

address, arpnd, bgp, device, devconfig, evpnVni, fs, ifCounters, interface, inventory, lldp, mac, mlag, namespace, network, ospf, route, sqPoller, topology, vlan

Failure Behavior

• If a tool call fails with an authentication or connection error, check that SUZIEQ_API_KEY, SUZIEQ_API_URL are set and valid before assuming a data or device problem.
• On a tool error (timeout, unreachable host, malformed response), report the failure and its error message directly to the user rather than fabricating or guessing at results.
• For a confirmed read-only call, check connectivity and retry once if appropriate. For any call that changes state or sends a message, a timeout does not prove the action failed: inspect current state or delivery status before retrying, preserve the required approval/change gates, and do not repeat an action whose outcome is unknown.