Telemetry has the following configuration guidelines and limitations:
-
For information about supported platforms, see the Nexus Switch Platform Matrix.
-
Cisco NX-OS releases that support the data management engine (DME) Native Model support Telemetry.
-
Support is in place for the following:
-
The smallest sending interval (cadence) supported is five seconds for a depth of 0. The minimum cadence values for depth values
greater than 0 depends on the size of the data being streamed out. Configuring any cadences below the minimum value may result
in undesirable system behavior.
-
Telemetry supports up to five remote management receivers (destinations). Configuring more than five remote receivers may
result in undesirable system behavior.
-
Telemetry can consume up to 20% of the CPU resource.
-
In releases earlier than NX-OS Release 10.4(1)F, the time properties in DME config MOs are printed in local time, but the
time zone offset is always 00.00. For example, the time is displayed as 2024-05-21T14:01:03.012+00:00.
Beginning with NX-OS Release 10.5(1)F, the timestamps in DME config MOs like currentTime, modTs, and so on are displayed in
the localtime-timezone_offset format. For example, the time is displayed as 2024-05-21T14:01:03.012-04:00.
-
Beginning with Cisco NX-OS Release 10.4(2)F, telemetry is supported on the Cisco Nexus 93400LD-H1 platform switches.
-
Beginning with Cisco NX-OS Release 10.4(3)F, Telemetry is supported on 92348GC-X.
-
Beginning with Cisco NX-OS Release 10.4(2)F, telemetry is supported on the Cisco Nexus N9KC9364C-H1 platform switches.
-
Beginning with Cisco NX-OS Release 10.6(1)F, telemetry is supported on the Cisco Nexus N9336C-SE1 platform switches.
-
Beginning with Cisco NX-OS Release 10.6(1)F, the Securing NX-OS with Cisco Live Protect feature supports event logs that can
be exported using the telemetry feature with a new sensor path for nxsecure.
Configuration Commands After Downgrading to an Older Release
After a downgrade to an older release, some configuration commands or command options can fail because the older release may
not support them. When downgrading to an older release, unconfigure and reconfigure the telemetry feature after the new image
comes up. This sequence avoids the failure of unsupported commands or command options.
The following example shows this procedure:
-
Copy the telemetry configuration to a file:
switch# show running-config | section telemetry
feature telemetry
telemetry
destination-group 100
ip address 1.2.3.4 port 50004 protocol gRPC encoding GPB use-chunking size 4096
sensor-group 100 path sys/bgp/inst/dom-default depth 0
subscription 600
dst-grp 100
snsr-grp 100 sample-interval 7000
switch# show running-config | section telemetry > telemetry_running_config switch# show file bootflash:telemetry_running_config
feature telemetry
telemetry
destination-group 100
ip address 1.2.3.4 port 50004 protocol gRPC encoding GPB use-chunking size 4096
sensor-group 100 path sys/bgp/inst/dom-default depth 0
subscription 600
dst-grp 100
snsr-grp 100 sample-interval 7000
switch#
-
Execute the downgrade operation. When the image comes up and the switch is ready, copy the telemetry configurations back to
the switch.
switch# copy telemetry_running_config running-config echo-commands
`switch# config terminal`
`switch(config)# feature telemetry`
`switch(config)# telemetry`
`switch(config-telemetry)# destination-group 100`
`switch(conf-tm-dest)# ip address 1.2.3.4 port 50004 protocol gRPC encoding GPB `
`switch(conf-tm-dest)# sensor-group 100`
`switch(conf-tm-sensor)# path sys/bgp/inst/dom-default depth 0`
`switch(conf-tm-sensor)# subscription 600`
`switch(conf-tm-sub)# dst-grp 100`
`switch(conf-tm-sub)# snsr-grp 100 sample-interval 7000`
`switch(conf-tm-sub)# end`
Copy complete, now saving to disk (please wait)...
Copy complete. switch#
gRPC Error Behavior
The switch client disables the connection to the gRPC receiver if the gRPC receiver sends 20 errors. Unconfigure then reconfigure
the receiver's IP address under the destination group to enable the gRPC receiver.
Errors include:
-
The gRPC client sends the wrong certificate for secure connections.
-
The gRPC receiver takes too long to handle client messages and incurs a timeout. Avoid timeouts by processing messages using
a separate message processing thread.
Support for gRPC Chunking
Cisco NX-OS supports gRPC chunking. For streaming to occur successfully, you must enable chunking if gRPC has to send an amount
of data greater than 12 MB to the receiver.
The gRPC user must do the gRPC chunking. The gRPC client side does the fragmentation, and the gRPC server side does the reassembly.
Telemetry is still bound to memory and data can be dropped if the memory size is more than the allowed limit of 12 MB for
telemetry. In order to support chunking, use the telemetry .proto file that is available at Cisco's GibLab, which has been updated for gRPC chunking, as described in
The chunking size is from 64 through 4096 bytes.
Following shows a configuration example through the NX-API CLI:
feature telemetry !
telemetry
destination-group 1
ip address 171.68.197.40 port 50051 protocol gRPC encoding GPB use-chunking size 4096
destination-group 2
ip address 10.155.0.15 port 50001 protocol gRPC encoding GPB use-chunking size 64
sensor-group 1 path sys/intf depth unbounded
sensor-group 2 path sys/intf depth unbounded
subscription 1
dst-grp 1
snsr-grp 1 sample-interval 10000
subscription 2
dst-grp 2 snsr-grp 2 sample-interval 15000
Following shows a configuration example through the NX-API REST:
{
"telemetryDestGrpOptChunking": {
"attributes": {
"chunkSize": "2048",
"dn": "sys/tm/dest-1/chunking"
}
The following error message appears on systems that do not support gRPC chunking, such as the Cisco MDS series switches:
switch# use-chunking size 200
ERROR: Operation failed: [chunking support not available]
NX-API Sensor Path Limitations
NX-API can collect and stream switch information not yet in the DME using show commands. However, using the NX-API instead of streaming data from the DME has inherent scale limitations as outlined:
-
The switch backend dynamically processes NX-API calls such as show commands,
-
NX-API spawns several processes that can consume up to a maximum of 20% of the CPU.
-
NX-API data translates from the CLI to XML to JSON.
The following is a suggested user flow to help limit excessive NX-API sensor path bandwidth consumption:
-
Check whether the show command has NX-API support. You can confirm whether NX-API supports the command from the VSH with the pipe option:
show
<command> | json
or show <command> | json pretty.
Note
|
Avoid commands that take the switch more than 30 seconds to return JSON output.
|
-
Refine the show command to include any filters or options.
Avoid enumerating the same command for individual outputs; for example, show vlan id 100 , show vlan id 101 , and so on. Instead,
use the CLI range options; for example, show vlan id 100-110,204 , whenever possible to improve performance.
If only the summary or counter is needed, then avoid dumping a whole show command output to limit the bandwidth and data storage
that is required for data collection.
-
Configure telemetry with sensor groups that use NX-API as their data sources. Add the show commands as sensor paths
-
Configure telemetry with a cadence of five times the processing time of the respective show command to limit CPI usage.
-
Receive and process the streamed NX-API output as part of the existing DME collection.
Telemetry VRF Support
Telemetry VRF support allows you to specify a transport VRF, which means that the telemetry data stream can egress through
front-panel ports and avoid possible competition between SSH or NGINX control sessions.
You can use the use-vrf vrf-name command to specify the transport VRF.
The following example specifies the transport VRF:
The following is an example of use-vrf as a POST payload:
{
"telemetryDestProfile": {
"attributes": {
"adminSt": "enabled"
},
"children": [
{
"telemetryDestOptVrf": { "attributes": {
"name": "default"
}
}
}
]
}
}
In a given configuration, only one VRF can be used to route data for a specific IP address and port combination. The VRF that
will be used is determined by the vrf configuration done at the end.
For example:
telemetry
destination-group 1
ip address 91.1.1.1 port 50007
use-vrf default
destination-group 2
ip address 91.1.1.1 port 50007
use-vrf test
sensor-group 1
data-source DME
path sys/fm
subscription 1
dst-grp 1
dst-grp 2
snsr-grp 1 sample-interval 1000
In the above configuration, both destination-group 1 and destination-group 2 have the same destination IP address and port
(91.1.1.1 50007), but different VRFs are configured (default and test). In this scenario, if destination-group 2 is configured
last, the data sent to 91.1.1.1 50007 will be routed using the test VRF. If there are no VRF configured for a destination-group, it will implicitly use management VRF.
Certificate Trustpoint Support
Telemetry supports the trustpoint keyword.
The following is the command syntax:
switch(config-telemetry)# certificate ?
trustpoint specify trustpoint label
WORD .pem certificate filename (Max Size 256)
switch(config-telemetry)# certificate trustpoint
WORD trustpoint label name (Max Size 256)
switch(config-telemetry)# certificate trustpoint trustpoint1 ?
WORD Hostname associated with certificate (Max Size 256)
switch(config-telemetry)#certificate trustpoint trustpoint1 foo.test.google.fr
Destination Hostname Support
Telemetry supports the host keyword in destination-group command.
The following is the example for the destination hostname support:
switch(config-telemetry)# destination-group 1
switch(conf-tm-dest)# ?
certificate Specify certificate
host Specify destination host
ip Set destination IPv4 address
ipv6 Set destination IPv6 address
...
switch(conf-tm-dest)# host ?
A.B.C.D|A:B::C:D|WORD IPv4 or IPv6 address or DNS name of destination
switch(conf-tm-dest)#
switch(conf-tm-dest)# host abc port 11111 ?
protocol Set transport protocol
switch(conf-tm-dest)# host abc port 11111 protocol ?
HTTP
UDP
gRPC
switch(conf-tm-dest)# host abc port 11111 protocol gRPC ?
encoding Set encoding format
switch(conf-tm-dest)# host abc port 11111 protocol gRPC encoding ?
Form-data Set encoding to Form-data only
GPB Set encoding to GPB only
GPB-compact Set encoding to Compact-GPB only
JSON Set encoding to JSON
XML Set encoding to XML
switch(conf-tm-dest)# host ip address 1.1.1.1 port 2222 protocol HTTP encoding JSON
<CR>
Support for Node ID
Telemetry supports a custom Node ID string for a telemetry receiver through the use-nodeid command. By default, the host name is used, but support for a node ID enables you to set or change the identifier for the
node_id_str of the telemetry receiver data.
You can assign the node ID through the telemetry destination profile, by using the usenode-id command. This command is optional.
The following example shows configuring the node ID.
switch(config)# telemetry
switch(config-telemetry)# destination-profile
switch(conf-tm-dest-profile)# use-nodeid test-srvr-10
switch(conf-tm-dest-profile)#
The following example shows a telemetry notification on the receiver after the node ID is configured.
Telemetry receiver:
==================================
node_id_str: "test-srvr-10"
subscription_id_str: "1" encoding_path:
"sys/ch/psuslot-1/psu" collection_id:
3896 msg_timestamp: 1559669946501
Use the use-nodeid sub-command under the host command. The destination level use-nodeid configuration precedes the global level configuration. The following example shows the command syntax:
switch(config-telemetry)# destination-group 1
switch(conf-tm-dest)# host 172.19.216.78 port 18112 protocol http enc json
switch(conf-tm-dest-host)# use-nodeid ?
WORD Node ID (Max Size 128)
switch(conf-tm-dest-host)# use-nodeid session_1:18112
The following example shows the output from the Telemetry receiver:
>> Message size 923
Telemetry msg received @ 23:41:38 UTC Msg Size: 11
node_id_str : session_1:18112 collection_id : 3118
data_source : DME
encoding_path : sys/ch/psuslot-1/psu collection_
start_time : 1598485314721
collection_end_time : 1598485314721
data :
Support for Streaming of YANG Models
Telemetry supports the YANG ("Yet Another Next Generation") data modeling language. Telemetry supports data streaming for
both device YANG and OpenConfig YANG.
Support for Proxy
Telemetry supports the proxy keyword in the host command. The following is the command syntax:
switch(config-telemetry)# destination-group 1
switch(conf-tm-dest)# host 172.19.216.78 port 18112 protocol http enc json
switch(conf-tm-dest-host)# proxy ?
A.B.C.D|A:B::C:D|WORD IPv4 or IPv6 address or DNS name of proxy server
<1-65535> Proxy port number, Default value is 8080 username Set proxy authentication username
password Set proxy authentication password
gRPC Asynchronous Mode
The gRPC asynchronous mode is available only under the host command. In normal stream condition, this mode allows the receivers to stream data in mdtDialout call without exiting or receiving WriteDone() call.
The following is the command syntax:
nxosv-1(config-telemetry)# destination-group 1
nxosv-1(conf-tm-dest)# host 172.22.244.130 port 50007 ?
nxosv-1(conf-tm-dest-host)# grpc-async ?
Single Telemetry Collection for Sensor Groups
Beginning with Cisco NX-OS 10.5(2)F, users can use a new CLI option merge-subscriptions under telemetry CLI to create a single telemetry collection for the sensor groups when they are included in multiple subscriptions unless
a parser file is configured in any of its destination groups.
-
You cannot use this configuration for event subscriptions.
-
Filter file configuration under destination group and merge-subscriptions are not compatible with each other. It is not blocked
in the NX-OS. The collections will happen separately for all sensor groups in that case, which is same as earlier releases.
-
The sample interval for sending data for subscriptions with a larger sample interval is determined using the following formula:
min_sample_interval*floor(cur_sample_interval /min_sample_interval).
-
This option is not available in the earlier releases, remove this configuration before downgrading to avoid compatibility
check failure.
Support for HEC Protocol
Beginning with Cisco NX-OS 10.6(3), telemetry supports HEC Protocol that users can use to stream telemetry data to a Splunk
HTTP Event Collector (HEC). To configure the protocol, users need to configure a HEC token, an index name, and a specific
HEC REST API endpoint URL via the CLI. If not specified, index-name defaults to "main", and the endpoint defaults to "services/collector".
Note
|
Only JSON encoding is supported for the HEC protocol.
|
Feedback