T2 Common Library Overview

T2.0 Common Library can be used by RDK Components that wish to report Telemetry data.

This library and its APIs allow migration away from the Telemetry 1/DCA mechanism that uses log file searches to report component metrics and information.

This library will insulate Components from needing to know the underlying BUS/IPC used on the device; the T2 Common Library uses RBUS as its platform agnostic IPC.

NOTE:  For backward compatibility and ad-hoc reporting, the log search mechanism continues to exist.  Going forward, components should be migrated to use the T2 Common Library to report Telemetry data in order to reduce the need for log search on devices.  

T2 Common Library APIs

Telemetry APIs - for use by Components wishing to report metrics/data:

• t2_init( char* componentName) – init BUS/IPC for component
• t2_event_s(char* markerName, char* value) – send marker with string value to T2
• t2_event_f(char* markerName, double value) – send marker with double value to T2
• t2_event_d(char* markerName, int value) – send marker with int value to T2

Usage:

• For count-based XConf markers:
  • t2_event_d(“WIFI_INFO_clientdisconnect”, 1);

• For string-match (_split) XConf markers:
  • t2_event_s("2GRSSI_split", "Test_BOX_WIFI”)
  • t2_event_d("Total_5G_clients_split", num_devs)

Notes about marker names:

• In the T1/Legacy/DCM profile, the "_split" suffix on marker names was used for a special purpose. 
  • When the old DCA script in RDK encountered a marker name with a "_split" suffix, it would report the actual value from the last log line where the search string was found. 
  • If the marker name did not have a "_split" suffix, the value reported for the marker was the number of times the search string was found in the specified log file.
• In T2 report profiles, there is no special functionality associated with the marker name.  Instead, T2 report profiles can specify a "use" property for all parameters.  The "use" property indicates how the event data shall be reported for this marker, for instance as a "count" or "absolute".  Please see "use" details for each parameter type by clicking on each Parameter Type here. "Use" defaults to "absolute" for all parameters.

Instrumenting Components to Send Telemetry Data

Components should use the T2 Common Library APIs to make interesting telemetry data available for reporting from the T2 component/RDK Telemetry Framework. 

Steps to instrument telemetry markers from components

1. Include required header:  #include <telemetry_busmessage_sender.h>  Example: source/Ssp/ssp_main.c#41
2. Initialize the module with telemetry using t2_init(char* ComponentName);
   1. This needs to be done only once at component initialization/startup.  Example: source/Ssp/ssp_main.c#305
   2. Pass a component name that will be used to identify telemetry data from this component:  t2_init("myComponentName");
3. Use appropriate APIs to report markers and values where desired

   1. t2_event_s(char* marker, char* value)      - To send _split marker with string value to T2

      1. Usage:

         1. t2_event_s("mac_3_split", "xh_MAC_value”);

         2. t2_event_s("mac_3_split", strBuff); /* where strBuff contains the string value to be reported for this marker */

      2. Example:  source/TR-181/sbapi/wifi_monitor.c#566

      3. NOTE: The instrumented component could use a static buffer or do a buffer malloc itself; but T2 common lib makes its own copy regardless, so instrumented component must clean up after itself.

   2. t2_event_f(char* marker, double value)      - To send marker with double value to T2

      1. Usage:  t2_event_f("HWREV_split", 2.2);

   3. t2_event_d(char* marker, int value)            - To send marker with integer value to T2  (or) to report count based markers

      1. Usage:

         1. t2_event_d("WIFI_INFO_Zero_5G_Clients", 1);  /* To report counter based markers-- The value is reported as "1" *

         2. t2_event_d("Total_5G_clients_split", num_devs); /* To report integer type split markers */

      2. Example:  source/lm/lm_main.c#779

4. Important notes

   1. If you are defining a character array buffer to store the value corresponding to marker, make sure maximum buffer size is allocated and is reset with '\0' before and after its use.
       Example: "telemetryBuff" usage in source/TR-181/sbapi/wifi_monitor.c#566
       In many cases, an existing buffer already being built/used within the component can be used rather than necessitating creation of a new buffer; see  source/TR-181/sbapi/wifi_monitor.c#3134      

   2. To Report count based markers, the value should be mentioned as "1" while using t2_event_d(char*, int) API.

Steps to instrument telemetry markers from scripts

1. Source the utility script /lib/rdk/t2Shared_api.sh
2. Use appropriate APIs to report markers and values where desired

   1. t2ValNotify "Marker" "Value"                 - To report split based markers

      1. Usage: t2ValNotify "LOAD_AVG_ATOM_split" "$LOAD_AVG_15"

      2. Example: log_factoryPartnerId.sh#38

   2. t2CountNotify  "Marker"                        - To report count based markers.

      1. Usage: t2CountNotify "SYS_ERROR_NotRegisteredOnCMTS"

      2. Example: rdkbLogMonitor.sh#248

How to Report Data Sent Via T2 Common Library APIs

Using T2 Report Profiles

Data sent via the T2 Common Library APIs is captured via the "event" parameter in a T2 report profile.

For example, if the componentA were instrumented to send an event named "WIFI_INFO_clients", it could be captured and reported by adding the following to the Parameters in a T2 report profile:

{
   "type": "event",
   "eventName": "WIFI_INFO_clients",
   "component": "componentA"
 }

See Parameter Types: event for more details on event properties that can be specified in a T2 report profile.

Using the T1/Legacy/DCM profile

As mentioned above, support for events was initially added to help migrate away from using log search strings as a telemetry source.  To aid in quicker adoption, the T1/Legacy/DCM profile supports events by replacing the log file name with the string "<event>" in the DCM configuration.  

For instance, the following is an example of the T1/Legacy/DCM profile specifying a search string and log file, where the "content" is the search string and the "type" is the log in which to search. "header" is the marker name that will be seen in the generated telemetry report.

"telemetryProfile": [{ 
    "header": "SYS_SH_MTA_restart", 
     "content": "MTA_process is not running", 
     "type": "SelfHeal.txt.0", 
     "pollingFrequency": "0" 
 },

To change this to use an event from the T2 Common Library, the T1/Legacy/DCM profile would specify "<event>" instead of a log file name and the component name instead of the search string, as follows:

"telemetryProfile": [{ 
  "header": "SYS_SH_MTA_restart", 
   "content": ""com.cisco.spvtg.ccsp.meshagent"", 
   "type": "<event>", 
   "pollingFrequency": "0" 
},

Because this mechanism uses existing fields, the XConf UI for entering the T1/Legacy/DCM profile did not need to change.

Sequence Diagrams

T2 Component

@startuml
participant T2Agent as A
participant RBUS as R
participant T2CommonLib as C
participant Component as Co

A -> A: rBusInterface_Init
activate A
A -> R: rbus_open
R -> A: done
A -> A: done
deactivate A
... ...

A -> A: registerRbusT2EventListener(callback)
activate A
A -> R: rbus_regDataElements
note right R
Telemetry.ReportProfiles.EventMarker as property
Telemetry.ReportProfiles.ProfilesUpdated as event
end note
R -> A: done
A -> A: done
deactivate A
... ...

A -> A: regDEforCompEventList(COMPONENT_ID, callback)
activate A
A -> R: rbus_regDataElements
note right R
Telemetry.ReportProfiles.<COMPONENT_ID>.EventMarkerList as property
end note
R -> A: done
A -> A: hash_map_put(property name, COMPONENT_ID)
A -> A: done
deactivate A
... ...

A -> A: regDEforProfileDataModel(callbacks)
activate A
A -> R: rbus_regDataElements
note right R
Device.X_RDKCENTRAL-COM_T2.ReportProfiles as property
Device.X_RDKCENTRAL-COM_T2.ReportProfilesMsgPack as property
end note
R -> A: done
A -> A: hash_map_put(property name, COMPONENT_ID)
A -> A: done
deactivate A
... ...

A -> A: getRbusProfileParamValues(parameter list)
activate A
loop for each parameter in list
A -> R: rbus_getExt
note right A
FIXME: rbus_getExt is optimized for handling
a list of properties instead of sending 1 by 1
end note
end loop
A -> A: done
deactivate A
... ...

Co -> C: t2_event
activate C
alt if not initialized
C -> R:rbusEvent_Subscribe
note left C
event Telemetry.ReportProfiles.ProfilesUpdated
end note
R -> C: done
end alt
C --> R: rbus_set: Telemetry.ReportProfiles.EventMarker
R --> A: t2PropertyDataSetHandler
activate A
alt property is Telemetry.ReportProfiles.EventMarker
A -> A: eventCallBack
else property is Device.X_RDKCENTRAL-COM_T2.ReportProfiles
A -> A: store reportProfileVal = property value
else property is Device.X_RDKCENTRAL-COM_T2.ReportProfilesMsgPack
A -> A: store reportProfilemsgPckVal = property value
end
A --> R: done
deactivate A
R --> C: done
C -> Co: done
deactivate C
... ...

C -> R: rbus_get
activate C
note right of C
name: Telemetry.ReportProfiles.<COMPONENT_ID>.EventMarkerList
end note
R --> A: t2PropertyDataGetHandler
activate A
alt property is Device.X_RDKCENTRAL-COM_T2.ReportProfiles
A -> R: reportProfileVal
else property is Device.X_RDKCENTRAL-COM_T2.ReportProfilesMsgPack
A -> R: reportProfilemsgPckVal
else
A -> A: hash_map_get(property name)
activate A
A -> A: COMPONENT_ID
deactivate A
A -> A: getMarkerListCallBack(COMPONENT_ID)
activate A
A -> A: marker_list
deactivate A
note right A
Create rbusProperty_t list from marker list.
Each marker will be the name of a property.
end note
A -> R: marker list as rbusProperty list
end
deactivate A
R -> C: marker list
deactivate C
... ...

A -> A: publishEventsProfileUpdates
activate A
A -> R: rbusEvent_Publish
note right R
event Telemetry.ReportProfiles.ProfilesUpdated
end note
R -> C: event
ref over C
see doPopulateEventMarkerList above
end ref
A -> A: done
deactivate A
... ...

A -> A: rbusT2ConsumerReg(triggerConditionList)
loop for each triggerCondition in list
activate A
A -> A: T2RbusConsumer(triggerCondition)
activate A
note right A
subscribing to event named: triggerCondition->reference
with filter based on: triggerCondition->oprator
and event handler: triggerCondtionReceiveHandler
end note
alt no filter
A -> R: rbusEvent_Subscribe
R -> A: Done
else if filter
A -> R: rbusEvent_SubscribeEx
R -> A: Done
end
A -> A: done
deactivate A
end loop
A -> A: done
deactivate A
... ...

R -> A: triggerCondtionReceiveHandler
activate A
A -> A: triggerReportOnCondtion(event name)
A -> R: done
deactivate A

@enduml

T2 Common Library

@startuml
box "Component using t2 common library"
participant Component as C
participant T2CommonLib as TC
end box
participant T2Agent as TA

C -> TC: t2_init(COMPONENT_ID)
activate TC
TC -> TC: store COMPONENT_ID
TC -> C: done
deactivate TC
... ...

C -> TC: t2_event(marker,value)
alt if not initialized
activate TC
TC -> TC: doPopulateEventMarkerList
activate TC
TC -> TA: rbus_get
activate TA
note right of TA
name: Telemetry.ReportProfiles.<COMPONENT_ID>.EventMarkerList
end note
TA -> TC: marker list
note right of TA
marker list as rbusProperty_t list
with the name of each property being the marker
end note
deactivate TA
TC -> TC: clear marker hash map
loop for each marker in list
note right of TC
looping through rbusProperty_t list
end note
TC -> TC: add marker to hash map
end loop
TC -> TC: done
deactivate TC
TC -> TA: rbusEvent_Subscribe
note right of TA
name: Telemetry.ReportProfiles.ProfilesUpdated
end note
end
alt marker in hash map
TC -> TA: rbus_set
note right of TA
name: Telemetry.ReportProfiles.EventMarker
value: marker=value
end note
end
TC -> C: done
deactivate TC
... ...

TA --> TC: rbusEvent_Publish
note right of TA
name: Telemetry.ReportProfiles.ProfilesUpdated
date: empty
end note
activate TC
TC -> TC: doPopulateEventMarkerList
activate TC
ref over TC
see doPopulateEventMarkerList above
end ref
TC -> TC: done
deactivate TC
deactivate TC
@enduml