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 (implies `alloc`)
20//! - `alloc` - Enable allocator support for dynamic data structures
21//!
22//! ## Basic Usage
23//!
24//! First, set up an exporter in your application:
25//!
26//! ```rust
27//! use veecle_osal_std::{time::Time, thread::Thread};
28//! use veecle_telemetry::collector::ConsoleJsonExporter;
29//!
30//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
31//! veecle_telemetry::collector::build()
32//!     .random_process_id()
33//!     .exporter(&ConsoleJsonExporter::DEFAULT)
34//!     .time::<Time>()
35//!     .thread::<Thread>()
36//!     .set_global()?;
37//! # Ok(())
38//! # }
39//! ```
40//!
41//! Then use the telemetry macros and functions:
42//!
43//! ```rust
44//! use veecle_telemetry::{Span, info, instrument, span};
45//!
46//! // Structured logging
47//! info!("Server started", port = 8080, version = "1.0.0");
48//!
49//! // Manual span creation
50//! let span = span!("process_request", user_id = 123);
51//! let _guard = span.entered();
52//!
53//! // Automatic instrumentation
54//! #[instrument]
55//! fn process_data(input: &str) -> String {
56//!     // Function body is automatically wrapped in a span
57//!     format!("processed: {}", input)
58//! }
59//! ```
60//!
61//! ## Span Management
62//!
63//! Spans represent units of work and can be nested to show relationships:
64//!
65//! ```rust
66//! use veecle_telemetry::{CurrentSpan, span};
67//!
68//! let parent_span = span!("parent_operation");
69//! let _guard = parent_span.entered();
70//!
71//! // Child spans automatically inherit the parent context
72//! let child_span = span!("child_operation", step = 1);
73//! let _child_guard = child_span.entered();
74//!
75//! // Add events to the current span
76//! CurrentSpan::add_event("milestone_reached", &[]);
77//! ```
78//!
79//! ## Conditional Compilation
80//!
81//! When the `enable` feature is disabled, all telemetry operations compile to no-ops,
82//! ensuring zero runtime overhead in production builds where telemetry is not needed.
83
84#![no_std]
85#![cfg_attr(coverage_nightly, feature(coverage_attribute))]
86
87#[cfg(feature = "std")]
88extern crate std;
89
90#[cfg(feature = "alloc")]
91extern crate alloc;
92
93pub mod collector;
94pub mod future;
95pub mod id;
96#[doc(hidden)]
97pub mod log;
98#[doc(hidden)]
99pub mod macro_helpers;
100mod macros;
101pub mod protocol;
102mod span;
103#[cfg(feature = "alloc")]
104#[doc(hidden)]
105pub mod test_helpers;
106
107pub use id::{ProcessId, SpanContext, SpanId};
108pub use span::{CurrentSpan, Span, SpanGuard, SpanGuardRef};
109pub use veecle_telemetry_macros::instrument;
veecle_telemetry/lib.rs

veecle_telemetry/
lib.rs
