gNMI Collector

The gNMI Collector microservice discovers gNMI devices for the Discovery Service microservice and periodically polls the discovered devices for performance metrics. This microservice is part of the Discovery and Metric microservice pipelines. See Understanding Microservice Pipelines in Unified Assurance Concepts for conceptual information about microservice pipelines.

You can configure redundancy settings for this microservice when you deploy it. See Configuring Microservice Redundancy for general information.

This microservice provides additional Prometheus monitoring metrics. See gNMI Collector Self-Monitoring Metrics.

gNMI Collector Prerequisites

Before deploying the gNMI Collector microservice, confirm that the following prerequisites are met:

  1. A microservice cluster is set up. See Microservice Cluster Setup.

  2. The Pulsar microservice is deployed.

  3. (Optional) You have created a Kubernetes secret containing the certificates:

    • TLS: If you want to use TLS without mutual authentication, create a Kubernetes Secret containing the CA certificate by running the following command as the assure1 user:

      a1k create secret generic <microservice-release-name> --from-file=ca.crt=<path-to-cert>/<ca-cert> -n <namespace>

    • Mutual TLS (mTLS): If you want to use TLS with mTLS, create a Kubernetes Secret containing the client certificate, client private key, and the CA certificate:

      a1k create secret generic <microservice-release-name> --from-file=ca.crt=<path-to>/<ca-cert> --from-file=client.crt=<path-to-cert>/<client-cert> --from-file=client.key=<path-to>/<client-key> -n <namespace>

    where:

    • <microservice-release-name> is the name used for the microservice instance. By default, this is the microservice name (gnmi-collector).

    • <namespace> is the namespace where you will deploy the microservice. The default namespace is a1-zone1-pri.

    • <path-to-cert> is the file path leading to the certificate file.

    • <ca-cert> is the CA certificate file.

    • <client-cert> is the client certificate file.

    • <client-key> is the client key certificate file.

Before discovering or polling devices with this poller, you must also deploy the following microservices:

See Understanding the Discovery Pipeline in Unified Assurance Concepts for more information about how these microservices work together.

Deploying gNMI Collector Poller

To deploy the microservice, run the following commands:

su - assure1
export NAMESPACE=<namespace>
export WEBFQDN=<webFQDN> 
a1helm install <microservice-release-name> assure1/gnmi-collector -n $NAMESPACE --set global.imageRegistry=$WEBFQDN

In the commands:

You can also use the Unified Assurance UI to deploy microservices. See Deploying a Microservice by Using the UI for more information.

Changing gNMI Collector Configuration Parameters

When running installation command, you can optionally change default configuration parameter values by including them in the command with additional --set arguments. You can add as many additional --set arguments as you need.

For example, set a parameter described in Default gNMI Collector Configuration by adding --set configData.<parameter_name>=<parameter_value>. For example, --set configData.LOG_LEVEL=DEBUG.

Default gNMI Collector Configuration

The following table describes the default configuration parameters found in the Helm chart under configData for the gNMI Collector microservice.

Name Default Value Possible Values Notes
LOG_LEVEL INFO FATAL, ERROR, WARN, INFO, DEBUG The logging level used by the microservice.
STREAM_INPUT "" persistent://assure1/discovery/gnmi-collector-zoneX The path to the Pulsar topic to get data from. The topic at end of path may be any text value.
STREAM_OUTPUT "" persistent://assure1/discovery/discovery-service-zoneX The path to the Pulsar topic to send data to. The topic at end of path may be any text value.
STREAM_OUTPUT_METRIC persistent://assure1/metric/sink Text, 255 characters The path to the Pulsar topic to send metric data to. The topic at end of path may be any text value. Set this according to the database you are using for metrics:
  • Use persistent://assure1/metric/sinkos for the Observability Analytics database.
  • Use persistent://assure1/metric/sink for the Metric database.
