[OPIK-2497] [BE] [FE] Add bulk tag operations for traces, spans and threads #3920

YarivHashaiComet · 2025-11-03T15:54:54Z

Details

https://www.loom.com/share/ea176178bbae43338a8247ff45605c8e

This PR implements batch tag update operations for traces, spans, and threads, allowing users to efficiently update tags for multiple items at once.

Backend Changes

Added new batch update endpoints in SpansResource and TracesResource for traces, spans, and threads
Created new API models: SpanBatchUpdate, TraceBatchUpdate, and TraceThreadBatchUpdate
Implemented DAO methods in SpanDAO, TraceDAO, and TraceThreadDAO to handle batch tag operations efficiently
Added service layer methods in SpanService, TraceService, and TraceThreadService for batch updates
Introduced BatchOperationsConfig for configurable batch operation limits
Added comprehensive test coverage with 508 new test lines in SpansResourceTest and TracesResourceTest

Frontend Changes

Created React Query hooks for batch mutations:
- useSpanBatchUpdateMutation
- useTraceBatchUpdateMutation
- useThreadBatchUpdateMutation
Refactored AddTagDialog component to support batch operations
Updated ThreadsActionsPanel to integrate batch tag updates
Enhanced UX for bulk tag operations in the traces UI

Configuration

Added batch operation configuration in config.yml with size limits and validation

Change checklist

User facing
Documentation update

Issues

Resolves #
OPIK-2497

Testing

Unit tests added for all three batch endpoints (traces, spans, threads)
Tests cover:
- Successful batch updates with multiple items
- Tag addition and removal operations
- Validation of batch size limits
- Error handling for invalid inputs
- Empty and null tag scenarios
Manual testing performed on ThreadsTab UI with bulk selection and tag operations

Documentation

API endpoint documentation to be added for new batch operations
Configuration documentation for BatchOperationsConfig settings

github-actions · 2025-11-03T15:56:59Z

🌿 Preview your docs: https://opik-preview-16b57c7e-3e71-4ffa-94fd-9b35c46744b2.docs.buildwithfern.com/docs/opik

The following broken links where found:

Page:
❌ Broken link: {} ()

Page:
❌ Broken link: ] ()

Page:
❌ Broken link: {} ()

Page:
❌ Broken link: ] ()

Page: https://opik-preview-16b57c7e-3e71-4ffa-94fd-9b35c46744b2.docs.buildwithfern.com/docs/opik/integrations/gretel
❌ Broken link: https://docs.gretel.ai/create-synthetic-data/gretel-data-designer/ (404)

Page: https://opik-preview-16b57c7e-3e71-4ffa-94fd-9b35c46744b2.docs.buildwithfern.com/docs/opik/integrations/gretel/
❌ Broken link: https://docs.gretel.ai/create-synthetic-data/gretel-data-designer/ (404)

github-actions · 2025-11-03T15:58:11Z

🌿 Preview your docs: https://opik-preview-e0aa25e5-f681-4d62-b690-25f6aa194226.docs.buildwithfern.com/docs/opik

The following broken links where found:

Page: https://opik-preview-e0aa25e5-f681-4d62-b690-25f6aa194226.docs.buildwithfern.com/docs/opik/integrations/gretel
❌ Broken link: https://docs.gretel.ai/create-synthetic-data/gretel-data-designer/ (404)

Page: https://opik-preview-e0aa25e5-f681-4d62-b690-25f6aa194226.docs.buildwithfern.com/docs/opik/integrations/gretel/
❌ Broken link: https://docs.gretel.ai/create-synthetic-data/gretel-data-designer/ (404)

github-actions · 2025-11-03T16:20:13Z

🌿 Preview your docs: https://opik-preview-9b77cd39-88fa-46c6-99e4-cc329e42e5c0.docs.buildwithfern.com/docs/opik

The following broken links where found:

Page: https://opik-preview-9b77cd39-88fa-46c6-99e4-cc329e42e5c0.docs.buildwithfern.com/docs/opik/integrations/gretel
❌ Broken link: https://docs.gretel.ai/create-synthetic-data/gretel-data-designer/ (404)

