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