Telemetry 2.0

A lightweight, efficient telemetry framework for RDK (Reference Design Kit) embedded devices.

Overview

Telemetry 2.0 provides real-time monitoring, event collection, and reporting capabilities optimized for resource-constrained embedded devices such as set-top boxes, gateways, and IoT devices.

Key Features

⚡ Efficient: Connection pooling and batch reporting
🔒 Secure: mTLS support for encrypted communication
📊 Flexible: Profile-based configuration (JSON/XConf)
🔧 Platform-Independent: Multiple architecture support

Architecture Highlights

graph TB
    A[Telemetry Events/Markers] --> B[Profile Matcher]
    B --> C[Report Generator]
    C --> D[HTTP Connection Pool]
    D --> E[XConf Server / Data Collector]
    F[XConf Client] -.->|Config| B
    G[Scheduler] -.->|Triggers| C

Quick Start

Prerequisites

GCC 4.8+ or Clang 3.5+
pthread library
libcurl 7.65.0+
cJSON library
OpenSSL 1.1.1+ (for mTLS)

Build

# Clone repository
git clone https://github.com/rdkcentral/telemetry.git
cd telemetry

# Configure
autoreconf -i
./configure 

# Build
make

# Install
sudo make install

Docker Development

Refer to the provided Docker container for a consistent development environment:

https://github.com/rdkcentral/docker-device-mgt-service-test

See Build Setup Guide for detailed build options.

Basic Usage

#include "telemetry2_0.h"

int main(void) {
    // Initialize telemetry
    if (t2_init() != 0) {
        fprintf(stderr, "Failed to initialize telemetry\n");
        return -1;
    }
    
    // Send a marker event
    t2_event_s("SYS_INFO_DeviceBootup", "Device started successfully");
    
    // Cleanup
    t2_uninit();
    return 0;
}

Compile: gcc -o myapp myapp.c -ltelemetry

Documentation

📚 Complete Documentation

Key Documents

Architecture Overview - System design and components
API Reference - Public API documentation
Developer Guide - Getting started
Build Setup - Build configuration
Testing Guide - Test procedures

Component Documentation

Individual component documentation is in source/docs/:

Bulk Data System - Profile and marker management
HTTP Protocol - Communication layer
Scheduler - Report scheduling
XConf Client - Configuration retrieval

Project Structure

telemetry/
├── source/              # Source code
│   ├── bulkdata/       # Profile and marker management
│   ├── protocol/       # HTTP/RBUS communication
│   ├── scheduler/      # Report scheduling
│   ├── xconf-client/   # Configuration retrieval
│   ├── dcautil/        # Log marker utilities
│   └── test/           # Unit tests (gtest/gmock)
├── include/            # Public headers
├── config/             # Configuration files
├── docs/               # Documentation
├── containers/         # Docker development environment
└── test/               # Functional tests

Configuration

Profile Configuration

Telemetry uses JSON profiles to define what data to collect:

{
  "Profile": "RDKB_BasicProfile",
  "Version": "1.0.0",
  "Protocol": "HTTP",
  "EncodingType": "JSON",
  "ReportingInterval": 300,
  "Parameters": [
    {
      "type": "dataModel",
      "name": "Device.DeviceInfo.Manufacturer"
    },
    {
      "type": "event",
      "eventName": "bootup_complete"
    }
  ]
}

See Profile Configuration Guide for details.

Environment Variables

Variable	Description	Default
`T2_ENABLE_DEBUG`	Enable debug logging	`0`
`T2_PROFILE_PATH`	Default profile directory	`/etc/DefaultT2Profile.json`
`T2_XCONF_URL`	XConf server URL	-
`T2_REPORT_URL`	Report upload URL	-

Runtime Operations

Signal Handling

The Telemetry 2.0 daemon responds to the following signals for runtime control:

Signal	Value	Purpose
SIGTERM	15	Gracefully terminate the daemon, cleanup resources and exit
SIGINT	2	Interrupt signal - uninitialize services, cleanup and exit
SIGUSR1	10	Trigger log upload with seekmap reset
SIGUSR2	12	Reload configuration from XConf server
LOG_UPLOAD	10	Custom signal to trigger log upload and reset retain seekmap flag
EXEC_RELOAD	12	Custom signal to reload XConf configuration and restart XConf client
LOG_UPLOAD_ONDEMAND	29	Custom signal for on-demand log upload without seekmap reset
SIGIO	-	I/O signal - repurposed for on-demand log upload

Examples:

# Gracefully stop telemetry
kill -SIGTERM $(pidof telemetry2_0)

# Trigger log upload
kill -10 $(pidof telemetry2_0)

# Reload configuration
kill -12 $(pidof telemetry2_0)

# On-demand log upload
kill -29 $(pidof telemetry2_0)

Notes:

Custom signal values (10, 12, 29) are defined to avoid conflicts with standard system signals
Signals SIGUSR1, SIGUSR2, LOG_UPLOAD, EXEC_RELOAD, LOG_UPLOAD_ONDEMAND, and SIGIO are blocked during signal handler execution to prevent race conditions
Child processes ignore most signals except SIGCHLD, SIGPIPE, SIGALRM, and the log upload/reload signals

WebConfig/Profile Reload

Telemetry 2.0 supports multiple mechanisms for dynamically reloading report profiles and configuration:

1. Signal-Based XConf Reload

Trigger XConf configuration reload using signals:

# Using custom signal value
kill -12 $(pidof telemetry2_0)

