Crate iron_telemetry

Crate iron_telemetry 

Source
Expand description

Centralized structured logging and tracing for Iron Runtime.

Provides unified logging infrastructure across all Iron Runtime crates with structured log entries, contextual metadata, and configurable output formats. Built on the tracing ecosystem for zero-cost abstractions.

§Purpose

This crate standardizes logging across Iron Runtime:

  • Structured logging with semantic key-value fields
  • Automatic agent context injection in all log entries
  • Configurable log levels per module
  • Thread-safe async logging
  • Multiple output formats (text, JSON)

§Key Features

§Structured Logging

All logs include structured fields rather than unstructured text:

  • Agent IDs automatically attached to all operations
  • Numeric values (costs, tokens, percentages) as typed fields
  • Timestamps with microsecond precision
  • Thread IDs for concurrent debugging

§Domain-Specific Helpers

Pre-built logging functions for common events:

  • Agent lifecycle (start, stop, error)
  • PII detection alerts
  • Budget threshold warnings
  • Request tracing

§Zero-Cost Abstractions

When enabled feature is disabled, all logging compiles to no-ops with zero runtime overhead.

§Key Types

  • LogLevel - Log verbosity level (Debug, Info, Warn, Error)

§Public API

§Initialization

use iron_telemetry::{init_logging, LogLevel};

fn main() -> Result<(), Box<dyn std::error::Error>> {
  // Initialize once at startup
  init_logging(LogLevel::Info)?;

  // Now all crates can use tracing macros
  tracing::info!("Application started");
  Ok(())
}

§Domain-Specific Logging

use iron_telemetry::{log_agent_event, log_pii_detection, log_budget_warning};

// Agent lifecycle events
log_agent_event("agent_550e8400-...", "started");
log_agent_event("agent_550e8400-...", "processing_request");
log_agent_event("agent_550e8400-...", "stopped");

// PII detection alerts
log_pii_detection("agent_550e8400-...", "email", 1024);
log_pii_detection("agent_550e8400-...", "phone", 2048);

// Budget warnings
log_budget_warning("agent_550e8400-...", 85.0, 100.0);

§Direct Tracing Usage

For custom events, use tracing macros directly:

use tracing::{info, warn, error};

// Structured info logging
info!(
  agent_id = "agent_550e8400-...",
  model = "gpt-4",
  tokens = 1500,
  cost_usd = 0.045,
  "LLM request completed"
);

// Warning with context
warn!(
  agent_id = "agent_550e8400-...",
  retry_count = 3,
  "Circuit breaker opened"
);

// Error with details
error!(
  agent_id = "agent_550e8400-...",
  error = %err,
  "Request failed"
);

§Output Format

§Text Format (Default)

2025-12-12T15:30:45.123456Z INFO [thread:1] agent_event agent_id="agent_550e8400-..." event="started"
2025-12-12T15:30:46.234567Z WARN [thread:2] pii_detected agent_id="agent_550e8400-..." pii_type="email" location=1024

§JSON Format (Production)

{
  "timestamp": "2025-12-12T15:30:45.123456Z",
  "level": "INFO",
  "thread": 1,
  "message": "Agent event",
  "agent_id": "agent_550e8400-...",
  "event": "started"
}

§Feature Flags

  • enabled - Enable logging infrastructure (disabled for minimal builds)

§Configuration

§Log Levels

  • Debug: Detailed diagnostic information (function entry/exit, variable values)
  • Info: General informational messages (requests, lifecycle events)
  • Warn: Warning conditions (budget thresholds, retries, degraded mode)
  • Error: Error conditions requiring attention (failures, panics)

§Environment Variables

Control logging via environment:

# Set global level
RUST_LOG=debug ./iron_runtime

# Per-module levels
RUST_LOG=iron_runtime=debug,iron_cost=trace ./iron_runtime

§Performance

Logging overhead when enabled:

  • Structured field serialization: ~200ns per log entry
  • Buffer write: ~500ns per entry
  • Async flush: Batched, non-blocking

Total overhead: <1% CPU for typical workloads (100 logs/sec).

When enabled feature is disabled, all logging compiles to zero-cost no-ops.

Enums§

LogLevel
Log level configuration

Functions§

init_logging
Initialize logging infrastructure
log_agent_event
Log an agent lifecycle event
log_budget_warning
Log a budget warning
log_pii_detection
Log a PII detection event