Skip to content

feat: Add with-otel example with pre-configured Grafana dashboard#12043

Merged
anthonyshew merged 9 commits intomainfrom
shew/otel-collector-friendly-example
Feb 27, 2026
Merged

feat: Add with-otel example with pre-configured Grafana dashboard#12043
anthonyshew merged 9 commits intomainfrom
shew/otel-collector-friendly-example

Conversation

@anthonyshew
Copy link
Copy Markdown
Contributor

@anthonyshew anthonyshew commented Feb 27, 2026

Summary

  • Moves examples/local-otel-collector to examples/with-otel and transforms it into a standard Turborepo example following the create-turbo pattern
  • Adds a pre-configured Grafana dashboard so users see Turborepo metrics immediately after docker compose up -d -- no manual datasource or dashboard setup required

Try it

npx create-turbo@latest \
  -e https://github.com/vercel/turborepo/tree/shew/otel-collector-friendly-example \
  -p examples/with-otel

Testing

cd with-otel
pnpm install
docker compose up -d

# 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

turbo build
# Open http://localhost:3001 to see the Grafana dashboard

Moves examples/local-otel-collector to examples/with-otel and transforms
it into a proper Turborepo example following the create-turbo pattern.

- Full monorepo structure (apps/web, apps/docs, shared packages)
- Installed turbo@2.8.13-canary.1 as a devDependency
- Pre-configured Grafana with a Turborepo Runs dashboard
- Anonymous Grafana access so users see metrics immediately
- meta.json, pnpm-workspace.yaml, and all standard boilerplate
@anthonyshew anthonyshew requested a review from a team as a code owner February 27, 2026 20:13
@anthonyshew anthonyshew requested review from tknickman and removed request for a team February 27, 2026 20:13
@vercel
Copy link
Copy Markdown
Contributor

vercel Bot commented Feb 27, 2026

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
examples-basic-web Ready Ready Preview, Comment, Open in v0 Feb 27, 2026 9:46pm
examples-designsystem-docs Ready Ready Preview, Comment, Open in v0 Feb 27, 2026 9:46pm
examples-gatsby-web Ready Ready Preview, Comment, Open in v0 Feb 27, 2026 9:46pm
examples-kitchensink-blog Ready Ready Preview, Comment, Open in v0 Feb 27, 2026 9:46pm
examples-nonmonorepo Ready Ready Preview, Comment, Open in v0 Feb 27, 2026 9:46pm
examples-svelte-web Ready Ready Preview, Comment, Open in v0 Feb 27, 2026 9:46pm
examples-tailwind-web Ready Ready Preview, Comment, Open in v0 Feb 27, 2026 9:46pm
examples-vite-web Building Building Preview, Comment, Open in v0 Feb 27, 2026 9:46pm
turbo-site Ready Ready Preview, Comment, Open in v0 Feb 27, 2026 9:46pm
turborepo-agents Ready Ready Preview, Comment, Open in v0 Feb 27, 2026 9:46pm
1 Skipped Deployment
Project Deployment Actions Updated (UTC)
turborepo-test-coverage Skipped Skipped Open in v0 Feb 27, 2026 9:46pm

Comment thread examples/with-otel/turbo.json
Comment thread examples/with-otel/docker-compose.yml
…rimentalObservability: true`, causing the OTEL example to fail with an error when following the documented instructions.

This commit fixes the issue reported at examples/with-otel/turbo.json:2

## Bug Analysis

The `examples/with-otel` example documents a workflow where users set environment variables like `TURBO_EXPERIMENTAL_OTEL_ENABLED=1` and then run `turbo build` to export OpenTelemetry metrics. However, the example's `turbo.json` is missing the required `futureFlags.experimentalObservability: true` setting.

### How the gate works

In `crates/turborepo-lib/src/run/builder.rs` (lines 453-463), there is a hard gate:

```rust
if let Some(obs_opts) = &self.opts.experimental_observability {
    if obs_opts.otel.is_some() && !self.opts.future_flags.experimental_observability {
        return Err(turborepo_config::Error::InvalidExperimentalOtelConfig {
            message: "experimentalObservability.otel is configured but \
                      futureFlags.experimentalObservability is not enabled in turbo.json."
                .to_string(),
        }
        .into());
    }
}
```

### The flow

1. User sets `TURBO_EXPERIMENTAL_OTEL_ENABLED=1` (and other env vars) as documented in the README
2. The env vars are parsed in `crates/turborepo-config/src/experimental_otel.rs` into `ExperimentalOtelOptions`
3. This gets wrapped as `ExperimentalObservabilityOptions { otel: Some(otel) }` in the config funnel
4. When `turbo build` runs, the gate checks `obs_opts.otel.is_some()` (true) AND `!self.opts.future_flags.experimental_observability` (true, since `FutureFlags` defaults to `false`)
5. The run fails with the error: "experimentalObservability.otel is configured but futureFlags.experimentalObservability is not enabled in turbo.json."

### The fix

Added the `futureFlags` block with `experimentalObservability: true` to `examples/with-otel/turbo.json`. This is a valid top-level field in turbo.json (defined in `crates/turborepo-turbo-json/src/raw.rs` line 291 and extensively tested). Without this, the example is completely non-functional as documented.

Co-authored-by: Vercel <vercel[bot]@users.noreply.github.com>
Co-authored-by: anthonyshew <anthonyshew@gmail.com>
- All stat panels use sum() to aggregate across runs (no duplicate numbers)
- Cache Hit Rate shows a single gauge
- Run Duration uses instant query that works with one-off runs
- Replaced Runs Over Time with a Total Runs stat + Run Duration Over Time chart
- Task Details table uses filterFieldsByName to exclude Prometheus-injected columns
- All task breakdown queries use sum by (turbo_task_name) for clean grouping
- Time-series panels use showPoints: always + spanNulls for sparse data
@vercel vercel Bot temporarily deployed to Preview – turborepo-test-coverage February 27, 2026 21:45 Inactive
@anthonyshew anthonyshew enabled auto-merge (squash) February 27, 2026 21:52
@anthonyshew anthonyshew merged commit d47c6c7 into main Feb 27, 2026
39 checks passed
@anthonyshew anthonyshew deleted the shew/otel-collector-friendly-example branch February 27, 2026 21:53
github-actions Bot added a commit that referenced this pull request Feb 27, 2026
## Release v2.8.13-canary.4

Versioned docs: https://v2-8-13-canary-4.turborepo.dev

### Changes

- release(turborepo): 2.8.13-canary.3 (#12046) (`f384967`)
- docs: Fix incorrect otel future flag bypass claim (#12047) (`ddbb12d`)
- feat: Add with-otel example with pre-configured Grafana dashboard
(#12043) (`d47c6c7`)
- fix: Address root causes of 9 flaky tests and remove retry workarounds
(#12045) (`ba2a830`)

---------

Co-authored-by: Turbobot <turbobot@vercel.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area: examples Improvements or additions to examples

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant