Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 
ON THIS PAGE
 

Configure a NETCONF Proxy Telemetry Sensor in Junos

Using Junos telemetry streaming, you can turn any available state information into a telemetry sensor by means of the XML Proxy functionality. The NETCONF XML management protocol and Junos XML API fully document all options for every supported Junos OS operational request. After you configure XML proxy sensors, you can access data over NETCONF “get” remote procedure calls (RPCs).

This task shows you how to stream the output of a Junos OS operational mode command.

Best Practice:

We recommend not to use YANG files that map to a Junos OS operational command with extensive or verbose output or one that is slow in producing output. Commands with a noticeable delay should be avoided in YANG files. Including such commands can affect other xmlproxyd sensors as well as the performance of xmlproxyd.

The output from some operational mode commands is dynamic and the level of their verbosity depends on factors such as the configuration and hardware. Examples of such commands include any variation of show interfaces, show route, show arp, show bfd, show bgp, and show ddos-protection.

To check the verbosity level of a command, issue the command-name| display xml | count command. If the line count exceeds a value of 4000 lines, then the command is not recommended for XML proxy streaming. This value is more of an approximation based on internal base-lining. It can be less depending upon various factors such as device type, processing power of the device, and the existing CPU load. Consequently, this feature needs to be used judiciously based on how the device is performing.

You can issue the command command-name| display xml before using a YANG file that maps to a Junos OS or Junos OS Evolved operational mode command to verify that the command produces valid XML output and does not contain invalid tags, data, or formatting.

Using a YANG file that maps to a verbose command results in one or more of following:

  • The xmlproxyd process CPU utilization remains high. If xmlproxyd has tracing enabled, the CPU utilization is even higher.

  • An increase in the xmlproxyd process memory utilization.

  • The xmlproxyd process state may show sbwait, indicating that the command output is verbose and that xmlproxyd is spending significant time reading the command's remote procedure call’s (RPC’s) output.

  • The xmlproxyd sensor data does not complete the wrap.

  • The xmlproxyd streams partial or no data for the sensors.

  • The xmlproxyd misses reporting-interval cycles. The intervals start to overlap because of a command’s verbose output, resulting in the xmlproxyd's sensor streaming data that is slow or delayed.

  • The process or application that serves the verbose command's RPC may show high CPU numbers or delays in performing main tasks. This behavior is caused when the process or application is busy serving the RPC that has verbose output.

This task requires the following:

  • An MX Series, vMX Series, or PTX Series router operating Junos OS Release 17.3R2 or later.

  • A telemetry data receiver, such as OpenNTI, to verify proper operation of your telemetry sensor.

In this task, you will stream the contents of the Junos OS command show system users.

show system users (vMX Series)

In addition to the expected list of currently logged-in users, the show system users output also provides the average system load as 1, 5 and 15 minutes. You can find the load averages by using the show system users | display xml command to view the XML tagging for the output fields. See <load-average-1>, <load-average-5>, and <load-average-15> in the XML tagging output below.

Tip:

The uptime-information tag shown in the preceding output is a container that contains leafs, such as date-time, up-time, active-user-count. and load-average-1. Below is a sample YANG file for this container:
Tip:

The uptime-information tag also has another container named user-table that contains a list of user entries.

Below is a sample YANG file for this container:

Create a User-Defined YANG File

The YANG file defines the Junos CLI command to be executed, the resource path the sensors are placed under, and the key value pairs taken from the matching XML tags.

Custom YANG files for Junos OS conform to the YANG language syntax defined in RFC 6020 YANG 1.0 YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF) and RFC 7950 The YANG 1.1 Data Modeling Language. Certain directives need to be present in the file that configure XML proxy.

To use the xmlproxyd process to translate telemetry data, create a render.yang file. In this file, the dr:command-app is set to xmlproxyd.

The XML proxy YANG filename and module name must start with xmlproxyd_:

  • For the XML proxy YANG filename, add the extension .yang, for example, xmlproxyd_sysusers.yang

  • For the module name, use the filename without the extension .yang, for example, xmlproxyd_sysusers

