observability_core

Observability Core

Core traits and foundational components for structured logging and observability. This crate provides zero-cost abstractions for telemetry, metrics, and structured logging that can be conditionally compiled based on feature flags.

Features

observability: Enables all observability features
otel-2025: OpenTelemetry 2025 integration
structured-logging: JSON structured logging support
prometheus-federation: Prometheus metrics federation
auto-instrumentation: Automatic instrumentation capabilities

Constants

`VERSION`

const VERSION: &str = ;

Version information for the observability core

`DEFAULT_BATCH_SIZE`

const DEFAULT_BATCH_SIZE: usize = ;

Default batch size for telemetry data

`DEFAULT_FLUSH_INTERVAL_SECS`

const DEFAULT_FLUSH_INTERVAL_SECS: u64 = ;

Default flush interval in seconds

Type Aliases

`ObservabilityResult`

type ObservabilityResult = Result<T, ObservabilityError>;

Result type for observability operations

Traits

`MetricsCollector`

Trait for collecting and managing metrics

Required / Provided Methods

fn register_counter(&mut self, name: &str, description: &str, labels: &[&str]) -> ObservabilityResult<()>

fn register_histogram(&mut self, name: &str, description: &str, buckets: &[f64], labels: &[&str]) -> ObservabilityResult<()>

fn register_gauge(&mut self, name: &str, description: &str, labels: &[&str]) -> ObservabilityResult<()>

fn record_counter(&self, name: &str, value: f64, labels: &HashMap<String, String>) -> ObservabilityResult<()>

Record a counter increment

fn record_histogram(&self, name: &str, value: f64, labels: &HashMap<String, String>) -> ObservabilityResult<()>

Record a histogram observation

fn set_gauge(&self, name: &str, value: f64, labels: &HashMap<String, String>) -> ObservabilityResult<()>

Set a gauge value

fn get_metrics(&self) -> HashMap<String, f64>

Get current metric values (for testing/debugging)

fn clear(&mut self)

Clear all metrics

`ObservabilityPlugin`

Core observability plugin trait

Required / Provided Methods

fn start_span(&self, name: &str, attributes: &[(&str, &str)]) -> SpanGuard

Start a new span and return a guard

fn end_span(&self, span_id: &str)

End a span by ID

fn add_span_attribute(&self, span_id: &str, key: &str, value: &str)

Add an attribute to an existing span

fn set_span_status(&self, span_id: &str, status: SpanStatus)

Set the status of a span

fn record_metric(&self, name: &str, value: f64, labels: &[(&str, &str)])

Record a metric with labels

fn increment_counter(&self, name: &str, labels: &[(&str, &str)])

Increment a counter metric

fn record_histogram(&self, name: &str, value: f64, labels: &[(&str, &str)])

Record a histogram value

fn log_structured(&self, level: LogLevel, message: &str, fields: &JsonValue)

Log a structured message with fields

fn log(&self, level: LogLevel, message: &str)

Log a simple message

fn write_log(&self, message: &str)

Write log output (implementation-specific)

fn flush(&self) -> ObservabilityResult<()>

Flush any pending telemetry data

fn is_enabled(&self) -> bool

Check if the plugin is enabled

fn plugin_type(&self) -> &''static str

Get the plugin name/type

`StructuredLogger`

Trait for structured logging

Required / Provided Methods

fn log_with_trace(&self, level: LogLevel, message: &str, fields: &JsonValue, trace_id: Option<&str>, span_id: Option<&str>)

Log with trace context correlation

fn log_performance(&self, operation: &str, duration: Duration, success: bool, additional_fields: &JsonValue)

Log performance metrics

fn log_error(&self, error: &dyn Error, context: &JsonValue)

Log errors with context

fn set_level(&mut self, level: LogLevel)

Set the minimum log level

fn is_level_enabled(&self, level: LogLevel) -> bool

Check if a level is enabled

