otelbox

README

otelbox

Telemetry signal generator for testing observability components. otelbox generates coherent metric signals derived from the same underlying data sources, enabling verification of monitoring pipelines, collectors, and transformation logic without requiring live systems.

Built on simv for guaranteed mathematical consistency between related metrics.

Quick Start

# Run with default configuration
podman run -p 9090:9090 ghcr.io/neox5/otelbox:latest

# Run with custom configuration
podman run -p 9090:9090 \
  -v $(pwd)/custom-config.yaml:/config/config.yaml:ro \
  ghcr.io/neox5/otelbox:latest

Verify it's working:

curl http://localhost:9090/metrics

Installation

Container (Recommended)

podman pull ghcr.io/neox5/otelbox:latest

Binary Releases

Download the latest release for your platform from GitHub Releases:

# Linux (amd64)
wget https://github.com/neox5/otelbox/releases/download/v0.1.0/otelbox-linux-amd64
chmod +x otelbox-linux-amd64
./otelbox-linux-amd64 --version

Verify checksums:

wget https://github.com/neox5/otelbox/releases/download/v0.2.0/otelbox-linux-amd64.sha256
sha256sum -c otelbox-linux-amd64.sha256

Build from Source

Requires Go 1.25+:

go install github.com/neox5/otelbox/cmd/otelbox@latest

Usage

otelbox -config <path>    Path to configuration file
otelbox --version         Print version and exit

Configuration

Minimal configuration generating a single counter metric:

instances:
  clocks:
    tick:
      type: periodic
      interval: 1s

  sources:
    events:
      type: random_int
      clock:
        instance: tick
      min: 0
      max: 10

  values:
    total_events:
      source:
        instance: events
      transforms: [accumulate]

metrics:
  - name: app_events_total
    type: counter
    description: "Total events processed"
    value:
      instance: total_events
    attributes:
      service: myapp

export:
  prometheus:
    enabled: true
    port: 9090
    path: /metrics

See Configuration Guide for complete documentation and examples/ directory for more configuration patterns.

Documentation

• Configuration Guide - How to write configurations
• Reference Documentation - Complete parameter reference

License

MIT License - see LICENSE file for details.