Desktop-First Observability Platform for Local Development

---

Origins

ollyScale is based on the excellent TinyOlly project by Infrastructure Architects, LLC.

TinyOlly pioneered the concept of "desktop observability" - bringing enterprise-grade observability tools to local development environments. ollyScale continues this vision while adding enhancements and maintaining compatibility with the OpenTelemetry ecosystem.

Key Attribution:

• Original concept and core architecture: TinyOlly (BSD-3-Clause)
• ollyScale enhancements and modifications: AGPL-3.0
• See NOTICE for complete licensing information

---

Quick Start

See the Quick Start Guide to get up and running in minutes.

Documentation

Docs are here: https://ryanfaircloth.github.io/ollyscale/

What is ollyScale?

Why send telemetry to a cloud observability platform while coding? Why not have one on your desktop?

ollyScale is a lightweight OpenTelemetry-native observability platform for local development, evolved from TinyOlly.
Visualize and correlate logs, metrics, and traces without sending data to the cloud.

Key Features:

• Full OpenTelemetry Protocol (OTLP) support with gRPC and HTTP ingestion
• REST API with OpenAPI documentation
• Service catalog, dependency maps, and distributed tracing
• Works with any OTel Collector distro
• Built with Python (FastAPI), Redis, and JavaScript
• Pre-built Docker images available on Docker Hub

Platform Support: Tested on Docker Desktop and KIND Kubernetes (Apple Silicon Mac) Architectures: linux/amd64, linux/arm64 (Apple Silicon)

Screenshots

Trace waterfall with correlated logs	Real-time logs with trace/span linking
Metrics with chart visualizations	Service catalog with RED metrics
Interactive service dependency map	OpenTelemetry Collector configuration via OpAMP

---

Quick Start

All examples are launched from the repo- clone it first:

git clone https://github.com/ryanfaircloth/ollyscale

Docker Deployment

1. Deploy ollyScale Core (Required)

Start the observability backend:

task up     # Create kind cluster and deploy ollyScale

Deployment time: ~30 seconds (pulls images from Docker Hub)

Services:

• OTLP Receiver: Cluster IP (gRPC)
• OpAMP Server: WebSocket + HTTP REST API endpoints
• UI: http://ollyscale.test
• Redis: Internal service
• OTel Collector: Internal service

Stop: task down

---

2. Deploy Demo Apps (Optional)

task deploy  # Build and deploy demo applications

Two Flask microservices with automatic traffic generation. Wait 30 seconds for telemetry to appear.

Stop: task down

---

3. eBPF Zero-Code Tracing Demo (Optional)

Deploy a demo showing OpenTelemetry eBPF Instrumentation (OBI) - traces captured at the kernel level with zero code changes:

task deploy  # Build and deploy with eBPF agent enabled

Deployment time: ~30 seconds (pulls pre-built images from Docker Hub)

This demonstrates:

• eBPF Agent captures HTTP traces automatically at kernel level
• No tracing SDK in application code - traces come from eBPF
• Logs & Metrics still use OTel SDK (shows hybrid approach)

See eBPF Demo Documentation for details on how traces differ from SDK-instrumented apps.

Stop: task down

---

5. AI Agent Demo with Ollama (Optional)

Deploy an AI agent demo with zero-code OpenTelemetry auto-instrumentation:

task deploy  # Build and deploy AI demo with Ollama

This starts:

• Ollama with TinyLlama model for local LLM inference
• AI Agent with automatic GenAI span instrumentation via opentelemetry-instrumentation-ollama

View AI traces in the AI Agents tab - see prompts, responses, token usage (in/out), and latency for each LLM call.

Stop: task down

---

6. OpenTelemetry Demo (~20 Services - Optional)

Clone and configure the OpenTelemetry Demo to route telemetry to ollyScale. Edit src/otel-collector/otelcol-config-extras.yml to add ollyScale as an exporter, then deploy with built-in observability tools disabled.

---

7. Use ollyScale with Your Own Apps

Point your OpenTelemetry exporter to:

• gRPC: http://otel-collector:4317
• HTTP: http://otel-collector:4318

8. Core-Only Deployment (Use Your Own OTel Collector)

task deploy  # Deploy ollyScale without bundled collector

Deploys ollyScale without the bundled OTel Collector. Includes:

• OTLP Receiver: Cluster IP (gRPC)
• OpAMP Server: WebSocket + HTTP REST API
• UI: http://ollyscale.test
• Redis: Internal service

Point your external collector to the ollyScale OTLP receiver service for telemetry ingestion.

OpAMP Configuration (Optional)

The OpenTelemetry Collector + OpAMP Config page in the ollyScale UI allows you to view and manage collector configurations remotely. To enable this feature, add the OpAMP extension to your collector config:

extensions:
  opamp:
    server:
      ws:
        endpoint: ws://opamp-server.ollyscale.svc.cluster.local/v1/opamp

service:
  extensions: [opamp]

The default configuration template (located at config/otelcol/config.yaml) shows a complete example with OTLP receivers, OpAMP extension, batch processing, and spanmetrics connector. Your collector will connect to the OpAMP server and receive configuration updates through the ollyScale UI.

Stop: task down

Kubernetes Deployment

1. Deploy ollyScale Core

cd charts
task deploy  # Build, push, and deploy to Kubernetes