`BatchingPort`

Port for batching log entries

This allows different batching strategies:

TimeBasedBatcher (flush every N seconds)
SizeBasedBatcher (flush when buffer reaches N entries)
HybridBatcher (combination of time and size)

Required / Provided Methods

fn add_to_batch(&self, entry: LogEntry) -> ObservabilityResult<()>

Add an entry to the batch

fn flush_batch(&self) -> ObservabilityResult<()>

Force flush the current batch

fn batch_size(&self) -> usize

Get current batch size

`ContextPort`

Port for accessing context information

This allows the logging system to enrich entries with context:

Agent ID, request ID, trace ID
User-defined context fields
Thread/task local context

Required / Provided Methods

fn get_context(&self) -> HashMap<String, serde_json::Value>

Get current context fields

fn add_context(&self, key: String, value: serde_json::Value)

Add a context field

fn remove_context(&self, key: &str)

Remove a context field

fn clear_context(&self)

Clear all context

`FormatterPort`

Port for formatting log entries

Different formatters can be plugged in:

JsonFormatter (structured JSON output)
PlainTextFormatter (human-readable text)
CompactFormatter (single-line JSON)

Required / Provided Methods

fn format(&self, entry: &LogEntry) -> ObservabilityResult<String>

Format a log entry into a string

`MetricsPort`

Port for metrics collection (basic interface for correlation).

Required / Provided Methods

fn emit_counter_simple(&self, name: &str, value: f64) -> ObservabilityResult<()>

Emit a simple counter metric

fn emit_histogram_simple(&self, name: &str, value: f64) -> ObservabilityResult<()>

Emit a simple histogram/timing metric

fn emit_gauge_simple(&self, name: &str, value: f64) -> ObservabilityResult<()>

Emit a simple gauge metric

fn is_enabled(&self) -> bool

Check if metrics collection is enabled

fn emit_metrics_batch(&self, entries: &[MetricsEntry]) -> ObservabilityResult<()>

Batch emit multiple metrics (optional, has default implementation)

`StandardLoggingPort`

Port for standard logging integration

This port allows us to hook into standard Rust logging infrastructure:

log::Log implementation
tracing::Subscriber implementation

Required / Provided Methods

fn initialize(&self) -> ObservabilityResult<()>

Initialize the logging system (called once during agent startup)

fn process_standard_log(&self, entry: LogEntry) -> ObservabilityResult<()>

Process a log entry from standard logging macros

fn enabled(&self, level: &LogLevel) -> bool

Check if logging is enabled for this level

`TransportPort`

Port for transporting log entries to external systems

This is the interface that different adapters implement:

WasmStdoutAdapter (writes to WASM stdout)
HttpTransportAdapter (sends via HTTP)
BatchingTransportAdapter (batches entries)

Required / Provided Methods

fn transport(&self, entry: &LogEntry) -> ObservabilityResult<()>

Transport a single log entry

fn transport_batch(&self, entries: &[LogEntry]) -> ObservabilityResult<()>

Transport multiple log entries (for batching)

Structs

`BatchingConfig`

Configuration for batching behavior

Fields

Field	Type	Description
`max_batch_size`	`usize`	Maximum number of items in a batch
`flush_interval`	`web_time::Duration`	Maximum time to wait before flushing a batch
`max_memory_bytes`	`usize`	Maximum memory usage in bytes (approximate)
`drop_on_overflow`	`bool`	Whether to drop items when buffer is full
`min_batch_size`	`usize`	Minimum batch size to trigger early flush

`BatchingManager`

Batching manager for telemetry data

Methods

`new`

fn new(config: BatchingConfig) -> Self

`set_flush_callback`

fn set_flush_callback<F>(&mut self, callback: F)
where
    F: Fn + Send + Sync + ?

Set the flush callback function

`add_span`

fn add_span(&self, span: SpanData) -> ObservabilityResult<()>

