Crate telemetry

veecle-telemetry

A telemetry library for collecting and exporting observability data including traces, logs, and metrics.

This crate provides telemetry collection capabilities with support for both std and no_std environments, including FreeRTOS targets.

Features

• Tracing: Distributed tracing with spans, events, and context propagation
• Logging: Structured logging with multiple severity levels
• Zero-cost abstractions: When telemetry is disabled, operations compile to no-ops
• Cross-platform: Works on std, no_std, and FreeRTOS environments
• Exporters: Multiple export formats including JSON console output

Feature Flags

• enable - Enable collecting and exporting telemetry data, should only be set in binary crates
• std - Enable standard library support
• alloc - Enable allocator support for dynamic data structures
• freertos - Enable FreeRTOS support
• system_time - Enable system time synchronization

Basic Usage

First, set up an exporter in your application:

use veecle_telemetry::collector::{ConsoleJsonExporter, set_exporter};
use veecle_telemetry::protocol::ExecutionId;

let execution_id = ExecutionId::random(&mut rand::rng());
set_exporter(execution_id, &ConsoleJsonExporter)?;

Then use the telemetry macros and functions:

use veecle_telemetry::{Span, info, instrument, span};

// Structured logging
info!("Server started", port = 8080, version = "1.0.0");

// Manual span creation
let span = span!("process_request", user_id = 123);
let _guard = span.entered();

// Automatic instrumentation
#[instrument]
fn process_data(input: &str) -> String {
    // Function body is automatically wrapped in a span
    format!("processed: {}", input)
}

Span Management

Spans represent units of work and can be nested to show relationships:

use veecle_telemetry::{CurrentSpan, span};

let parent_span = span!("parent_operation");
let _guard = parent_span.entered();

// Child spans automatically inherit the parent context
let child_span = span!("child_operation", step = 1);
let _child_guard = child_span.entered();

// Add events to the current span
CurrentSpan::add_event("milestone_reached", &[]);

Conditional Compilation

When the enable feature is disabled, all telemetry operations compile to no-ops, ensuring zero runtime overhead in production builds where telemetry is not needed.

Modules

collector

Telemetry data collection and export infrastructure.

future

Future instrumentation utilities for tracing async operations.

id

Unique identifiers for traces and spans.

log

Structured logging functionality with multiple severity levels.

macros

Macros for structured logging and telemetry.

protocol

Telemetry protocol types and message definitions.

to_static

Utilities for converting borrowed data to owned data.

types

Type definitions that adapt to different platform capabilities.

value

Key-value attribute types for telemetry data.

Macros

attribute

Constructs a single attribute KeyValue pair.

attributes

Constructs a slice of KeyValue attributes.

debug

Logs a debug-level message.

error

Logs an error-level message.

event

Adds an event to the current span.

fatal

Logs a fatal-level message.

info

Logs an info-level message.

log

Logs a message with the specified severity level.

root_span

Creates a new root span.

span

Creates a new span.

trace

Logs a trace-level message.

warn

Logs a warning-level message.

Structs

CurrentSpan

Utilities for working with the currently active span.

KeyValue

A key-value attribute pair used in telemetry data.

Span

A distributed tracing span representing a unit of work.

SpanContext

A struct representing the context of a span, including its TraceId and SpanId.

SpanGuard

Exits and drops the span when this is dropped.

SpanGuardRef

Exits the span when dropped.

SpanId

An identifier for a span within a trace.

TraceId

An identifier for a trace, which groups a set of related spans together.

Enums

Value

A value that can be stored in a telemetry attribute.

Attribute Macros

instrument

An attribute macro designed to eliminate boilerplate code.