Access UI:

# UI exposed via Envoy Gateway on localhost

UI available at: http://ollyscale.test

Enable eBPF agent for zero-code instrumentation:

helm install ollyscale ./charts/ollyscale \
  --namespace ollyscale \
  --create-namespace \
  --set ebpfAgent.enabled=true \
  --set ebpfAgent.config.openPorts="5000,8080,3000"

The eBPF agent runs as a DaemonSet and automatically captures HTTP/gRPC traces from applications on specified ports without any code changes. See the Helm Chart README for full configuration options.

Cleanup:

helm uninstall ollyscale -n ollyscale
kubectl delete namespace ollyscale

---

2. Demo Applications (Optional)

Demo applications are automatically deployed with the main ollyScale deployment. To redeploy or update:

task deploy  # Build and deploy all components

Cleanup: task down

---

Building Images

For building and publishing Docker images, see build/README.md.

---

Features

UI

• Auto-refresh every 5 seconds (pausable)
• Export JSON with one click
• Service catalog with RED metrics
• Interactive service dependency map
• Distributed trace waterfall with correlated logs
• Metric cardinality protection with visual warnings
• OpAMP-based OpenTelemetry Collector configuration management
• AI Agents tab for GenAI observability

AI Agents

• View LLM calls with prompts, responses, and token usage
• Zero-code auto-instrumentation via OpenTelemetry GenAI semantic conventions
• Token tracking (input/output) with visual indicators
• Latency monitoring per LLM call
• Click-to-expand JSON span details
• Supports any OpenTelemetry-instrumented LLM (Ollama, OpenAI, etc.)

Metrics

• Dense, aligned table layout with "Chart" buttons
• Inline "Cardinality" column showing label dimensions and series count
• Cardinality Explorer:
  • Deep-dive into metric attributes
  • Label Analysis: View high-cardinality labels and their top values (expandable)
  • Raw Series: Scrollable view of all active series in PromQL-like syntax
  • Export: Copy PromQL or Download JSON for offline analysis

Service Catalog

• RED metrics (Rate, Errors, Duration) with P50/P95 latencies
• Inline metric visualization
• Sortable columns with persistent filters
• Color-coded error rates

Service Map

• Auto-detected node types (Client, Server, Database, Messaging)
• Interactive graph with zoom/pan
• Call counts between services
• Real-time topology updates

Cardinality Protection

• Hard limit of 1000 unique metric names (configurable via MAX_METRIC_CARDINALITY)
• Visual warnings at 70% and 90%
• Drops metrics exceeding limit with tracking

OpenTelemetry Collector + OpAMP Config

• View and manage OpenTelemetry Collector configuration via the OpAMP protocol
• Real-time validation of collector configurations before applying
• Configuration templates for common use cases (default, prometheus-remote-write, etc.)
• View OpAMP server status and connected collector agents
• Apply configuration changes with diff preview
• Requires collector to be connected to the OpAMP server (configured in collector config)

---

REST API & OpenAPI

Full REST API with OpenAPI 3.0 documentation:

• Swagger UI: http://localhost:5005/docs
• ReDoc: http://localhost:5005/redoc
• OpenAPI Spec: http://localhost:5005/openapi.json

Generate clients in any language:

curl http://localhost:5005/openapi.json > openapi.json
openapi-generator-cli generate -i openapi.json -g python -o ./ollyscale-client

All responses return OpenTelemetry-native JSON with full trace/span context.

Technical Details

Stack

• Backend: FastAPI (async), Redis with ZSTD compression + msgpack
• Frontend: Vanilla JavaScript, HTML, CSS
• Ingestion: OTLP/gRPC and OTLP/HTTP
• Storage: 30-minute TTL, sorted sets indexed by timestamp
• Correlation: Native trace/span/log linking

OTLP Support

• Full OpenTelemetry Protocol compliance
• ResourceSpans, ResourceLogs, ResourceMetrics
• Spanmetrics integration for RED metrics
• OpAMP protocol support for remote collector configuration management
• No vendor lock-in

---

Development

Pre-commit Hooks

ollyScale uses pre-commit to maintain code quality:

# Setup (first time)
make precommit-setup

# Run checks manually
make lint

# Run with auto-fix
make lint-fix

Checks include:

• Python: ruff (lint + format)
• YAML/JSON: validation + formatting
• Shell: shellcheck
• Docker: hadolint
• Helm: helm lint
• Go: golangci-lint
• Markdown: markdownlint

See docs/precommit.md for details.

Release System

ollyScale uses release-please for automated releases:

• Conventional Commits for version bumping
• Separate releases for each component
• Automatic Docker image builds and publishing
• Helm chart packaging and OCI registry publishing
• Cross-component dependency management via bumpDependents

See docs/release-system.md for complete documentation.

Admin Endpoints

• GET /admin/stats - Redis memory, cardinality, uptime
• GET/POST/DELETE /admin/alerts - Alert management
• GET /health - Connectivity status

Licensing

Dual Licensing:

• Original TinyOlly Code: BSD-3-Clause (see LICENSE-BSD3-ORIGINAL)
• ollyScale Modifications/Enhancements: AGPL-3.0 (see LICENSE)

See NOTICE for complete attribution and licensing information.

---

Built for the OpenTelemetry community

GitHub • Issues