Add a span to the batch

`add_metric`

fn add_metric(&self, metric: MetricData) -> ObservabilityResult<()>

Add a metric to the batch

`add_log`

fn add_log(&self, log: LogData) -> ObservabilityResult<()>

Add a log to the batch

`flush_all`

fn flush_all(&self) -> ObservabilityResult<()>

Force flush all buffers

`get_stats`

fn get_stats(&self) -> BatchingStats

Get buffer statistics

`ContextFuture`

Future wrapper that restores trace context across async poll boundaries.

`HeaderExtractor`

Header extractor for W3C trace context propagation

Methods

`extract`

fn extract(&self) -> ObservabilityResult<Option<W3CTraceContext>>

`HeaderInjector`

Header injector for W3C trace context propagation

Methods

`inject`

fn inject(&mut self, context: &W3CTraceContext)

`TraceContext`

Simplified trace context for internal use

Fields

Field	Type	Description
`trace_id`	`String`
`span_id`	`String`
`parent_span_id`	`Option<String>`
`sampled`	`bool`

Methods

`new_root`

fn new_root() -> Self

Create a new root trace context

`new_child`

fn new_child(&self) -> Self

Create a child span

`to_w3c`

fn to_w3c(&self) -> W3CTraceContext

Convert to W3C trace context

`from_w3c`

fn from_w3c(w3c: &W3CTraceContext) -> Self

Create from W3C trace context

`W3CTraceContext`

W3C Trace Context implementation for distributed tracing

Fields

Field	Type	Description
`trace_id`	`String`	W3C trace ID (32 hex characters)
`parent_id`	`String`	W3C span ID (16 hex characters)
`trace_flags`	`String`	Trace flags (2 hex characters)
`trace_state`	`Option<String>`	Additional trace state

Methods

`new_root`

fn new_root() -> Self

Create a new root trace context

`new_child`

fn new_child(&self) -> Self

Create a child span context

`from_traceparent`

fn from_traceparent(header: &str) -> ObservabilityResult<Self>

Create from W3C traceparent header

`from_headers`

fn from_headers(headers: &HashMap<String, String>) -> ObservabilityResult<Option<Self>>

Create from W3C headers

`to_traceparent`

fn to_traceparent(&self) -> String

Generate W3C traceparent header value

`to_headers`

fn to_headers(&self) -> HashMap<String, String>

Generate W3C headers for propagation

`is_sampled`

fn is_sampled(&self) -> bool

Check if the trace is sampled

`set_sampled`

fn set_sampled(&mut self, sampled: bool)

Set sampling flag

`add_trace_state`

fn add_trace_state(&mut self, key: &str, value: &str)

Add or update trace state

`get_trace_state`

fn get_trace_state(&self, key: &str) -> Option<String>

Get value from trace state

`NoOpObservabilityPlugin`

No-op observability plugin that does nothing

This implementation provides zero runtime cost when observability is disabled. All methods are inlined and compile to nothing in release builds.

Methods

`new`

fn new() -> Self

Create a new no-op plugin

`shared`

fn shared() -> Arc<Self>

Create an Arc’d no-op plugin for sharing

`SpanGuard`

Span guard that automatically ends spans when dropped

Methods

`new`

fn new(span_id: String, plugin: Arc<dyn ObservabilityPlugin>) -> Self

`no_op`

fn no_op() -> Self

`span_id`

fn span_id(&self) -> &str

`duration`

fn duration(&self) -> Duration

`add_attribute`

fn add_attribute(&self, key: &str, value: &str)

`set_status`

fn set_status(&self, status: SpanStatus)

`CompactJsonFormatter`

Compact JSON formatter (single line)

`JsonFormatter`

JSON formatter for structured logging output

`LogDirectives`

Parsed RUST_LOG-style directives for per-target log filtering.

Supports: "info", "info,agent_sdk=debug,a2a_protocol_core=trace". Unknown tokens are silently ignored.

