SNMP Receiver

Telegen’s SNMP receiver collects metrics from network devices, storage systems, and other SNMP-enabled infrastructure.

Overview

The SNMP receiver supports:

  • SNMP v1, v2c, v3 - All protocol versions
  • Polling and Traps - Both collection modes
  • Standard MIBs - IF-MIB, HOST-RESOURCES-MIB, etc.
  • Custom MIBs - Load vendor-specific MIBs
  • Auto-discovery - Find SNMP devices on your network

Architecture

flowchart LR
    subgraph Devices["Network Devices"]
        SW["Switches"]
        RT["Routers"]
        UPS["UPS"]
    end
    
    subgraph Telegen["Telegen Collector"]
        P["SNMP Poller"]
        T["Trap Receiver"]
        M["MIB Resolver"]
        C["Metric Converter"]
    end
    
    SW -->|"SNMP Poll"| P
    RT -->|"SNMP Poll"| P
    UPS -->|"Traps"| T
    P --> M
    T --> M
    M --> C
    C -->|"OTLP"| O["OTel Collector"]

Configuration

Basic SNMP v2c

telegen:
  mode: collector

otlp:
  endpoint: "otel-collector:4317"

collector:
  snmp:
    enabled: true
    poll_interval: 60s
    timeout: 10s
    retries: 3
    
    targets:
      - name: "core-switch-01"
        address: "10.0.1.1:161"
        version: "v2c"
        community: "public"
        modules:
          - if_mib
          - entity_mib
        labels:
          location: "dc1-rack1"
          role: "core"

SNMP v3 (Secure)

collector:
  snmp:
    targets:
      - name: "secure-router"
        address: "10.0.1.10:161"
        version: "v3"
        security:
          user: "monitor"
          security_level: "authPriv"
          auth_protocol: "SHA256"
          auth_password: "${SNMP_AUTH_PASSWORD}"
          priv_protocol: "AES256"
          priv_password: "${SNMP_PRIV_PASSWORD}"
        modules:
          - if_mib
          - bgp4_mib

Security Levels

Level Authentication Privacy
noAuthNoPriv ❌ ❌
authNoPriv ✅ ❌
authPriv ✅ ✅

Auth/Priv Protocols

Auth Protocol Description
MD5 MD5 (legacy, not recommended)
SHA SHA-1
SHA224 SHA-224
SHA256 SHA-256 (recommended)
SHA384 SHA-384
SHA512 SHA-512
Priv Protocol Description
DES DES (legacy, not recommended)
AES AES-128
AES192 AES-192
AES256 AES-256 (recommended)

Standard MIB Modules

if_mib (Interface Statistics)

Collects interface metrics from IF-MIB:

modules:
  - if_mib

Metrics collected:

Metric Description
snmp_if_in_octets Bytes received
snmp_if_out_octets Bytes transmitted
snmp_if_in_unicast_pkts Unicast packets received
snmp_if_out_unicast_pkts Unicast packets transmitted
snmp_if_in_errors Input errors
snmp_if_out_errors Output errors
snmp_if_in_discards Input discards
snmp_if_out_discards Output discards
snmp_if_oper_status Operational status (1=up, 2=down)
snmp_if_speed Interface speed (bps)

entity_mib (Physical Entities)

modules:
  - entity_mib

Metrics collected:

Metric Description
snmp_entity_name Entity name
snmp_entity_class Entity class (chassis, module, port)
snmp_entity_serial Serial number

host_resources (Host Information)

modules:
  - host_resources

Metrics collected:

Metric Description
snmp_hr_system_uptime System uptime
snmp_hr_processor_load CPU utilization
snmp_hr_storage_used Storage used
snmp_hr_storage_size Storage capacity
snmp_hr_memory_size Memory size

Vendor-Specific Modules

Cisco

modules:
  - cisco_process     # CPU/memory statistics
  - cisco_envmon      # Environmental monitoring
  - cisco_flash       # Flash memory

Juniper

modules:
  - juniper_alarm     # System alarms
  - juniper_cos       # Class of Service
  - juniper_firewall  # Firewall statistics

Arista

modules:
  - arista_hw         # Hardware status
  - arista_queue      # Queue statistics

Custom MIB Modules

Define custom modules for specific OIDs:

collector:
  snmp:
    custom_modules:
      - name: "custom_ups"
        walk:
          - "1.3.6.1.4.1.318.1.1"  # APC enterprise OID
        
        metrics:
          - name: "ups_battery_capacity_percent"
            oid: "1.3.6.1.4.1.318.1.1.1.2.2.1.0"
            type: gauge
            help: "UPS battery capacity percentage"
          
          - name: "ups_output_load_percent"
            oid: "1.3.6.1.4.1.318.1.1.1.4.2.3.0"
            type: gauge
            help: "UPS output load percentage"
          
          - name: "ups_runtime_remaining_seconds"
            oid: "1.3.6.1.4.1.318.1.1.1.2.2.3.0"
            type: gauge
            help: "UPS estimated runtime remaining"
          
          - name: "ups_battery_status"
            oid: "1.3.6.1.4.1.318.1.1.1.2.1.1.0"
            type: gauge
            help: "UPS battery status"
            enum_values:
              1: "unknown"
              2: "normal"
              3: "low"
              4: "in_fault"

