Telemetry KPI Reports

The rXg telemetry system provides unified Key Performance Indicator (KPI) reporting for network infrastructure devices through the to_kpi_report method. This functionality supports both Cisco gRPC telemetry and Ruckus MQTT telemetry systems, providing standardized performance metrics for wireless and switching infrastructure.

Overview

KPI reports transform raw telemetry data into structured performance metrics that can be consumed by monitoring dashboards, analytics systems, and operational tools. The system supports:

• Cisco Devices: Via gRPC telemetry for Catalyst IOS-XE switches and wireless controllers (full infrastructure coverage)
• Ruckus Devices: Via MQTT telemetry for wireless controllers and access points only (switching telemetry not implemented)

Cisco gRPC KPI Reports

Implementation: Telemetry::Cisco::Grpc::Grpc

The Cisco implementation (console/app/lib/telemetry/cisco/grpc/grpc.rb:103) provides comprehensive metrics for:

Supported Device Types

• Radio metrics: Wireless access points and controllers
• Port metrics: Switch port statistics and configuration
• Switch metrics: Device-level performance and status

Key Performance Indicators

Radio KPIs (lines 31-49): - Client counts, channel utilization, noise floors - SNR/RSSI averages, throughput metrics - Channel configuration (width, channels, bonded channels) - Power levels and antenna gains - MCS rate averages

Port KPIs (lines 7-28): - Speed, status, uptime, duplex configuration - Traffic statistics (bytes, packets, discards) - VLAN configuration (tagged, access, native VLANs) - PoE usage per port - CDP neighbor information

Switch KPIs (lines 51-63): - CPU load, memory usage, device uptime - Temperature monitoring, PoE budget/usage - Routing table information - Spanning tree protocol status - VTY line configuration

Usage Example

# Generate comprehensive KPI report for all device types
cisco_telemetry = Telemetry::Cisco::Grpc::Grpc.new(
  start_time: 15.minutes.ago.utc,
  end_time: Time.current.utc
)
metrics = cisco_telemetry.to_kpi_report(types: [:radio, :port, :switch])

Data Structure

