feat: Add OpenTelemetry tracing spans for batch job operations

[JanCizmar]

Summary

• Added OpenTelemetry instrumentation to improve observability of batch job operations
• Added @WithSpan annotations to key methods handling database operations on activity tables
• Added span attributes to handleItem for better trace filtering

Changes

Dependencies

• Added io.opentelemetry.instrumentation:opentelemetry-instrumentation-annotations:2.10.0

Instrumented Components

OldBatchJobCleaner - Batch job cleanup operations:

• All cleanup methods including DELETE/UPDATE operations on activity tables

BatchJobActivityFinalizer - Activity revision merging:

• Methods handling UPDATE/DELETE operations on activity tables during job finalization

ChunkProcessingUtil - Chunk processing:

• Main chunk processing logic

BatchJobActionService - Chunk execution:

• Database locking and chunk execution handling
• Added span attributes: batch.job.id, batch.chunk.execution.id, project.id

Benefits

• Properly named spans for all batch job operations visible in tracing tools
• Easy filtering and identification of specific jobs, chunks, and projects
• Better visibility into DELETE/UPDATE operations on activity tables (activity_revision, activity_modified_entity, activity_describing_entity)

Testing

• Code compiles successfully
• ktlint formatting applied

🤖 Generated with Claude Code

Summary by CodeRabbit

• Chores
  • Enhanced system observability and monitoring infrastructure: Added comprehensive tracing and instrumentation support across batch processing operations, enabling improved visibility into system behavior, performance diagnostics, and troubleshooting capabilities. Updated build dependencies to support modern observability standards throughout the batch job lifecycle.

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR adds OpenTelemetry instrumentation annotations and tracing spans to batch job processing services. Build configuration is updated with the opentelemetry-instrumentation-annotations dependency and version property. The @WithSpan annotation is applied to multiple methods across batch service classes for observability without altering logic or control flow.

Changes

Cohort / File(s)	Summary
Build Configuration gradle.properties, settings.gradle, backend/data/build.gradle	Added new OpenTelemetry instrumentation dependency. Updated gradle.properties with opentelemetryInstrumentationVersion=2.24.0 and revised OpenTelemetry comment. Added opentelemetryInstrumentationAnnotations to the libs version catalog in settings.gradle.
Batch Job Service Tracing backend/data/src/main/kotlin/io/tolgee/batch/BatchJobActionService.kt	Applied @WithSpan annotation to handleItem and getExecutionIfCanAcquireLockInDb methods. Added span attribute setting for batch.job.id, batch.chunk.execution.id, and project.id; enhanced error handling with recordException and ERROR status in catch block.
Batch Job Activity & Cleanup Finalization backend/data/src/main/kotlin/io/tolgee/batch/BatchJobActivityFinalizer.kt, backend/data/src/main/kotlin/io/tolgee/batch/cleaning/OldBatchJobCleaner.kt	Applied @WithSpan annotation to multiple methods (finalizeActivityWhenJobCompleted, setJobIdAndAuthorIdToRevision, deleteUnusedRevisions, mergeModifiedEntities, mergeDescribingEntities, removeDuplicityDescribingEntities in ActivityFinalizer; cleanup, cleanupCompletedJobs, cleanupFailedJobs, deleteJobsOlderThan, deleteJobBatch, nullifyActivityRevisionReferences, and related methods in OldBatchJobCleaner) for distributed tracing.
Chunk Processing backend/data/src/main/kotlin/io/tolgee/batch/ChunkProcessingUtil.kt	Applied @WithSpan annotation to processChunk function to enable tracing around chunk processing.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰 Hops through the code with observability grace,
Tracing each span at a quickened pace,
OpenTelemetry annotations bloom,
Lighting the batch jobs' processing room!
Distributed insights now flow like spring rain, ☔✨

🚥 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 'feat: Add OpenTelemetry tracing spans for batch job operations' directly and accurately summarizes the main change: adding OpenTelemetry instrumentation with @WithSpan annotations across batch job components.