Methods

`from_level`

fn from_level(level: LogLevel) -> Self

`parse`

fn parse(s: &str) -> Self

Parse a RUST_LOG-style directive string.

Examples: "info", "info,agent_sdk=debug", "warn,a2a_protocol_core=trace,llm_client=debug".

`global_level`

fn global_level(&self) -> LogLevel

`max_level`

fn max_level(&self) -> LogLevel

`enabled`

fn enabled(&self, level: LogLevel, target: &str) -> bool

Check whether a log record at level from target should be emitted.

`StandardLogAdapter`

Standard logging adapter that hooks into Rust’s log crate

Methods

`new`

fn new(processor_chain: ProcessorChain, transport: Arc<dyn TransportPort>, directives: LogDirectives) -> Self

`UnifiedWasmStdoutAdapter`

Extended WASM adapter that handles both logs and metrics with correlation

Methods

`new`

fn new() -> Self

`transport_metric`

fn transport_metric(&self, entry: &MetricsEntry) -> ObservabilityResult<()>

Process metrics entry through same formatting as logs for correlation

`WasmStdoutAdapter`

WASM stdout transport adapter

Methods

`new`

fn new(formatter: Box<dyn FormatterPort>) -> Self

`with_json_formatter`

fn with_json_formatter() -> Self

`with_compact_formatter`

fn with_compact_formatter() -> Self

`with_plain_text_formatter`

fn with_plain_text_formatter() -> Self

`WasmStdoutMetricsAdapter`

Basic WASM stdout adapter for metrics (correlation-focused)

Methods

`new`

fn new() -> Self

`disabled`

fn disabled() -> Self

`TracingIntegrationBuilder`

Builder for creating tracing-integrated logging setup

Methods

`new`

fn new() -> Self

`with_processor_chain`

fn with_processor_chain(self, chain: ProcessorChain) -> Self

`with_transport`

fn with_transport(self, transport: Arc<dyn TransportPort>) -> Self

`with_level_filter`

fn with_level_filter(self, level: LogLevel) -> Self

`build`

fn build(self) -> ObservabilityResult<TracingSubscriberAdapter>

`TracingSubscriberAdapter`

Tracing subscriber adapter for structured logging integration

This adapter implements tracing::Subscriber to capture tracing events and convert them to LogEntry for processing through the hexagonal architecture

Methods

`new`

fn new(processor_chain: ProcessorChain, transport: Arc<dyn TransportPort>, level_filter: LogLevel) -> Self

`EnhancedContextEnricher`

Enhanced processor that combines context enrichment with kv extraction

Methods

`new`

fn new() -> Self

`with_field`

fn with_field<impl Into<String>, impl Into<serde_json::Value>>(self, key: impl Into, value: impl Into) -> Self

`with_kv_extraction`

fn with_kv_extraction(self, extract_kv: bool) -> Self

`LogEntry`

Core log entry - pure data structure

Fields

Field	Type	Description
`timestamp`	`chrono::DateTime<chrono::Utc>`
`level`	`LogLevel`
`message`	`String`
`fields`	`serde_json::Value`
`trace_context`	`Option<TraceContext>`
`source`	`LogSource`

`LogKvExtractor`

Processor that extracts structured fields from log::kv

This processor supports the log::info!(“msg”; “key” => value) syntax by extracting key-value pairs from log::Record and adding them to LogEntry fields

Methods

`new`

fn new() -> Self

`extract_kv_from_record`

