This repository contains the files of the Sternum Linux SDK, a versatile and flexible tool to add observability and traceability to Linux devices using C/C++.

The SDK package is organized into three main directories:

linux - Sources for building Sternum Linux SDK library,
posix_native_sdk - The SDK core files, included into Linux build automatically.
linux/modules - Third-party libraries: OpenSSL.

Setup

Build OpenSSL

Linux SDK requires OpenSSL for encrypted transmission. Default version of OpenSSL is provided as source in the SDK package, and it should be built during the SDK build process. However, if your device already has OpenSSL installed and you prefer to use that version, you can skip this step and configure the SDK to use the existing installation. Keep in mind that OpenSSL APIs can vary between versions, so for compatibility, we recommend using the version included with the SDK. The SDK currently is tested with the following OpenSSL versions:

3.2.1 (default)
1.0.2j (custom) To use your own version of OpenSSL, simply skip the "Build OpenSSL" step and proceed directly to configuring the SDK with your version.

OpenSSL requirements setup

Before building or compiling the OpenSSL module, ensure that you have the necessary development packages installed on your Linux system. The required packages may vary depending on your Linux distribution. Typically, you'll need development tools and libraries. Here's how to install the prerequisites on Debian-based systems (such as Ubuntu):

Update the package index:

sudo apt update

Install the necessary development packages for OpenSSL:

sudo apt install build-essential

This command installs essential development tools including compilers and libraries required for building OpenSSL.

Build OpenSSL library

Change into the OpenSSL submodule directory by running the following command:

cd sternum_linux_sdk/linux/modules/openssl

Configure OpenSSL build:

./config

This command configures OpenSSL build environment based on your system's architecture and installed libraries.

When cross-compiling, ensure to modify the build parameters accordingly. An example is provided in the Cross Compilation section.

Build OpenSSL:

make

This command compiles OpenSSL from the source code.

(Optional) Run tests:

make test

This command runs the OpenSSL test suite to ensure that the build is successful and the library functions correctly.

The compiled libraries will be located in the modules/openssl directory. During the SDK build process, these libraries will be placed into the sternum_linux_sdk/linux/output directory.

OpenSSL Cross Compilation

The following example demonstrates how to cross-compile OpenSSL for AARCH64.

Assuming your cross-compilation toolchain is accessible as aarch64-linux-gnu-, the OpenSSL configuration can be done as follows:

export CROSS_COMPILE=aarch64-linux-gnu-
./Configure linux-aarch64 shared --cross-compile-prefix=${CROSS_COMPILE}
make

Adapt the parameters to your toolchain and architecture as needed.

Build Sternum Linux SDK

Once you have built OpenSSL successfully, you can build Sternum SDK library. Navigate to Linux SDK directory:

cd sternum_linux_sdk/linux

Configure SDK build:

To configure the SDK build for your host environment with default features, use the following command:

cmake .

This command generates the necessary build files based on your environment, including your system architecture and the default SDK feature settings. It prepares the project for compilation, tailored to your specific development environment.

Custom OpenSSL configuration

Select the custom OpenSSL version by specifying the version number as a CMake option. For example, to use OpenSSL 1.0.2j, run the following command:

cmake . -DUSE_CUSTOM_OPENSSL=1.0.2j

If the OpenSSL installation is not in the default system path, you need to specify the path to the OpenSSL installation directory using the OPENSSL_ROOT_DIR option:

cmake . -DUSE_CUSTOM_OPENSSL=1.0.2j -DOPENSSL_ROOT_DIR=/usr/local/openssl-1.0.2j

Build SDK:

make

The sternum_linux_sdk/linux/output directory will contain generated SDK library libsternum_linux_sdk.so, OpenSSL libraries libssl.so, libcrypto.so, and include directory encompassing all necessary SDK headers.

After building the SDK, move created libraries (libsternum_linux_sdk.so, libssl.so, libcrypto.so) to target device and ensure that they are accessible for dynamic linker. You have three options to make these libraries accessible:

Set RPATH in the Target Project:

In your target project's CMakeLists.txt, set the RPATH to include the directory where the SDK's shared libraries are located. This ensures that the dynamic linker can find the libraries at runtime without requiring additional environment variables.

For example, if the shared libraries are in the lib/ directory relative to the executable:

set_target_properties(your_target PROPERTIES
    INSTALL_RPATH "$ORIGIN/../lib"
    BUILD_RPATH "$ORIGIN/../lib"
    INSTALL_RPATH_USE_LINK_PATH TRUE
)

Update LD_LIBRARY_PATH:

Set the LD_LIBRARY_PATH environment variable on your target device to include the paths to these libraries. This allows the dynamic linker to find the libraries at runtime. For example:

export LD_LIBRARY_PATH=/path/to/libraries:$LD_LIBRARY_PATH

Move Libraries to a Default Location:

Alternatively, you can move the libraries to a standard system directory where the dynamic linker automatically searches for shared libraries. Common default paths include /usr/lib or /usr/local/lib.

By following these steps, you ensure that your target device can locate and use the SDK and its dependencies correctly.

SDK Cross Compilation

When cross-compiling the SDK, adjust the build parameters to match the target architecture. Detailed instructions are provided in this section.

