Crate grafos_observe 

grafos-observe — Fabric observability for grafOS.

Provides metrics, events, distributed tracing, and structured logging for lease lifecycles, data-plane operations, and graph rewrites. The core types (MetricCounter, MetricGauge, MetricHistogram, EventRingBuffer, TraceContext, ResourceSpan) are no_std compatible.

Quick start

use grafos_observe::{FabricMetrics, EventRingBuffer, FabricEvent, ResourceType};

// Record metrics via the global singleton
let m = FabricMetrics::global();
m.leases_total.inc();
m.leases_active.inc();
m.ops_total.add(3);
m.op_latency.observe(250); // 250 microseconds

// Capture events in a ring buffer
let mut ring = EventRingBuffer::with_default_capacity();
ring.push(FabricEvent::LeaseAcquired {
    resource_type: ResourceType::Mem,
    lease_id: 1,
    node: "10.10.0.11".into(),
    bytes: 4096,
    trace_id: None,
});
assert_eq!(ring.len(), 1);

Distributed tracing

use grafos_observe::trace::{TraceContext, TraceId, SpanId};
use grafos_observe::span::{ResourceSpan, SpanStatus};
use grafos_observe::export::{NullExporter, SpanExporter};

// Create a root trace context
let random: [u8; 24] = [0x42; 24]; // use real entropy in production
let ctx = TraceContext::new_root(&random);
assert!(ctx.trace_id.is_valid());

// Create a child span
let child_ctx = ctx.child(&[0xAA; 8]);
let mut span = ResourceSpan::new("my_operation", child_ctx);
span.bytes_read = 4096;
span.status = SpanStatus::Ok;

// Export to a collector (NullExporter for tests)
let exporter = NullExporter::new();
exporter.export(&[span]);
assert_eq!(exporter.len(), 1);

Feature flags

Feature	Default	Effect
std	Yes	Enables StdoutSink, ResourceContext, thread-local trace context
json-log	No	Enables JsonEventSink for structured JSON logging
prometheus	No	Enables PrometheusExporter text format generation + serve_metrics
tracing	No	Enables TracingEventSink for tracing crate integration
dashboard	No	Enables live dashboard HTTP server (Dashboard::serve)
macros	No	Re-exports #[grafos_instrument] proc macro
otlp	No	Enables OTLP/HTTP JSON exporter for OTel collectors

Modules

• metrics — Counters, gauges, histograms, and the FabricMetrics singleton.
• event — FabricEvent enum, EventRingBuffer, and EventSink trait.
• trace — TraceContext, TraceId, SpanId — W3C traceparent types (no_std).
• span — ResourceSpan with lease attribution (no_std).
• sampling — Sampling strategies (AlwaysOn, AlwaysOff, HeadBased, RateBased).
• export — SpanExporter trait and NullExporter for tests.
• propagation — Trace context injection/extraction for RPC and MQ headers.
• context — ResourceContext thread-local tracking (requires std).
• json_log — One-line JSON event serializer (requires json-log feature).
• prometheus — Prometheus text exposition format exporter (requires prometheus feature).
• tracing_sink — tracing crate integration (requires tracing feature).
• dashboard — Live web dashboard (requires dashboard feature).
• otlp — OTLP/HTTP JSON exporter (requires otlp feature).
• macro_support — Runtime support for the #[grafos_instrument] proc macro.

Re-exports

pub use cache_metrics::CacheMetrics;

pub use event::emit_event;

pub use event::set_global_sink;

pub use event::EventRingBuffer;

pub use event::EventSink;

pub use event::FabricEvent;

pub use event::NullSink;

pub use event::OpType;

pub use event::ResourceType;

pub use event::RewritePhase;

pub use export::NullExporter;

pub use export::SpanExporter;

pub use metrics::FabricMetrics;

pub use metrics::MetricCounter;

pub use metrics::MetricGauge;

pub use metrics::MetricHistogram;

pub use span::ResourceSpan;

pub use trace::SpanId;

pub use trace::TraceContext;

pub use trace::TraceId;

pub use event::StdoutSink;

Modules

cache_metrics

Cache-specific observability metrics for LLM inference KV caches.

context

Resource context tracking for fabric observability.

event

Event system for fabric observability.

export

Span exporters for grafOS distributed tracing.

macro_support

Support module for the #[grafos_instrument] proc macro.

metrics

Core metrics types for fabric observability.

propagation

Trace context propagation helpers for grafos-rpc and grafos-mq.

sampling

Sampling strategies for distributed tracing.

span

Resource-attributed spans for grafOS distributed tracing.

trace

Distributed trace context types for W3C traceparent propagation.