This stops the XConf client and restarts it to fetch updated configuration from the XConf server.

2. RBUS-Based Profile Updates

For WebConfig integration, profiles can be set directly via RBUS (requires rbuscli):

# Load a temporary profile (JSON format)
rbuscli setv "Device.X_RDKCENTRAL-COM_T2.Temp_ReportProfiles" string '{"profiles":[...]}'

# Set permanent profiles
rbuscli setv "Device.X_RDKCENTRAL-COM_T2.ReportProfiles" string '{"profiles":[...]}'

# Set profiles in MessagePack binary format
rbuscli setv "Device.X_RDKCENTRAL-COM_T2.ReportProfilesMsgPack" bytes <msgpack_data>

# Clear all profiles
rbuscli setv "Device.X_RDKCENTRAL-COM_T2.ReportProfiles" string '{"profiles":[]}'

3. DCM Event-Based Reload

Subscribe to DCM reload events via RBUS (typically used by WebConfig framework):

# Publish DCM reload event
rbuscli publish Device.X_RDKCENTREL-COM.Reloadconfig

4. Using Test Utilities

The project includes a convenience script for testing profile updates:

# Load example profile
./test/set_report_profile.sh example

# Load DOCSIS reference profile
./test/set_report_profile.sh docsis

# Clear all profiles
./test/set_report_profile.sh empty

# Load custom JSON profile
./test/set_report_profile.sh '{"profiles":[...]}'

Available RBUS Parameters:

Device.X_RDKCENTRAL-COM_T2.ReportProfiles - Persistent report profiles (JSON)
Device.X_RDKCENTRAL-COM_T2.ReportProfilesMsgPack - Persistent profiles (MessagePack binary)
Device.X_RDKCENTRAL-COM_T2.Temp_ReportProfiles - Temporary profiles (JSON)
Device.X_RDKCENTRAL-COM_T2.UploadDCMReport - Trigger on-demand report upload
Device.X_RDKCENTRAL-COM_T2.AbortDCMReport - Abort ongoing report upload

Development

Running Tests

# Unit tests
make check

# Functional tests
cd test
./run_ut.sh

# Code coverage
./cov_build.sh

Development Container

Use the provided Docker container for consistent development: https://github.com/rdkcentral/docker-device-mgt-service-test

cd docker-device-mgt-service-test
docker compose up -d

A directory above the current directory is mounted as a volume in /mnt/L2_CONTAINER_SHARED_VOLUME . Login to the container as follows:

docker exec -it native-platform /bin/bash
cd /mnt/L2_CONTAINER_SHARED_VOLUME/telemetry
sh test/run_ut.sh

See Docker Development Guide for more details.

Platform Support

Telemetry 2.0 is designed to be platform-independent and has been tested on:

RDK-B (Broadband devices)
RDK-V (Video devices)
Linux (x86_64, ARM, ARM64)
Yocto Project builds

See Platform Porting Guide for porting to new platforms.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Workflow

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Add tests for new functionality
Ensure all L1 and L2 tests pass
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Code Style

Follow existing C code style and ensure astyle formatting and checks pass with below commands

          find . -name '*.c' -o -name '*.h' | xargs astyle --options=.astylerc
          find . -name '*.orig' -type f -delete

Use descriptive variable names
Document all public APIs
Add unit tests for new functions
Add functional tests for new features

See Coding Guidelines for details.

Troubleshooting

Common Issues

Q: Telemetry not sending reports

Check network connectivity
Verify XConf URL configuration
Review logs in /var/log/telemetry/

Q: High memory usage

Reduce number of active profiles
Decrease reporting intervals
Check for memory leaks with valgrind

Q: Build errors

Ensure all dependencies installed
Check compiler version (GCC 4.8+)
Review build logs for missing libraries

See Troubleshooting Guide for more solutions.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Acknowledgments

RDK Management LLC
RDK Community Contributors
Open Source Community

Contact

Repository: https://github.com/rdkcentral/telemetry
Issues: https://github.com/rdkcentral/telemetry/issues
RDK Central: https://rdkcentral.com

Changelog

See CHANGELOG.md for version history and release notes.

Built for the RDK Community

Name		Name	Last commit message	Last commit date
Latest commit History 308 Commits
.github		.github
config		config
containers		containers
docs		docs
include		include
schemas		schemas
source		source
test		test
.astylerc		.astylerc
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
COPYING		COPYING
LICENSE		LICENSE
Makefile.am		Makefile.am
NOTICE		NOTICE
README.md		README.md
build_inside_container.sh		build_inside_container.sh
configure.ac		configure.ac
cov_build.sh		cov_build.sh
rdk_env.xml		rdk_env.xml
telemetry2_0.path		telemetry2_0.path
telemetry2_0.service		telemetry2_0.service

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Telemetry 2.0

Overview

Key Features

Architecture Highlights

Quick Start

Prerequisites

Build

Docker Development

Basic Usage

Documentation

Key Documents

Component Documentation

Project Structure

Configuration

Profile Configuration

Environment Variables

Runtime Operations

Signal Handling

WebConfig/Profile Reload

1. Signal-Based XConf Reload

2. RBUS-Based Profile Updates

3. DCM Event-Based Reload

4. Using Test Utilities

Development

Running Tests

Development Container

Platform Support

Contributing

Development Workflow

Code Style

Troubleshooting

Common Issues

License

Acknowledgments

Contact

Changelog

About

Topics

Resources

Contributing

Security policy

Stars

Watchers

Forks

Packages

Used by

Contributors

Languages