Create a toolchain file that specifies the necessary variables for cross-compilation. Below is an example for AArch64 (ARM 64-bit architecture) that utilizes a previously defined CROSS_COMPILE environment variable.

Example: aarch64-toolchain.cmake

# Set the cross-compilation environment
set(CMAKE_SYSTEM_NAME Linux)
set(CMAKE_SYSTEM_PROCESSOR aarch64)
 
# Specify the cross-compiler
set(CMAKE_C_COMPILER $ENV{CROSS_COMPILE}gcc)
set(CMAKE_CXX_COMPILER $ENV{CROSS_COMPILE}g++)
set(CMAKE_ASM_COMPILER $ENV{CROSS_COMPILE}gcc)

To build the library using the toolchain file, run the following command:

cmake -DCMAKE_TOOLCHAIN_FILE=aarch64-toolchain.cmake .

make

Customizing Features

You can customize various features of the SDK by adding CMake options when configuring the build. Here are the available options:

-DAPPEND_PROCESS_NAME=ON/OFF: Enable or disable adding the executing process name to each trace (default: ON).
-DENABLE_CRASH_DETECTION=ON/OFF: Enable or disable crash detection feature (default: ON).
-DLOG_LEVEL=0..3: Specify the log level (Default: 2).

Log Level

The log level determines the verbosity of logging messages generated by the library. Accepted values are:

ERR   0
WARN  1
INF   2
DBG   3

Crash detection

The Crash Detection feature automatically captures program state information when the program crashes due to certain signals, including SIGSEGV, SIGBUS, SIGILL, SIGABRT, SIGFPE, SIGSYS, and SIGTERM. This information is stored in a crash dump file in the cache. On the next boot of the program, the stored crash dump is automatically transmitted to Sternum Platform within TRACE_CRASH. This allows developers to analyze the crash and diagnose the root cause more effectively.

Append process name

If APPEND_PROCESS_NAME is enabled, executing process name will be included automatically to each transmitted trace.

Integrate Sternum Linux into your project

Your project will need the SDK headers, SDK library libsternum_linux_sdk.so, and its dependencies (libssl.so, libcrypto.so) in order to instrument and build your applications with the SDK.

Copy and paste the contents of sternum_linux_sdk/linux/output to your project or general location on your device. You can create new folder in your project structure for this purpose, for instance sternum_sdk.

Adjust the configuration according to your build system to include the SDK directory and link with SDK library. If you are using CMake, an example of configuration is documented next.

Example of CMake configuration

To build your application with the SDK, update your CMake configuration as follows:

Add sternum_sdk/include directory to the list of include directories for your project:

target_include_directories(app PRIVATE
    # existing include directories...
    sternum_sdk/include
)

Link your application with Sternum SDK library:

target_link_libraries(app PRIVATE sternum_sdk/libsternum_linux_sdk.so)

If you're using a different build system, adjust the configuration accordingly to include the SDK directory and link with SDK library.

Using the API

Include sternum_sdk.h

#include "sternum_sdk.h"

Initialize Sternum SDK

You must initialize Sternum SDK before using it.

Transmission initialization:

sternum_settings_t::sternum_url - The designated endpoint provided by Sternum, serving as the destination for transmitting traces.
sternum_settings_t::access_token - Identifier for the product to which traces will be transmitted.

File cache initialization:

Traces are cached in a file cache. If transmission fails, they will remain stored in the file cache until successfully sent. Once transmitted, they are then removed from the cache. The file cache maintains persistence across multiple application executions and must be unique for each application instance.

sternum_settings_t::cache_file_path - You can specify your preferred file cache location as a full path or filename that will be located in current working directory. Each application instance using the SDK must set its own file cache. Refer to field documentation to understand the accepted path formats and other details.
sternum_settings_t::max_cache_size_bytes - Sets the maximum cache size. The recommended size is 65kB. If there's no space in the cache to construct a trace, it won't be created even if immediate transmission is possible.

For more information about the initialization structure, refer to the documentation of struct sternum_settings_t .

Below is an example of how to initialize the SDK:

sternum_settings_t settings;
// Ensure clear initial state of settings
init_sternum_settings(&settings);
 
settings.sternum_url = "gateway.sternum.cloud";
settings.access_token = 0x10101010;
settings.device_id = 0x20304050;
settings.relay_override_device_id = NULL;
settings.is_production = false;
settings.max_cache_size_bytes = 65000;
settings.cache_file_path = "sternum_cache.bin";
 
if (sternum_sdk_initialize(&settings) != STERNUM_CODE_SUCCESS) {
    printf("SDK initialization failed");
    return -1;
}

Thread safety

The SDK library is thread-safe.

Sending traces

STERNUM_ADS_TRACE(TRACE_UPDATE_START);

Traces are sent to the cloud in the background. The SDK will automatically handle the transmission of traces to the designated endpoint. There is no need of calling any additional functions to send traces.

Relaying device data

sternum_sdk_relay_device_data(device_type, data, size);

Flushing traces

Flush transmission queue and save data to cache. It should be called before the sternum_sdk_close() and program exit, to ensure no data loss. This function will block until data is process and saved to cache. This function will not ensure a transmission of data to the cloud.

sternum_sdk_flush();

Closing the Sternum SDK

sternum_sdk_close();