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//! - [`contract`] — Stable Phase 219 metric, event, and span names.
72//! - [`event`] — [`FabricEvent`] enum, [`EventRingBuffer`], and [`EventSink`] trait.
73//! - [`trace`] — [`TraceContext`], [`TraceId`], [`SpanId`] — W3C traceparent types (`no_std`).
74//! - [`span`] — [`ResourceSpan`] with lease attribution (`no_std`).
75//! - [`sampling`] — Sampling strategies (AlwaysOn, AlwaysOff, HeadBased, RateBased).
76//! - [`export`] — [`SpanExporter`] trait and [`NullExporter`] for tests.
77//! - [`propagation`] — Trace context injection/extraction for RPC and MQ headers.
78//! - [`context`] — `ResourceContext` thread-local tracking (requires `std`).
79//! - `json_log` — One-line JSON event serializer (requires `json-log` feature).
80//! - `prometheus` — Prometheus text exposition format exporter (requires `prometheus` feature).
81//! - `tracing_sink` — `tracing` crate integration (requires `tracing` feature).
82//! - `dashboard` — Live web dashboard (requires `dashboard` feature).
83//! - `otlp` — OTLP/HTTP JSON exporter (requires `otlp` feature).
84//! - `macro_support` — Runtime support for the `#[grafos_instrument]` proc macro.
85
86#![cfg_attr(not(feature = "std"), no_std)]
87
88extern crate alloc;
89
90pub mod cache_metrics;
91pub mod contract;
92pub mod dataplane;
93pub mod event;
94pub mod export;
95pub mod metrics;
96pub mod propagation;
97pub mod sampling;
98pub mod span;
99pub mod trace;
100
101#[cfg(feature = "std")]
102pub mod context;
103
104#[cfg(feature = "std")]
105pub mod macro_support;
106
107// Re-export macro_support as a hidden module for proc macro expansion
108#[cfg(feature = "std")]
109#[doc(hidden)]
110pub use macro_support as _macro_support;
111
112#[cfg(feature = "json-log")]
113pub mod json_log;
114
115#[cfg(feature = "prometheus")]
116pub mod prometheus;
117
118#[cfg(feature = "prometheus")]
119pub mod serve;
120
121#[cfg(feature = "tracing")]
122pub mod tracing_sink;
123
124#[cfg(feature = "dashboard")]
125pub mod dashboard;
126
127#[cfg(feature = "otlp")]
128pub mod otlp;
129
130#[cfg(feature = "file-socket")]
131pub mod file_socket_sink;
132
133pub use cache_metrics::CacheMetrics;
134pub use contract::{
135    is_forbidden_default_metric_label, FORBIDDEN_DEFAULT_METRIC_LABELS, PHASE_219_EVENT_NAMES,
136    PHASE_219_METRIC_FAMILIES, PHASE_219_SPAN_NAMES, STABLE_METRIC_FAMILIES,
137};
138pub use dataplane::{
139    build_dataplane_span, build_dataplane_span_from_traceparent, dataplane_operation_label,
140    dataplane_span_kind_for_op_type, emit_dataplane_span, emit_dataplane_span_from_traceparent,
141    DataplaneSpanKind,
142};
143pub use event::{
144    emit_event, set_global_sink, EventRingBuffer, EventSink, FabricEvent, NullSink, OpType,
145    ResourceType, RewritePhase,
146};
147// Re-export the policy vocabulary types that appear as fields on
148// FabricEvent variants. Consumers of grafos-observe should be able to
149// construct events without needing a direct grafos-core import — both
150// conceptually (events are observe's surface) and ergonomically (saves
151// every dependent crate from adding the type-home crate to its
152// manifest).
153pub use export::{emit_span, NullExporter, SpanExporter};
154#[cfg(feature = "std")]
155pub use export::{flush_global_span_exporter, set_global_span_exporter};
156pub use grafos_core::PreemptionReason;
157pub use metrics::{FabricMetrics, MetricCounter, MetricGauge, MetricHistogram};
158pub use span::ResourceSpan;
159pub use trace::{SpanId, TraceContext, TraceId};
160
161#[cfg(feature = "std")]
162pub use event::StdoutSink;
163
164#[cfg(feature = "json-log")]
165pub use json_log::{event_layer, JsonEventSink};
166
167#[cfg(feature = "prometheus")]
168pub use prometheus::{LabeledMetrics, MetricLabels, PrometheusExporter};
169
170#[cfg(feature = "tracing")]
171pub use tracing_sink::TracingEventSink;
172
173#[cfg(feature = "file-socket")]
174pub use file_socket_sink::FileAndSocketSink;
175
176#[cfg(feature = "macros")]
177pub use grafos_observe_macros::grafos_instrument;
grafos_observe/lib.rs

grafos_observe/
lib.rs