See Metric Sink for more information about the options.
SVN_BRANCH /core/default String The SVN branch to use for the PCOM mapping.
SVN_DIR_PATH /collection/metric/gnmi String The SVN path to the PCOM mapping.
ENABLE_PCOM_POLLING true Boolean Whether to enable performance polling (true) or disable it (false).
ENABLE_COMPATIBILITY_METRICS true Boolean Whether to enable compatibility metrics (true) or disable it (false).
CONFIG_CHECK_INTERVAL_M 60 Integer The interval, in minutes, after which to refresh the device configuration from the database.
MAX_CONCURRENT_DISCOVERY 0 Integer The maximum number of devices discovered concurrently (0 means no limit).
GRPC_CLIENT_KEEPALIVE false Boolean Whether to use keepalive checks, to validate communication with the device.
GRPC_CLIENT_KEEPALIVE_TIME 30s String The time period, after no communication, to ping the device.
GRPC_CLIENT_KEEPALIVE_TIMEOUT 5s String The time period to wait for a response to the ping before the device connection is considered down.
REDUNDANCY_POLL_PERIOD 5 Integer The number of seconds between status checks from the secondary microservice to the primary microservice.
REDUNDANCY_FAILOVER_THRESHOLD 4 Integer The number of times the primary microservice must fail checks before the secondary microservice becomes active.
REDUNDANCY_FALLBACK_THRESHOLD 1 Integer The number of times the primary microservice must succeed checks before the secondary microservice becomes inactive.

gNMI Collector Autoscaling Configuration

Autoscaling is supported for this microservice. See Configuring Autoscaling for general information and details about the standard autoscaling configurations.

This microservice also supports the additional configurations described in the following table.

Name Default Value Possible Values Notes
thresholds.maxDevicesPerWorker 0 Integer The number of targets that should be polled by each worker (0 disables autoscaling).

gNMI Collector Self-Monitoring Metrics

The gNMI Collector microservice exposes the self-monitoring metrics described in the following table to Prometheus.

Metric Name Type Description
pcom_targets Gauge The number of PCOM targets being polled.
device_poll_duration_seconds Gauge The metric poll duration per device in seconds.

Note:

Metric names in the database include a prefix that indicates the service that inserted them. The prefix is prom_ for metrics inserted by Prometheus. For example, pcom_targets is stored as prom_pcom_targets in the database.

Example gNMI Discovery Payload

In the following example discovery payload for gNMI devices:

{
   "Type": "discovery",
   "Version": "7.0.0",
   "Data": {
      "Configuration": {
         "ContextExpiryTimeM": 60,
         "GNMIConfiguration": [
            {
               "Mode": "insecure",
               "ForcedObjectDiscovery": false,
               "Username": "base64EncodedValue",
               "Password": "base64EncodedValue",
               "Port": 8080
            }
         ]
      },
      "IPList": [
         "192.0.2.1"
      ],
      "IPRanges": []
   }
}

Example Discovery Result with gNMI PCOM Objects

In the following example discovery result:

{
  "Capabilities": [
    {
      "PCOMBranch": "/core/default",
      "PCOMPath": "/collection/metric/gnmi/_objects/openconfig-if-ethernet-PCOM.json",
      "availableObjects": [
        "OPENCONFIG-IF-ETHERNET::interfaces-interface-ethernet-state-counters-out-mac-pause-frames",
        "OPENCONFIG-IF-ETHERNET::interfaces-interface-ethernet-state-counters-out-mac-control-frames",
        "OPENCONFIG-IF-ETHERNET::interfaces-interface-ethernet-state-counters-in-oversize-frames",
        "OPENCONFIG-IF-ETHERNET::interfaces-interface-ethernet-state-counters-in-crc-errors",
        "OPENCONFIG-IF-ETHERNET::interfaces-interface-ethernet-state-counters-in-mac-control-frames",
        "OPENCONFIG-IF-ETHERNET::interfaces-interface-ethernet-state-counters-in-jabber-frames",
        "OPENCONFIG-IF-ETHERNET::interfaces-interface-ethernet-state-counters-in-fragment-frames",
        "OPENCONFIG-IF-ETHERNET::interfaces-interface-ethernet-state-port-speed.2",
        "OPENCONFIG-IF-ETHERNET::interfaces-interface-ethernet-state-hw-mac-address",
        "OPENCONFIG-IF-ETHERNET::interfaces-interface-ethernet-state-counters-in-mac-pause-frames",
        "OPENCONFIG-IF-ETHERNET::interfaces-interface-ethernet-config-mac-address.2"
      ],
      "name": "openconfig-if-ethernet",
      "organization": "OpenConfig working group",
      "pathsDiscovered": 11,
      "totalPaths": 21,
      "version": "2.6.1"
    }
  ]
}

