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::ProcessId;
31//!
32//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
33//! let process_id = ProcessId::random(&mut rand::rng());
34//! set_exporter(process_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#![cfg_attr(coverage_nightly, feature(coverage_attribute))]
84
85#[cfg(feature = "std")]
86extern crate std;
87
88#[cfg(feature = "alloc")]
89extern crate alloc;
90
91#[cfg(all(feature = "enable", not(any(feature = "std", feature = "freertos"))))]
92compile_error! {
93    "veecle_telemetry requires that either the `std` (default) or the `freertos` feature is enabled to work"
94}
95
96pub mod collector;
97pub mod future;
98pub mod id;
99pub mod log;
100#[doc(hidden)]
101pub mod macro_helpers;
102pub mod macros;
103pub mod protocol;
104mod span;
105#[cfg(feature = "alloc")]
106#[doc(hidden)]
107pub mod test_helpers;
108#[cfg(feature = "enable")]
109mod time;
110pub mod to_static;
111pub mod types;
112pub mod value;
113
114pub use id::{ProcessId, SpanContext, SpanId};
115pub use span::{CurrentSpan, Span, SpanGuard, SpanGuardRef};
116pub use value::{KeyValue, Value};
117pub use veecle_telemetry_macros::instrument;
veecle_telemetry/lib.rs

veecle_telemetry/
lib.rs