Each metric includes standardized fields: ruby { measurement_id: "noise_avg", # Metric identifier value: -85, # Numeric value humanized_value: "-85 dBm", # Human-readable format source_id: "aa:bb:cc:dd:ee:ff", # Device MAC address extra: "0", # Additional context (slot ID, etc.) source_subtype: 0, # Device type (0=AP, 1=Switch) source_subcategory: 1 # Band (0=2.4GHz, 1=5GHz, 2=6GHz) }

Ruckus MQTT KPI Reports

Implementation: Telemetry::Ruckus::Mqtt::Mqtt

The Ruckus implementation (console/app/lib/telemetry/ruckus/mqtt/mqtt.rb:82) focuses exclusively on wireless performance metrics. Note: Switching telemetry collection for Ruckus devices is not yet implemented.

Supported Message Types

• AP_REPORT_MESSAGE_TYPE (0): Client statistics and radio performance
• AP_STATUS_MESSAGE_TYPE (1): Access point status and configuration

Key Performance Indicators

Wireless-Only KPIs (lines 7-25): - Client counts per radio - Channel utilization and noise floors - Signal quality (SNR, RSSI averages) - Throughput metrics (bidirectional) - Channel configuration and power levels - MCS rate calculations with PHY mode detection

Limitations: - No switch port metrics available - No device-level switching statistics - Limited to wireless controller and access point data

Usage Example

# Generate Ruckus wireless KPI report
ruckus_telemetry = Telemetry::Ruckus::Mqtt::Mqtt.new(
  start_time: 15.minutes.ago,
  end_time: Time.current
)
metrics = ruckus_telemetry.to_kpi_report

Data Structure

Ruckus metrics follow the same standardized format but focus on wireless-specific measurements: ruby { measurement_id: "client_count_per_ap", value: 12, source_id: "AA:BB:CC:DD:EE:FF", # AP MAC address extra: "1", # Radio slot ID source_subcategory: 1 # Band (0=2.4G, 1=5G, 2=6G) }

Common Measurement IDs

Both systems provide these standardized metrics:

Universal Wireless Metrics

• noise_avg: Average noise floor in dBm
• channel_utilization_avg: Channel busy percentage
• client_count_per_ap: Connected clients per radio
• radio_band_primary_channel: Primary channel number
• radio_channel_width: Channel width in MHz
• radio_power_level: Transmit power level
• snr_avg: Signal-to-noise ratio average
• rssi_avg: Received signal strength average
• throughput_per_client_avg: Per-client throughput
• aggregate_throughput_avg: Total radio throughput

Cisco-Specific Metrics

• speed: Port speed in bits per second
• connection_status: Port up/down status
• cpu_utilization: Switch CPU usage percentage
• memory_utilization: Switch memory usage percentage
• device_uptime: Device uptime in seconds
• poe_usage: Power over Ethernet consumption

Administrative Interface

KPI reports can be accessed through the admin scaffolds:

Cisco gRPC Subscriptions

Path: /admin/scaffolds/grpc_subscriptions

The Cisco telemetry scaffold provides two distinct data access methods:

Lookups (Raw Data Layer)

The Lookups button group provides access to the base layer of raw telemetry lookups. These represent the fundamental SQL queries that extract data directly from the gRPC telemetry streams. Each lookup corresponds to a specific telemetry path and provides unprocessed data as received from the network devices.

Available Raw Lookups: - Direct SQL access to telemetry subscription data - Raw device responses without aggregation or processing - Base-level metrics as streamed from gRPC subscriptions - Useful for debugging telemetry collection issues

Performance Data Elements (Processed KPI Layer)

The Performance Data Elements button group presents the finalized, processed version of the telemetry data. This is the output of the to_kpi_report method, where raw telemetry has been:

• Aggregated and calculated into meaningful KPIs
• Standardized with consistent measurement IDs
• Enhanced with human-readable values
• Organized by device type (radio/port/switch)

Available Processed Elements: - Radio: Wireless performance metrics (signal quality, throughput, channel utilization) - Port: Switch port statistics (speed, VLAN config, traffic counters)
- Switch: Device-level metrics (CPU, memory, uptime, PoE usage)

Data Flow: Raw gRPC Subscriptions SQL Lookups KPI Calculations Performance Data Elements

Ruckus Telemetry Payloads

• Path: /admin/scaffolds/telemetry_payloads
• Performance Data Elements: Unified wireless metrics view
• Message Type Filtering: Filter by AP report vs. status messages

Configuration Requirements

Cisco Devices

1. Enable telemetry on infrastructure device: enable_telemetry = true
2. Configure gRPC source settings: grpc_source_host, grpc_source_ip
3. Ensure gRPC subscriptions are configured for required metrics

Ruckus Devices

1. Enable telemetry: enable_telemetry = true
2. Configure MQTT message collection
3. Ensure AP_REPORT (0) and AP_STATUS (1) message types are being received

Error Handling and Validation

Both implementations include: - Initialization checks: Verify required data sources are available - Graceful degradation: Missing metrics don't break the entire report - Logging: Detailed debug information for troubleshooting - Data validation: Type checking and range validation for metric values

The KPI reporting system provides a unified interface for accessing performance data across diverse network infrastructure, enabling consistent monitoring and analysis regardless of the underlying vendor technology.

Webhook Integration Example

The KPI reporting system can be integrated with external systems through webhooks. Below is an example webhook body that combines both Cisco and Ruckus telemetry data into a standardized reporting format:

<%=
PROTOBUF_MEASUREMENT_TYPES = {
  "client_count_per_ap_avg" => 111,
  "channel_utilization_avg" => 112,
  "throughput_per_client_avg" => 113,
  "aggregate_throughput_avg" => 114,
  "rssi_avg" => 115,
  "snr_avg" => 116,
  "mcs_avg" => 117,
  "packet_retransmit_avg" => 118,
  "latency_avg" => 119,
  "jitter_avg" => 120,
  "packet_loss_avg" => 121,
  "noise_avg" => 122,
  'radio_band_primary_channel' => 123,
  'radio_channel_width' => 124,
  #'radio_channel_list' => 125,
  'radio_power_level' => 126
}

# Collect KPI data from both platforms
cisco_measurements = Telemetry::Cisco::Grpc::Grpc.new.to_kpi_report
ruckus_measurements = Telemetry::Ruckus::Mqtt::Mqtt.new.to_kpi_report

# Tag measurements with manufacturer
cisco_measurements.each do |m|
  m[:device_manufacturer] = 'cisco'
end

ruckus_measurements.each do |m|
  m[:device_manufacturer] = 'ruckus'
end

# Combine all measurements
raw_measurements = cisco_measurements + ruckus_measurements

# Standardize measurement format for external reporting
raw_measurements.each do |m|
  m[:measurement_type] = PROTOBUF_MEASUREMENT_TYPES[m[:measurement_id].to_s]
  m[:measurement_id] = m[:measurement_id].gsub('_', ' ')

  # Convert throughput measurements to Mbps
  if m[:measurement_id].in? ['aggregate throughput avg','throughput per client_avg']
    m[:value] = m[:value] / 10**6
  end
end

measurements = raw_measurements.map { |measurement| HashWithIndifferentAccess.new(**measurement) }
venue_info = CustomDataSet.find_by(name: 'venue_info')

# Generate standardized webhook payload
{
  message_type: 'Measurement_event',
  message: {
    measurements: measurements.map do |measurement|
      new_measurement = {
        measurement_id: measurement['measurement_id'].to_s,
        customer_id: venue_info.try(:get, :customer_id).to_s,
        venue_id: venue_info.try(:get, :venue_id).to_s,
        measurement_type: measurement['measurement_type'],
        timestamp: measurement['timestamp'] || Time.now.to_i,
        collection_interval: 300, # time in seconds
        reporter_id: DeviceOption.active.domain_name,
        reporter_id_type: 1, # MAC
        reporter_type: 0,
        source_id: measurement['source_id'].to_s,
        source_id_type: 1, # MAC address
        source_type: 0, # device
        source_subtype: measurement['source_subtype'].to_i,
        source_vendor: 0,
        extra: measurement['extra'],
        source_subcategory: measurement['source_subcategory']
      }
      new_measurement[:svalue] = measurement['svalue'] if measurement['svalue']
      new_measurement[:value] = measurement['value'].to_i if measurement['value']
      new_measurement
    end
  }
}.to_json
%>

Webhook Integration Features

Multi-Vendor Support: - Combines Cisco gRPC and Ruckus MQTT telemetry in a single payload - Tags measurements with manufacturer for filtering

Standardized Format: - Maps measurement IDs to protobuf message types - Converts underscore notation to space-separated format - Normalizes throughput values to Mbps

External Reporting Structure: - Venue and customer identification - Timestamp and collection interval metadata
- Reporter and source device information - Flexible value types (numeric and string values)

Configuration Requirements: - Venue information stored in CustomDataSet named 'venue_info' - Active device domain name from DeviceOption.active.domain_name

This example demonstrates how KPI data from multiple telemetry sources can be unified and formatted for external system integration.