Stream data with gNMI

The Cisco Crosswork Assurance solution provides a gNMI interface for streaming supported monitored-object metrics to external clients. This page describes authentication, subscription paths, schema access, and expected stream behavior.

Getting Started: Authentication

Authentication methods differ based on your deployment type. Select the section that matches your environment.

Cloud Deployments

For cloud-hosted Crosswork Assurance deployments, use one of the following authentication methods:

• Credentials: Use your Crosswork Assurance login details
• JWT (JSON Web Token): A long-lived token created via the Crosswork Assurance API
• Bearer Token: A short-lived token obtained from the Crosswork Assurance login

On-Premises Deployments

For on-premises Crosswork Assurance deployments, use one of the following authentication methods:

• Personal Access Token (PAT): Use a Personal Access Token as a bearer token in the Authorization header (no username required)
• Username and Password: Use your email address and password directly

Authentication Details

Cloud Deployment Authentication

Using Credentials (Cloud)

You can connect to gNMI using your Crosswork Assurance username and password. Here are example commands using gnmic, a gNMI client:

gnmic

gnmic -a {tenant-url}:443 --format protojson -u user@domain.com -p {passwd} subscribe --path '/object-type/twamp-sf/monitored-objects/monitored-object[meta/data/name/usage=europe-east]/metrics' --mode stream

gnmi_cli (Openconfig reference implementation)

gnmi_cli -a {tenant-url}:443 -tls_skip_verify -display_type p -query_type s -t '/gnmi.gNMI/' -q /object-type/twamp-sf/monitored-objects/monitored-object[meta/data/name/usage=europe-east]/metrics -with_per_rpc_auth -with_user_pass

JWT (Cloud)

Authentication is done using a long-lived JWT (JSON Web Token). The JWT is created via the Crosswork Assurance API. When a gNMI subscription request is issued, the JWT must be included in the gRPC metadata under the Authorization key.

1. Log in to Crosswork Assurance as tenant-admin.
2. Issue a request to {{baseUrl}}/api/v1/auth/tokens:

{
    "data": {
        "attributes" : {
            "aud": "accedian",
            "iss": "accedian",
            "sub": "user@domain.com",
            "tenantURL": "{{baseUrl}}",
            "exp" : 35683279714
        },
        "type": "tokens"
    }
}

3. Copy the created JWT:

   eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJhY2NlZ...M0NTQ5NzgzIiwidGVuYW50VVJMIjoiaHR0cHM6Ly90rZW5hbnQxLmJlcGVyZi5ucGD2LmFjY2VkaWFuLm5ldCJ9.cKmhYJbYBjSrsf9l-NlzuQ8781chGUjTnhfRzclQ2IY
   

4. Add to gRPC metadata with key: Authorization.

Tip: The Cisco gNMI client supports JWT auth ($AUTH_TOKEN is a JWT token string).

Example:

./gnmicli --addr {tenant-url}:443  --query /object-type/twamp-sf/monitored-objects/monitored-object[meta/data/name/usage=europe-east]/metrics/jitter-p95 --auth token --insecureTls --authToken $AUTH_TOKEN

Bearer Token (Cloud)

You can also use the Bearer token returned by the Crosswork Assurance login and add that to the gRPC metadata Authorization header. Note however, that these tokens are short lived.

Bearer MTY2ODQzNzI...ukNkQ==

The Cisco gNMI client supports Bearer token auth ($AUTH_TOKEN is a Bearer token string, without the prefix: Bearer):

./gnmicli --addr {tenant-url}:443 --query /object-type/twamp-sf/monitored-objects/monitored-object[meta/data/name/usage=europe-east]/metrics/jitter-p95 --auth token --insecureTls --authToken $AUTH_TOKEN

On-Premises Deployment Authentication

For on-premises deployments, you have two authentication options.

Personal Access Token (On-Premises)

