MiniAPM

The smallest useful APM. A single-binary, self-hosted application performance monitor and error tracker built on OpenTelemetry.

Features

• Distributed Tracing - Full request-to-response visibility with waterfall visualization
• Error Tracking - Exceptions with stack traces and source context, auto-grouped by fingerprint
• Route Performance - P50, P95, P99 latencies with request counts and error rates
• N+1 Query Detection - Automatically identifies repeated query patterns
• Deploy Tracking - Correlate releases with performance changes
• MCP Integration - Built-in Model Context Protocol server for AI assistants

Quick Start

Docker (recommended)

docker run -d -p 3000:3000 -v miniapm_data:/data ghcr.io/miniapm/miniapm

On first run, you'll see your API key in the logs:

INFO miniapm::server: Single-project mode - API key: proj_abc123...

From Source

git clone https://github.com/miniapm/miniapm
cd miniapm
cargo build --release
./target/release/miniapm server

Sending Data

Rails with miniapm gem (recommended)

Add to your Gemfile:

gem 'miniapm'

Configure in config/initializers/miniapm.rb:

MiniAPM.configure do |config|
  config.endpoint = "http://localhost:3000"
  config.api_key = "proj_abc123..."
  config.service_name = "my-app"
end

Any OpenTelemetry SDK

Configure your OTLP exporter:

OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:3000/ingest
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer proj_abc123...

Error Tracking API

curl -X POST http://localhost:3000/ingest/errors \
  -H "Authorization: Bearer proj_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "error_type": "RuntimeError",
    "message": "Something went wrong",
    "backtrace": "app/models/user.rb:42:in `validate'\n...",
    "context": {"user_id": 123}
  }'

Deploy Tracking API

curl -X POST http://localhost:3000/ingest/deploys \
  -H "Authorization: Bearer proj_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "version": "v1.2.3",
    "git_sha": "abc123",
    "deployer": "ci"
  }'

Configuration

All configuration is via environment variables:

See .env.example for a complete template.

Multi-User Mode

To enable login and user management:

# Generate a session secret
export SESSION_SECRET=$(openssl rand -hex 32)
export ENABLE_USER_ACCOUNTS=true

Default admin credentials on first run:

• Username: admin
• Password: admin (you'll be prompted to change it)

MCP Integration

MiniAPM includes a Model Context Protocol server for AI assistants like Claude.

Stdio Mode (Claude Desktop)

Run miniapm mcp-config to get the configuration for Claude Desktop.

HTTP Mode

curl -X POST http://localhost:3000/mcp \
  -H "Authorization: Bearer proj_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Available tools:

• list_errors - List recent errors with filtering
• error_details - Get full error details with stack trace
• slow_routes - Find slowest routes by P95 latency
• system_status - Get system health overview

CLI Commands

miniapm server              # Start the server (default port 3000)
miniapm server -p 8080      # Start on custom port
miniapm create-key <name>   # Create a new API key
miniapm list-keys           # List all API keys

Docker Compose

services:
  miniapm:
    image: ghcr.io/miniapm/miniapm
    ports:
      - "3000:3000"
    volumes:
      - miniapm_data:/data
    environment:
      - RUST_LOG=miniapm=info
    restart: unless-stopped

volumes:
  miniapm_data:

Architecture

• Single binary (~4MB) - No external dependencies
• SQLite storage - Zero-config, automatic migrations
• Rust/Axum - Fast, memory-efficient
• OTLP/HTTP - Standard OpenTelemetry protocol

Development

# Run with hot reload
cargo watch -x run

# Run tests
cargo test

# Run with simulator
cargo run -- simulate --continuous --requests-per-minute 60

License

MIT License - see LICENSE for details.