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.
• contract — Stable Phase 219 metric, event, and span names.
• 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 contract::is_forbidden_default_metric_label;

pub use contract::FORBIDDEN_DEFAULT_METRIC_LABELS;

pub use contract::PHASE_219_EVENT_NAMES;

pub use contract::PHASE_219_METRIC_FAMILIES;

pub use contract::PHASE_219_SPAN_NAMES;

pub use contract::STABLE_METRIC_FAMILIES;

pub use dataplane::build_dataplane_span;

pub use dataplane::build_dataplane_span_from_traceparent;

pub use dataplane::dataplane_operation_label;

pub use dataplane::dataplane_span_kind_for_op_type;

pub use dataplane::emit_dataplane_span;

pub use dataplane::emit_dataplane_span_from_traceparent;

pub use dataplane::DataplaneSpanKind;

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::emit_span;

pub use export::NullExporter;

pub use export::SpanExporter;

pub use export::flush_global_span_exporter;

pub use export::set_global_span_exporter;

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;

pub use json_log::event_layer;

pub use json_log::JsonEventSink;

pub use file_socket_sink::FileAndSocketSink;

Modules

cache_metrics

Cache-specific observability metrics for LLM inference KV caches.

context

Resource context tracking for fabric observability.

contract

Stable Phase 219 observability contract names.

dataplane

Phase 219 data-plane span vocabulary.

event

Event system for fabric observability.

export

Span exporters for grafOS distributed tracing.

file_socket_sink

File + Unix socket event sink.

json_log

JSON structured logging sink.

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.

Enums

PreemptionReason

Typed reasons for which an admission was rejected or an existing lease was preempted. Phase 218 enumerates these up front so the admission, audit, and DRA layers all agree on the vocabulary.