Tutorials: OpenTelemetry

[predic8]

Summary by CodeRabbit

• New Features
  • Added an end-to-end OpenTelemetry tutorial demonstrating trace propagation across a gateway and backend services.
  • Included a complete OTLP-based tutorial configuration with full sampling for the example setup.
• Documentation
  • Expanded OpenTelemetry interceptor and OTLP exporter configuration documentation, including clearer YAML examples and attribute descriptions.
• Bug Fixes
  • Improved OTLP exporter handling for an empty path value (more reliable HTTP endpoint path resolution).
• Tests
  • Added tutorial tests to verify successful requests and confirm trace information in logs, including consistent traceparent hop behavior.

[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

Run ID: 7a233236-3492-45fa-8b99-0ec1565948e3

📥 Commits

Reviewing files that changed from the base of the PR and between 3b2c318 and 2969d5b.

📒 Files selected for processing (2)

• core/src/main/java/com/predic8/membrane/core/interceptor/opentelemetry/exporter/OtlpExporter.java
• distribution/src/test/java/com/predic8/membrane/tutorials/operation/OpenTelemetryTutorialTest.java

🚧 Files skipped from review as they are similar to previous changes (1)

• distribution/src/test/java/com/predic8/membrane/tutorials/operation/OpenTelemetryTutorialTest.java

---

📝 Walkthrough

Walkthrough

Adds an OpenTelemetry tutorial YAML with three chained APIs and a matching integration test. Expands Javadoc on the OpenTelemetry interceptor and exporter, and adjusts one exporter path check.

Changes

OpenTelemetry Tutorial and Documentation

Layer / File(s)	Summary
OpenTelemetryInterceptor Javadoc core/src/main/java/com/predic8/membrane/core/interceptor/opentelemetry/OpenTelemetryInterceptor.java	Expanded class-level and setter Javadoc covering span lifecycle, header propagation, MDC logging, customAttributes, exporter defaults, sampleRate, and CustomAttribute fields.
OtlpExporter documentation and path handling core/src/main/java/com/predic8/membrane/core/interceptor/opentelemetry/exporter/OtlpExporter.java	Expanded OTLP exporter Javadoc for transport, security, path, host, and headers, and changed empty-path detection in getPathExtension() to path.isEmpty().
OpenTelemetry tutorial configuration and test distribution/tutorials/operation/40-OpenTelemetry.yaml, distribution/src/test/java/com/predic8/membrane/tutorials/operation/OpenTelemetryTutorialTest.java	Added the 40-OpenTelemetry.yaml tutorial with global OTLP gRPC export config, Gateway → Microservice A → Microservice B trace propagation, and an integration test that asserts the gateway response and console trace output.

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant Gateway as Gateway :2000
  participant MicroserviceA as Microservice A :2001
  participant MicroserviceB as Microservice B :2002
  participant Jaeger as Jaeger OTLP :4317

  Client->>Gateway: HTTP request
  Gateway->>MicroserviceA: forward with traceparent header
  MicroserviceA->>MicroserviceB: forward with traceparent header
  MicroserviceB-->>MicroserviceA: static 200 response
  MicroserviceA-->>Gateway: response
  Gateway-->>Client: response
  Gateway->>Jaeger: export spans via gRPC
  MicroserviceA->>Jaeger: export spans via gRPC
  MicroserviceB->>Jaeger: export spans via gRPC

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• membrane/api-gateway#2211: Adds the CustomAttribute mechanism that this PR now documents in OpenTelemetryInterceptor.
• membrane/api-gateway#2971: Implements MDC traceId/spanId propagation that this PR documents and exercises in the tutorial test.

Suggested reviewers

• rrayst

Poem

🐇 Hop, hop, the traces glow,
From Gateway to the services below.
traceparent dances through the air,
Javadocs and tests now join the hare.
Jaeger shines where spans all go!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is concise and clearly points to the OpenTelemetry tutorial changes in this PR.
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 tutorials-opentelemetry

---

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]

Actionable comments posted: 3

🤖 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.

Inline comments:
In
`@core/src/main/java/com/predic8/membrane/core/interceptor/opentelemetry/exporter/OtlpExporter.java`:
- Around line 139-147: The secured flag description in OtlpExporter is
inconsistent with how getEndpointUrl() and buildGrpcExporter(...) actually use
it: when secured is true, the endpoint becomes https even for gRPC. Update the
Javadoc/@description on setSecured(boolean secured) to reflect that secured
affects both HTTP and gRPC endpoint URLs, or change the implementation to limit
secured to HTTP-only if that was the intended behavior.
- Around line 149-155: The HTTP path default handling in OtlpExporter#setPath is
using a reference comparison against an empty string, which can miss explicitly
configured empty values. Update the path default logic in OtlpExporter to check
for emptiness with isEmpty() when deciding whether to apply the /v1/traces
default, so both literal and configured empty strings are handled correctly.

In
`@distribution/src/test/java/com/predic8/membrane/tutorials/operation/OpenTelemetryTutorialTest.java`:
- Around line 59-69: The test traceparentIsPropagatedToBackend only waits for a
single traceparent substring, which can be satisfied by the Gateway alone and
does not prove end-to-end propagation. Update this test to follow the stronger
pattern used in OpenTelemetryExampleTest by capturing the trace ID from the
first hop and asserting matching traceparent logs across multiple downstream
hops (for example, Gateway plus Microservice A and B) using the existing console
event helper. Keep the assertion tied to the same trace ID so the test fails if
propagation breaks anywhere in the chain.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 19f5faed-8db8-4ed8-be0d-97285a64dcc3

📥 Commits

Reviewing files that changed from the base of the PR and between d7e3dfa and 3b2c318.

📒 Files selected for processing (4)

• core/src/main/java/com/predic8/membrane/core/interceptor/opentelemetry/OpenTelemetryInterceptor.java
• core/src/main/java/com/predic8/membrane/core/interceptor/opentelemetry/exporter/OtlpExporter.java
• distribution/src/test/java/com/predic8/membrane/tutorials/operation/OpenTelemetryTutorialTest.java
• distribution/tutorials/operation/40-OpenTelemetry.yaml

[rrayst]

/ok-to-test