gNMI PCOM Overview

The gNMI Collector uses the PCOM model for discovery and collection of gNMI metrics. PCOM definitions are stored as a JSON model in the Unified Assurance rules repository at the default location:

Core Rules (core)/Default read-write branch (default)/collection/metric/gnmi/_objects

Although file names can be anything, because objects are read and stored based on their root object and path objects, Oracle recommends using the format <openconfig-module-name>-PCOM.json. For example, OPENCONFIG-ETHERNET-PCOM.json.

Example gNMI PCOM file

{
  "@vendor": "OPENCONFIG-PLATFORM-FAN-EXAMPLE",
  "imports": [
    "openconfig-alarm-types",
    "openconfig-extensions",
    "openconfig-platform"
  ],
  "revision": "2025-07-16",
  "yangVersion": "1",
  "notes": "",
  "objects": [
    {
      "@objectName": "OPENCONFIG-PLATFORM-FAN-EXAMPLE::components-component-fan-state-speed",
      "objectType": "speed",
      "certification": "BASIC",
      "class": "FAN",
      "subClass": "SPEED",
      "description": "Current (instantaneous) fan speed",
      "domain": "PERFORMANCE",
      "measurement": "chassis",
      "values": [
        {
          "field": "fanSpeed",
          "path": "/components/component/chassis/fan/state/speed",
          "valueType": "speed",
          "unit": "rpm",
          "metricType": "Fan Speed",
          "weight": 2
        },
        {
          "field": "fanSpeed",
          "path": "/components/component/chassis/telemetry/fan/speed",
          "valueType": "speed",
          "unit": "rpm",
          "metricType": "Fan Speed",
          "weight": 1
        },
        {
          "field": "fanUtilization",
          "eval": "($OPENCONFIG-PLATFORM-FAN-EXAMPLE::components-component-fan-state-speed / $OPENCONFIG-PLATFORM-FAN-EXAMPLE::components-component-fan-state-speed.maximum) * 100",
          "metricType": "Fan Utilization"
        }
      ],
      "keys": [
        {
          "list": "component",
          "keys": [
            "name"
          ]
        },
        {
          "list": "chassis",
          "keys": [
            "id"
          ]
        }
      ],
      "enumValues": {
        "0": "FAN_POWERED_OFF"
      },
      "minimum": 0,
      "maximum": 4294967295
    }
  ]
}

Fields Schema (Envelope)

Field Required Description
@vendor Required The capitalized name of the corresponding YANG model. Used as the root object name for the path objects.
imports Informational The names of YANG models that the root model (vendor field) uses as imports.
revision Informational The revision date of the YANG model used for PCOM creation.
yangVersion Informational The YANG version of the YANG model used for PCOM creation.
notes Meta/Optional Optional notes regarding the objects used.
objects Required The array of PCOM objects defined in the corresponding YANG model.

PCOM Object Schema