fn extract_kv_from_record(record: &log::Record<'_>) -> serde_json::Value

Extract key-value pairs from log::Record

This function would be called by StandardLogAdapter when processing log::Record but we’ll implement the interface here for the processor chain

`MetricsEntry`

Basic metric entry for correlation with logs

Fields

Field	Type	Description
`name`	`String`
`value`	`f64`
`metric_type`	`BasicMetricType`
`timestamp`	`chrono::DateTime<chrono::Utc>`
`trace_context`	`Option<TraceContext>`
`source`	`MetricsSource`

Methods

`new`

fn new<impl Into<String>>(name: impl Into, value: f64, metric_type: BasicMetricType) -> Self

Create a new metrics entry

`with_trace_context`

fn with_trace_context(self, trace_context: TraceContext) -> Self

Add trace context for correlation

`with_source`

fn with_source(self, module: Option<String>, component: Option<String>, operation: Option<String>) -> Self

Add source information

`to_json`

fn to_json(&self) -> serde_json::Value

Convert to JSON for transport

`MetricsSource`

Source of the metric

Fields

Field	Type	Description
`module`	`Option<String>`
`component`	`Option<String>`
`operation`	`Option<String>`

`ProcessorChain`

Processor chain pattern (inspired by structlog)

Methods

`new`

fn new() -> Self

Create a new empty processor chain

`add_processor`

fn add_processor(self, processor: Box<dyn LogProcessor>) -> Self

Add a processor to the chain

`process`

fn process(&self, entry: LogEntry) -> ObservabilityResult<LogEntry>

Process an entry through the entire chain

`len`

fn len(&self) -> usize

Get number of processors in the chain

`is_empty`

fn is_empty(&self) -> bool

Check if chain is empty

`TraceCorrelation`

Serializable trace identifiers for log/metric correlation.

Distinct from [crate::context::TraceContext] which is the runtime tracing context with sampling decisions and W3C conversion methods.

Fields

Field	Type	Description
`trace_id`	`String`
`span_id`	`String`
`parent_span_id`	`Option<String>`

`GlobalLoggerSingleton`

Singleton global logger that initializes once and is shared across all extension instances

Methods

`get_or_init`

fn get_or_init(config: ObservabilityConfig) -> ObservabilityResult<&''static GlobalLoggerSingleton>

Get or create the singleton instance

This is thread-safe and will initialize exactly once

`adapter`

fn adapter(&self) -> &Arc<StandardLogAdapter>

Get the logger adapter

`config`

fn config(&self) -> &ObservabilityConfig

Get the configuration used

`ObservabilityConfig`

Configuration for observability

Fields

Field	Type	Description
`level`	`String`	Minimum log level to process
`format`	`String`	Output format: “json”, “compact”, “plain”
`structured`	`bool`	Enable structured logging features
`context_enrichment`	`bool`	Enable context enrichment
`default_context`	`HashMap<String, serde_json::Value>`	Additional context fields to always include

Methods

`parse_level`

fn parse_level(&self) -> ObservabilityResult<LogLevel>

Parse log level from string (global level only, ignores per-crate directives).

`parse_directives`

fn parse_directives(&self) -> LogDirectives

Parse RUST_LOG-style directives from the level string.

Accepts both simple levels ("info") and per-crate directives ("info,agent_sdk=debug,a2a_protocol_core=trace").

`create_transport`

fn create_transport(&self) -> Arc<dyn TransportPort>

Create transport based on format configuration

`validate`

fn validate(&self) -> ObservabilityResult<()>

Validate configuration

`ObservabilityManager`

Core observability manager

This provides structured logging integration with standard Rust logging macros (log::info!, log::debug!, etc.) without external extension system dependencies

Methods

`new`

fn new(config: ObservabilityConfig) -> ObservabilityResult<Self>

Create a new observability manager with configuration

`initialize`

fn initialize(&mut self) -> ObservabilityResult<()>

Initialize global logging (convenience method)

`config`

fn config(&self) -> &ObservabilityConfig

Get current configuration

`is_enabled`

fn is_enabled(&self, level: LogLevel) -> bool

Check if logging is enabled for a level

`global_logger`

fn global_logger() -> Option<Arc<StandardLogAdapter>>

Get the global logger instance (always available with singleton pattern)

`capabilities`

fn capabilities(&self) -> Vec<String>

Get capabilities as strings

Enums

`ObservabilityError`

Comprehensive error types for observability operations

Variants

Variant	Description
`Configuration { ... }`	Configuration errors
`Serialization { ... }`	Serialization/deserialization errors
`Transport { ... }`	Network/transport errors
`TraceContext { ... }`	Trace context propagation errors
`Metric { ... }`	Metric collection errors
`Logging { ... }`	Logging errors
`Batching { ... }`	Batching system errors
`Buffer { ... }`	Buffer overflow or memory errors
`FeatureNotEnabled { ... }`	Feature not enabled
`Generic { ... }`	Generic errors for compatibility

Methods

`configuration`

fn configuration<impl Into<String>>(message: impl Into) -> Self

Create a configuration error

`serialization`

fn serialization<impl Into<String>>(message: impl Into) -> Self

Create a serialization error

`transport`

fn transport<impl Into<String>>(message: impl Into) -> Self

Create a transport error

`trace_context`

fn trace_context<impl Into<String>>(message: impl Into) -> Self

Create a trace context error

`metric`

fn metric<impl Into<String>>(message: impl Into) -> Self

Create a metric error

`logging`

fn logging<impl Into<String>>(message: impl Into) -> Self

Create a logging error

`batching`

fn batching<impl Into<String>>(message: impl Into) -> Self

Create a batching error

`buffer`

fn buffer<impl Into<String>>(message: impl Into) -> Self

Create a buffer error

`feature_not_enabled`

fn feature_not_enabled<impl Into<String>>(feature: impl Into) -> Self

Create a feature not enabled error

`generic`

fn generic<impl Into<String>>(message: impl Into) -> Self

Create a generic error

`LogLevel`

Log levels for structured logging

Variants

Variant	Description
`Error`
`Warn`
`Info`
`Debug`
`Trace`

Methods

`as_str`

fn as_str(&self) -> &''static str

`SpanStatus`

Status of a span

Variants

Variant	Description
`Ok`
`Error`
`Cancelled`

`BasicMetricType`

Simple metric types supported by core

Variants

Variant	Description
`Counter`	Counter metric (monotonically increasing)
`Histogram`	Histogram/timing metric (distribution of values)
`Gauge`	Gauge metric (current value)

Functions

`clear_current_context`

fn clear_current_context()

Clear the current trace context

`get_current_context`

fn get_current_context() -> Option<TraceContext>

Get the current trace context for this thread

`set_current_context`

fn set_current_context(context: TraceContext)

Set the current trace context for this thread

`with_context`

fn with_context<F, R>(context: TraceContext, f: F) -> R
where
    F: FnOnce

Execute a function with a specific trace context

`with_context_future`

fn with_context_future<F>(context: TraceContext, future: F) -> ContextFuture<F>
where
    F: Future

Execute a future with a specific trace context re-applied on every poll.

`create_counter_metric`

fn create_counter_metric<impl Into<String>>(name: impl Into, value: f64) -> MetricsEntry

Convenience function to create a counter metric

`create_gauge_metric`

fn create_gauge_metric<impl Into<String>>(name: impl Into, value: f64) -> MetricsEntry

Convenience function to create a gauge metric

`create_histogram_metric`

fn create_histogram_metric<impl Into<String>>(name: impl Into, value: f64) -> MetricsEntry

Convenience function to create a histogram metric

`create_observability_manager`

fn create_observability_manager(config: Option<serde_json::Value>) -> ObservabilityResult<ObservabilityManager>

Factory function for creating observability manager from JSON configuration

Macros

`observability_plugin!`

Macro to conditionally create observability plugin based on features

`shared_observability_plugin!`

Macro to conditionally create shared observability plugin based on features

`observability_span!`

Conditional span creation macro

`observability_metric!`

Conditional metric recording macro

`observability_log!`

Conditional logging macro