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::SdkLoggerProvider;
use opentelemetry_sdk::Resource;
use opentelemetry_user_events_logs::Processor;

let user_event_processor = Processor::builder("myprovider")
  .build()
  .unwrap_or_else(|err| {
    eprintln!("Failed to create user_events processor. Error: {err}");
    panic!("exiting due to error during initialization");
             });

let provider = SdkLoggerProvider::builder()
    .with_resource(
        Resource::builder_empty()
            .with_service_name("example")
            .build(),
    )
    .with_log_processor(user_event_processor)
    .build();

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

Resource Attribute Handling

Important: By default, resource attributes are NOT exported with log records. The user_events exporter only automatically exports these specific resource attributes:

• service.name → Exported as cloud.roleName in PartA of Common Schema
• service.instance.id → Exported as cloud.roleInstance in PartA of Common Schema

All other resource attributes are ignored unless explicitly specified.

Opting in to Additional Resource Attributes

To export additional resource attributes, use the with_resource_attributes() method:

use opentelemetry_sdk::logs::SdkLoggerProvider;
use opentelemetry_sdk::Resource;
use opentelemetry_user_events_logs::Processor;
use opentelemetry::KeyValue;

let user_event_processor = Processor::builder("myprovider")
    // Only export specific resource attributes
    .with_resource_attributes(["custom_attribute1", "custom_attribute2"])
    .build()
    .unwrap();

let provider = SdkLoggerProvider::builder()
    .with_resource(
        Resource::builder_empty()
            .with_service_name("example")
            .with_attribute(KeyValue::new("custom_attribute1", "value1"))
            .with_attribute(KeyValue::new("custom_attribute2", "value2"))
            .with_attribute(KeyValue::new("custom_attribute2", "value3"))  // This won't be exported
            .build(),
    )
    .with_log_processor(user_event_processor)
    .build();

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

Structs

Processor

Processes and exports logs to user_events.

ProcessorBuilder

Builder for configuring and constructing a user_events Processor