Skip to content
KOPAIDocs
Open Kopai

Getting Started

Try with Demo App

Try Kopai with the OpenTelemetry Astronomy Shop, a pre-instrumented microservices demo with 10+ services generating traces, metrics, and logs.

Prerequisites

Section titled “Prerequisites”
  • Docker and Docker Compose
  • Node.js v22.13.0+ — Kopai stores telemetry through the built-in node:sqlite module, which stays behind --experimental-sqlite until v22.13.0
  • 3–6 GB of free memory, depending on the mode you pick in Step 2

Step 1: Start Kopai

Section titled “Step 1: Start Kopai”
Terminal window
npx @kopai/app start

Step 2: Clone & Start the Demo

Section titled “Step 2: Clone & Start the Demo”

In a separate terminal:

Terminal window
git clone https://github.com/kopai-app/opentelemetry-demo.git
cd opentelemetry-demo
make start-kopai

Pick the mode that fits your machine:

Command Services Memory
make start-kopai Core demo + Kafka, accounting, fraud detection ~4.1 GiB
make start-kopai-minimal Core demo only ~3.1 GiB
make start-kopai-agentic Everything above, plus the GenAI services ~5.6 GiB

All three stop with make stop-kopai.

Step 3: Generate Traffic

Section titled “Step 3: Generate Traffic”

Open http://localhost:8080 and browse the Astronomy Shop — add items to cart, place orders, etc. This generates telemetry across all services.

Step 4: Query Telemetry

Section titled “Step 4: Query Telemetry”

Use the Kopai CLI to explore what’s been collected:

Terminal window
# Recent traces
npx @kopai/cli traces search --limit 5


# Logs from a specific service
npx @kopai/cli logs search --service cart --fields Timestamp,Body --sort ASC


# Discover available metrics
npx @kopai/cli metrics discover

Step 5: Open the Dashboard

Section titled “Step 5: Open the Dashboard”

View your telemetry visually at http://localhost:8000.

Step 6: Ask Your Coding Agent

Section titled “Step 6: Ask Your Coding Agent”

With the Kopai skills installed, your agent can investigate the demo for you:

Use @kopai/cli to find errors in my services

Step 7: Stop the Demo

Section titled “Step 7: Stop the Demo”
Terminal window
make stop-kopai

GenAI Telemetry

Section titled “GenAI Telemetry”

make start-kopai-agentic adds the demo’s agent, chatbot, and MCP services, so Kopai also receives LLM spans, token usage, and MCP tool calls. Chat with the shop at http://localhost:8080/chatbot/.

LLM calls replay from recorded cassettes by default — no API key, no cost. Cassettes exist only for the azure/gpt-5.5 and claude-opus-4-7 models; point LLM_MODEL anywhere else and there’s nothing to replay.

For live traffic, set these in .env.override — any OpenAI-compatible endpoint works:

Terminal window
USE_VCR=False
LLM_BASE_URL=https://api.openai.com/v1
LLM_MODEL=gpt-4o-mini
API_KEY=<your key>

How It Works

Section titled “How It Works”
┌────────────────────────────────────────────────┐
│  Docker Compose Network                        │
│                                                │
│  ┌─────────────────────────────┐               │
│  │   Astronomy Shop Demo       │               │
│  │   (10+ microservices)       │               │
│  │                             │               │
│  │   All services instrumented │               │
│  │   with OpenTelemetry        │               │
│  └────────────┬────────────────┘               │
│               │                                │
│               │ OTLP (traces, metrics, logs)   │
│               ▼                                │
│  ┌─────────────────────────────┐               │
│  │   OTel Collector            │               │
│  │   (in Docker)               │               │
│  └────────────┬────────────────┘               │
│               │                                │
│               │ OTLP/HTTP                      │
│               ▼                                │
│       host.docker.internal:4318                │
└───────────────┬────────────────────────────────┘
                │
                ▼
┌────────────────────────────────────┐
│   @kopai/app (on host machine)     │
│                                    │
│   OTel collector: localhost:4318   │
│   Dashboard:      localhost:8000   │
└────────────────────────────────────┘

The demo loads a customization file, otelcol-config-extras.yml, last in its collector config chain. Kopai mounts its own exporter config over that seam and skips the demo’s observability layer entirely, so the only upstream file the fork touches is the Makefile.

Learn More

Section titled “Learn More”

For details on the collector config, Compose layering, and running Kopai alongside the bundled stack, see the full README on GitHub.