api7 / api7/aisix

docs: write a 'connect observability exporters' tutorial, with end-to-end OTLP/HTTP verification

Open
#272 1 comment 1 reaction 0 assignees View on GitHub

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

  1. 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
  2. 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.