akadmin/headroom
1
0
Fork 0
mirror of https://github.com/headroomlabs-ai/headroom.git synced 2026-08-27 14:17:10 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions
headroom/docs
History
Tejas Chopra 6b63b623e0
docs(metrics): document OTLP metric export and Dynatrace ingest (#2785) 
## Description

The proxy can already push its counters to any OTLP/HTTP endpoint via
`HEADROOM_OTEL_METRICS_*`, but the docs site only surfaced this as a
single row in the proxy env table (`proxy.mdx:287`). The endpoint,
header, service-name, and resource-attribute variables were documented
only in `wiki/metrics.md` — so an operator reading the Vercel docs had
no way to wire Headroom into their existing observability stack.

This adds that section, plus a Dynatrace subsection, because Dynatrace
has a silent failure mode that costs an afternoon to diagnose.

Closes #

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- `docs/content/docs/metrics.mdx` — new `### OpenTelemetry (OTLP)
Export` section after the Prometheus section: the
`headroom-ai[proxy,otel]` install, all seven `HEADROOM_OTEL_*` variables
in a table, the exported counter names (`headroom.proxy.tokens.saved` et
al.), the `curl /stats | jq .otel` verification, and the note that an
app-managed global meter provider is recorded into automatically.
- `docs/content/docs/metrics.mdx` — new `### Dynatrace` subsection:
copy-paste env block, `metrics.ingest` token scope, a `warn` Callout on
the delta-temporality requirement, the ActiveGate URL variant, the
Collector + `cumulativetodelta` alternative, and one paragraph
explaining that trace export needs `opentelemetry-instrument`
(Headroom's self-configured tracing targets Langfuse only).
- `docs/content/docs/proxy.mdx` — the `HEADROOM_OTEL_METRICS_ENABLED`
row now links to `/docs/metrics#opentelemetry-otlp-export`.

No code, config, or nav changes — the Observability nav slot already
points at `metrics.mdx`.

## Testing

- [ ] Unit tests pass (`pytest`)
- [ ] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`)
- [ ] New tests added for new functionality
- [x] Manual testing performed

Docs-only change: no Python touched, so pytest/ruff/mypy have nothing to
cover here. `next build` was **not** run — `docs/node_modules` is absent
in this checkout, which would require a full `npm install`; Vercel's
preview build is the real gate. In its place I verified the MDX cannot
break the build by parsing for the two things that actually fail MDX v3
— unbalanced JSX and bare `<`/`{` in prose.

### Test Output

```text
$ python - <<'PY'   # strip fenced + inline code, then scan prose for MDX hazards
...
PY
hazards: [(80, '<Tabs groupId="lang" items={[\'TypeScript\', \'Python\']}>'),
          (125, '<Tabs groupId="lang" items={[\'Python\', \'Proxy\']}>')]
Callout balance: 1 open / 1 close
```

Both flagged lines are pre-existing `<Tabs>` JSX expressions, untouched
by this PR. The added prose introduces no bare `<` or `{` (every
`<env-id>` / `<activegate>` placeholder sits inside a code fence or
inline backticks). `type="warn"` is already used on three other pages,
and the anchor `#opentelemetry-otlp-export` matches the GitHub-slugger
form of the new heading.

## Real Behavior Proof

- **Environment:** macOS (darwin 25.4.0), repo `.venv`,
`opentelemetry-sdk` 1.44.0, `opentelemetry-exporter-otlp-proto-http`,
headroom @ 6422a80a.
- **Exact command / steps:** verified the central claim of the new
Callout — that the OTLP HTTP exporter defaults to cumulative (which
Dynatrace rejects) and that the standard env var flips it to delta with
no Headroom code change:

```text
$ python -c '...'
DELTA= 1 CUMULATIVE= 2
default counter: 2

$ OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=DELTA python -c '...'
counter temporality with env=DELTA: 1
```

- **Observed result:**
`OTLPMetricExporter._preferred_temporality[Counter]` is `CUMULATIVE` (2)
by default and `DELTA` (1) with the env var set. Since every Headroom
OTEL instrument is a `Counter`
(`headroom/observability/metrics.py:136-189`), without the env var
Dynatrace drops all of them — matching its documented
`UNSUPPORTED_METRIC_TYPE_MONOTONIC_CUMULATIVE_SUM` rejection. Also
confirmed against the code that `HEADROOM_OTEL_METRICS_ENDPOINT` is
passed verbatim to the exporter (`metrics.py:539-543`), hence the doc's
warning that `/v1/metrics` must be included by hand, and that
`HEADROOM_OTEL_METRICS_HEADERS` splits on the first `=` so
`Authorization=Api-Token dt0c01...` parses correctly.
- **Not tested:** no live export against a real Dynatrace tenant — the
URL shapes and token scopes come from Dynatrace's docs, not from an
observed 200. The `opentelemetry-instrument` trace path is described
from the code's global-provider fallback (`tracing.py:95-99`), not run
end-to-end. `next build` not run (see Testing).

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my
feature works
- [ ] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Additional Notes

- N/A on the pytest / ruff / mypy / new-tests items: this PR changes two
`.mdx` files and no Python.
- Follow-up worth considering: `wiki/metrics.md:244` carries the same
OTEL variable table and still lacks the Dynatrace guidance — happy to
mirror it there, kept out of this PR to hold the diff to the Vercel docs
as asked.
- Second follow-up: the delta-temporality fix currently depends on an
upstream OTEL SDK env var that Headroom neither sets nor documents in
code. A `HEADROOM_OTEL_METRICS_TEMPORALITY=delta` passthrough would make
the Dynatrace case self-contained instead of relying on a variable one
layer down.
2026-08-04 18:46:39 -07:00
..
app docs: improve discoverability for AI agents and search crawlers 2026-05-13 17:36:06 -07:00
components docs: sync Vercel docs with current code and add in-depth proxy config (#2475) 2026-07-21 16:26:56 -07:00
content/docs docs(metrics): document OTLP metric export and Dynatrace ingest (#2785) 2026-08-04 18:46:39 -07:00
lib docs: sync Vercel docs with current code and add in-depth proxy config (#2475) 2026-07-21 16:26:56 -07:00
overrides fix: repair release and docs pipelines 2026-04-16 12:53:51 -05:00
screenshots Merge pull request #147 from JerrettDavis/feat/anthropic-usage-insights 2026-04-12 10:54:22 -07:00
.gitignore new docs UI + ts doc coverage 2026-04-12 13:15:58 +06:00
bun.lock fix(deps): remediate dependency CVEs and publish SBOM (#1509) 2026-06-27 15:28:12 -07:00
claude-code-bedrock-headroom.md fix(bedrock): route ARNs via converse, named AWS profiles, and au. re… (#1456) 2026-07-02 22:51:05 -05:00
next.config.mjs new docs UI + ts doc coverage 2026-04-12 13:15:58 +06:00
observability.md fix: remove rtk and lean-ctx CLI context tools (#2677) 2026-07-30 22:59:41 -07:00
package-lock.json deps: bump the npm-minor-patch group across 3 directories with 7 updates (#2276) 2026-07-21 11:21:14 -05:00
package.json deps: bump the npm-minor-patch group across 3 directories with 7 updates (#2276) 2026-07-21 11:21:14 -05:00
platform-feature-matrix.json fix: harden persistent install startup (#1851) 2026-07-10 00:40:34 -04:00
platform-stabilization.md fix: harden persistent install startup (#1851) 2026-07-10 00:40:34 -04:00
postcss.config.mjs new docs UI + ts doc coverage 2026-04-12 13:15:58 +06:00
proxy.ts new docs UI + ts doc coverage 2026-04-12 13:15:58 +06:00
README.md new docs UI + ts doc coverage 2026-04-12 13:15:58 +06:00
source.config.ts docs(ci): add CI/CD flow diagrams (#1062) 2026-06-16 23:05:15 -07:00
tsconfig.json new docs UI + ts doc coverage 2026-04-12 13:15:58 +06:00
vercel.json fix: add Vercel deploy config and workflow for docs site (#1739) 2026-07-14 13:25:18 -04:00

README.md

docs

This is a Next.js application generated with Create Fumadocs.

Run development server:

npm run dev
# or
pnpm dev
# or
yarn dev

Open http://localhost:3000 with your browser to see the result.

Explore

In the project, you can see:

  • lib/source.ts: Code for content source adapter, loader() provides the interface to access your content.
  • lib/layout.shared.tsx: Shared options for layouts, optional but preferred to keep.
Route Description
app/(home) The route group for your landing page and other pages.
app/docs The documentation layout and pages.
app/api/search/route.ts The Route Handler for search.

Fumadocs MDX

A source.config.ts config file has been included, you can customise different options like frontmatter schema.

Read the Introduction for further details.

Learn More

To learn more about Next.js and Fumadocs, take a look at the following resources: