Add tracing support with OpenTelemetry

[itssimon]

Summary by CodeRabbit

• New Features

  • Optional OpenTelemetry tracing: when enabled, request logs can include trace IDs and detailed span data.

• Configuration

  • New tracing-enabled flag to toggle span collection.

• Refactor

  • Logging component renamed and standardized to integrate with tracing.

• Tests

  • Added and updated tests covering tracing, span collection, and enhanced log output.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[codecov]

Codecov Report

❌ Patch coverage is 82.97872% with 32 lines in your changes missing coverage. Please review.
✅ Project coverage is 79.38%. Comparing base (378420b) to head (0ad2069).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
...rc/main/java/io/apitally/common/SpanCollector.java	86.90%	3 Missing and 8 partials ⚠️
...java/io/apitally/spring/ApitallySpanCollector.java	67.85%	5 Missing and 4 partials ⚠️
...c/main/java/io/apitally/spring/ApitallyFilter.java	84.37%	0 Missing and 5 partials ⚠️
.../io/apitally/spring/ApitallyAutoConfiguration.java	0.00%	4 Missing ⚠️
...rc/main/java/io/apitally/common/RequestLogger.java	75.00%	0 Missing and 2 partials ⚠️
...c/main/java/io/apitally/common/ApitallyClient.java	66.66%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##               main      #58      +/-   ##
============================================
+ Coverage     78.87%   79.38%   +0.50%     
- Complexity      362      408      +46     
============================================
  Files            36       39       +3     
  Lines          1302     1470     +168     
  Branches        164      185      +21     
============================================
+ Hits           1027     1167     +140     
- Misses          190      201      +11     
- Partials         85      102      +17     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[coderabbitai]

Walkthrough

Adds OpenTelemetry tracing: new SpanCollector and SpanData DTO, integrates span collection into request logging and filter, exposes tracing flag in RequestLoggingConfig, renames ApitallyAppender to LogAppender, introduces ApitallySpanCollector bridge, updates ApitallyClient, and adds OpenTelemetry SDK dependency and related tests.

Changes

Cohort / File(s)	Summary
Dependency Management pom.xml	Added dependency io.opentelemetry:opentelemetry-sdk:1.58.0.
Tracing core src/main/java/io/apitally/common/SpanCollector.java, src/main/java/io/apitally/common/dto/SpanData.java	New SpanCollector (span processor/collector with SpanHandle lifecycle, serialization and per-trace queuing) and new immutable SpanData DTO with Jackson annotations.
OpenTelemetry bridge src/main/java/io/apitally/spring/ApitallySpanCollector.java	New singleton ApitallySpanCollector implementing SpanProcessor that forwards to a delegate SpanCollector and wires a Tracer.
Client & Config src/main/java/io/apitally/common/ApitallyClient.java, src/main/java/io/apitally/common/RequestLoggingConfig.java	ApitallyClient gains a public spanCollector field initialized from config; RequestLoggingConfig adds tracingEnabled flag with getter/setter.
Request logging integration src/main/java/io/apitally/common/RequestLogger.java, src/main/java/io/apitally/common/dto/RequestLogItem.java	logRequest signature expanded to accept List<SpanData> spans and String traceId; RequestLogItem extended with spans and trace_id fields and getters; writer serializes these when present.
Log appender rename src/main/java/io/apitally/common/LogAppender.java	Renamed ApitallyAppender → LogAppender, updated NAME constant and registration uses.
Spring integration & filter src/main/java/io/apitally/spring/ApitallyAutoConfiguration.java, src/main/java/io/apitally/spring/ApitallyFilter.java	Replaced appender registration with LogAppender.register(); when tracing enabled, sets ApitallySpanCollector delegate to client.spanCollector. ApitallyFilter starts/ends span collection, derives span names from handler, captures spans and traceId, and passes them into logRequest.
Tests — updated src/test/java/io/apitally/common/ApitallyClientTest.java, src/test/java/io/apitally/common/LogAppenderTest.java, src/test/java/io/apitally/common/RequestLoggerTest.java, src/test/java/io/apitally/spring/ApitallyFilterTest.java	Tests updated to use LogAppender, to pass additional spans/traceId params to logRequest, and to enable/verify tracing where applicable.
Tests — new src/test/java/io/apitally/common/SpanCollectorTest.java	New unit tests for SpanCollector (enabled/disabled behavior, hierarchy, filtering, serialization).
Test support src/test/java/io/apitally/spring/app/TestController.java, src/test/resources/application.yml	TestController instrumented with a local OpenTelemetry span; test application.yml enables apitally.request-logging.log-capture-enabled: true and tracing-enabled: true.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

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

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Add tracing support with OpenTelemetry' accurately reflects the main objective and primary changes in the pull request, which adds comprehensive tracing capability via OpenTelemetry integration.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch simon/dev-11-add-tracing-support-to-java-sdk

---

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

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@src/main/java/io/apitally/common/ApitallyClient.java`:
- Around line 89-92: Currently ApitallyClient constructs SpanCollector with a
computed boolean (requestLoggingConfig.isEnabled() &&
requestLoggingConfig.isTracingEnabled()); change it to pass the full
RequestLoggingConfig instance instead so SpanCollector can read config at
runtime. Update the instantiation in ApitallyClient to new
SpanCollector(requestLoggingConfig) and modify the SpanCollector
constructor/signature to accept a RequestLoggingConfig (and internally evaluate
isEnabled/isTracingEnabled as needed), removing reliance on the precomputed
boolean; preserve existing semantics while enabling future runtime config
access.

In `@src/main/java/io/apitally/spring/ApitallySpanCollector.java`:
- Around line 33-47: The IllegalStateException branch in
initializeTracer(SpanCollector spanCollector) sets tracer from
GlobalOpenTelemetry but never informs users that the local SpanProcessor (this)
cannot be registered against an already-built provider; update that branch to
log a warning via logger.warn explaining that OpenTelemetry was already
configured, the local SdkTracerProvider/SdkSpanProcessor could not be attached
(so onStart/onEnd won't run), and that we're using the pre-existing tracer
instead, then proceed to set the tracer on spanCollector
(SpanCollector.setTracer(tracer)); reference initializeTracer,
SdkTracerProvider, GlobalOpenTelemetry, spanCollector, and logger in your
change.

🧹 Nitpick comments (1)

src/test/java/io/apitally/spring/app/TestController.java (1)

56-59: Consider using try-finally for proper span lifecycle.

While this is test code, using try-finally ensures the span is always ended, even if an exception occurs. This also demonstrates the recommended pattern for span management.

Suggested improvement

         Tracer tracer = GlobalOpenTelemetry.getTracer("test");
         Span childSpan = tracer.spanBuilder("fetchItemFromDatabase").startSpan();
-        childSpan.setAttribute("item.id", id);
-        childSpan.end();
-
-        TestItem item = new TestItem(id, "bob");
+        try {
+            childSpan.setAttribute("item.id", id);
+        } finally {
+            childSpan.end();
+        }
+        TestItem item = new TestItem(id, "bob");