_{✏️ 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 jancizmar/add-opentelemetry-tracing-spans

Important

Action Needed: IP Allowlist Update

If your organization protects your Git platform with IP whitelisting, please add the new CodeRabbit IP address to your allowlist:

• ✨ 136.113.208.247/32 (new)
• 34.170.211.100/32
• 35.222.179.152/32

Failure to add the new IP will result in interrupted reviews.

---

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

[coderabbitai]

Actionable comments posted: 2

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

backend/data/src/main/kotlin/io/tolgee/batch/BatchJobActionService.kt (1)

254-271: ⚠️ Potential issue | 🟡 Minor

Remove @WithSpan annotation from private method or refactor to separate bean.

Spring AOP proxies cannot intercept private methods (CGLIB cannot override private methods), and since getExecutionIfCanAcquireLockInDb is invoked via self-invocation from getPendingUnlockedExecutionItem, the @WithSpan annotation will not create a span.

Either remove the annotation (the parent span from handleItem already covers this operation), make the method public and call it through a separate Spring-managed bean, or use manual span creation similar to handleItem if dedicated tracing for this lock acquisition is needed.

🤖 Fix all issues with AI agents

In `@backend/data/build.gradle`:
- Line 185: Update the OpenTelemetry instrumentation annotations dependency
version from 2.10.0 to 2.24.0 by changing the implementation declaration that
references
"io.opentelemetry.instrumentation:opentelemetry-instrumentation-annotations:2.10.0"
to use 2.24.0; optionally extract this coordinate into the project’s version
catalog (so other modules can reference a managed version) and replace the
literal with the catalog reference to keep dependency versions consistent.

In
`@backend/data/src/main/kotlin/io/tolgee/batch/BatchJobProjectLockingManager.kt`:
- Line 3: Remove the unused import
io.opentelemetry.instrumentation.annotations.WithSpan from the
BatchJobProjectLockingManager file; locate the import block at the top of the
file (around class BatchJobProjectLockingManager) and delete that specific
import line so the file no longer references WithSpan.

🧹 Nitpick comments (1)

backend/data/src/main/kotlin/io/tolgee/batch/cleaning/OldBatchJobCleaner.kt (1)

102-116: Consider span attribute for batch size context.

The deleteJobBatch span would benefit from attributes indicating how many jobs/chunks are being processed in this batch, similar to how BatchJobActionService.handleItem adds context attributes.

💡 Optional enhancement for span attributes

+ import io.opentelemetry.api.trace.Span
+
  `@WithSpan`
  private fun deleteJobBatch(
    statuses: List<String>,
    cutoffDate: Date,
  ): Pair<Int, Int> {
    val jobIds = findJobIdsToDelete(statuses, cutoffDate)
    if (jobIds.isEmpty()) return Pair(0, 0)
+   Span.current().setAttribute("batch.job.count", jobIds.size.toLong())

    val executionIds = findExecutionIds(jobIds)
+   Span.current().setAttribute("batch.execution.count", executionIds.size.toLong())

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@gradle.properties`:
- Around line 12-14: The opentelemetryInstrumentationVersion constant is out of
sync with opentelemetryJavaagentVersion; update
opentelemetryInstrumentationVersion to the same release string as
opentelemetryJavaagentVersion (set opentelemetryInstrumentationVersion to
2.24.0) so both versions align (look for the opentelemetryJavaagentVersion and
opentelemetryInstrumentationVersion entries in gradle.properties).

In `@settings.gradle`:
- Line 82: Update the OpenTelemetry annotation version so it matches the
javaagent: change the opentelemetryInstrumentationVersion value in
gradle.properties to 2.24.0 so the dependency declared with
library('opentelemetryInstrumentationAnnotations',
'io.opentelemetry.instrumentation',
'opentelemetry-instrumentation-annotations').version(opentelemetryInstrumentationVersion)
uses the same 2.x version as the opentelemetry-javaagent.

[gabrielshanahan]

Superseded by #3450