gNMIc

gNMIc provides several different interfaces depending on your use case:

• CLI: For manual exploration, reading state, applying configuration, and subscribing to updates from the terminal.
• Collector Configuration: For building production telemetry pipelines that collect from many devices and route data to outputs like Prometheus or Kafka.
• Kubernetes Operator: For deploying and managing gNMIc collectors as Kubernetes resources (defining targets, subscriptions, and outputs).
• Go API: For integrating gNMI capabilities directly into your own automation workflows and applications.

Single instance deployments are used for simple gNMI telemetry collection and export to a single output. Common patterns include exporting to:

• NATS
• Kafka
• InfluxDB
• ClickHouse
• Prometheus
• Multiple outputs simultaneously.

gNMIc supports running automated actions in response to specific events. These events include receiving a gNMI SubscribeResponse or GetResponse that matches certain criteria, or when a target is discovered or deleted by a target loader.

Actions are executed in sequence. A key feature is that an action can access the results of any previous action in the sequence using Go Template syntax:

• {{ .Env.$action_name }}
• {{ index .Env "$action_name" }}

There are four primary action types:

1. HTTP: Build and send an HTTP request.
2. gNMI: Run a single gNMI RPC (Get, Set, or Subscribe) as a gNMI client.
3. Template: Execute a Go template against received input.
4. Script: Run arbitrary shell scripts or commands.

The collector supports gRPC tunnels and can accept connections from gNMI dial-out targets. Matching rules for these targets are stored in the tunnel-target-matches config store.

Managing Match Rules

• Startup: Define rules under the tunnel-server.targets section in your configuration file. These are mirrored into the runtime store upon loading.
• Runtime: Add, update, or remove rules using the REST API or by calling POST /api/v1/config/apply.

When a target registers via the tunnel, the collector matches its ID and type against these rules and automatically creates a managed target using the config block defined in the matching rule. Targets created via the tunnel are preserved even if they are omitted from subsequent /config/apply requests.

gNMIc can be extended using event processors written as plugins.

• Language: Plugins must be written in Golang.
• Mechanism: gNMIc uses HashiCorp's go-plugin package.
• Protocol: Communication between gNMIc and the plugin is handled via netrpc.

The event format is the internal representation gNMIc uses to transform gNMI Notification messages. While primarily used for influxdb or prometheus outputs, it can be used with any output type. An event message contains five fields:

• name (string): The subscription name. Used as a metric name (Prometheus) or measurement name (InfluxDB).
• timestamp (int64): The timestamp from the gNMI Update.
• tags (map[string]string): A map of keys and values extracted from gNMI PathElement keys. Includes the subscription name and target name/address.
• values (map[string]interface{}): A map where keys are XPath representations of the gNMI path (without keys) and values are the gNMI Node values.
• deletes ([]string): A list of strings built from the delete field of the gNMI Notification message.

The event-starlark processor allows you to apply a Starlark function (a Python-like dialect) to a list of event messages. This enables you to transform, augment, or filter events before they proceed through the gNMIc pipeline to the output.

To work as a gNMIc processor, your Starlark program must define an apply function that accepts an arbitrary number of Event arguments and returns zero or more Event objects.

def apply(*events):
  # events transformed/augmented/filtered here
  return events

When navigating the YANG tree in gnmic prompt mode, suggestions are augmented with metadata from the YANG models:

• Description: The element's description from the YANG description statement is displayed.
• Configuration State: Indicates if the element is read-write (rw) or read-only (ro) per RFC 7950.
• Node Type Markers:
  • [+]: Denotes a container or list. You can type / after these to see nested elements.
  • [⋯]: Denotes a leaf-list element.
  • (Empty space): Denotes a leaf element.

The jetstream input supports two message formats:

1. event: Expects a JSON-encoded array of EventMsg. This format supports using event-processors and exporting to multiple outputs.
2. proto: Expects binary-encoded gnmi.SubscribeResponse messages. Metadata like source and subscription-name is extracted from the NATS subject using the subject-format setting.

Subject Format Behavior (for proto only):

• subscription.target: subscription-name = first part of subject, source = second part.
• target.subscription: subscription-name = second part of subject, source = first part.
• static: No parsing; no additional metadata is extracted.