Apply Custom Module

collector:
  snmp:
    targets:
      - name: "ups-01"
        address: "10.0.2.100:161"
        version: "v2c"
        community: "public"
        modules:
          - custom_ups

SNMP Trap Receiver

Receive asynchronous SNMP traps:

collector:
  snmp:
    trap_receiver:
      enabled: true
      listen_address: ":162"
      
      # v2c trap communities
      community_allowlist:
        - "public"
        - "traps"
      
      # v3 trap authentication
      v3_users:
        - user: "trap-sender"
          auth_protocol: "SHA256"
          auth_password: "${TRAP_AUTH_PASSWORD}"
          priv_protocol: "AES256"
          priv_password: "${TRAP_PRIV_PASSWORD}"

Trap Events

Traps are converted to OpenTelemetry logs:

{
  "timestamp": "2024-01-15T10:30:00Z",
  "severity": "WARNING",
  "body": "Link down on interface Ethernet1/1",
  "attributes": {
    "snmp.trap.oid": "1.3.6.1.6.3.1.1.5.3",
    "snmp.trap.name": "linkDown",
    "snmp.source": "10.0.1.1",
    "snmp.if_index": 1001,
    "snmp.if_descr": "Ethernet1/1",
    "device.name": "core-switch-01"
  }
}

Auto-Discovery

Automatically find SNMP devices:

collector:
  snmp:
    discovery:
      enabled: true
      interval: 1h
      
      # Networks to scan
      networks:
        - "10.0.0.0/16"
        - "192.168.0.0/24"
      
      # Ports to probe
      ports:
        - 161
      
      # Communities to try (v2c)
      communities:
        - "public"
        - "private"
      
      # v3 credentials to try
      v3_credentials:
        - user: "monitor"
          auth_protocol: "SHA256"
          auth_password: "${SNMP_AUTH}"
      
      # Skip specific addresses
      exclude:
        - "10.0.0.1"
        - "10.0.255.255"

Discovery Results

Discovered devices are logged:

{
  "timestamp": "2024-01-15T10:30:00Z",
  "severity": "INFO",
  "body": "SNMP device discovered: 10.0.1.50",
  "attributes": {
    "snmp.discovery.address": "10.0.1.50:161",
    "snmp.discovery.version": "v2c",
    "snmp.discovery.sys_descr": "Cisco IOS Software, C3850...",
    "snmp.discovery.sys_name": "access-switch-05"
  }
}

Metrics Output

Prometheus Format

# Interface traffic rate
rate(snmp_if_in_octets{device="core-switch-01",interface="Ethernet1/1"}[5m]) * 8

# Interface errors
sum(rate(snmp_if_in_errors[5m])) by (device)

# Interface utilization
(rate(snmp_if_in_octets[5m]) + rate(snmp_if_out_octets[5m])) * 8
/ snmp_if_speed * 100

Labels

All metrics include:

Label Description
device Target name
device_address SNMP target address
interface Interface description (for interface metrics)
if_index SNMP interface index
+ custom labels From target configuration

Performance Tuning

Concurrent Polling

collector:
  snmp:
    # Max concurrent SNMP requests
    max_concurrent: 100
    
    # Bulk request settings
    bulk:
      enabled: true
      max_repetitions: 25

Large Environments

For 1000+ devices:

collector:
  snmp:
    poll_interval: 120s  # Reduce frequency
    max_concurrent: 200   # More parallel requests
    timeout: 15s          # Longer timeout
    
    # Use bulk requests
    bulk:
      enabled: true
      max_repetitions: 50

Example: Complete Network Monitoring

telegen:
  mode: collector
  service_name: "network-collector"

otlp:
  endpoint: "otel-collector:4317"

collector:
  snmp:
    enabled: true
    poll_interval: 60s
    timeout: 10s
    retries: 3
    max_concurrent: 100
    
    targets:
      # Core switches
      - name: "core-sw-01"
        address: "10.0.1.1:161"
        version: "v3"
        security:
          user: "monitor"
          security_level: "authPriv"
          auth_protocol: "SHA256"
          auth_password: "${SNMP_AUTH}"
          priv_protocol: "AES256"
          priv_password: "${SNMP_PRIV}"
        modules: [if_mib, entity_mib, cisco_process]
        labels:
          tier: "core"
          location: "dc1"
      
      # Access switches (many)
      - name: "access-sw-*"
        addresses:
          - "10.0.10.0/24"
        version: "v2c"
        community: "public"
        modules: [if_mib]
        labels:
          tier: "access"
      
      # UPS systems
      - name: "ups-*"
        addresses:
          - "10.0.20.1"
          - "10.0.20.2"
        version: "v2c"
        community: "private"
        modules: [custom_ups]
        labels:
          device_type: "ups"
    
    trap_receiver:
      enabled: true
      listen_address: ":162"

Next Steps

Back to top ↑