Notes on Performance metrics module in openonu-go adapter

Openonu-go adapter supports performance metrics configuration and collection from the ONUs. There are two types of performance metrics

  • Group metrics
  • Standalone metrics

The group metrics are managed as a group, meaning we can only set sampling frequency, disable/enable group as a whole and not individual metrics within the group. While in contrast the standalone metrics can be managed individually.

The performance metrics configuration is carried out via the PmConfigs protobuf messages.

The meaning of various information elements in the PmConfigs and its default value (if applicable) for openonu-go adapter is documented in the below table.

KeyMeaningDefault for openonu-goAdditional notes
idonu device idonu device id
default_freqDefault sampling rate15 * 60 secondsApplicable only when freq_override is set to false
groupedForces group names and group semanticsTrueWhen this is set to true, it forces group names and group semantics. This is a READ ONLY attribute and cannot be changed from NBI
freq_overrideAllows Pm to set an individual sample frequencyTrueWhen this is set to true, the group specific sampling rate comes into effect. This is a READ ONLY attribute and cannot be changed from NBI
groupsThe groups if grouped is trueMore details about the groups supported by openonu-go adapter is documented further in this notes.
metricsThe metrics themselves if grouped is false.Unsupported at the moment
max_skewHow long the next sampling is skewed0openonu-go adapter metrics collection does not skew metric collection

Group Metrics

The following group metrics are supported by openonu-go adapter.

OpticalPower

// OpticalPowerGroupMetrics are supported optical pm names
var OpticalPowerGroupMetrics = map[string]voltha.PmConfig_PmType{
	"ani_g_instance_id":  voltha.PmConfig_CONTEXT,
	"transmit_power_dBm": voltha.PmConfig_GAUGE,
	"receive_power_dBm":  voltha.PmConfig_GAUGE,
}

UniStatus

// UniStatusGroupMetrics are supported UNI status names
var UniStatusGroupMetrics = map[string]voltha.PmConfig_PmType{
	"uni_port_no":     voltha.PmConfig_CONTEXT,
	"me_class_id":     voltha.PmConfig_CONTEXT,
	"entity_id":       voltha.PmConfig_CONTEXT,
	"sensed_type":     voltha.PmConfig_GAUGE,
	"oper_status":     voltha.PmConfig_GAUGE,
	"uni_admin_state": voltha.PmConfig_GAUGE,
}

Note:

  1. UniStatusMetrics comprise metrics for either PPTP or VEIP ME's and the UNI-G ME.
  2. me_class_id defines the corresponding metric type with the ME class value as defined in G988, Table 12.2.4-1
  3. sensed_type is relevant only for PPTP ME (meaning me_class_id = 11) and per G.988 specification, "When a circuit pack is present, this attribute represents its type as one of the values from Table 9.1.5-1."
  4. Valid values for oper_state are 0 (enabled) and 1 (disabled)
  5. Valid values for uni_admin_state are 0 (unlocks) and 1 (locks)
  6. oper_state and uni_admin_state are relevant for both PPTP (me_class_id = 11) and VEIP ME (me_class_id = 329), however only uni_admin_state is relevant for UNI-G ME (me_class_id = 264).

EthernetBridgeHistory

var EthernetBridgeHistory = map[string]voltha.PmConfig_PmType{
	"class_id":          voltha.PmConfig_CONTEXT,
	"entity_id":         voltha.PmConfig_CONTEXT,
	"interval_end_time": voltha.PmConfig_CONTEXT,
	"parent_class_id":   voltha.PmConfig_CONTEXT,
	"parent_entity_id":  voltha.PmConfig_CONTEXT,
	"upstream":          voltha.PmConfig_CONTEXT,

	"drop_events":         voltha.PmConfig_COUNTER,
	"octets":              voltha.PmConfig_COUNTER,
	"packets":             voltha.PmConfig_COUNTER,
	"broadcast_packets":   voltha.PmConfig_COUNTER,
	"multicast_packets":   voltha.PmConfig_COUNTER,
	"crc_errored_packets": voltha.PmConfig_COUNTER,
	"undersize_packets":   voltha.PmConfig_COUNTER,
	"oversize_packets":    voltha.PmConfig_COUNTER,
	"64_octets":           voltha.PmConfig_COUNTER,
	"65_to_127_octets":    voltha.PmConfig_COUNTER,
	"128_to_255_octets":   voltha.PmConfig_COUNTER,
	"256_to_511_octets":   voltha.PmConfig_COUNTER,
	"512_to_1023_octets":  voltha.PmConfig_COUNTER,
	"1024_to_1518_octets": voltha.PmConfig_COUNTER,
}

EthernetUniHistory

var EthernetUniHistory = map[string]voltha.PmConfig_PmType{
	"class_id":          voltha.PmConfig_CONTEXT,
	"entity_id":         voltha.PmConfig_CONTEXT,
	"interval_end_time": voltha.PmConfig_CONTEXT,

	"fcs_errors":                        voltha.PmConfig_COUNTER,
	"excessive_collision_counter":       voltha.PmConfig_COUNTER,
	"late_collision_counter":            voltha.PmConfig_COUNTER,
	"frames_too_long":                   voltha.PmConfig_COUNTER,
	"buffer_overflows_on_rx":            voltha.PmConfig_COUNTER,
	"buffer_overflows_on_tx":            voltha.PmConfig_COUNTER,
	"single_collision_frame_counter":    voltha.PmConfig_COUNTER,
	"multiple_collisions_frame_counter": voltha.PmConfig_COUNTER,
	"sqe_counter":                       voltha.PmConfig_COUNTER,
	"deferred_tx_counter":               voltha.PmConfig_COUNTER,
	"internal_mac_tx_error_counter":     voltha.PmConfig_COUNTER,
	"carrier_sense_error_counter":       voltha.PmConfig_COUNTER,
	"alignment_error_counter":           voltha.PmConfig_COUNTER,
	"internal_mac_rx_error_counter":     voltha.PmConfig_COUNTER,
}

