Introduction

While migrating to Telemetry2.0 from DCA telemetry, the traditional log grepping is targetted to reduce as much as possible by instrumenting the  markers coming from RDKB components.To achieve this, RDKB components are supposed make required changes with the use of APIs from Telemetry 2.0 shared library (commonlib - https://code.rdkcentral.com/r/plugins/gitiles/rdk/components/generic/telemetry/+/refs/heads/rdk-next/source/commonlib/ )

Brief Background:

In DCA telemetry, the markers fetched from xconf are grepped in log files and reported in json format to splunk server.

The markers are of 3 types:

1. Split based markers. 
2. Count based markers
3. TR-181 based markers.

{"header":"WIFI_ACS_1_split","content":"WIFI_ACS_1:","type":"wifihealth.txt","pollingFrequency":"0"}

{"header":"RF_ERROR_IPV6PingFailed","content":"Ping to IPv6 Gateway Address are failed","type":"SelfHeal.txt.0","pollingFrequency":"0"}

In T2.0,  the aim is to instrument possible number of split and count based markers from component side. These are termed as event markers. Can be classified as one more type under the classification of  markers. Once a marker is instrumented from component side, its configuration on xconf will be changed  from the configured file name to "<event>" in   'type:' section.

Example: {"header":"WIFI_ACS_1_split","content":"WIFI_ACS_1:","type":<event>","pollingFrequency":"0"}

Overview of Instrumenting RDKB components with T2 shared library (commonlib) APIs:

Steps to instrument split based and count based markers from RDKB components side:

1. Check if that particular device Build have the Telemtry2.0 building capability
2. Include required headers 
3. Compile the component with telemetry 2.0 support
4. Initialize the module with telemetry
5. Find the correct place to report a marker
6. Use appropriate APIs to report markers and values.
7. Must check notes

1. To check if a particular device build have the Telemtry2.0 building capability
   1. Should have an entry in device based.xml file
   2. "telemetry2_0" should be appeneded to DISTRO_FEATURES in machine configuration file. NOTE: Distro feature will be removed soon, and this page will be updated to reflect that.
2. Include required headers / declare enough sized telemetry buffer and send events to T2 with t2_event_s() api
   1. NOTE: Now that T2.0 is present on all RDK-B platforms, there is no need to use the #if defined for the header or T2.0 API calls
      1. #if defined(ENABLE_FEATURE_TELEMETRY2_0)
         #include <telemetry_busmessage_sender.h>
         #endif
         1. https://code.rdkcentral.com/r/plugins/gitiles/rdkb/components/opensource/ccsp/CcspWifiAgent/+/refs/heads/rdk-next/include/TR-181/ml/cosa_wifi_internal.h
         2. https://code.rdkcentral.com/r/plugins/gitiles/rdkb/components/opensource/ccsp/CcspWifiAgent/+/refs/heads/rdk-next/source/TR-181/sbapi/wifi_monitor.c
3. To compile a component with Telemetry2.0 if it is enabled for that device. NOTE: Distro feature will be removed soon, and this page will be updated to reflect that.
   1. Add depends to telemetry module.
   2. Add Compile time (-DENABLE_FEATURE_TELEMETRY2_0) and linking time (-ltelemetry_msgsender) flags  to the recipe file.
   3. Make sure that bb file has below line to avoid compilation errors.
      1. CFLAGS_append = " -I${STAGING_INCDIR}/ccsp "
      2. Sample review: https://code.rdkcentral.com/r/plugins/gitiles/rdk/components/generic/rdk-oe/meta-rdk-broadband/+/refs/heads/rdk-next/recipes-ccsp/ccsp/ccsp-wifi-agent.bb
4. Initialize the module with telemetry
   1. Initialization needs to be done only once at the very initial stage of application / module
      1. Example: https://code.rdkcentral.com/r/plugins/gitiles/rdkb/components/opensource/ccsp/CcspCr/+/refs/heads/rdk-next/source/CrSsp/ssp_main.c
5. Find the correct place to report a marker
   1. Previously  in DCA telemetry, a marker is reported based on the xconf configured "content" string -  when the content string is found in corresponding configured filename configured under 'type:' section .
      1. /* Refer :  {"header": "WIFI_INFO_Hotspot_client_connected", "content": "Added case, Client with:", "type": "Hotspotlog.txt.0","pollingFrequency":"0"} */
   2. So, find the right place where the content string is being written to the corresponding log file in order to event a marker in T2.0.
      1. https://code.rdkcentral.com/r/plugins/gitiles/rdkb/components/opensource/ccsp/hotspot/+/refs/heads/rdk-next/source/hotspotfd/cosa_hotspot_dml.c (Line number 144 gives the idea) CcspTraceInfo(("Added case, Client with MAC:%s will be added\n", l_cMacAddr));
   3. Once the place is decided, use the right API to report Marker and values. 
      1. For markers without "_split" suffix, the marker data is just a count of the number of times the marker is received.  In this case, the t2_event_d API can be used because the marker data passed to the API is not important.
         1. Example:  t2_event_d("WIFI_INFO_Hotspot_client_connected", 1); in https://code.rdkcentral.com/r/plugins/gitiles/rdkb/components/opensource/ccsp/hotspot/+/refs/heads/rdk-next/source/hotspotfd/cosa_hotspot_dml.c
      2. For markers with "_split" suffix, the marker data is important, so use the API most appropriate to the marker data.  For instance, if the marker data is a string, use t2_event_s.  But if marker data is numeric, use one of t2_event_d or t2_event_f.  Also note that testing must ensure the string used for marker data matches the string expected by legacy telemetry.
         1. Example : t2_event_s("acs_split", pStr); in https://code.rdkcentral.com/r/plugins/gitiles/rdkb/components/opensource/ccsp/CcspTr069Pa/+/refs/heads/rdk-next/source-embedded/DslhManagementServer/ccsp_management_server_pa_api.c#767
6. Use appropriate APIs to event markers and values
   1. In RDKB we have logs coming from both scripts and component's code (code in C). From which markers are reported/grepped.
   2. List of APIs :
      1. To report markers from components
         • t2_event_s(char* marker, char* value) - To send _split marker with string value to T2
           • Usage:
             • t2_event_s("xh_mac_3_split", "xh_MAC_value”);
             • t2_event_s("xh_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_d("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:
             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 */
                1. Sample Review: https://code.rdkcentral.com/r/plugins/gitiles/rdkb/components/opensource/ccsp/CcspWifiAgent/+/refs/heads/rdk-next/source/TR-181/sbapi/wifi_monitor.c
7. Must Check Notes
   1. While instrumenting components
      •  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 https://code.rdkcentral.com/r/plugins/gitiles/rdkb/components/opensource/ccsp/CcspWifiAgent/+/refs/heads/rdk-next/source/TR-181/sbapi/wifi_monitor.c
        • 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 https://code.rdkcentral.com/r/plugins/gitiles/rdkb/components/opensource/ccsp/CcspTr069Pa/+/refs/heads/rdk-next/source-embedded/DslhManagementServer/ccsp_management_server_pa_api.c
      • To Report count based markers , The value should be mentioned as "1" while using t2_event_d() API.
   2. While instrumenting  Scripts
      1. Source the utility script /lib/rdk/t2Shared_api.sh 
      2. Invoke :
         1. t2ValNotify "Marker" "Value" - To report split based markers
         2. t2CountNotify  "Marker" - To report count based markers.
         3. https://code.rdkcentral.com/r/plugins/gitiles/rdkb/components/opensource/ccsp/sysint/+/refs/heads/rdk-next/uploadRDKBLogs.sh

References

1. T2.0 Common Library APIs
2. Relates to Instrumenting RDKV components to use Telemetry 2.0