Turborepo with OpenTelemetry

This example shows a Turborepo monorepo with a local OpenTelemetry Collector, Prometheus, and Grafana for visualizing Turborepo's OTEL metrics.

Using this example

Run the following command:

npx create-turbo@latest -e with-otel

What's inside?

This Turborepo includes the following packages/apps:

Apps and Packages

docs: a Next.js app
web: another Next.js app
@repo/ui: a stub React component library shared by both web and docs applications
@repo/eslint-config: eslint configurations (includes eslint-config-next and eslint-config-prettier)
@repo/typescript-config: tsconfig.jsons used throughout the monorepo

Each package/app is 100% TypeScript.

Utilities

This Turborepo has some additional tools already setup for you:

TypeScript for static type checking
ESLint for code linting
Prettier for code formatting

OTEL Collector Stack

The included docker-compose.yml starts:

otel-collector -- OTLP gRPC receiver with a debug exporter and Prometheus exporter
prometheus -- scrapes metrics from the collector
grafana -- pre-configured with a Turborepo dashboard (anonymous access enabled)

Service	Port
OTLP gRPC	4317
Collector metrics	8888
Prometheus exporter	8889
Prometheus UI	9090
Grafana UI	3001

How to use

1. Start the collector stack

docker compose up -d

Confirm it's ready:

docker compose logs otel-collector
# Look for: "Everything is ready. Begin running and processing data."

2. Configure Turborepo OTEL environment variables

macOS / Linux:

export TURBO_EXPERIMENTAL_OTEL_ENABLED=1
export TURBO_EXPERIMENTAL_OTEL_ENDPOINT=https://127.0.0.1:4317
export TURBO_EXPERIMENTAL_OTEL_RESOURCE="service.name=turborepo,env=local"
export TURBO_EXPERIMENTAL_OTEL_METRICS_TASK_DETAILS=1

Windows (PowerShell):

powershell

$env:TURBO_EXPERIMENTAL_OTEL_ENABLED=1
$env:TURBO_EXPERIMENTAL_OTEL_ENDPOINT="https://127.0.0.1:4317"
$env:TURBO_EXPERIMENTAL_OTEL_RESOURCE="service.name=turborepo,env=local"
$env:TURBO_EXPERIMENTAL_OTEL_METRICS_TASK_DETAILS=1

3. Run a task

turbo build

4. Verify metrics

Collector logs (debug exporter):

docker compose logs --tail=100 otel-collector

You should see entries like:

text

Metrics {"otelcol.component.id": "debug", "otelcol.signal": "metrics", "resource metrics": 1, "metrics": 4, "data points": 4}
Resource attributes:
     -> env: Str(local)
     -> service.name: Str(turborepo)
Metric #0
     -> Name: turbo.run.duration_ms
Metric #1
     -> Name: turbo.run.tasks.attempted
Metric #2
     -> Name: turbo.run.tasks.failed
Metric #3
     -> Name: turbo.run.tasks.cached

Prometheus UI: Click any of these links to open pre-filled queries:

All run metrics -- {__name__=~"turbo_run_.+"}
Run duration (histogram) -- avg duration per run
Tasks attempted
Tasks cached
Tasks failed
Cache hit rate

Grafana dashboard: Open http://localhost:3001 -- the Turborepo Runs dashboard is pre-configured and loads automatically. No login required. The dashboard includes:

Run duration (avg and p95) and runs over time
Tasks attempted, cached, failed, and cache hit rate
Task breakdown -- duration by task (build, lint, check-types, etc.), cache status by task, a detail table with package names, and time-series charts for tracking changes across runs

5. Cleanup

docker compose down

Useful Links

Learn more about the power of Turborepo: