Cisco Nexus 3000 and 9000 Series NX-API REST SDK and API, Release 7.x

NX-OS 7(x)

Cisco Nexus 3000 and 9000 Series NX-API REST Documentation

Step 1

DME

Copy
GET http://<IP_Address>/api/mo/sys/fm/nxapi.json
Response
{
  "fmNxapi": {
    "attributes": {
      ...
      "adminSt": "enabled"
      ...
}}}

Configuring Telemetry

This section contains payload examples to demonstrate how to use the NX-API REST API to configure telemetry on the Cisco Nexus 3000 and 9000 Series switches.

Telemetry offers a push model of network monitoring that provides clients with a near-real-time stream of network data.

Enabling the Telemetry Feature

The following steps enable the telemetry feature.

Use GET to check that the NX-API is enabled.
Enable the telemetry feature.
Enable the telemetry configuration.

Step 1

Use GET to check that the NX-API is enabled.

Step 1

See the NX-API DME Model Reference for detailed information about classes and attributes described in the payload: https://developer.cisco.com/site/nx-os/docs/nexus-model-reference/

For information about using the payloads, see the Cisco Nexus 9000 Series NX-OS Programmability Guide https://www.cisco.com/c/en/us/support/switches/nexus-9000-series-switches/products-programming-reference-guides-list.html

Step 2

Enable the Telemetry Feature

Step 2

This example enables the streaming telemetry feature.

CLI Command

The CLI command below is the equivalent to the payload example displayed in the pane on the right. Click the DME tab in the top-left corner of the right pane to view the JSON payload or the YANG tab to view the XML payload.

feature telemetry

For other CLI options, see the Cisco Nexus 9000 Series NX-OS Command Reference: http://www.cisco.com/c/en/us/support/switches/nexus-9000-series-switches/products-command-reference-list.html

See the NX-API DME Model Reference for detailed information about classes and attributes described in the payload: https://developer.cisco.com/site/nx-os/docs/nexus-model-reference/

Step 3

Enable the telemetry configuration.

Step 3

Enters configuration mode for streaming telemetry.

CLI Command

telemetry

For other CLI options, see the Cisco Nexus 9000 Series NX-OS Command Reference: http://www.cisco.com/c/en/us/support/switches/nexus-9000-series-switches/products-command-reference-list.html

See the NX-API DME Model Reference for detailed information about classes and attributes described in the payload: https://developer.cisco.com/site/nx-os/docs/nexus-model-reference/

Configuring Sensor Groups

This section contains examples that demonstrate how to configure a sensor group.

Creating a Sensor Group

Creates a sensor group and enters sensor group configuration mode.

CLI Commands

The CLI commands and options are equivalent to the payload examples displayed in the pane on the right. Click the DME tab in the top-left corner of the right pane to view the JSON payload or the YANG tab to view the XML payload.

telemetry
sensor-group 100

For other CLI options, see the Cisco Nexus 9000 Series NX-OS Command Reference: http://www.cisco.com/c/en/us/support/switches/nexus-9000-series-switches/products-command-reference-list.html

See the NX-API DME Model Reference for detailed information about classes and attributes described in the payload: https://developer.cisco.com/site/nx-os/docs/nexus-model-reference/

Adding a Sensor Group Path

Adds a sensor path to the sensor group. The depth setting specifies the retrieval level for the sensor path. A depth setting of 0, the only supported setting, retrieves only the root MO properties. The optional filter-condition parameter can be specified to create a specific filter for event-based subscriptions.

CLI Commands

telemetry
sensor-group 100
path sys/bgp depth 0

For other CLI options, see the Cisco Nexus 9000 Series NX-OS Command Reference: http://www.cisco.com/c/en/us/support/switches/nexus-9000-series-switches/products-command-reference-list.html

See the NX-API DME Model Reference for detailed information about classes and attributes described in the payload: https://developer.cisco.com/site/nx-os/docs/nexus-model-reference/

Configuring Intended Data Depth in Streaming Telemetry

Note: This is an existing command with newly allowed depth values. Unbounded in Release 7.0.3.6(1), the value could only be 0 or 1. Beginning in Release 7.0.3.7(1), the value can be either from 0 up to 32 or the special value unbounded. The command indicates the number of child levels to retrieve given a MO.

Note: This example was added in Release 7.0(3)I7(1).

CLI Commands

The CLI commands and options are equivalent to the payload example displayed in the pane on the right.

telemetry
sensor-group 10
path sys/bgp depth 3