Page: https://opik-preview-9b77cd39-88fa-46c6-99e4-cc329e42e5c0.docs.buildwithfern.com/docs/opik/integrations/gretel/
❌ Broken link: https://docs.gretel.ai/create-synthetic-data/gretel-data-designer/ (404)

Page: https://opik-preview-9b77cd39-88fa-46c6-99e4-cc329e42e5c0.docs.buildwithfern.com/docs/opik/integrations/gretel
❌ Broken link: https://docs.gretel.ai/ (404)

Page: https://opik-preview-9b77cd39-88fa-46c6-99e4-cc329e42e5c0.docs.buildwithfern.com/docs/opik/integrations/gretel/
❌ Broken link: https://docs.gretel.ai/ (404)

Page:
❌ Broken link: {} ()

Page:
❌ Broken link: ] ()

Page:
❌ Broken link: {} ()

Page:
❌ Broken link: ] ()

github-actions · 2025-11-03T16:47:02Z

Backend Tests Results

295 files 295 suites 50m 32s ⏱️
5 493 tests 5 486 ✅ 7 💤 0 ❌
5 454 runs 5 447 ✅ 7 💤 0 ❌

Results for commit 4a1d0f8.

♻️ This comment has been updated with latest results.

github-actions · 2025-11-03T17:55:08Z

🌿 Preview your docs: https://opik-preview-a62a4ad2-3f90-40bb-8552-d0b946071b7f.docs.buildwithfern.com/docs/opik

The following broken links where found:

Page: https://opik-preview-a62a4ad2-3f90-40bb-8552-d0b946071b7f.docs.buildwithfern.com/docs/opik/integrations/gretel
❌ Broken link: https://docs.gretel.ai/create-synthetic-data/gretel-data-designer/ (404)

Page: https://opik-preview-a62a4ad2-3f90-40bb-8552-d0b946071b7f.docs.buildwithfern.com/docs/opik/integrations/gretel/
❌ Broken link: https://docs.gretel.ai/create-synthetic-data/gretel-data-designer/ (404)

Page: https://opik-preview-a62a4ad2-3f90-40bb-8552-d0b946071b7f.docs.buildwithfern.com/docs/opik/contributing/guides/backend
❌ Broken link: https://docs.liquibase.com/secure/user-guide-5-0/what-is-a-rollback (429)

Page: https://opik-preview-a62a4ad2-3f90-40bb-8552-d0b946071b7f.docs.buildwithfern.com/docs/opik/contributing/guides/backend/
❌ Broken link: https://docs.liquibase.com/secure/user-guide-5-0/what-is-a-rollback (429)

github-actions · 2025-11-03T18:25:42Z

🌿 Preview your docs: https://opik-preview-db6a5713-4f3e-40d4-814d-967a97980e95.docs.buildwithfern.com/docs/opik

The following broken links where found:

Page: https://opik-preview-db6a5713-4f3e-40d4-814d-967a97980e95.docs.buildwithfern.com/docs/opik/contributing/guides/backend
❌ Broken link: https://docs.liquibase.com/secure/user-guide-5-0/what-is-a-rollback (429)

Page: https://opik-preview-db6a5713-4f3e-40d4-814d-967a97980e95.docs.buildwithfern.com/docs/opik/contributing/guides/backend/
❌ Broken link: https://docs.liquibase.com/secure/user-guide-5-0/what-is-a-rollback (429)

Page: https://opik-preview-db6a5713-4f3e-40d4-814d-967a97980e95.docs.buildwithfern.com/docs/opik/integrations/gretel
❌ Broken link: https://docs.gretel.ai/create-synthetic-data/gretel-data-designer/ (404)

Page: https://opik-preview-db6a5713-4f3e-40d4-814d-967a97980e95.docs.buildwithfern.com/docs/opik/integrations/gretel/
❌ Broken link: https://docs.gretel.ai/create-synthetic-data/gretel-data-designer/ (404)

Page: https://opik-preview-db6a5713-4f3e-40d4-814d-967a97980e95.docs.buildwithfern.com/docs/opik/integrations/gretel
❌ Broken link: https://docs.gretel.ai/ (404)

