docs: write a 'connect observability exporters' tutorial, with end-to-end OTLP/HTTP verification
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 157
- Forks
- 32
- Avg merge
- 1h 25m
- Merged PRs (30d)
- 145
Description
Context
docs/tutorials/connect-observability-exporters.md was added as a 24-line skeleton in #249 but did not include an executable verification step. It was removed in the docs-rebuild-batch-1 follow-up because the only honest verification ("the trace shows up in the collector") requires standing up a local OTel collector or Jaeger in the tutorial, and there is no e2e test covering the full export path today.
What we need
- An e2e test in `tests/e2e/src/cases/observability-exporter-e2e.test.ts` that:
- starts a mock OTLP/HTTP receiver in the test harness (or uses `testcontainers` to spin up an OTel collector)
- creates an `ObservabilityExporter` resource via admin API (`kind: "otlp_http"`, endpoint pointing at the mock receiver)
- sends one chat-completion request through the gateway
- asserts the receiver got at least one span / metric / log within a bounded wait window
- Once the test lands, restore `docs/tutorials/connect-observability-exporters.md` to a Kong-cookbook-tier walkthrough. The tutorial should include the docker / collector setup so the reader can reproduce the verification locally, not just trust a CI test.
Why we removed it
The skeleton's "verify span or telemetry reception on the receiver side" line was not actionable without a concrete collector setup, and writing one without an e2e test would have meant fabricating steps that no automated test pins against drift.
Reference
- Resource: `crates/aisix-core/src/models/observability_exporter.rs`
- Configuration page: `docs/configuration/observability-exporters.md`
- Tutorial template: `~/.claude/skills/ai-gateway-tech-writer/templates/tutorial-cookbook-template.md`
Definition of done
- e2e test added with a mock OTLP receiver and green in CI
- `docs/tutorials/connect-observability-exporters.md` restored, Kong-tier shape, with collector setup in the tutorial AND citing the e2e test as the contract anchor
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with tests/e2e/src/cases/observability-exporter-e2e.test.ts, crates/aisix-core/src/models/observability_exporter.rs, and docs/configuration/observability-exporters.md. Run the existing e2e setup to understand the harness, then use the tutorial template as the documentation guide. Done means the e2e case verifies telemetry from an otlp_http resource and docs/tutorials/connect-observability-exporters.md explains reproducible collector setup and cites the test.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- docker, rust, typescript
- Domain
- backend, documentation, observability, testing-qa
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 45/100