For other CLI options, see the Cisco Nexus 9000 Series NX-OS Command Reference: http://www.cisco.com/c/en/us/support/switches/nexus-9000-series-switches/products-command-reference-list.html

See the NX-API DME Model Reference for detailed information about classes and attributes described in the payload: https://developer.cisco.com/site/nx-os/docs/nexus-model-reference/

Streaming Foreign Data from as Part of Streaming Telemetry

The query-condition option takes rsp-foreign-subtree=applied-config and rsp-foreign-subtree=ephemeral; it indicates whether to look up an applied configuration or an ephemeral MO.

Note: This example was added in Release 7.0(3)I7(1).

CLI Commands

The CLI commands and options are equivalent to the payload example displayed in the pane on the right.

telemetry
sensor-group 10
path sys/bgp/inst/dom-default/af-ipv4-ucast depth 3 query-condition rsp-foreign-subtree=applied-config
path sys/bgp/inst/dom-default/af-[l2vpn-evpn] depth 1 query-condition rsp-foreign-subtree=ephemeral

For other CLI options, see the Cisco Nexus 9000 Series NX-OS Command Reference: http://www.cisco.com/c/en/us/support/switches/nexus-9000-series-switches/products-command-reference-list.html

See the NX-API DME Model Reference for detailed information about classes and attributes described in the payload: https://developer.cisco.com/site/nx-os/docs/nexus-model-reference/

Configuring Destination Groups

The destination group specifies the destination address, port, encoding and transport that the router uses to send out telemetry data.

This section contains payload examples and CLIs to demonstrate many of the destination group configuration options and to show how the REST APIs correspond to the CLI commands.

Adding a Destination Group

Creates a destination group with ID destination_group_ID and enters destination group configuration mode. Currently only numeric ID values are supported.

CLI Commands

telemetry
destination-group 100

For other CLI options, see the Cisco Nexus 9000 Series NX-OS Command Reference: http://www.cisco.com/c/en/us/support/switches/nexus-9000-series-switches/products-command-reference-list.html

See the NX-API DME Model Reference for detailed information about classes and attributes described in the payload: https://developer.cisco.com/site/nx-os/docs/nexus-model-reference/

Configuring the HTTP Protocol for a Destination Group

Configures the HTTP Protocol for a Destination Group

Note: This example was added in Release 7.0(3)I7(1).

CLI Commands

The CLI commands are equivalent to the payload examples displayed in the pane on the right. Click the DME tab in the top-left corner of the right pane to view the JSON payload. Click the YANG tab to view the XML payload.

telemetry
destination-group 100
ip address 1.2.3.4 port 50008 protocol http encoding json

For other CLI options, see the Cisco Nexus 9000 Series NX-OS Command Reference: http://www.cisco.com/c/en/us/support/switches/nexus-9000-series-switches/products-command-reference-list.html

See the NX-API DME Model Reference for detailed information about classes and attributes described in the payload: https://developer.cisco.com/site/nx-os/docs/nexus-model-reference/

Configuring the UDP Protocol for a Destination Group

Configures the UDP Protocol for a Destination Group

Note: This example was added in Release 7.0(3)I7(1).

CLI Commands

telemetry
destination-group 100
ip address 1.2.3.4 port 50008 protocol udp encoding json

For other CLI options, see the Cisco Nexus 9000 Series NX-OS Command Reference: http://www.cisco.com/c/en/us/support/switches/nexus-9000-series-switches/products-command-reference-list.html

See the NX-API DME Model Reference for detailed information about classes and attributes described in the payload: https://developer.cisco.com/site/nx-os/docs/nexus-model-reference/

Creating a Destination Profile for Outgoing Data

Configures telemetry to send data to a destination IP address. You can specify transporting the data using the Google remote procedure call (gRPC) protocol, and to encode the data using Google Protocol Buffers (GPB) format.

Note: This example was added in Release 7.0(3)I7(1).

CLI Commands

telemetry
destination-group 100
ip address 1.2.3.4 port 50003

For other CLI options, see the Cisco Nexus 9000 Series NX-OS Command Reference: http://www.cisco.com/c/en/us/support/switches/nexus-9000-series-switches/products-command-reference-list.html

See the NX-API DME Model Reference for detailed information about classes and attributes described in the payload: https://developer.cisco.com/site/nx-os/docs/nexus-model-reference/

Configuring a Subscription

This section contains payload examples and CLIs to demonstrate many of the subscription configuration options and to show how the REST APIs correspond to the CLI commands.

