Skip to content

MDT_XPATH_SPEC.md

Latest commit

 

History

History
121 lines (90 loc) · 6.64 KB

MDT_XPATH_SPEC.md

File metadata and controls

121 lines (90 loc) · 6.64 KB

MDT / gRPC Dial-Out Filter XPath Specification

Status: Active (Phase 0 of multi-version rollout) Scope: Defines how the project derives, stores, and surfaces Model-Driven Telemetry (MDT) filter xpaths for gRPC dial-out subscriptions. Companion to VERSIONING.md and PROJECT_REQUIREMENTS.md.

The authoritative reference for human-curated subscription metadata is telemetry-reference.md at the workspace root.

1. The rule

For an operational YANG container at module-prefix <prefix> and absolute path <path>, the MDT filter xpath used in subscription configuration is:

filter xpath /<prefix>:<path-without-leading-slash>

Worked examples (taken from telemetry-reference.md):

Feature YANG container path Filter xpath
CPU utilization /cpu-usage/cpu-utilization (module Cisco-IOS-XE-process-cpu-oper, prefix process-cpu-ios-xe-oper) /process-cpu-ios-xe-oper:cpu-usage/cpu-utilization
Memory statistics /memory-statistics/memory-statistic (memory-ios-xe-oper) /memory-ios-xe-oper:memory-statistics/memory-statistic
Interface stats /interfaces/interface (interfaces-ios-xe-oper) /interfaces-ios-xe-oper:interfaces/interface
Environment sensors /environment-sensors (environment-ios-xe-oper) /environment-ios-xe-oper:environment-sensors
BGP state /bgp-state-data (bgp-ios-xe-oper) /bgp-ios-xe-oper:bgp-state-data

The filter xpath always begins with a single /, then the YANG module's prefix: (no slash between / and the prefix), then the YANG path (no leading slash on the path component).

2. Validation regex

CI gate (see VERSIONING.md §9) validates every emitted xpath against:

^/[a-z][a-z0-9\-]*:[A-Za-z][A-Za-z0-9_\-]*(/[A-Za-z][A-Za-z0-9_\-]*(\[[^\]]+\])?)*$

This permits:

  • a single module prefix segment immediately after the leading /,
  • subsequent path segments separated by /,
  • optional list-key predicates in [name='Gi0/0/1'] shape on any segment.

It forbids: leading /<container> without a prefix; multiple : segments; spaces; non-ASCII characters.

3. OpenAPI extensions

Operational-model OpenAPI specs annotate operations with the following vendor extensions. All are optional; absence means the operation is not currently flagged as a recommended MDT subscription target.

Key Type Description
x-mdt-filter-xpath string The filter xpath produced by §1 (one operation may be the recommended subscription root for multiple xpaths; in that case the annotation is on the closest matching operation).
x-mdt-tier enum: HOT | WARM | COOL Subscription tier from telemetry-reference.md.
x-mdt-cadence-seconds integer Recommended sample interval. Conventional values: 30 (HOT), 60 (WARM), 300 (COOL). Use 0 to denote on-change.
x-mdt-encoding enum: kvGPB | JSON_IETF Wire encoding. Default kvGPB.
x-mdt-on-change-capable boolean True if this xpath supports on-change (subscribe interval 0).
x-mdt-feature-section string Anchor link back to the matching §N section in telemetry-reference.md, e.g. #§1-cpu-utilization.

Example fragment in an oper-model spec operation:

{
  "get": {
    "summary": "Read cpu-usage/cpu-utilization",
    "x-mdt-filter-xpath": "/process-cpu-ios-xe-oper:cpu-usage/cpu-utilization",
    "x-mdt-tier": "WARM",
    "x-mdt-cadence-seconds": 60,
    "x-mdt-encoding": "kvGPB",
    "x-mdt-on-change-capable": false,
    "x-mdt-feature-section": "telemetry-reference.md#§1-cpu-utilization"
  }
}

4. telemetry-index.json (per release)

The annotation pass also emits releases/<ver>/telemetry-index.json consumed by the global telemetry browser (telemetry.html). Schema:

{
  "version": "26.1.1",
  "generated": "2026-04-25T12:00:00Z",
  "entries": [
    {
      "module": "Cisco-IOS-XE-process-cpu-oper",
      "spec": "swagger-oper-model/api/Cisco-IOS-XE-process-cpu-oper.json",
      "operation_id": "get-cpu-usage-cpu-utilization",
      "feature_section": "telemetry-reference.md#§1-cpu-utilization",
      "feature_title": "CPU Utilization",
      "filter_xpath": "/process-cpu-ios-xe-oper:cpu-usage/cpu-utilization",
      "tier": "WARM",
      "cadence_seconds": 60,
      "encoding": "kvGPB",
      "on_change_capable": false
    }
  ]
}

5. Annotation source of truth

The annotation pipeline (scripts/annotate_mdt_xpaths.py) joins three inputs:

  1. telemetry-reference.md — provides the authoritative feature → xpath, tier, cadence, on-change-capable mapping. The script parses each §N section and the "Subscription Summary Table" in Part IV.
  2. The OpenAPI spec for that module — locates the operation whose path most closely matches the YANG container path, and writes the extensions onto that operation.
  3. The pyang tree (releases/<ver>/yang-trees/<module>.html) — used as a fallback to confirm the prefix and that the container exists in the source YANG; if the tree disagrees with the reference doc, the build emits a warning and skips the annotation rather than emitting a wrong xpath.

If a feature in telemetry-reference.md references a module not present in the active release (e.g. a 26.1.1-only module annotating into a 17.9.x build), the annotator records it in the per-release telemetry-skipped.json with reason module-not-in-release. This is allowed and not a CI failure.

6. UI surfaces

Three surfaces, all reading the data above (no separate copy):

  1. Per-operation badge — Swagger UI plugin in swagger-oper-model/index.html reads x-mdt-filter-xpath from the rendered operation and injects an "MDT" badge with copy-to-clipboard.
  2. Per-viewer MDT panel — collapsible side panel listing every x-mdt-filter-xpath in the currently loaded oper spec; searchable; jumps to the matching operation when clicked.
  3. Global telemetry browser (telemetry.html) — loads releases/<ver>/telemetry-index.json; filters by tier (HOT/WARM/COOL), encoding, on-change-capable; deep-links into the appropriate oper-model viewer with #ver=<v>&spec=swagger-oper-model/<module> and scrolls to the matching operation.

7. Out of scope

  • Generating Postman/Bruno MDT subscribe payloads from these annotations (deferred; the project records this as a future enhancement).
  • gNMI dial-in / dial-out path syntax (the rule and validation in §1–2 are RESTCONF/MDT-flavored YANG xpath; gNMI prefix-relative paths require a different shape).
  • Subscriptions for non-operational models (config, RPC, events). Those are not MDT subscription targets.