Field Required Description
@objectName Required The name of the PCOM object used for metric subscription, in the format <YANG-MODEL-NAME>::<name-derived-from-path>.
objectType Informational The type of the leaf object as defined by the gNMI schema.
certification Required/Meta The Unified Assurance Certification field. For gNMI PCOMs, use BASIC.
class Required/Meta The Unified Assurance classification of the object, used for report creation.
subClass Required/Meta The Unified Assurance sub-classification of the object, used for report creation.
description Informational The gNMI leaf description as defined in the OpenConfig module.
domain Meta The Unified Assurance domain classification. For gNMI metrics, always use PERFORMANCE.
measurement Required The measurement name under which the current object metric will be stored for OpenSearch metrics.
values Required The array of gNMI path objects for collecting the current object metric.
keys Informational The array of keys as defined in the gNMI OpenConfig module. These keys will be used during runtime to determine the instance name of the metric object for compatibility metrics display. The instance name is created starting with the first common key present in the path, followed by others. In our example, if the device returns /components/component[name="main-rack"]/chassis[id=2]/fan/state/speed, the corresponding metric would show up under the main-rack 2 instance.
enumValues Informational The array of enums as defined in the YANG model. If present, during runtime, the collector will try to match the enum key name with the returned gNMI value and, on a match, replace it with the enumerated value.
Although not recommended in production, for illustrative purposes, the PCOM example uses a value of 0 to indicate that the fan is off (it will send the FAN_POWERED_OFF string instead of 0 as a metric, including for the custom eval metric).
minimum Informational/Meta If defined in the OpenConfig module, the minimum possible value for the collected object. This value can be referenced in the eval function.
maximum Informational/Meta If defined in the OpenConfig module, the maximum possible value for the collected object. This value can be referenced in the eval function.
instanceName Optional Not present by default (null). If present, it will override any auto-generated instance name with the provided value.

PCOM Object Values Schema