Page: https://opik-preview-db6a5713-4f3e-40d4-814d-967a97980e95.docs.buildwithfern.com/docs/opik/integrations/gretel/
❌ Broken link: https://docs.gretel.ai/ (404)

andrescrz · 2025-11-04T10:26:02Z

Let's check the overlap with this other PR:

[issue-3494] [FE] [BE] Ability to add tags to multiple threads #3494 #3715

There was a PR review there and feedback comments, and also a decent implementation that you can use as a base.

andrescrz

Left a preliminary review on this draft, with the stuff to be addressed.

apps/opik-backend/src/main/java/com/comet/opik/api/SpanBatchTagUpdate.java

apps/opik-backend/src/main/java/com/comet/opik/domain/SpanDAO.java

apps/opik-backend/src/main/java/com/comet/opik/domain/SpanService.java

apps/opik-documentation/documentation/fern/openapi/opik.yaml

github-actions · 2025-11-10T07:34:26Z

SDK E2E Tests Results

0 tests 0 ✅ 0s ⏱️
0 suites 0 💤
0 files 0 ❌

Results for commit 4a1d0f8.

♻️ This comment has been updated with latest results.

Copilot

Pull Request Overview

This PR adds batch tag operations for traces, spans, and threads, removing the 10-item limitation and enabling users to tag up to 1000 items simultaneously. The implementation includes both backend API endpoints and frontend UI integration.

Key changes:

New batch update endpoints for traces, spans, and threads with configurable tag merge/replace behavior
Comprehensive test coverage with 17 new tests covering success paths, validation, and edge cases
Frontend batch mutation hooks replacing individual update operations

Reviewed Changes

Copilot reviewed 24 out of 24 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
`ThreadsTab.tsx`	Added callback prop to clear selection after successful tag operation
`ThreadsActionsPanel.tsx`	Integrated "Add tags" button and dialog for threads, reordered buttons to accommodate new feature
`AddTagDialog.tsx`	Refactored to use batch operations, removed 10-item limit, added thread support
`useTraceBatchUpdateMutation.ts`	New mutation hook for batch trace tag updates
`useThreadBatchUpdateMutation.ts`	New mutation hook for batch thread tag updates
`useSpanBatchUpdateMutation.ts`	New mutation hook for batch span tag updates
`TracesResourceTest.java`	Added comprehensive test suite for trace batch operations
`SpansResourceTest.java`	Added test suite for span batch operations
`TraceResourceClient.java`	Added client methods for batch update API calls
`SpanResourceClient.java`	Added client method for span batch updates
`BatchOperationsConfig.java`	Added analytics config for bulk update chunk sizes and streaming buffer
`TraceThreadService.java`	Implemented batch update logic with tag merging support
`TraceThreadIdService.java`	Added method to retrieve thread ID models by thread model IDs
`TraceThreadDAO.java`	Implemented bulk tag update queries with chunking for efficient ClickHouse operations
`TraceService.java`	Implemented batch update orchestration with tag merge logic
`TraceDAO.java`	Added bulk tag update implementation with StringTemplate error suppression
`SpanService.java`	Implemented span batch update with tag merging
`SpanDAO.java`	Added span bulk update queries with chunking support
`TracesResource.java`	Added REST endpoints for trace and thread batch updates
`SpansResource.java`	Added REST endpoint for span batch updates
`TraceThreadBatchUpdate.java`	DTO for thread batch update requests
`TraceBatchUpdate.java`	DTO for trace batch update requests
`SpanBatchUpdate.java`	DTO for span batch update requests
`config.yml`	Added configuration for bulk update chunk size and stream buffer size

apps/opik-backend/src/main/java/com/comet/opik/domain/TraceDAO.java

apps/opik-frontend/src/components/pages-shared/traces/AddTagDialog/AddTagDialog.tsx

apps/opik-backend/src/main/java/com/comet/opik/domain/threads/TraceThreadDAO.java

apps/opik-backend/src/main/java/com/comet/opik/domain/TraceDAO.java

github-actions · 2025-11-12T10:53:30Z

🔄 Test environment deployment started

Building images for PR #3920...

You can monitor the build progress here.

apps/opik-backend/src/main/java/com/comet/opik/domain/SpanDAO.java

CometActions · 2025-11-12T11:02:15Z