Creating a Subscription Node

Creates a subscription node with ID sub_id and enters the subscription configuration mode. Currently only numeric ID values are supported.

CLI Commands

telemetry
subscription 100

For other CLI options, see the Cisco Nexus 9000 Series NX-OS Command Reference: http://www.cisco.com/c/en/us/support/switches/nexus-9000-series-switches/products-command-reference-list.html

See the NX-API DME Model Reference for detailed information about classes and attributes described in the payload: https://developer.cisco.com/site/nx-os/docs/nexus-model-reference/

Configuring a Subscription Sensor Group

Links the sensor group with ID sensor_group_ID to this subscription and also sets the data sampling interval in milliseconds. An interval value of 0 creates an event-based subscription, in which telemetry data is sent only upon changes under the specified MO. An interval value greater than 0 creates a frequency-based subscription, in which telemetry data is sent periodically at the specified interval. For example, an interval value of 15000 results in the sending of telemetry data every 15 seconds.

CLI Commands

telemetry
subscription 100
snsr-grp 100 sample-interval 1500

For other CLI options, see the Cisco Nexus 9000 Series NX-OS Command Reference: http://www.cisco.com/c/en/us/support/switches/nexus-9000-series-switches/products-command-reference-list.html

See the NX-API DME Model Reference for detailed information about classes and attributes described in the payload: https://developer.cisco.com/site/nx-os/docs/nexus-model-reference/

Configuring a Subscription Destination Group

Links the destination group with ID destination_group_ID to this subscription.

CLI Commands

telemetry
subscription 100
sdst-grp 100

For other CLI options, see the Cisco Nexus 9000 Series NX-OS Command Reference: http://www.cisco.com/c/en/us/support/switches/nexus-9000-series-switches/products-command-reference-list.html

See the NX-API DME Model Reference for detailed information about classes and attributes described in the payload: https://developer.cisco.com/site/nx-os/docs/nexus-model-reference/

Configuring a Subscription for Event Notification Without Filter Conditions

The following example shows how to subscribe to notifications for when BGP is enabled or disabled using the path attribute.

CLI Commands

telemetry
subscription 100
path sys/fm/bgp depth 0

For other CLI options, see the Cisco Nexus 9000 Series NX-OS Command Reference: http://www.cisco.com/c/en/us/support/switches/nexus-9000-series-switches/products-command-reference-list.html

See the NX-API DME Model Reference for detailed information about classes and attributes described in the payload: https://developer.cisco.com/site/nx-os/docs/nexus-model-reference/

Configuring a Subscription for Event Notifications with Filter Conditions

The following example will only generate notifications for BGP when BGP is disabled using the path attribute. The DME provides the filter expressions for the filterCondition attribute.

CLI Commands

