feat: add tutorial for lokiExchangeStore

[rrayst]

Adds tutorials/operation/70-Loki.yaml, teaching how to push exchanges to Grafana Loki and query them with LogQL. It follows on from the Prometheus and Grafana steps: those cover aggregate metrics, this one covers the content of individual calls.

The tutorial walks through starting Loki and Grafana, generating traffic on two named APIs, and querying by stream label, by json stage and by line_format. It also notes the three things that surprise people: only finished exchanges are pushed, bodies are Base64-encoded inside the JSON, and the store is write-only.

Support files: a docker-compose for Loki and Grafana with the Loki datasource pre-provisioned.

LokiTutorialTest verifies the lesson end-to-end. A local router stands in for Loki on the port the tutorial configures, so the push is asserted without needing a container: the job and api labels, and log lines that render as the tutorial's line_format claims.

Summary by CodeRabbit

• New Features

  • Added a tutorial for recording API exchanges in Grafana Loki.
  • Included sample APIs demonstrating successful and not-found responses.
  • Added Docker Compose setup for Loki and Grafana with automatic datasource configuration.

• Documentation

  • Documented Loki setup, querying, labels, batching, body handling, write-only mode, and troubleshooting.

• Tests

  • Added end-to-end coverage verifying exchange data is sent to Loki with request and response details.

[rrayst]

/ok-to-test

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 4a9654e5-d2eb-40e2-a100-f826e7c99da7

📥 Commits

Reviewing files that changed from the base of the PR and between 75704a2 and 7df4df9.

📒 Files selected for processing (2)

• distribution/src/test/java/com/predic8/membrane/tutorials/operation/LokiTutorialTest.java
• distribution/tutorials/operation/70-Record-Messages-In-Loki.yaml

---

📝 Walkthrough

Walkthrough

The PR adds a Loki and Grafana tutorial, a Loki exchange-store configuration with sample APIs, and an end-to-end test that captures and validates Loki push payloads.

Changes

Loki tutorial

Layer / File(s)	Summary
Loki and Grafana environment distribution/tutorials/operation/loki/docker-compose.yml, distribution/tutorials/operation/loki/provisioning/datasources/datasource.yml	Adds Loki and Grafana services. Grafana uses Loki as its default proxied datasource.
Gateway Loki configuration distribution/tutorials/operation/70-Record-Messages-In-Loki.yaml	Configures exchange recording to Loki with job label membrane-instance-1. Adds sample APIs that return HTTP 200 and 404 responses. Documents setup, queries, batching, body handling, write-only behavior, and troubleshooting.
End-to-end Loki validation distribution/src/test/java/com/predic8/membrane/tutorials/operation/LokiTutorialTest.java	Starts and stops an embedded Loki mock, executes both sample API requests, captures push payloads, polls labeled streams, and validates method, URI, and status code fields.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant LokiTutorialTest
  participant MembraneRouter
  participant BackendA
  participant BackendB
  participant MockLokiRouter
  LokiTutorialTest->>MembraneRouter: Send successful and failed API requests
  MembraneRouter->>BackendA: Invoke API returning 200
  BackendA-->>MembraneRouter: Return 200
  MembraneRouter->>MockLokiRouter: Push exchange payload
  MembraneRouter->>BackendB: Invoke API returning 404
  BackendB-->>MembraneRouter: Return 404
  MembraneRouter->>MockLokiRouter: Push exchange payload
  LokiTutorialTest->>MockLokiRouter: Poll and validate captured streams

Loading

Possibly related PRs

• membrane/api-gateway#3106: Introduces the LokiExchangeStore used and tested by this tutorial.

Poem

A rabbit hops where Loki streams,
With Grafana charts and logging dreams.
Two APIs answer, one bright, one sore,
Their paths and statuses count once more.
The mock catches every push with care,
While carrots sparkle in the air.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding a tutorial for lokiExchangeStore.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat-tutorial-loki

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

🧹 Nitpick comments (1)

distribution/tutorials/operation/loki/docker-compose.yml (1)

3-3: 🔒 Security & Privacy | 🔵 Trivial | ⚡ Quick win

Update the pinned Loki and Grafana image versions.

grafana/loki:2.9.8 and grafana/grafana:9.5.2 are previous major versions. Update these tags to current stable releases so the tutorial does not ship unpatched images.

Also applies to the Grafana-compose pin for grafana/grafana:9.5.2.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@distribution/tutorials/operation/loki/docker-compose.yml` at line 3, Update
the image tags in the Loki Docker Compose configuration, including the
grafana/loki image and the grafana/grafana image, from their outdated pinned
versions to current stable releases. Keep the images pinned to explicit stable
version tags rather than using floating tags.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@distribution/tutorials/operation/loki/docker-compose.yml`:
- Line 3: Update the image tags in the Loki Docker Compose configuration,
including the grafana/loki image and the grafana/grafana image, from their
outdated pinned versions to current stable releases. Keep the images pinned to
explicit stable version tags rather than using floating tags.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 608d2720-571f-4b46-9c6a-1c3ff444fa09

📥 Commits

Reviewing files that changed from the base of the PR and between b7442bd and 75704a2.

📒 Files selected for processing (4)

• distribution/src/test/java/com/predic8/membrane/tutorials/operation/LokiTutorialTest.java
• distribution/tutorials/operation/70-Loki.yaml
• distribution/tutorials/operation/loki/docker-compose.yml
• distribution/tutorials/operation/loki/provisioning/datasources/datasource.yml