✅ Test environment is now available!

Access Information

URL: https://pr-3920.dev.comet.com
Cluster: comet-ml-development
Namespace: pr-3920
Version: 1.9.8.3920-merge-383
Application logs: View in Grafana

The deployment has completed successfully and the version has been verified.

andriidudar

The frontend side looks very good — great work! 👏
I’ve left two comments; it’s up to you to decide how you’d like to proceed with them.
Frontend part is approved ✅

apps/opik-frontend/src/components/pages-shared/traces/AddTagDialog/AddTagDialog.tsx

apps/opik-frontend/src/components/pages/TracesPage/ThreadsTab/ThreadsTab.tsx

andrescrz

This new revision still has a hybrid approach were data is queried and service level and then queried again and inserted.

In addition, it has a chunking mechanism that increases complexity without providing benefits.

These endpoints can be implemented in a much simpler manner, specially because they don't provide concurrency guarantees (like the individual create/update span and trace etc. endpoints).

I gave guidance to accomplish this.

apps/opik-backend/config.yml

apps/opik-backend/src/main/java/com/comet/opik/domain/SpanDAO.java

apps/opik-backend/src/main/java/com/comet/opik/domain/TraceDAO.java

apps/opik-backend/src/main/java/com/comet/opik/domain/SpanDAO.java

andrescrz · 2025-11-12T14:06:58Z

apps/opik-backend/src/main/java/com/comet/opik/domain/SpanService.java

    }