Use a Personal Access Token (PAT) as a bearer token in the Authorization header. No username is required when using this method.

1. Generate a Personal Access Token from your Crosswork Assurance deployment.
2. Pass the PAT as a bearer token in the Authorization header

gnmic example:

gnmic -a {tenant-url}:443 --token {your-personal-access-token} subscribe --path '/object-type/twamp-sf/monitored-objects/monitored-object[meta/data/name/usage=europe-east]/metrics' --mode stream

Username and Password (On-Premises)

You can connect directly using your email address and password.

gnmic example:

gnmic -a {tenant-url}:443 --username user@example.com --password {password} --skip-verify subscribe --path '/object-type/twamp-sf/monitored-objects/monitored-object[meta/data/name/usage=europe-east]/metrics' --mode stream

gnmi_cli example:

gnmi_cli -a {tenant-url}:443 -tls_skip_verify -display_type p -query_type s -t '/gnmi.gNMI/' -q /object-type/twamp-sf/monitored-objects/monitored-object[meta/data/name/usage=europe-east]/metrics -with_per_rpc_auth -with_user_pass

YANG model

The YANG model defines the structure for monitored objects in the Crosswork Assurance solution. This model specifies the containers and groupings necessary for effective network data management, focusing on metrics and metadata essential for network assurance.

https://github.com/Accedian/skylight-yang/blob/main/skylight-gNMI/accedian-session.yang

Currently it only support TWAMP data.

Subscriptions

Subscriptions only supports gNMI STREAM subscriptions using ON_CHANGE semantics . Updates begin when the subscription is established; historical values are not sent. The subscriber cannot set the reporting interval. Updates arrive approximately according to the source session’s reporting interval. After a connection loss, the client should reconnect and re-establish its subscription.

Note: The gNMI streaming interface currently supports subscription modes as described. Integration with certain third-party plugins, such as Telegraf, may have limitations. Users should consider their specific data ingestion requirements when configuring subscriptions.

Subscription Paths:

The primary subscription paths are:

• All data available about the session
• Session metrics only
• Specific session metrics

All metrics and metadata

/object-type/twamp-sf/monitored-objects/monitored-object[meta/data/name/usage=europe-east]

All metrics

/object-type/twamp-sf/monitored-objects/monitored-object[meta/data/name/usage=europe-east]/metrics

All metrics with multiple values for category

/object-type/twamp-sf/monitored-objects/monitored-object[meta/data/name/usage=europe-east|europe-west]/metrics

All metrics with multiple categories

/object-type/twamp-sf/monitored-objects/monitored-object[meta/data/name/usage=europe-east;meta/data/name/service=abc]/metrics

Specific metric (leaf)

/object-type/twamp-sf/monitored-objects/monitored-object[meta/data/name/usage=europe-east]/metrics/jitter-p95

Reporting Interval

The gNMI interface delivers data in real-time as it is received, because the Crosswork Assurance-streamer is designed to operate without maintaining any state. Consequently, you cannot set a specific reporting interval when you subscribe.

As a result, the data is reported at approximately the same intervals as the session reports its data. For instance, if a subscribed session reports every 30 seconds, you will receive updates approximately every 30 seconds.

Client and subscription planning guidance

For larger gNMI integrations, we recommend using at least two independent gNMI clients. Each client may use one or more metadata-filtered subscriptions, depending on how the monitored objects are organized. Multiple subscriptions are optional; a single subscription per client is also valid.
As a planning guideline, assign approximately 1,000–9,000 monitored objects to each client. Larger integrations can distribute the workload across additional clients, with approximately 2–18 clients as a reasonable planning range.
These figures are planning guidance, not hard service limits or capacity guarantees. Actual sizing depends on the source reporting interval, selected metrics, update rate, payload size, and network conditions.

Testing gNMI

gNMI Test Client

We provide a test client, based on the openconfig gNMI framework, to connect to the Crosswork Assurance gNMI and verify that data is flowing.

