RDK Resources
[*RDK Preferred*]
Code Management Facility
RDK Forums
[RDK Conferences]
RDK Support
Archives
Papers & Presentations Archive
Table of Contents |
---|
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.
The APIs can be called by Components whenever there is interesting data to report. The data will only be sent over the bus to the T2 component if there is an active telemetry profile interested in it. See the T2 Common Library Diagram in the Sequence Diagrams section.
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.
Telemetry APIs - for use by Components wishing to report metrics/data:
t2_init( char* componentName) –
init BUS/IPC for componentt2_event_s(char* markerName, char* value) –
send marker with string value to T2t2_event_f(char* markerName, double value) –
send marker with double value to T2t2_event_d(char* markerName, int value) –
send marker with int value to T2Usage:
t2_event_d(“WIFI_INFO_clientdisconnect”, 1)
;t2_event_s("2GRSSI_split", "Test_BOX_WIFI”)
t2_event_d("Total_5G_clients_split", num_devs)
Notes about marker names:
Components should use the T2 Common Library APIs to make interesting telemetry data available for reporting from the T2 component/RDK Telemetry Framework.
#include <telemetry_busmessage_sender.h>
Example: source/Ssp/ssp_main.c#41t2_init(char* ComponentName)
;t2_init("myComponentName");
t2_event_s(char* marker, char* value)
- To send _split marker with string value to T2
Usage:
t2_event_s("mac_3_split", "xh_MAC_value”);
t2_event_s("mac_3_split", strBuff);
/* where strBuff contains the string value to be reported for this marker */
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.
t2_event_f(char* marker, double value)
- To send marker with double value to T2
Usage: t2_event_f("HWREV_split", 2.2);
t2_event_d(char* marker, int value)
- To send marker with integer value to T2 (or) to report count based markers
Usage:
t2_event_d("WIFI_INFO_Zero_5G_Clients", 1);
/* To report counter based markers-- The value is reported as "1" *
t2_event_d("Total_5G_clients_split", num_devs);
/* To report integer type split markers */
Example: source/lm/lm_main.c#779
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
/lib/rdk/t2Shared_api.sh
t2ValNotify "Marker" "Value" - To report split based markers
Usage: t2ValNotify "LOAD_AVG_ATOM_split" "$LOAD_AVG_15"
Example: log_factoryPartnerId.sh#38
t2CountNotify "Marker" - To report count based markers.
Usage: t2CountNotify "SYS_ERROR_NotRegisteredOnCMTS"
Example: rdkbLogMonitor.sh#248
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.
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.
PlantUML Macro |
---|
@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 |
Anchor | ||||
---|---|---|---|---|
|
PlantUML Macro |
---|
@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 |