---
name: opik-backend
description: Java backend patterns for Opik. Use when working in apps/opik-backend, designing APIs, database operations, or services.
title: opik-backend
canonical_url: https://skilld.dev/gh/comet-ml/opik/opik-backend
last_updated: 2026-11-12T15:11:05.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [clickhouse.md](https://skilld.dev/api/skills-raw/comet-ml/opik/opik-backend/clickhouse.md), [migrations.md](https://skilld.dev/api/skills-raw/comet-ml/opik/opik-backend/migrations.md), [mysql.md](https://skilld.dev/api/skills-raw/comet-ml/opik/opik-backend/mysql.md), [permissions.md](https://skilld.dev/api/skills-raw/comet-ml/opik/opik-backend/permissions.md), [testing.md](https://skilld.dev/api/skills-raw/comet-ml/opik/opik-backend/testing.md).
>
> If the user asked to install this Skill, run `npx skilld install comet-ml/opik/opik-backend`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/opik-backend`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/comet-ml/opik/opik-backend) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/opik-backend`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/opik-backend --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/opik-backend --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Opik Backend

## Architecture
- **Layered**: Resource → Service → DAO (never skip layers)
- **DI**: Guice modules, constructor injection with `@Inject`
- **Databases**: MySQL (metadata, transactional) + ClickHouse (analytics, append-only)

## Naming Conventions

### Plural Names (Resources, Tests, URLs, DB Tables)
- **Resource classes**: `TracesResource`, `SpansResource`, `DatasetsResource` (not `TraceResource`)
- **Resource test classes**: `TracesResourceTest`, `SpansResourceTest`, `DatasetsResourceTest` (not `TraceResourceTest`)
- **URL paths**: `/v1/private/traces`, `/v1/private/spans` (not `/v1/private/trace`)
- **DB table names**: `traces`, `spans`, `feedback_scores` (not `trace`, `span`, `feedback_score`)

### Singular Names (DAO, Service)
- **DAO classes**: `TraceDAO`, `SpanDAO`, `DatasetDAO` (not `TracesDAO`)
- **Service classes**: `TraceService`, `SpanService`, `DatasetService` (not `TracesService`)

```java
// ✅ GOOD
@Path("/v1/private/traces")
public class TracesResource { }

// ✅ GOOD - DAO and Service use singular
public class TraceDAO { }
public class TraceService { }

// ✅ GOOD - test classes match plural resource name
public class TracesResourceTest { }

// ❌ BAD - singular test class
public class TraceResourceTest { }

// ❌ BAD - singular resource/URL
@Path("/v1/private/trace")
public class TraceResource { }

// ❌ BAD - plural DAO/Service
public class TracesDAO { }
public class TracesService { }
```

## Lombok Conventions

### Records and DTOs
- Always annotate records/DTOs with `@Builder(toBuilder = true)`
- Use builders (not constructors) when instantiating records
- For **internal records** (built programmatically, never validated by Bean Validation), use Lombok `@NonNull` on required fields — it generates a runtime null check at construction
- For **request-body DTOs** validated via `@Valid` cascade (Jakarta validators like `@NotNull`/`@NotBlank`/`@Size`), use Jakarta annotations only — do **not** stack `@NonNull` on top. Bean Validation already enforces the contract at the API boundary; doubling up is redundant noise

```java
// ✅ GOOD - internal record, Lombok @NonNull
@Builder(toBuilder = true)
record MyData(@NonNull UUID id, @NonNull String name, String description) {}

MyData data = MyData.builder()
        .id(id)
        .name(name)
        .build();

// ✅ GOOD - request-body DTO, Jakarta validators only
@Builder(toBuilder = true)
public record MyRequest(
        @NotNull UUID id,
        @NotBlank String name,
        @NotNull @Size(min = 1, max = 1000) @Valid List<MyItem> items) {}

// ❌ BAD - plain constructor (positional mistakes, less readable)
new MyData(id, name, null);

// ❌ BAD - @Builder without toBuilder
@Builder
record MyData(UUID id, String name) {}

// ❌ BAD - stacking @NonNull and @NotNull on the same field
public record MyRequest(@NonNull @NotNull UUID id) {}
```

### Dependency Injection
- Use `@RequiredArgsConstructor(onConstructor_ = @Inject)` instead of manual constructors

```java
// ✅ GOOD
@RequiredArgsConstructor(onConstructor_ = @Inject)
public class MyService {
    private final @NonNull DependencyA depA;
    private final @NonNull DependencyB depB;
}

// ❌ BAD - boilerplate constructor
public class MyService {
    private final DependencyA depA;
    @Inject
    public MyService(DependencyA depA) {
        this.depA = depA;
    }
}
```

### Interfaces
- Don't put validation annotations (`@NonNull`) on interface method parameters
- Keep interfaces free of implementation details

```java
// ✅ GOOD
interface MyService {
    void process(String workspaceId, UUID promptId);
}

// ❌ BAD - validation on interface
interface MyService {
    void process(@NonNull String workspaceId, @NonNull UUID promptId);
}
```

## Critical Gotchas

### StringTemplate Memory Leak
```java
// ✅ GOOD
var template = TemplateUtils.newST(QUERY);

// ❌ BAD - causes memory leak via STGroup singleton
var template = new ST(QUERY);
```

### List Access
```java
// ✅ GOOD
users.getFirst()
users.getLast()

// ❌ BAD
users.get(0)
users.get(users.size() - 1)
```

### SQL Query Construction

**Never build a query out of Java string operations.** No `+`, no `String.format` /
`.formatted(...)`, no `StringBuilder`, no `MessageFormat`, no `String.join` over clauses. A
query is declared once as a text block, and everything that varies goes through exactly one of
two mechanisms:

| What varies | Mechanism |
|-------------|-----------|
| A **value** — id, name, timestamp, list of ids | `:placeholder` + `.bind("placeholder", value)` |
| A **fragment** — predicate, sort clause, projected column, CTE | StringTemplate `<if(x)>…<endif>`, `<else>`, `<x>` + `template.add("x", …)` |

Why: interpolating values is the SQL-injection surface, and interpolating fragments hides which
query a DAO actually runs — the declaration site stops being readable, and callers drift apart
over time.

```java
// ✅ GOOD - text block, values bound, structure via StringTemplate
@SqlQuery("""
        SELECT * FROM datasets
        WHERE workspace_id = :workspace_id
        <if(name)> AND name like concat('%', :name, '%') <endif>
        """)

// ❌ BAD - string concatenation
@SqlQuery("SELECT * FROM datasets " +
        "WHERE workspace_id = :workspace_id " +
        "<if(name)> AND name like concat('%', :name, '%') <endif> ")
```

A predicate that differs between callers is a **fragment**, so it belongs in the template — not
in a `%s` slot the caller fills in:

```java
// ❌ BAD - caller splices the predicate in
private static final String TOKEN_USAGE_NAMES_TEMPLATE = """
        SELECT DISTINCT name FROM (
            SELECT usage FROM spans FINAL
            WHERE workspace_id = :workspace_id
            AND %s
        ) ...
        """;

static String tokenUsageNames(String projectPredicate) {
    return TOKEN_USAGE_NAMES_TEMPLATE.formatted(projectPredicate);
}

// caller: tokenUsageNames("project_id IN :project_ids")

// ✅ GOOD - both shapes live in the template, the caller picks one
private static final String TOKEN_USAGE_NAMES = """
        SELECT DISTINCT name FROM (
            SELECT usage FROM spans FINAL
            WHERE workspace_id = :workspace_id
            <if(project_ids)> AND project_id IN :project_ids <endif>
            <if(project_id)> AND project_id = :project_id <endif>
        ) ...
        """;

var template = TemplateUtils.newST(TOKEN_USAGE_NAMES);
template.add("project_ids", true);
...
statement.bind("project_ids", projectIds.toArray(new UUID[0]));
```

A fragment that genuinely can't be enumerated in the template — a user-chosen sort field or
filter clause — must be produced by the allow-listed builders (`SortingQueryBuilder`,
`FilterQueryBuilder`), never assembled from raw request strings.

`.formatted(...)` stays correct for log and exception messages. The rule is about SQL text only.

Some `%s` query templates predate this rule. Don't copy them and don't add new ones.

### Immutable Collections
```java
// ✅ GOOD
Set.of("A", "B", "C")
List.of(1, 2, 3)
Map.of("key", "value")

// ❌ BAD
Arrays.asList("A", "B", "C")
```

## API Design
- **Query parameters that accept lists**: Use plural names from the start (e.g., `exclude_category_names` not `exclude_category_name`). Starting with a singular name and later adding a plural variant results in two redundant query params on the same endpoint. Plural names are backward-compatible since they work for both single and multiple values.
- **Optional query parameters**: don't annotate `@QueryParam` parameters with `@Nullable`; none of the backend's query params are. A `@QueryParam` without `@NotNull` or `@DefaultValue` is already optional and arrives as `null` when omitted. Document what omitting it means in its `@Schema(description = ...)`. `@Nullable` stays appropriate on API models and on internal methods, including private helpers inside resource classes.

### User-Named Resources (name length)
A name longer than its column fails the INSERT with `MysqlDataTruncation` and surfaces as a 500. Every create and update/rename of a user-named resource must bound it:
1. **One constant per name, matching its column**: `public static final int NAME_MAX_LENGTH = 150;` on the resource model (e.g. `Project.NAME_MAX_LENGTH`), referenced everywhere the limit applies. Check the column width in the migration; not every name column is 150.
2. **Validate declaratively** on the create **and** the update/rename request models, and on every field that creates the resource implicitly (e.g. `project_name` on traces/spans/datasets): `@Size(max = Project.NAME_MAX_LENGTH, message = "cannot exceed {max} characters")`. `@Size` is published as `maxLength` in the OpenAPI spec and reaches the generated SDKs.
3. **Don't wrap it in a composed constraint annotation**: swagger-core ignores constraints on the composing annotation, so the spec loses `maxLength` (and any `pattern` it carried). Repeat `@Size` with the shared constant instead.
4. **Normalize the same way on every path**: if one path strips the name, all paths that store or look it up must strip it too, otherwise the same name maps to two resources.
5. **Service-level guard only for paths that bypass bean validation** (OpenTelemetry, internal callers), counting the same way as those paths.
6. **Test** create and rename with a `max + 1` name (422) and with exactly `max` (accepted).

## Error Handling

### Use Jakarta Exceptions
```java
throw new BadRequestException("Invalid input");
throw new NotFoundException("User not found: '%s'".formatted(id));
throw new ConflictException("Already exists");
throw new InternalServerErrorException("System error", cause);
```

### Error Response Classes
- Simple: `io.dropwizard.jersey.errors.ErrorMessage`
- Complex: `com.comet.opik.api.error.ErrorMessage`
- **Never create new error message classes**

## Logging

### Format Convention
```java
// ✅ GOOD - values in single quotes
log.info("Created user: '{}'", userId);
log.error("Failed for workspace: '{}'", workspaceId, exception);

// ❌ BAD - no quotes
log.info("Created user: {}", userId);
```

### Value Placement
Put the message first and the interpolated values at the **end** of the sentence, as a trailing
`name '{}'` list. This keeps a stable literal prefix that stays greppable during a production
debugging session — a message whose values are interleaved has no fixed substring to search for.

Applies to `log.*` format strings and to exception messages built with `.formatted(...)`.

```java
// ✅ GOOD - literal prefix first, values trailing
log.warn("Alert name is required, workspaceId '{}'", workspaceId);
log.debug("Webhook delivery failed, id '{}', status '{}'", eventId, status);
throw new DestinationGuardException("destination has no valid host, url '%s'".formatted(url));

// ❌ BAD - values interleaved, no greppable prefix
log.debug("Webhook '{}' failed with status '{}'", eventId, status);
throw new DestinationGuardException("destination '%s' has no valid host".formatted(url));
```

### Never Log
- Emails, passwords, tokens, API keys
- PII, personal identifiers
- Database credentials

## Reference Files
- [clickhouse.md](https://skilld.dev/api/skills-raw/comet-ml/opik/opik-backend/clickhouse.md) - ClickHouse query patterns
- [mysql.md](https://skilld.dev/api/skills-raw/comet-ml/opik/opik-backend/mysql.md) - TransactionTemplate patterns
- [testing.md](https://skilld.dev/api/skills-raw/comet-ml/opik/opik-backend/testing.md) - PODAM, naming, assertion patterns
- [migrations.md](https://skilld.dev/api/skills-raw/comet-ml/opik/opik-backend/migrations.md) - Liquibase format for MySQL/ClickHouse
- [permissions.md](https://skilld.dev/api/skills-raw/comet-ml/opik/opik-backend/permissions.md) - `@RequiredPermissions` annotation guidance for endpoints