The Object Values schema contains the definition of a single metric (with eval` being the exception) to be collected, along with some additional metadata. For example:

{
  "field": "fanSpeed",
  "path": "/components/component/chassis/fan/state/speed",
  "valueType": "speed",
  "unit": "rpm",
  "metricType": "Fan Speed",
  "weight": 2
}
Field Required Description
field Required The name of the field under which the metric value will be stored in OpenSearch.
path Required The gNMI path used for metric collection. This must be a gNMI leaf; gNMI lists are not supported.
valueType Informational If defined in the OpenConfig module, the gNMI type of the path leaf.
unit Informational If defined in the OpenConfig module, the unit corresponding to the returned path value.
metricType Required The name of the Unified Assurance Metric Type to use to store the returned path value in compatibility metrics mode. It must match the name present in Unified Assurance exactly; otherwise metric creation will be skipped. If the required metric type does not exist in Unified Assurance, create it through the UI.
weight Informational The weight of the object used to determine discovery order (prioritized from highest to lowest). If multiple paths allow collection of the exact same metric, those value objects will be present in the array with different weights. During discovery, the collector will try each path ordered by weight from highest to lowest and will use the first path that responds with a valid value. The selected path will be stored in the DeviceObjects table (Details column) for further collection after DOM insert.

PCOM Object Custom eval Metric

Every object, other than eval statements, supports creating only one unique metric for each collected path. However, you can use eval statements to create custom metrics based on collected values and available metadata.

The example collects runtime fan speed, and includes the maximum value as a meta/info field. You can calculate utilization using (speed / max) x 100 in the eval statement:

{
  "field": "fanUtilization",
  "eval": "($OPENCONFIG-PLATFORM-FAN-EXAMPLE::components-component-fan-state-speed / $OPENCONFIG-PLATFORM-FAN-EXAMPLE::components-component-fan-state-speed.maximum) * 100",
  "metricType": "Fan Utilization"
}
Field Description
eval A mathematical expression evaluated during runtime. Any object stored in memory (created within the same PCOM) can be referenced by its object name prefixed with $. Maximum and minimum values are also available through that reference. For example: 
($OPENCONFIG-PLATFORM-FAN-EXAMPLE::components-component-fan-state-speed / $OPENCONFIG-PLATFORM-FAN-EXAMPLE::components-component-fan-state-speed.maximum) * 100
field The metric field name for OpenSearch.
metricType The metric type for compatibility metrics display.

Creating a Custom PCOM

If you know the device well enough (including the modules and paths it provides), you can create a custom PCOM definition for metrics that are not provided by default, or for custom implementations not available in public YANG model definitions. Please note to have Custom PCOM's discovered ForcedObjectDiscovery needs to be set to true.

The example below shows a minimal custom metric PCOM. Values in this PCOM are fabricated examples only, and are only intended to show the required pattern.

Place the file with other PCOM definitions in the _objects folder.

Note the following:

{
  "vendor": "ORACLE-CUSTOM-TELEMETRY",
  "revision": "2026-02-24",
  "yangVersion": "custom",
  "notes": "This is a custom PCOM definition created for documentation purposes",
  "objects": [
    {
      "@objectName": "ORACLE-CUSTOM-TELEMETRY::system-vendor-oracle-telemetry-cpu-speed",
      "certification": "BASIC",
      "class": "CPU",
      "subClass": "SPEED",
      "domain": "PERFORMANCE",
      "measurement": "system",
      "instanceName": "My Custom CPU Instance",
      "values": [
        {
          "field": "cpuSpeed",
          "path": "/system/vendor/oracle/telemetry/cpu/speed",
          "metricType": "CPU Speed"
        }
      ]
    },
    {
      "@objectName": "ORACLE-CUSTOM-TELEMETRY::system-vendor-oracle-telemetry-site-datacenter-power-load",
      "certification": "BASIC",
      "class": "POWER",
      "subClass": "LOAD",
      "domain": "PERFORMANCE",
      "measurement": "datacenter",
      "values": [
        {
          "field": "powerLoad",
          "path": "/system/vendor/oracle/telemetry/site/datacenter/power-load",
          "metricType": "Datacenter Total Power Load"
        }
      ],
      "keys": [
        {
          "list": "site",
          "keys": [
            "name"
          ]
        },
        {
          "list": "datacenter",
          "keys": [
            "location"
          ]
        }
      ]
    }
  ]
}

In the example, the first custom object includes the instanceName field. This will create the metric in compatibility display mode under the My Custom CPU Instance instance.

The second custom object assumes that the example device responds with the following path for a given metric, and the keys are defined as name and location accordingly:

/system/vendor/oracle/telemetry/site[name="ACME Inc"]/datacenter[location="null island"]/power-load

During runtime, the example would create a metric named Datacenter Total Power Load under the ACME Inc null island instance.

Using PCOM Overrides

gNMI Collector supports PCOM file overrides using the standard JSON Patch model. The original PCOMs may be overwritten when you update Unified Assurance, so you must store any changes made to PCOMs in these files.

By default, overrides are stored in the following location:

Core Rules (core)/Default read-write branch (default)/collection/metric/gnmi/overrides

The following example shows an override for the fan-state-speed object. It changes the measurement field value from the original chassis to network, and changes the metricName for the first value definition to Current Fan Speed (from Fan Speed).

{
  "@vendor": "OPENCONFIG-PLATFORM-FAN-EXAMPLE",
  "objects": [
    {
      "@objectName": "OPENCONFIG-PLATFORM-FAN-EXAMPLE::components-component-fan-state-speed",
      "overrides": [
        {
          "op": "replace",
          "path": "/measurement",
          "value": "network"
        },
        {
          "op": "replace",
          "path": "/values/0/metricName",
          "value": "Current Fan Speed"
        }
      ]
    }
  ]
}

Appendix 1 (Possible class Field Values)

CPU DISK FAN MEMORY NETWORK POWER SYSTEM TEMPERATURE

Appendix 2 (Possible subClass Field Values)

CAPACITY CONTEXTS DISCARDS ERRORS IO JITTER LATENCY LOAD OUTPUT PROCESSES SPEED STATUS SWAP UPTIME USAGE USERS UTILIZATION VALUE VOLTAGE CURRENT PACKETS FRAMES LLDP OCTETS