Yanggrpc Receiver

Available in: contrib Maintainers: @atoulme Source: opentelemetry-collector-contrib

Supported Telemetry

Overview

The YANG gRPC Receiver collects Model-Driven Telemetry (MDT) from network devices (primarily Cisco) via gRPC Dial-out. It transforms complex Cisco KV-GPB (Key-Value Google Protocol Buffers) data into standard OpenTelemetry metrics.

Key Features

Multi-OS Native Support: Unified gRPC Dial-out collection for both Cisco Catalyst (IOS-XE) and Cisco Nexus (NX-OS) architectures using standard YANG model data sources.
Two-Pass Tree Traversal Engine: Implements a strict separation between metadata extraction (extractKeysOnly) and metric processing (emitMetricsOnly). This ensures measurement values never leak into labels, maintaining clean data structures and avoiding metric cardinality explosions.
Cross-Platform Interface Aliasing: Automatically detects and normalizes platform-specific interface keys (name, cname, interface-name) into a single uniform interface attribute dimension, allowing unified dashboarding across Catalyst and Nexus.
Dynamic Type Normalization: Explicitly normalizes all downstream Protobuf numerical fields (Uint32, Uint64, Sint32, Sint64, Float, Double, Bool) into clean standard OTLP float64 data points.
State-to-Info Conversion: Intercepts string-based values (e.g., status strings, system names, operational states) and transforms them into standard _info Gauge metrics with a fixed value of 1.0, keeping the original string state safe within a structured value attribute.

Example Configuration

Add this receiver to your OpenTelemetry Collector configuration:

receivers:
  yang_grpc:
    endpoint: "0.0.0.0:57000"
    yang:
      module_paths:
        - "/etc/otelcol/yang/cisco/xe"
        - "/etc/otelcol/yang/standard/ietf"
    security:
      allowed_clients: ["10.0.0.0/8", "192.168.1.0/24"]
      rate_limiting:
        enabled: true
        requests_per_second: 100
        burst_size: 50

exporters:
  splunk_hec:
    endpoint: "https://your-splunk-instance:8088/services/collector"
    token: "${SPLUNK_HEC_TOKEN}"
    index: "network_metrics"

service:
  pipelines:
    metrics:
      receivers: [yang_grpc]
      processors: [batch]
      exporters: [splunk_hec]

gRPC Configuration

See configgrpc.

Default Configuration

yang_grpc:
  endpoint: "localhost:57500"
  transport: tcp
  max_concurrent_streams: 100
  max_recv_msg_size_mib: 4
  keepalive:
    server_parameters:
      time: 30s
      timeout: 10s
  security:
    connection_timeout: 30s
    enable_metrics: true
    rate_limiting:
      enabled: false
      requests_per_second: 100.0
      burst_size: 10
      cleanup_interval: 1m
  yang:
    enable_rfc_parser: true
    cache_modules: true
    max_modules: 1000

Configuration Reference

The yang_grpc receiver configuration parameters are mapped into three main blocks: the core gRPC settings, the security hardening settings, and the YANG parser settings.

YANG Parser Settings (`yang`)

module_paths: (Optional) A list of local directories where .yang schema files are stored. These schemas are used by the internal parser to resolve platform-specific keys and nodes (e.g., Cisco Catalyst or Nexus structures). If omitted, the receiver automatically falls back to a built-in naming heuristic.
enable_rfc_parser: Enables the RFC 6020/7950 compliant YANG parser (Default: true).
cache_modules: Enables caching of discovered and parsed YANG modules to drastically reduce CPU overhead under heavy telemetry stream processing (Default: true).
max_modules: Specifies the maximum number of YANG modules allowed in the internal cache concurrently (Default: 1000).

Security Hardening Settings (`security`)

allowed_clients: (Optional) A list of client IP addresses or CIDR blocks authorized to stream dial-out data to this receiver.
connection_timeout: The maximum duration allowed to establish and initialize a new incoming gRPC channel session (Default: 30s).
enable_metrics: Enables internal security-related and performance metrics collection for the receiver itself (Default: true).
rate_limiting:
- enabled: Enables request rate limiting controls per streaming client (Default: false).
- requests_per_second: The maximum allowed incoming metadata/message requests per second per client channel (Default: 100.0).
- burst_size: The maximum burst size allowed before rate limits trigger blocking (Default: 10).
- cleanup_interval: Defines how often the internal rate limiter structures are audited and cleared (Default: 1m).

gRPC Server Settings

As this component squashes the standard OpenTelemetry configgrpc.ServerConfig, all standard gRPC properties like endpoint, transport, tls, and keepalive parameters are fully supported. For details, see configgrpc.

Production Deployment Example

yang_grpc:
  endpoint: "0.0.0.0:57500"
  tls:
    enabled: true
    cert_file: "/etc/otel/certs/server.crt"
    key_file: "/etc/otel/certs/server.key"
  security:
    rate_limiting:
      enabled: true
    allowed_clients: 
      - "10.0.0.0/8"
  yang:
    cache_modules: true