telemetry
subscription 100
path sys/fm/bgp depth 0 filter-condition eq(fmBgp.operSt,\"disabled\")

For other CLI options, see the Cisco Nexus 9000 Series NX-OS Command Reference: http://www.cisco.com/c/en/us/support/switches/nexus-9000-series-switches/products-command-reference-list.html

See the NX-API DME Model Reference for detailed information about classes and attributes described in the payload: https://developer.cisco.com/site/nx-os/docs/nexus-model-reference/

Configuring Destination Profiles

This section contains payload examples and CLIs to demonstrate many of the destination profile configuration options and to show how the REST APIs correspond to the CLI commands.

Configuring the Default Destination Profile

Note: This example was added in Release Cisco NX-OS Release 7.0(3)I7(2).

CLI Commands

telemetry
destination-profile

For other CLI options, see the Cisco Nexus 9000 Series NX-OS Command Reference: http://www.cisco.com/c/en/us/support/switches/nexus-9000-series-switches/products-command-reference-list.html

See the NX-API DME Model Reference for detailed information about classes and attributes described in the payload: https://developer.cisco.com/site/nx-os/docs/nexus-model-reference/

Disabling the Default Destination Profile

Note: This example was added in Release Cisco NX-OS Release 7.0(3)I7(2).

CLI Commands

telemetry
no destination-profile

For other CLI options, see the Cisco Nexus 9000 Series NX-OS Command Reference: http://www.cisco.com/c/en/us/support/switches/nexus-9000-series-switches/products-command-reference-list.html

See the NX-API DME Model Reference for detailed information about classes and attributes described in the payload: https://developer.cisco.com/site/nx-os/docs/nexus-model-reference/

Configuring the Destination VRF for a Destination Profile

Configures the destination VRF for a destination profile.

Note: This example was added in Release 7.0(3)I7(1).

CLI Commands

telemetry
destination-profile
use-vrf default

For other CLI options, see the Cisco Nexus 9000 Series NX-OS Command Reference: http://www.cisco.com/c/en/us/support/switches/nexus-9000-series-switches/products-command-reference-list.html

See the NX-API DME Model Reference for detailed information about classes and attributes described in the payload: https://developer.cisco.com/site/nx-os/docs/nexus-model-reference/

Disabling the Destination VRF for a Destination Profile

Note: This example was added in Release Cisco NX-OS Release 7.0(3)I7(2).

CLI Commands

telemetry
destination-profile
no use-vrf

For other CLI options, see the Cisco Nexus 9000 Series NX-OS Command Reference: http://www.cisco.com/c/en/us/support/switches/nexus-9000-series-switches/products-command-reference-list.html

See the NX-API DME Model Reference for detailed information about classes and attributes described in the payload: https://developer.cisco.com/site/nx-os/docs/nexus-model-reference/

Enabling Gzip Compression for a Destination Profile

Enables gzip compression.

Note: This example was added in Release 7.0(3)I7(1).

CLI Commands

The CLI commands and options are equivalent to the payload example displayed in the pane on the right.

telemetry
destination-profile
use-compression gzip

For other CLI options, see the Cisco Nexus 9000 Series NX-OS Command Reference: http://www.cisco.com/c/en/us/support/switches/nexus-9000-series-switches/products-command-reference-list.html

See the NX-API DME Model Reference for detailed information about classes and attributes described in the payload: https://developer.cisco.com/site/nx-os/docs/nexus-model-reference/

Disabling Gzip Compression for a Destination Profile

Disables gzip compression.

Note: This example was added in Release 7.0(3)I7(1).

CLI Commands

The CLI commands and options are equivalent to the payload example displayed in the pane on the right.

telemetry
destination-profile
no use-compression gzip

For other CLI options, see the Cisco Nexus 9000 Series NX-OS Command Reference: http://www.cisco.com/c/en/us/support/switches/nexus-9000-series-switches/products-command-reference-list.html

See the NX-API DME Model Reference for detailed information about classes and attributes described in the payload: https://developer.cisco.com/site/nx-os/docs/nexus-model-reference/

Configuring an IPv6 Address Under a Telemetry Destination Group

The format options include:

UDP
gRPC
HTTP
GPB
JSON

Note: This example was added in Release 9.1(2).

CLI Commands

telemetry
destination-group 123
ip address 1.2.3.4 port 123 protocol udp encoding GPB

For other CLI options, see the Cisco Nexus 9000 Series NX-OS Command Reference: http://www.cisco.com/c/en/us/support/switches/nexus-9000-series-switches/products-command-reference-list.html

See the NX-API DME Model Reference for detailed information about classes and attributes described in the payload: https://developer.cisco.com/media/dme/index.html

Deleting an IPv6 Address Under a Telemetry Destination Group

The format options include:

UDP
gRPC
HTTP
GPB
JSON

Note: This example was added in Release 9.1(2).

CLI Commands

telemetry
destination-group 123
no ip address 1.2.3.4 port 123 protocol udp encoding json

For other CLI options, see the Cisco Nexus 9000 Series NX-OS Command Reference: http://www.cisco.com/c/en/us/support/switches/nexus-9000-series-switches/products-command-reference-list.html

See the NX-API DME Model Reference for detailed information about classes and attributes described in the payload: https://developer.cisco.com/media/dme/index.html

Configuring the Encoding Format (Under a Telemetry Destination-Group)

The format options include:

UDP
gRPC
HTTP
GPB
JSON

Note: This example was added in Release 9.1(2).

CLI Commands

telemetry
destination-group 123
ipv6 address 1:2::3:4 port 123 protocol udp encoding json

For other CLI options, see the Cisco Nexus 9000 Series NX-OS Command Reference: http://www.cisco.com/c/en/us/support/switches/nexus-9000-series-switches/products-command-reference-list.html

See the NX-API DME Model Reference for detailed information about classes and attributes described in the payload: https://developer.cisco.com/media/dme/index.html

Deleting the Encoding Format (Under a Telemetry Destination-Group)

The format options include:

UDP
gRPC
HTTP
GPB
JSON

Note: This example was added in Release 9.1(2).

CLI Commands

telemetry
destination-group 123
no ipv6 address 1:2::3:4 port 123 protocol udp encoding json

For other CLI options, see the Cisco Nexus 9000 Series NX-OS Command Reference: http://www.cisco.com/c/en/us/support/switches/nexus-9000-series-switches/products-command-reference-list.html

See the NX-API DME Model Reference for detailed information about classes and attributes described in the payload: https://developer.cisco.com/media/dme/index.html

Enabling Chunking

Note: This example was added in Release 9.1(2).

CLI Commands

telemetry
destination-group 1
ip address 171.68.197.40 port 50051 protocol gRPC encoding GPB
use-chunking size 4096

For other CLI options, see the Cisco Nexus 9000 Series NX-OS Command Reference: http://www.cisco.com/c/en/us/support/switches/nexus-9000-series-switches/products-command-reference-list.html

See the NX-API DME Model Reference for detailed information about classes and attributes described in the payload: https://developer.cisco.com/media/dme/index.html

Disabling Chunking

Note: This example was added in Release 9.1(2).

CLI Commands

telemetry
destination-group 1
ip address 171.68.197.40 port 50051 protocol gRPC encoding GPB
no use-chunking

For other CLI options, see the Cisco Nexus 9000 Series NX-OS Command Reference: http://www.cisco.com/c/en/us/support/switches/nexus-9000-series-switches/products-command-reference-list.html

See the NX-API DME Model Reference for detailed information about classes and attributes described in the payload: https://developer.cisco.com/media/dme/index.html

Configuring the Retry Buffer Size (Under a Telemetry Destination-Group)

Note: This example was added in Release 9.1(2).

CLI Commands

telemetry
destination-profile
use-retry size 123

For other CLI options, see the Cisco Nexus 9000 Series NX-OS Command Reference: http://www.cisco.com/c/en/us/support/switches/nexus-9000-series-switches/products-command-reference-list.html

See the NX-API DME Model Reference for detailed information about classes and attributes described in the payload: https://developer.cisco.com/media/dme/index.html

Deleting the Retry Buffer Size (Under a Telemetry Destination-Group)

Note: This example was added in Release 9.1(2).

CLI Commands

telemetry
destination-profile
no use-retry

For other CLI options, see the Cisco Nexus 9000 Series NX-OS Command Reference: http://www.cisco.com/c/en/us/support/switches/nexus-9000-series-switches/products-command-reference-list.html

See the NX-API DME Model Reference for detailed information about classes and attributes described in the payload: https://developer.cisco.com/media/dme/index.html

Configuring the Default Destination Profile

Note: This example was added in Release 9.1(2).

CLI Commands

telemetry
destination-profile
source-interface loopback0

For other CLI options, see the Cisco Nexus 9000 Series NX-OS Command Reference: http://www.cisco.com/c/en/us/support/switches/nexus-9000-series-switches/products-command-reference-list.html

See the NX-API DME Model Reference for detailed information about classes and attributes described in the payload: https://developer.cisco.com/media/dme/index.html

Deleting the Default Destination Profile

Note: This example was added in Release 9.1(2).

CLI Commands

telemetry
destination-profile
source-interface loopback0

For other CLI options, see the Cisco Nexus 9000 Series NX-OS Command Reference: http://www.cisco.com/c/en/us/support/switches/nexus-9000-series-switches/products-command-reference-list.html

See the NX-API DME Model Reference for detailed information about classes and attributes described in the payload: https://developer.cisco.com/media/dme/index.html

Configuring the Data Source

Note: This example was added in Release 9.1(2).

CLI Commands

telemetry
sensor-group 1
data-source YANG
path Cisco-NX-OS-device:System/intf-items

For other CLI options, see the Cisco Nexus 9000 Series NX-OS Command Reference: http://www.cisco.com/c/en/us/support/switches/nexus-9000-series-switches/products-command-reference-list.html

See the NX-API DME Model Reference for detailed information about classes and attributes described in the payload: https://developer.cisco.com/media/dme/index.html

Deleting the Data Source

Note: This example was added in Release 9.1(2).

CLI Commands

telemetry
sensor-group 1
data-source YANG
no path Cisco-NX-OS-device:System/intf-items

For other CLI options, see the Cisco Nexus 9000 Series NX-OS Command Reference: http://www.cisco.com/c/en/us/support/switches/nexus-9000-series-switches/products-command-reference-list.html

See the NX-API DME Model Reference for detailed information about classes and attributes described in the payload: https://developer.cisco.com/media/dme/index.html