viva_telemetry

Professional observability suite for Gleam: structured logging, metrics, and statistical benchmarking.

Inspired by: structlog (Python), zap (Go), tracing (Rust)

Install

gleam add viva_telemetry@1

Features

┌─────────────────────────────────────────────────────────────────┐
│  viva_telemetry                                                 │
├─────────────────────────────────────────────────────────────────┤
│  LOG         │  METRICS      │  BENCH                          │
│  ├─ Levels   │  ├─ Counter   │  ├─ Statistical analysis        │
│  ├─ Handlers │  ├─ Gauge     │  ├─ Confidence intervals        │
│  ├─ Context  │  ├─ Histogram │  ├─ Comparison (speedup)        │
│  ├─ Sampling │  ├─ BEAM mem  │  └─ Export (JSON/CSV/MD)        │
│  └─ Lazy     │  └─ Prometheus│                                 │
└─────────────────────────────────────────────────────────────────┘

Logging

import viva_telemetry/log

pub fn main() {
  // Quick setup (one import!)
  log.configure_console(log.debug_level)

  // Structured logging
  log.info("Server started", [#("port", "8080")])

  // Context propagation
  log.with_context([#("request_id", "abc123")], fn() {
    log.debug("Processing request", [])
  })

  // Lazy evaluation (avoid string construction when disabled)
  log.debug_lazy(fn() { "Item: " <> expensive_to_string(data) }, [])

  // Sampling for high-volume logs
  log.sampled(log.trace_level, 0.01, "Hot path", [])
}

Log Levels (RFC 5424)

Handlers

import viva_telemetry/log
import viva_telemetry/log/handler

// Console only
log.configure_console(log.info_level)

// JSON file only
log.configure_json("app.jsonl", log.debug_level)

// Console + JSON
log.configure_full(log.debug_level, "app.jsonl", log.info_level)

// Custom handler
log.configure([
  handler.console_with_level(log.info_level),
  handler.json_with_level("app.jsonl", log.debug_level),
  handler.custom(log.error_level, fn(entry) { send_to_slack(entry) }),
])

Metrics

import viva_telemetry/metrics

pub fn main() {
  // Counter
  let requests = metrics.counter("http_requests_total")
  metrics.inc(requests)
  metrics.inc_by(requests, 5)

  // Gauge
  let active = metrics.gauge("active_connections")
  metrics.set(active, 42)
  metrics.inc_gauge(active)
  metrics.dec_gauge(active)

  // Histogram with custom buckets
  let latency = metrics.histogram("request_latency_ms", [10.0, 50.0, 100.0, 500.0])
  metrics.observe(latency, 75.5)

  // Time a function automatically
  let result = metrics.time_ms(latency, fn() { do_work() })

  // With labels
  let labeled = metrics.counter_with_labels("http_requests", [#("method", "GET")])

  // BEAM memory tracking
  let mem = metrics.beam_memory()
  // → Dict with total, processes, atom, binary, code, ets

  // Export Prometheus format
  io.println(metrics.to_prometheus())
}

Benchmarking

import viva_telemetry/bench

pub fn main() {
  // Simple benchmark
  let result = bench.run("fib_recursive", fn() { fib(20) })

  // With configuration
  let result = bench.run_with_config(
    "fib",
    fn() { fib(30) },
    bench.Config(warmup_ms: 500, duration_ms: 2000, confidence: 0.95),
  )

  // Compare two implementations
  let comparison = bench.compare(
    bench.Fn("recursive", fn() { fib_recursive(20) }),
    bench.Fn("iterative", fn() { fib_iterative(20) }),
  )
  // → Comparison(speedup: 2.3x, significant: True)

  // Export results
  bench.to_json(result)
  bench.to_markdown(result)
}

Statistics

Each benchmark returns:

Stats(
  mean: Float,      // Average duration
  stddev: Float,    // Standard deviation
  min: Float,       // Minimum
  max: Float,       // Maximum
  p50: Float,       // Median
  p95: Float,       // 95th percentile
  p99: Float,       // 99th percentile
  ips: Float,       // Iterations per second
  ci_95: #(Float, Float),  // 95% confidence interval
)

Build

gleam build      # Build
gleam test       # Run tests (17 passing)
gleam docs build # Generate documentation

Part of VIVA Ecosystem

VIVA - Sentient Digital Life
├── viva_math      → Mathematical foundations
├── viva_emotion   → PAD emotional dynamics
├── viva_tensor    → Tensor compression (INT8/NF4/AWQ)
├── viva_aion      → Time perception
├── viva_glyph     → Symbolic language
└── viva_telemetry → Observability (this package)

_{Built with pure Gleam for the BEAM}