> ## Documentation Index
> Fetch the complete documentation index at: https://otel.fyi/llms.txt
> Use this file to discover all available pages before exploring further.

# Yanggrpc

> OpenTelemetry receiver for Yanggrpc

# Yanggrpc Receiver

![Status](https://img.shields.io/badge/status-alpha-red)

**Available in:** `contrib`

**Maintainers:** [@atoulme](https://github.com/atoulme)

**Source:** [opentelemetry-collector-contrib](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/yanggrpcreceiver)

## Supported Telemetry

![Metrics](https://img.shields.io/badge/metrics-alpha-green)

## 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:

```yaml theme={null}
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](https://pkg.go.dev/go.opentelemetry.io/collector/config/configgrpc).

## Default Configuration

```yaml theme={null}
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](https://pkg.go.dev/go.opentelemetry.io/collector/config/configgrpc).

## Production Deployment Example

```YAML theme={null}
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)

```json theme={null}
{
   "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)

```JSON theme={null}
{
   "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

```yaml theme={null}
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-10-05*