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 (implies alloc)
• alloc - Enable allocator support for dynamic data structures

Basic Usage

First, set up an exporter in your application:

use veecle_osal_std::{time::Time, thread::Thread};
use veecle_telemetry::collector::ConsoleJsonExporter;

veecle_telemetry::collector::build()
    .random_process_id()
    .exporter(&ConsoleJsonExporter::DEFAULT)
    .time::<Time>()
    .thread::<Thread>()
    .set_global()?;

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.

flatten

Traits for emitting telemetry key-value pairs from data types.

future

Future instrumentation utilities for tracing async operations.

id

Unique identifiers for traces and spans.

protocol

Telemetry protocol types and message definitions.

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.

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.

ProcessId

A globally-unique id identifying a process.

Span

A distributed tracing span representing a unit of work.

SpanContext

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

SpanGuard

Exits and drops the span when this is dropped.

SpanGuardRef

Exits the span when dropped.

SpanId

A process-unique id for a span.

Traits

Flatten

Allows a type to emit its telemetry representation as key-value pairs into a MetricBuffer.

MetricBuffer

Receiver for key-value telemetry entries produced by Flatten::flatten.

Attribute Macros

instrument

An attribute macro designed to eliminate boilerplate code.

Derive Macros

FlattenNoop

Derives an empty Flatten implementation for a struct or enum.