carvers/anwesen
5
0
Fork 0
Code Releases 4 Activity Actions

ANW-37 Telemetry: request metrics + selective traces over OTLP

Browse source 
Optional OTLP export of request-level metrics (request and response-byte
counters keyed by route/status/conditional-GET, a duration histogram out
to 600s) plus server spans for slow or 5xx requests, nested under the
incoming W3C trace context. Off unless an OTLP endpoint or uptrace DSN is
configured; a config-less server is byte-for-byte unchanged.
This commit is contained in:
Andreas Brenner 2026-07-24 20:29:06 +03:00
parent b271d57cbb
commit 23ce90e103
9 changed files with 2014 additions and 55 deletions
Download patch file Download diff file Expand all files Collapse all files

26
README.md
View file

@ -56,19 +56,31 @@ anwesen merge --vault /path/to/vault --query 'tags=adr&__anw-order=title' > ADRs
```
anwesen serve --vault <path> [--bind <addr:port>] [--log-level <level>]
[--uptrace-dsn <dsn> | --otlp-endpoint <url>]
[--otlp-header <key=value>]... [--otlp-slow-request-ms <n>]
anwesen doctor --vault <path>
anwesen merge --vault <path> --query <query-string>
anwesen version
```
| Flag | Env var | Default | Meaning |
| ------------------------ | ------------------- | ---------------------- | ----------------------------------------------------------------------- |
| `--vault <path>` | `ANWESEN_VAULT` | _required_ | Path to the vault root. |
| `--bind <addr:port>` | `ANWESEN_BIND` | `127.0.0.1:8080` | Listen address for `serve`. |
| `--log-level <level>` | `ANWESEN_LOG_LEVEL` | `info` | `error`, `warn`, `info`, `debug`, or `trace`. |
| `--query <query-string>` | -- | _required for `merge`_ | A `/query` query string: frontmatter predicates plus `__anw-` controls. |
| Flag | Env var | Default | Meaning |
| --------------------------- | ------------------------------ | ---------------------- | ----------------------------------------------------------------------------- |
| `--vault <path>` | `ANWESEN_VAULT` | _required_ | Path to the vault root. |
| `--bind <addr:port>` | `ANWESEN_BIND` | `127.0.0.1:8080` | Listen address for `serve`. |
| `--log-level <level>` | `ANWESEN_LOG_LEVEL` | `info` | `error`, `warn`, `info`, `debug`, or `trace`. |
| `--query <query-string>` | -- | _required for `merge`_ | A `/query` query string: frontmatter predicates plus `__anw-` controls. |
| `--uptrace-dsn <dsn>` | `ANWESEN_UPTRACE_DSN` | unset | uptrace DSN (`https://<token>@api.uptrace.dev`). Excludes `--otlp-endpoint`. |
| `--otlp-endpoint <url>` | `ANWESEN_OTLP_ENDPOINT` | unset | OTLP/HTTP base URL. Excludes `--uptrace-dsn`. |
| `--otlp-header <key=value>` | `ANWESEN_OTLP_HEADERS` | none | Extra export header, repeatable. The env var takes a comma-separated list. |
| `--otlp-slow-request-ms` | `ANWESEN_OTLP_SLOW_REQUEST_MS` | `500` | Requests at or over this duration, or answering 5xx, also export a span. |
Every flag has a matching `ANWESEN_<UPPER>` environment variable; CLI flags win over env vars.
Every flag has a matching `ANWESEN_<UPPER>` environment variable, except
`--otlp-header`, whose env var is the plural `ANWESEN_OTLP_HEADERS` because it
takes a list. CLI flags win over env vars.
Telemetry is off unless `--uptrace-dsn` or `--otlp-endpoint` is set. With
neither, nothing is exported and no exporter is built. The four telemetry
flags apply to `serve` only.
- **`serve`** -- run the daemon: walk the vault, build the index, watch for changes, serve the API.
- **`doctor`** -- walk the vault once and report what would stop clean ingestion: unreadable files, unparseable YAML, path collisions on the HTTP surface, and frontmatter type drift (the same key carrying incompatible types across notes). Read-only; non-zero exit if any issue is found.