[](https://gleam.run/) [](https://www.erlang.org/) [](https://www.erlang.org/doc/design_principles/des_princ) [](https://hex.pm/packages/viva_telemetry) [](https://prometheus.io/) [](./test) [](./CHANGELOG.md) [](./LICENSE) --- *"Logs whisper. Metrics count. Benchmarks judge. The BEAM observes."*

[!IMPORTANT] viva_telemetry IS NOT A FRAMEWORK. It is three independent observability surfaces — structured logging, Prometheus-shaped metrics, and statistical benchmarks — that you can pull into any Gleam/BEAM app without dragging in a runtime.

Plays well with Erlang :logger, Prometheus scrapers, and Grafana.

🎯 Overview

Observability for Gleam applications on the BEAM. Structured logging, in-memory metrics, Prometheus export, BEAM memory visibility, and small statistical benchmarks — without forcing a large framework into your application.

The three surfaces (log, metrics, bench) are deliberately independent: import only what you need, configure each per process.

⚡ Quick Start

gleam add viva_telemetry@1

Log, count, time — in one file

import viva_telemetry/bench
import viva_telemetry/log
import viva_telemetry/metrics

pub fn main() {
  log.configure_erlang(log.info_level)
  log.info("Server started", [#("port", "8080")])

  let requests = metrics.counter("http_requests_total")
  metrics.inc(requests)

  bench.run("my_function", fn() { heavy_work() })
  |> bench.print()
}

🏗️ Architecture

   ┌──────────────────────────────────────────────────────────┐
   │                Gleam application code                    │
   │      viva_telemetry/log · /metrics · /bench              │
   └────────┬─────────────────┬──────────────────┬────────────┘
            │                 │                  │
   ┌────────▼─────┐  ┌────────▼────────┐  ┌──────▼─────────┐
   │   Logging    │  │     Metrics     │  │   Benchmarks   │
   │              │  │                 │  │                │
   │ levels       │  │ counter         │  │ warmup         │
   │ handlers     │  │ gauge           │  │ samples        │
   │ context      │  │ histogram       │  │ percentiles    │
   │ sampling     │  │ Prometheus      │  │ ips / speedup  │
   │ named logger │  │ BEAM memory     │  │ JSON / MD      │
   └──────┬───────┘  └────────┬────────┘  └────────────────┘
          │                   │
   ┌──────▼─────┐     ┌───────▼──────┐
   │ Erlang     │     │ ETS-backed   │
   │ :logger    │     │ atomic ops   │
   └────────────┘     └──────────────┘

🧬 Design Principles

📊 Modules Walkthrough

Logging

import viva_telemetry/log

// Recommended on the BEAM
log.configure_erlang(log.info_level)

log.info("User logged in", [
  #("user_id", "42"),
  #("ip", "192.168.1.1"),
])

Metrics

import viva_telemetry/metrics

let requests = metrics.counter("http_requests_total")
metrics.inc(requests)
metrics.inc_by(requests, 5)

let connections = metrics.gauge("active_connections")
metrics.set(connections, 42.0)

let latency =
  metrics.histogram_with_labels_and_description(
    "request_duration_seconds",
    [0.1, 0.5, 1.0],
    [#("route", "/users")],
    "Request duration in seconds.",
  )

let result = metrics.time_ms(latency, fn() { do_work() })
io.println(metrics.to_prometheus())

Benchmarks

import viva_telemetry/bench

bench.run("fib_recursive", fn() { fib(30) })
|> bench.print()

let slow = bench.run("v1", fn() { algo_v1() })
let fast = bench.run("v2", fn() { algo_v2() })

bench.compare(slow, fast)
|> bench.print_comparison()

bench.to_json(result)
bench.to_markdown_table([slow, fast])

Warmup, percentiles (p50/p95/p99), 95% confidence intervals, IPS, and optional JSON/Markdown export — all in memory, no external profiler.

🗺️ Roadmap

🤝 Contributing

git checkout -b feature/your-feature
gleam test                  # 41 tests
gleam format --check src test
gleam docs build

See CONTRIBUTING.md for guidelines.

📚 Documentation

• Hex.pm package
• HexDocs reference
• CHANGELOG — release history.
• CONTRIBUTING — guidelines.
• SECURITY — vulnerability reporting.

Local development

make test      # run tests
make bench     # run benchmark example
make log       # run logging example
make metrics   # run metrics example
make docs      # generate HexDocs locally

🌌 VIVA Ecosystem

💡 Inspiration

• Logging: Erlang :logger, glimt, glog, structlog, zap, tracing
• Metrics: Prometheus + BEAM telemetry conventions
• Benchmarking: criterion, benchee, hyperfine

**Star if BEAM observability deserves a Gleam-native voice ⭐** [](https://github.com/gabrielmaialva33/viva_telemetry) *Created by Gabriel Maia · Apache-2.0 License*