veecle_telemetry/
lib.rs

1//! # `veecle-telemetry`
2//!
3//! A telemetry library for collecting and exporting observability data including traces, logs, and metrics.
4//!
5//! This crate provides telemetry collection capabilities with support for both `std` and `no_std`
6//! environments, including FreeRTOS targets.
7//!
8//! ## Features
9//!
10//! - **Tracing**: Distributed tracing with spans, events, and context propagation
11//! - **Logging**: Structured logging with multiple severity levels
12//! - **Zero-cost abstractions**: When telemetry is disabled, operations compile to no-ops
13//! - **Cross-platform**: Works on `std`, `no_std`, and FreeRTOS environments
14//! - **Exporters**: Multiple export formats including JSON console output
15//!
16//! ## Feature Flags
17//!
18//! - `enable` - Enable collecting and exporting telemetry data, should only be set in binary crates
19//! - `std` - Enable standard library support
20//! - `alloc` - Enable allocator support for dynamic data structures
21//! - `freertos` - Enable FreeRTOS support
22//! - `system_time` - Enable system time synchronization
23//!
24//! ## Basic Usage
25//!
26//! First, set up an exporter in your application:
27//!
28//! ```rust
29//! use veecle_telemetry::collector::{ConsoleJsonExporter, set_exporter};
30//! use veecle_telemetry::protocol::ExecutionId;
31//!
32//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
33//! let execution_id = ExecutionId::random(&mut rand::rng());
34//! set_exporter(execution_id, &ConsoleJsonExporter)?;
35//! # Ok(())
36//! # }
37//! ```
38//!
39//! Then use the telemetry macros and functions:
40//!
41//! ```rust
42//! use veecle_telemetry::{Span, info, instrument, span};
43//!
44//! // Structured logging
45//! info!("Server started", port = 8080, version = "1.0.0");
46//!
47//! // Manual span creation
48//! let span = span!("process_request", user_id = 123);
49//! let _guard = span.entered();
50//!
51//! // Automatic instrumentation
52//! #[instrument]
53//! fn process_data(input: &str) -> String {
54//!     // Function body is automatically wrapped in a span
55//!     format!("processed: {}", input)
56//! }
57//! ```
58//!
59//! ## Span Management
60//!
61//! Spans represent units of work and can be nested to show relationships:
62//!
63//! ```rust
64//! use veecle_telemetry::{CurrentSpan, span};
65//!
66//! let parent_span = span!("parent_operation");
67//! let _guard = parent_span.entered();
68//!
69//! // Child spans automatically inherit the parent context
70//! let child_span = span!("child_operation", step = 1);
71//! let _child_guard = child_span.entered();
72//!
73//! // Add events to the current span
74//! CurrentSpan::add_event("milestone_reached", &[]);
75//! ```
76//!
77//! ## Conditional Compilation
78//!
79//! When the `enable` feature is disabled, all telemetry operations compile to no-ops,
80//! ensuring zero runtime overhead in production builds where telemetry is not needed.
81
82#![no_std]
83
84#[cfg(feature = "std")]
85extern crate std;
86
87#[cfg(feature = "alloc")]
88extern crate alloc;
89
90#[cfg(all(feature = "enable", not(any(feature = "std", feature = "freertos"))))]
91compile_error! {
92    "veecle_telemetry requires that either the `std` (default) or the `freertos` feature is enabled to work"
93}
94
95pub mod collector;
96pub mod future;
97pub mod id;
98pub mod log;
99#[doc(hidden)]
100pub mod macro_helpers;
101pub mod macros;
102pub mod protocol;
103mod span;
104#[cfg(feature = "alloc")]
105#[doc(hidden)]
106pub mod test_helpers;
107#[cfg(feature = "enable")]
108mod time;
109pub mod to_static;
110pub mod types;
111pub mod value;
112
113pub use id::{SpanContext, SpanId, TraceId};
114pub use span::{CurrentSpan, Span, SpanGuard, SpanGuardRef};
115pub use value::{KeyValue, Value};
116pub use veecle_telemetry_macros::instrument;
veecle_telemetry/lib.rs

veecle_telemetry/
lib.rs