Example OTLP Output

When processing Cisco Model-Driven Telemetry via the YANG data source, the receiver traverses the nested tree structure and generates structured OTLP metrics directly indexable in Splunk.

Scenario A: Cisco Catalyst (IOS-XE) - Operational Status (String Value)

Raw Encoding Path: Cisco-IOS-XE-interfaces-oper:interfaces/interface
Metric Type: Gauge (Forced to 1.0 for state metrics)

{
   "cisco.encoding_path": "Cisco-IOS-XE-interfaces-oper:interfaces/interface",
   "cisco.node_id": "SWITCH-CAT-ACCESS",
   "host.name": "OTEL-COLLECTOR",
   "interface": "AppGigabitEthernet1/0/1",
   "metric_name": "cisco.phys-address_info",
   "metric_type": "Gauge",
   "name": "AppGigabitEthernet1/0/1",
   "node_id": "SWITCH-CAT-ACCESS",
   "os.type": "linux",
   "value": "00:aa:bb:cc:dd:ee",
   "_value": 1
}

Scenario B: Cisco Nexus (NX-OS) - Interface Statistics (Numeric Value)

**RRaw Encoding Path: Cisco-NX-OS-device:System/intf-items/phys-items/PhysIf-list/dbgIfIn-items/octets
**RMetric Type: Gauge (Normalized numeric counter)

{
   "cisco.encoding_path": "Cisco-NX-OS-device:System/intf-items/phys-items/PhysIf-list/dbgIfIn-items/octets",
   "cisco.node_id": "SWITCH-NEXUS-CORE",
   "host.name": "otel-ubuntu-server",
   "id": "eth1/1",
   "metric_name": "cisco.octets",
   "metric_type": "Gauge",
   "node_id": "SWITCH-NEXUS-CORE",
   "os.type": "linux",
   "_value": 1234567890
}

Implementation Note: Notice how the engine cleans up the path prefixes for Nexus (cisco.octets) while maintaining complete multidimensional context such as id: eth1/1 or interface: AppGigabitEthernet1/0/1 parsed directly from the YANG keys branches.

Configuration

Example Configuration

yang_grpc/default:
  endpoint: localhost:57500
  transport: tcp
  keepalive:
    server_parameters:
      time: 30s
      timeout: 10s
  max_concurrent_streams: 100
  max_recv_msg_size_mib: 4
  security:
    connection_timeout: 30s
    enable_metrics: true
    rate_limiting:
      burst_size: 10
      cleanup_interval: 1m0s
      enabled: false
      requests_per_second: 100
  yang:
    cache_modules: true
    enable_rfc_parser: true
    max_modules: 1000
yang_grpc/prod:
  endpoint: "0.0.0.0:57500"
  # TLS/mTLS Configuration
  tls:
    enabled: true
    cert_file: "/etc/otel/certs/server.crt"
    key_file: "/etc/otel/certs/server.key"
    ca_file: "/etc/otel/certs/ca.crt"
    client_auth_type: "RequireAndVerifyClientCert"
    min_version: "1.2"
    max_version: "1.3"
    reload_interval: 5m

  # Security & Rate Limiting
  security:
    rate_limiting:
      enabled: true
      requests_per_second: 100.0
      burst_size: 10
      cleanup_interval: 1m
    allowed_clients:
      - "10.0.0.0/8"
      - "192.168.0.0/16"
    max_connections: 1000
    connection_timeout: 30s
    enable_metrics: true

    # Performance Settings
    max_concurrent_streams: 100
    max_recv_msg_size_mib: 4

    # Keep-Alive Configuration
    keepalive:
      server_parameters:
        time: 30s
        timeout: 10s

    # YANG Parser Configuration
    yang:
      enable_rfc_parser: true
      cache_modules: true
      max_modules: 1000

Last generated: 2026-08-24

​Yanggrpc Receiver

​Supported Telemetry

​Overview

​Key Features

​Example Configuration

​gRPC Configuration

​Default Configuration

​Configuration Reference

​YANG Parser Settings (yang)

​Security Hardening Settings (security)

​gRPC Server Settings

​Production Deployment Example

​Example OTLP Output

​Scenario A: Cisco Catalyst (IOS-XE) - Operational Status (String Value)

​Scenario B: Cisco Nexus (NX-OS) - Interface Statistics (Numeric Value)

​Configuration

​Example Configuration

Yanggrpc Receiver

Supported Telemetry

Overview

Key Features

Example Configuration

gRPC Configuration

Default Configuration

Configuration Reference

YANG Parser Settings (`yang`)

Security Hardening Settings (`security`)

gRPC Server Settings

Production Deployment Example

Example OTLP Output

Scenario A: Cisco Catalyst (IOS-XE) - Operational Status (String Value)

Scenario B: Cisco Nexus (NX-OS) - Interface Statistics (Numeric Value)

Configuration

Example Configuration