FecHistory

var FecHistory = map[string]voltha.PmConfig_PmType{
	"class_id":          voltha.PmConfig_CONTEXT,
	"entity_id":         voltha.PmConfig_CONTEXT,
	"interval_end_time": voltha.PmConfig_CONTEXT,

	"corrected_bytes":          voltha.PmConfig_COUNTER,
	"corrected_code_words":     voltha.PmConfig_COUNTER,
	"uncorrectable_code_words": voltha.PmConfig_COUNTER,
	"total_code_words":         voltha.PmConfig_COUNTER,
	"fec_seconds":              voltha.PmConfig_COUNTER,
}

GemPortHistory

var GemPortHistory = map[string]voltha.PmConfig_PmType{
	"class_id":          voltha.PmConfig_CONTEXT,
	"entity_id":         voltha.PmConfig_CONTEXT,
	"interval_end_time": voltha.PmConfig_CONTEXT,

	"transmitted_gem_frames":    voltha.PmConfig_COUNTER,
	"received_gem_frames":       voltha.PmConfig_COUNTER,
	"received_payload_bytes":    voltha.PmConfig_COUNTER,
	"transmitted_payload_bytes": voltha.PmConfig_COUNTER,
	"encryption_key_errors":     voltha.PmConfig_COUNTER,
}

Basic KPI Format (KpiEvent2)

The KPI information is published on the kafka bus under the voltha.events topic. For VOLTHA PM information, the kafka key is empty and the value is a JSON message composed of the following key-value pairs.

keyvalueNotes
typestring"slice" or "ts". A "slice" is a set of path/metric data for the same time-stamp. A "ts" is a time-series: array of data for same metric
tsfloatUTC time-stamp of when the KpiEvent2 was created (seconds since the epoch of January 1, 1970)
slice_datalistOne or more sets of metrics composed of a metadata section and a metrics section.

NOTE: Time-series metrics and corresponding protobuf messages have not been defined.

Slice Data Format

For KPI slice KPI messages, the slice_data portion of the KpiEvent2 is composed of a metadata section and a metrics section.

metadata Section Format

The metadata section is used to:

  • Define which metric/metric-group is being reported (The title field)
  • Provide some common fields required by all metrics (title, timestamp, device ID, ...)
  • Provide metric/metric-group specific context (the context fields)
keyvalueNotes
titlestring"slice" or "ts". A "slice" is a set of path/metric data for the same time-stamp. A "ts" is a time-series: array of data for same metric
tsfloatUTC time-stamp of data at the time of collection (seconds since the epoch of January 1, 1970)
logical_device_idstringThe logical ID that the device belongs to. This is equivalent to the DPID reported in ONOS for the VOLTHA logical device with the 'of:' prefix removed.
device_idstringThe physical device ID that is reporting the metric.
serial_numberstringThe reported serial number for the physical device reporting the metric.
contextmapA key-value map of metric/metric-group specific information.

The context map is composed of key-value pairs where the key (string) is the label for the context specific value and the value (string) is the corresponding context value. While most values may be better represented as a float/integer, there may be some that are better represented as text. For this reason, values are always represented as strings to allow the ProtoBuf message format to be as simple as possible.

Here is an JSON example of a current KPI published on the kafka bus under the voltha.events topic.

   "kpiEvent2":{
      "type":"slice",
      "ts":1611605902528748000,
      "sliceData":[
         {
            "metadata":{
               "title":"OpticalPower",
               "ts":1611605902515836000,
               "logicalDeviceId":"1eda0422-f1cc-42e6-9a23-08039e7cdf43",
               "serialNo":"ALPHe3d1cf70",
               "deviceId":"1eda0422-f1cc-42e6-9a23-08039e7cdf43",
               "context":{
                  "devicetype":"brcm_openomci_onu",
                  "intfID":"0",
                  "onuID":"1"
               },
               "uuid":""
            },
            "metrics":{
               "ani_g_instance_id":32769,
               "receive_power_dBm":1.2,
               "transmit_power_dBm":-16.7
            }
         }
      ]
   }

Useful voltctl commands to manage Performance Metrics

Get PM config

voltctl device pmconfig get <onu-device-id>

List metric groups for a device

voltctl device pmconfig group list <onu-device-id>

List metrics within a group

voltctl device pmconfig groupmetric list <onu-device-id> <group-name>

Set default sampling rate

 voltctl device pmconfig frequency set <onu-device-id> <sampling-rate>

Note1: Sampling rate unit is in seconds

Note2: default sample rate is applicable only if frequency override is false

Note3 : The frequency has to be greater than 0 and a multiple of FrequencyGranularity which is currently set to 5.

Disable a group metric

voltctl device pmconfig group disable <onu-device-id> <group-name>

Enable a group metric

voltctl device pmconfig group enable <onu-device-id> <group-name>

Set group frequency

voltctl device pmconfig group set <onu-device-id> <group-name> <frequency>

Note1 : The frequency has to be greater than 0 and a multiple of FrequencyGranularity which is currently set to 5.

Note2 : The frequency of L2 PM counters is fixed at 15m and cannot be changed.

Listen for KPI events on kafka

voltctl -k <kafka-ip:port> event listen --show-body -t 10000 -o json -F

Note: For more event listen options, check voltctl event listen --help command.

Future work

The following Metrics could be supported in the future.

  • ANI-G Test report on demand
  • EthernetBridgeHistory and EthernetUniHistory counters on demand
  • xgPON_TC_History
  • xgPON_Downstream_History
  • xgPON_Upstream_History