Crate opentelemetry_user_events_logs

OpenTelemetry User Events Exporter for Logs

This crate provides a log exporter for exporting logs to the Linux user_events subsystem. The user_events subsystem is a Linux kernel feature introduced in version 6.4, designed for efficient user process tracing. It is conceptually similar to Event Tracing for Windows (ETW) on Windows and leverages Linux Tracepoints to enable user processes to create traceable events and data. These events can be analyzed using existing tools like ftrace and perf.

Key Features of user_events

• Efficient Tracing Path: Provides a faster path for tracing from user-mode applications by utilizing kernel-mode memory address space.
• Selective Event Export: Allows user processes to export telemetry events only when they are actively needed, i.e., when the corresponding tracepoint events are enabled.

Purpose of this Exporter

The user_events exporter enables applications to use the OpenTelemetry API to capture telemetry events and write them to the user_events subsystem. Once written, these events can be:

• Captured by Local Agents: Agents running locally can listen for specific events within the user_events subsystem.
• Monitored in Real-Time: Events can be monitored in real-time using Linux tools like perf or ftrace.

Prerequisite

• Linux Kernel Version: Requires Linux kernel 6.4 or later with user_events support enabled to use the exporter.

Synchronous Export

This exporter writes telemetry events to the user_events subsystem synchronously, without any buffering or batching. The exporter is non-blocking, and each event is immediately exported, ensuring that no telemetry is lost in the event the application crashes.

Example Use Case

Applications can use this exporter to:

• Emit logs to the user_events subsystem.
• Enable local agents or monitoring tools to capture and analyze these events for debugging or performance monitoring.

For more details on the user_events subsystem, refer to the official documentation.

Getting Started

To use the user_events exporter, you can set up a logger provider as follows:

use opentelemetry_sdk::logs::LoggerProviderBuilder;
use opentelemetry_user_events_logs::UserEventsLoggerProviderBuilderExt;

let logger_provider = LoggerProviderBuilder::default()
    .with_user_events_exporter("myprovider")
    .build();

This will create a logger provider with the user_events exporter enabled.

Listening to Exported Events

Tools like perf or ftrace can be used to listen to the exported events.

• Using perf: For instance, the following command can be used to record events of severity Error and Warning:

  perf record -e user_events:myprovider_L2K1,user_events:myprovider_L3K1

Traits

UserEventsLoggerProviderBuilderExt

Extension trait for adding a user event exporter to the logger provider builder.