grafos_observe/
lib.rs

1//! grafos-observe — Fabric observability for grafOS.
2//!
3//! Provides metrics, events, distributed tracing, and structured logging for
4//! lease lifecycles, data-plane operations, and graph rewrites. The core types
5//! ([`MetricCounter`], [`MetricGauge`], [`MetricHistogram`], [`EventRingBuffer`],
6//! [`TraceContext`], [`ResourceSpan`]) are `no_std` compatible.
7//!
8//! # Quick start
9//!
10//! ```rust
11//! use grafos_observe::{FabricMetrics, EventRingBuffer, FabricEvent, ResourceType};
12//!
13//! // Record metrics via the global singleton
14//! let m = FabricMetrics::global();
15//! m.leases_total.inc();
16//! m.leases_active.inc();
17//! m.ops_total.add(3);
18//! m.op_latency.observe(250); // 250 microseconds
19//!
20//! // Capture events in a ring buffer
21//! let mut ring = EventRingBuffer::with_default_capacity();
22//! ring.push(FabricEvent::LeaseAcquired {
23//!     resource_type: ResourceType::Mem,
24//!     lease_id: 1,
25//!     node: "10.10.0.11".into(),
26//!     bytes: 4096,
27//!     trace_id: None,
28//! });
29//! assert_eq!(ring.len(), 1);
30//! ```
31//!
32//! # Distributed tracing
33//!
34//! ```rust
35//! use grafos_observe::trace::{TraceContext, TraceId, SpanId};
36//! use grafos_observe::span::{ResourceSpan, SpanStatus};
37//! use grafos_observe::export::{NullExporter, SpanExporter};
38//!
39//! // Create a root trace context
40//! let random: [u8; 24] = [0x42; 24]; // use real entropy in production
41//! let ctx = TraceContext::new_root(&random);
42//! assert!(ctx.trace_id.is_valid());
43//!
44//! // Create a child span
45//! let child_ctx = ctx.child(&[0xAA; 8]);
46//! let mut span = ResourceSpan::new("my_operation", child_ctx);
47//! span.bytes_read = 4096;
48//! span.status = SpanStatus::Ok;
49//!
50//! // Export to a collector (NullExporter for tests)
51//! let exporter = NullExporter::new();
52//! exporter.export(&[span]);
53//! assert_eq!(exporter.len(), 1);
54//! ```
55//!
56//! # Feature flags
57//!
58//! | Feature | Default | Effect |
59//! |---------|---------|--------|
60//! | `std` | Yes | Enables [`StdoutSink`], `ResourceContext`, thread-local trace context |
61//! | `json-log` | No | Enables `JsonEventSink` for structured JSON logging |
62//! | `prometheus` | No | Enables `PrometheusExporter` text format generation + `serve_metrics` |
63//! | `tracing` | No | Enables `TracingEventSink` for `tracing` crate integration |
64//! | `dashboard` | No | Enables live dashboard HTTP server (`Dashboard::serve`) |
65//! | `macros` | No | Re-exports `#[grafos_instrument]` proc macro |
66//! | `otlp` | No | Enables OTLP/HTTP JSON exporter for OTel collectors |
67//!
68//! # Modules
69//!
70//! - [`metrics`] — Counters, gauges, histograms, and the [`FabricMetrics`] singleton.
71//! - [`event`] — [`FabricEvent`] enum, [`EventRingBuffer`], and [`EventSink`] trait.
72//! - [`trace`] — [`TraceContext`], [`TraceId`], [`SpanId`] — W3C traceparent types (`no_std`).
73//! - [`span`] — [`ResourceSpan`] with lease attribution (`no_std`).
74//! - [`sampling`] — Sampling strategies (AlwaysOn, AlwaysOff, HeadBased, RateBased).
75//! - [`export`] — [`SpanExporter`] trait and [`NullExporter`] for tests.
76//! - [`propagation`] — Trace context injection/extraction for RPC and MQ headers.
77//! - [`context`] — `ResourceContext` thread-local tracking (requires `std`).
78//! - `json_log` — One-line JSON event serializer (requires `json-log` feature).
79//! - `prometheus` — Prometheus text exposition format exporter (requires `prometheus` feature).
80//! - `tracing_sink` — `tracing` crate integration (requires `tracing` feature).
81//! - `dashboard` — Live web dashboard (requires `dashboard` feature).
82//! - `otlp` — OTLP/HTTP JSON exporter (requires `otlp` feature).
83//! - `macro_support` — Runtime support for the `#[grafos_instrument]` proc macro.
84
85#![cfg_attr(not(feature = "std"), no_std)]
86
87extern crate alloc;
88
89pub mod cache_metrics;
90pub mod event;
91pub mod export;
92pub mod metrics;
93pub mod propagation;
94pub mod sampling;
95pub mod span;
96pub mod trace;
97
98#[cfg(feature = "std")]
99pub mod context;
100
101#[cfg(feature = "std")]
102pub mod macro_support;
103
104// Re-export macro_support as a hidden module for proc macro expansion
105#[cfg(feature = "std")]
106#[doc(hidden)]
107pub use macro_support as _macro_support;
108
109#[cfg(feature = "json-log")]
110pub mod json_log;
111
112#[cfg(feature = "prometheus")]
113pub mod prometheus;
114
115#[cfg(feature = "prometheus")]
116pub mod serve;
117
118#[cfg(feature = "tracing")]
119pub mod tracing_sink;
120
121#[cfg(feature = "dashboard")]
122pub mod dashboard;
123
124#[cfg(feature = "otlp")]
125pub mod otlp;
126
127#[cfg(feature = "file-socket")]
128pub mod file_socket_sink;
129
130pub use cache_metrics::CacheMetrics;
131pub use event::{
132    emit_event, set_global_sink, EventRingBuffer, EventSink, FabricEvent, NullSink, OpType,
133    ResourceType, RewritePhase,
134};
135pub use export::{NullExporter, SpanExporter};
136pub use metrics::{FabricMetrics, MetricCounter, MetricGauge, MetricHistogram};
137pub use span::ResourceSpan;
138pub use trace::{SpanId, TraceContext, TraceId};
139
140#[cfg(feature = "std")]
141pub use event::StdoutSink;
142
143#[cfg(feature = "json-log")]
144pub use json_log::{event_layer, JsonEventSink};
145
146#[cfg(feature = "prometheus")]
147pub use prometheus::{LabeledMetrics, MetricLabels, PrometheusExporter};
148
149#[cfg(feature = "tracing")]
150pub use tracing_sink::TracingEventSink;
151
152#[cfg(feature = "file-socket")]
153pub use file_socket_sink::FileAndSocketSink;
154
155#[cfg(feature = "macros")]
156pub use grafos_observe_macros::grafos_instrument;
grafos_observe/lib.rs

grafos_observe/
lib.rs