To simplify creating a YANG file, it’s easiest to start by modifying a working example.

  1. Provide a name for the module. The module name must start with xmlproxyd_ and be the same name as the XML proxy YANG file name.

    For example, for an XML proxy YANG file called sysusers.yang, drop the .yang extension and name the module xmlproxyd_sysusers:

    module xmlproxyd_sysusers {

  2. For the Junos telemetry interface include the process name xmlproxyd:

    dr:command-app "xmlproxyd";

  3. Include the following RPC for the NETCONF get request:

    rpc juniper-netconf-get {

  4. Specify the location of the output of the RPC, where company-name is the name you give to the location:

    dr:command-top-of-output "/company-name";

  5. Include the following command to execute the RPC:

    dr:command-full-name "drend juniper-netconf-get";

  6. Specify the CLI command from which to retrieve data. The Junos OS CLI command that gets executed at the requested sample frequency is defined under dr:cli-command and executed by the xmlproxyd process.

    To retrieve command output for the Junos OS command show system users:

    dr:cli-command "show system users";

  7. Escalate privileges, logon as “root”, connect to the internal management socket via Telnet, and specify help for an RPC:

    dr: command-help “default <get> rpc”;

    When this is included in the YANG file, output that is helpful for debugging is displayed in the help drend output on the internal management socket:

    200-juniper-netconf-get-0 system users <get> RPC

  8. Specify the hierarchy and use the dr:source command to map to a container, a list, or a specific leaf. The absolute path under which the sensors will be reported is built from the output group junos plus system-users-information, concatenated by /’. The path /junos/system-users-information/ is the path to query for information about this custom sensor.
    Warning:

    You should not create a custom YANG model that conflicts or overlaps with predefined native paths (Juniper defined paths) and OpenConfig paths (resources). Doing so can result in undefined behavior.

    For example, do not create a model that defines new leafs at or augments nodes for resource paths such as /junos/system/linecard/firewallor /interfaces.

    A one-to-one mapping between container, leafs and the XML tag or value from the CLI command output is defined in the grouping referenced by uses within the output container. A grouping can be referred to multiple times in different container outputs. The container system-users-information below uses the grouping system-users-information. However, it is defined without the aforementioned one-to-one mapping for every container, list and leaf to an output XML tag from the CLI command XML output.

  9. The following YANG file shows how to include these commands to enable the xmlproxyd process to retrieve the full operational state and map it to the leafs in Juniper’s own data model:

Load the Yang File in Junos

After the YANG file is complete, upload the YANG file and verify that the module is created.

  1. Upload the YANG file to the router.
  2. Register the YANG file using the request system yang add package command.
    Note:

    Starting in Junos OS Release 18.3R1, adding, deleting, or updating YANG packages in configuration mode with the run command is not supported.

  3. Verify that the module (sensor) is registered using the show system yang package sysusers command, where sysusers is the name of the package:
  4. Enable gRPC in the Junos OS configuration:

Collect Sensor Data

Use your favorite collector to pull the newly created telemetry sensor data from the device.

Consider resource constraints before initiating sensors:

  • Avoid specifying the same reporting interval for multiple XML proxy sensors.

  • Because xmlproxyd performs XML and text processing, a device should only contain XML proxy sensors that execute within the CPU utilization range.

Platform-Specific Collecting Sensor Data Behavior

Use Feature Explorer to confirm platform and release support for specific features.

Use the following table to review platform-specific behaviors for your platforms:

Table 1: Collecting Sensor Data Behavior

Platform

Difference

PTX10008

For PTX10008 routers operating Junos OS Evolved, do not connect more than 10 collectors per router for telemetry RPCs.

The following instructions use the collector jtimon. For information about jtimon setup, see Junos Telemetry Interface client.

Note:

If a subscription already exists for a sensor and a duplicate subscription is configured, the connection between the collector and the device will close with the error message AlreadyExists.
  1. Create a simple configuration file, here named vmx1.json. Adjust the host IP address and the port, as needed. The path /junos/system-users-information is specified. The freq field is defined in MicroSoft, streaming a new set of key value pairs every 5 seconds. Optionally, you can add multiple paths.
  2. Launch the collector, using either your own compiled file or an automatically built image from Docker Hub. The sample query output below shows the sensor report by path. Every key is sent in human-readable form as an absolute path. In case of lists, the absolute path contains an index in the form of XPATH which is ideal to group values from a (time series) database, such as InfluxDB. For example, the output below shows the path /junos/system-users-information/uptime-information/user-table/user-entry[user='ab']/.

    You can terminate the stream of sensor data using Ctrl-C.

    The sample query shown below shows two sensor reports per path, then I terminated it with Ctrl-C. Every key is sent in human readable form as an absolute path and in case of lists, contains an index in form of XPATH, ideal to group values from a (time series) database like InfluxDB e.g. /junos/system-users-information/uptime-information/user-table/user-entry[user='ab']/

  3. Verify that the module (sensor) is loaded using the show system yang package sysusers command, where sysusers is the name of the package:
  4. Enable gRPC in the Junos OS configuration:

Installing a User-Defined YANG File

To add, validate, modify, or delete a user-defined YANG file for XML proxy for the Junos telemetry interface, use the request system yang set of commands from the operational mode:

  1. Specify the name of the XML proxy YANG file and the file path to install it. This command creates a .json file in the /opt/lib/render directory.
    Note:

    This command can be performed only on the current routing engine.

    To add multiple YANG modules with the request system yang add package package-name proxy-xml module command, enclose the file-path-name in brackets: [ file-path-name 1 file-path-name 2 ]

  2. (Optional) Validate an module before adding it to the router using the request system yang validate proxy-xml module module-name command. .

    The output XML proxy YANG module validation for xmlproxyd_<module-name> : SUCCESS indicates successful module validation.

    Mismatch error sometimes occur. If the command returns the error below, you can eliminate the error by using Junos OS Release 17.3R2 or later:

  3. (Optional) Update an existing XML proxy YANG file that was previously added.
  4. Delete an existing XML proxy YANG file.
  5. Verify that the YANG file has been installed by entering the show system yang package command.

Troubleshoot Telemetry Sensors

Problem

Description

Use the following methods to troubleshoot user-define telemetry sensors:

  • Execute a tcpdump for the interface your gRPC requests came from (for this task, interface fxp0 was used).

  • Enable traceoptions using the set services analytics traceoptions flag xmlproxy command. Check the xmlproxyd log file for confirmation of whether the CLI command’s RPC was sent and if a response was received:

  1. Issue the show log xmlproxyd command to show the xmlproxyd log. The value for the field xmlproxy_execute_cli_command: indicates if the RPC was sent or not. The value for the field xmlproxy_build_context indicates the command.

Related Documentation