Usage: gnmicli --addr ADDR --query QUERY [--target TARGET] [--tenantId TENANTID] [--auth AUTH] [--authToken AUTHTOKEN] [--insecureTls] [--username USERNAME] [--password PASSWORD]

Options:
  --addr ADDR, -a ADDR   Address of the gNMI server
  --query QUERY, -q QUERY
                         gNMI subscription query path
  --target TARGET        Target of the gNMI endpoint [default: /gnmi.gNMI/]
  --tenantId TENANTID, -t TENANTID
                         Required for NoAuth [--auth none]
  --auth AUTH            Authentication type: [token], [credentials] or [none] [default: none]
  --authToken AUTHTOKEN
                         Token for authentication. Required for [token] authentication
  --insecureTls          Adds insecure TLS (skip verify) [default: false]
  --username USERNAME    Username for credentials auth
  --password PASSWORD    Password for credentials auth
  --help, -h             display this help and exit

Example usage:

./gnmicli --addr cisco-cnc.dhuscisco-dev.analytics.accedian.io:443  --query /object-type/twamp-sf/monitored-objects/monitored-object[meta/data/name/usage=europe-east]/metrics/jitter-p95 --auth token --insecureTls --authToken $AUTH_TOKEN

Postman Setup

This section guides you through setting up Postman to interact with the gNMI interface of the Crosswork Assurance solution. By following these steps, you can configure Postman to test and verify gNMI queries and subscriptions, enabling efficient network monitoring and data analysis.

1. Download/Clone gnmi.proto and gnmi_ext.proto from openconfig on github to your local machine.
   https://github.com/openconfig/gnmi/tree/master/proto
2. In postman by the workspace click “new” and then select gRPC request

3. Navigate to the service definition tab of the request, select “Import a .proto file”

4. Chose gnmi.proto as the proto file

5. Add your path to the gnmi_ext.proto file as an import path. Make sure that the postman import path is relative to the import path defined in the gnmi.proto (Which is: github.com/openconfig/gnmi/proto/gnmi_ext/gnmi_ext.proto).
   

6. Hit “Next”

7. In “Import as API”, type a name for your API, Provider-Connectivity-Assurance-gNMI for example. Then in the dropdown, select “Create new api” to save your custom name. Finally click the “Import as API” button to save.

8. Click the lock, to the left of the URL, to enable TLS

9. Add the server URL to the request (ex. cisco.dhuscisco.analytics.accedian.io/)

10. Next to the URL, select the gRPC method Subscribe

11. Navigate to the Authorization tab of the request, select bearer token as type and then add your token to the appropriate section. The token can be either the JSON Web Token (JWT) you created, or a Bearer token you obtained by logging in to Crosswork Assurance (as in the following screenshot).

12. Navigate to the Message tab, add your subscription request
    Ex.

    {
        "subscribe": {
            "mode": "STREAM",
            "prefix": {
                "origin": "accedian:session",
                "elem": [
                    {
                        "name": "object-type"
                    },
                    {
                        "name": "twamp-sf"
                    },
                    {
                        "name": "monitored-objects"
                    }
                ]
            },
            "subscription": [
                {
                   "path": {
                        "origin": "accedian:session",
                        "elem": [
                            {
                                "name": "monitored-object",
                                "key" : {
                                    "meta/data/name/state" : "texas"    
                                }
                            },
                            {
                                "name": "metrics"
                            },
                            {
                                "name": "delay-p75"
                            }
                        ]
                    } 
                },
                {
                   "path": {
                        "elem": [
                            {
                                "name": "monitored-object",
                                "key" : {
                                    "meta/data/name/state" : "colorado"    
                                }
                            },
                            {
                                "name": "metrics"
                            }
                        ]
                    } 
                }
            ]
        }
    }
    

13. Click the Invoke button to initiate the gRPC stream connection

14. Click the Send button to pass initiate your subscription streaming