+    @WithSpan
+    public Mono<Void> batchUpdate(@NonNull SpanBatchUpdate batchUpdate) {


There's a problem with this method, which is derived from using SpanUpdate directly.

You need to make sure that validations in SpanUpdate don't harm you e.g: projectName and projectId.

Then you might need to extend the validations from tag here to other fields if needed. Although I recommend delegating that to the DAO (see other update with insert + select queries).

The most important suggestion here is ignoring key fields, such as project, traceId etc. in the update operation.

Finally and related to 3, you could create a light-weight flavour of SpanUpdate if needed.

In summary, this method shouldn't do much beyond delegating to the DAO.

apps/opik-backend/src/main/java/com/comet/opik/domain/TraceDAO.java

apps/opik-backend/src/main/java/com/comet/opik/infrastructure/BatchOperationsConfig.java

andrescrz · 2025-11-12T14:09:38Z

apps/opik-backend/src/test/java/com/comet/opik/api/resources/v1/priv/SpansResourceTest.java

+    @Nested
+    @DisplayName("Batch Update Spans Tags:")
+    @TestInstance(TestInstance.Lifecycle.PER_CLASS)
+    class BatchUpdateSpans {


These test classes grew too long, we're actively splitting them now. Please create the tests for the new endpoints in a separated test file.

Please add your new tests to a separated class for BatchUpdateSpans etc.

andrescrz

This is very close to be ready. There are some considerations:

Please use string templates for your queries, this is a must in the service instead of replacing raw strings. This is trivial to change.
Your batch update endpoints only allow updating tags. It would be a pity to only deliver that, knowing that it would give us headaches in the future and that supporting any updatable field requires just a few small changes. Actually, the tests is what takes more effort as there are many updatable fields, but we could compromise on those tests.
Please do not add tests to the existing classes, create new separated files. We've been having troubles lately with their size and @thiagohora has been splitting them. Let's not go backwards with this problem.

Let me know if any question.

apps/opik-backend/src/main/java/com/comet/opik/domain/SpanDAO.java

apps/opik-backend/src/main/java/com/comet/opik/domain/SpanService.java

apps/opik-backend/src/main/java/com/comet/opik/domain/threads/TraceThreadDAO.java

andrescrz · 2025-11-14T11:25:25Z

apps/opik-backend/src/test/java/com/comet/opik/api/resources/v1/priv/SpansResourceTest.java

+    @Nested
+    @DisplayName("Batch Update Spans Tags:")
+    @TestInstance(TestInstance.Lifecycle.PER_CLASS)
+    class BatchUpdateSpans {


Please add your new tests to a separated class for BatchUpdateSpans etc.

apps/opik-backend/src/test/java/com/comet/opik/api/resources/v1/priv/SpansResourceTest.java

… threads

github-actions bot assigned YarivHashaiComet Nov 3, 2025

YarivHashaiComet force-pushed the yariv-h/OPIK-2497-bulk-tag-operations-traces-spans-threads branch from 83f159f to e59dbc9 Compare November 3, 2025 15:56

andrescrz requested changes Nov 4, 2025

View reviewed changes

YarivHashaiComet force-pushed the yariv-h/OPIK-2497-bulk-tag-operations-traces-spans-threads branch from 1eb38ea to e49b65b Compare November 10, 2025 07:29

YarivHashaiComet force-pushed the yariv-h/OPIK-2497-bulk-tag-operations-traces-spans-threads branch 4 times, most recently from 107a809 to 459824a Compare November 12, 2025 10:46

YarivHashaiComet marked this pull request as ready for review November 12, 2025 10:46

YarivHashaiComet requested a review from a team as a code owner November 12, 2025 10:46

YarivHashaiComet requested review from andrescrz and Copilot November 12, 2025 10:46

Copilot AI reviewed Nov 12, 2025

View reviewed changes

YarivHashaiComet requested a review from andriidudar November 12, 2025 10:49

YarivHashaiComet added the test-environment Deploy Opik adhoc environment label Nov 12, 2025

YarivHashaiComet commented Nov 12, 2025

View reviewed changes

apps/opik-backend/src/main/java/com/comet/opik/domain/SpanDAO.java Outdated Show resolved Hide resolved

andriidudar reviewed Nov 12, 2025

View reviewed changes

apps/opik-frontend/src/components/pages-shared/traces/AddTagDialog/AddTagDialog.tsx Outdated Show resolved Hide resolved

apps/opik-frontend/src/components/pages/TracesPage/ThreadsTab/ThreadsTab.tsx Outdated Show resolved Hide resolved

andrescrz requested changes Nov 12, 2025

View reviewed changes

andrescrz changed the title ~~[OPIK-2497] Add bulk tag operations for traces, spans and threads~~ [OPIK-2497] [BE] [FE] Add bulk tag operations for traces, spans and threads Nov 13, 2025

andrescrz reviewed Nov 14, 2025

View reviewed changes

YarivHashaiComet added 2 commits November 16, 2025 19:31

[OPIK-2497] [BE] Add batch tag update endpoints for traces, spans and…

7c1f7f5

… threads

Revision 3: Use TemplateUtils.newST to prevent memory leaks

4a1d0f8

YarivHashaiComet force-pushed the yariv-h/OPIK-2497-bulk-tag-operations-traces-spans-threads branch from 9c6acb5 to 4a1d0f8 Compare November 16, 2025 17:41

[OPIK-2497] [BE] [FE] Add bulk tag operations for traces, spans and threads #3920

Are you sure you want to change the base?

[OPIK-2497] [BE] [FE] Add bulk tag operations for traces, spans and threads #3920

Conversation

YarivHashaiComet commented Nov 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Details

Backend Changes

Frontend Changes

Configuration

Change checklist

Issues

Testing

Documentation

Uh oh!

github-actions bot commented Nov 3, 2025

Uh oh!

github-actions bot commented Nov 3, 2025

Uh oh!

github-actions bot commented Nov 3, 2025

Uh oh!

github-actions bot commented Nov 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Backend Tests Results

Uh oh!

github-actions bot commented Nov 3, 2025

Uh oh!

github-actions bot commented Nov 3, 2025

Uh oh!

andrescrz commented Nov 4, 2025

Uh oh!

andrescrz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Nov 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

SDK E2E Tests Results

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Nov 12, 2025

Uh oh!

Uh oh!

CometActions commented Nov 12, 2025

Access Information

Uh oh!

andriidudar left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

andrescrz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

andrescrz Nov 12, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

andrescrz Nov 12, 2025

Choose a reason for hiding this comment

Uh oh!

andrescrz Nov 14, 2025

YarivHashaiComet commented Nov 3, 2025 •

edited

Loading

github-actions bot commented Nov 3, 2025 •

edited

Loading

github-actions bot commented Nov 10, 2025 •

edited

Loading

andrescrz left a comment •

edited

Loading