feat: add OpenTelemetry tracing to branching operations

[bdshadow]

Add distributed tracing with @WithSpan annotations and span attributes to branch creation, merge preview, and merge execution. This enables performance analysis to identify bottlenecks in branching operations.

Traced operations include:

• Branch creation (BranchServiceImpl.createBranch)
• Branch copy with batched SQL operations (BranchCopyServiceSql)
• Merge dry-run/preview (BranchMergeService.dryRun)
• Merge execution (BranchMergeExecutor.execute)
• Snapshot management (BranchSnapshotService)
• Merge analysis (BranchMergeAnalyzer.compute)

Span attributes capture project/branch IDs, branch names, key counts, and merge change breakdowns (additions, updates, deletions, conflicts).

Summary by CodeRabbit

• Chores
  • Added distributed tracing infrastructure across branch management services for enhanced system observability
  • Implemented comprehensive operation tracking and performance instrumentation for branch creation, merging, copying, and snapshot management
  • Enhanced monitoring capabilities to improve diagnostic visibility and performance analysis of branch-related workflows
  • Improved system instrumentation for better troubleshooting and operational insights

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds OpenTelemetry distributed tracing instrumentation across branching-related services, including dependency additions, constructor injections of TolgeeTracingContext, @WithSpan annotations on key methods, and helper methods to populate span attributes with branch and merge operation metadata.

Changes

Cohort / File(s)	Summary
OpenTelemetry Dependencies ee/backend/app/build.gradle	Added two OpenTelemetry dependencies (libs.opentelemetryApi and libs.opentelemetryInstrumentationAnnotations) for distributed tracing support.
Branch Service Tracing ee/backend/app/src/main/kotlin/io/tolgee/ee/service/branching/BranchServiceImpl.kt, BranchSnapshotService.kt	Added @WithSpan annotations and TolgeeTracingContext dependency injection. Implemented tracing attribute helpers (setCreateBranchTracingAttributes, setApplyMergeTracingAttributes) to record branch and merge metadata on spans.
Branch Copy Tracing ee/backend/app/src/main/kotlin/io/tolgee/ee/service/branching/BranchCopyServiceSql.kt	Injected TolgeeTracingContext into constructor. Added setTracingAttributes method and @WithSpan annotations on 9 internal helper methods (createKeyMappingTable, createKeyMapping, copyKeyMetas, etc.) to trace copy operation flow and record source/target branch and batch sizing attributes.
Branch Merge Service Tracing ee/backend/app/src/main/kotlin/io/tolgee/ee/service/branching/BranchMergeService.kt, merging/BranchMergeAnalyzer.kt, merging/BranchMergeExecutor.kt	Injected TolgeeTracingContext into constructors. Added @WithSpan annotations on public methods (dryRun, applyMerge, compute) and private methods (attachKeysForMerge, applyConflict, applyUpdate, applyAddition, applyDeletion, persistAfterMerge). Implemented tracing attribute helpers to record merge ID, changes count, operation types (additions, updates, deletions, conflicts), and source/target branch metadata.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~30 minutes

Possibly related PRs

• tolgee-platform#3450 — Adds OpenTelemetry instrumentation and reuses the same tracing infrastructure (TolgeeTracingContext, @WithSpan annotations), representing coordinated tracing enhancements across the codebase.

Suggested reviewers

• JanCizmar

Poem

🐰 Tracing spans now flutter through the branches bright,
Each operation glimmers in the telemetry light,
From copy to merge, the story's now told,
With attributes shining, more insights to behold!
hops excitedly ✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 26.19% 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 to branching operations' accurately and clearly summarizes the main change—adding distributed tracing via OpenTelemetry to branching-related operations, which is the core focus across all modified files.

_{✏️ 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 bdshadow/add-tracing-to-branching

---

No actionable comments were generated in the recent review. 🎉

🧹 Recent nitpick comments

ee/backend/app/src/main/kotlin/io/tolgee/ee/service/branching/BranchMergeService.kt (1)

113-151: Minor Stepdown Rule violation: applyMerge appears after its helper.

setApplyMergeTracingAttributes (line 126) is placed before its caller applyMerge (line 139). Per the Stepdown Rule, a caller should appear before the functions it calls. Consider moving applyMerge above the two private tracing helpers, or grouping each helper directly below its caller.

As per coding guidelines, **/*.{ts,tsx,js,jsx,kt,kts}: "Functions should be ordered so that a caller appears before the functions it calls."

ee/backend/app/src/main/kotlin/io/tolgee/ee/service/branching/BranchServiceImpl.kt (1)

159-187: Minor Stepdown Rule note: tracing helpers placed before applyMerge caller.

Same pattern as in BranchMergeService — setApplyMergeTracingAttributes (line 172) appears before its caller applyMerge (line 228). Consider moving these helpers below their respective callers.

As per coding guidelines, **/*.{ts,tsx,js,jsx,kt,kts}: "Functions should be ordered so that a caller appears before the functions it calls."

---

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 and usage tips.}

[dkrizan]

This might sound silly, but I really don't like having all the tracing code directly inside the services, it makes them feel bloated and harder to read .. I’d personally prefer moving this into a separate layer/service if possible .. wdyt ?

[bdshadow]

i also don't like it, so at least moved it to separate methods. And asked Gabe for the same thing in his pr. We still don't have it in many places so it can be a good time to move it.
However, seems like the attributes of span are very context specific, so i'm not sure right now how to make it more universal. Probably there is a way