arize-phoenix 11.23.1__py3-none-any.whl → 12.28.1__py3-none-any.whl

phoenix/server/api/routers/v1/spans.py

@@ -5,21 +5,16 @@ from collections.abc import AsyncIterator
 from datetime import datetime, timezone
 from enum import Enum
 from secrets import token_urlsafe
-from typing import Annotated, Any, Literal, Optional, Union
+from typing import Annotated, Any, Optional, Union
 
 import pandas as pd
 import sqlalchemy as sa
 from fastapi import APIRouter, Depends, Header, HTTPException, Path, Query
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, BeforeValidator, Field
 from sqlalchemy import exists, select, update
 from starlette.requests import Request
 from starlette.responses import Response, StreamingResponse
-from starlette.status import (
-    HTTP_202_ACCEPTED,
-    HTTP_400_BAD_REQUEST,
-    HTTP_404_NOT_FOUND,
-    HTTP_422_UNPROCESSABLE_ENTITY,
-)
+from starlette.status import HTTP_404_NOT_FOUND
 from strawberry.relay import GlobalID
 
 from phoenix.config import DEFAULT_PROJECT_NAME
@@ -27,13 +22,13 @@ from phoenix.datetime_utils import normalize_datetime
 from phoenix.db import models
 from phoenix.db.helpers import SupportedSQLDialect, get_ancestor_span_rowids
 from phoenix.db.insertion.helpers import as_kv, insert_on_conflict
-from phoenix.db.insertion.types import Precursors
 from phoenix.server.api.routers.utils import df_to_bytes
+from phoenix.server.api.routers.v1.annotations import SpanAnnotationData
 from phoenix.server.api.types.node import from_global_id_with_expected_type
 from phoenix.server.authorization import is_not_locked
 from phoenix.server.bearer_auth import PhoenixUser
 from phoenix.server.dml_event import SpanAnnotationInsertEvent, SpanDeleteEvent
-from phoenix.trace.attributes import flatten
+from phoenix.trace.attributes import flatten, unflatten
 from phoenix.trace.dsl import SpanQuery as SpanQuery_
 from phoenix.trace.schemas import (
     Span as SpanForInsertion,
@@ -440,7 +435,7 @@ class SpansResponseBody(PaginatedResponseBody[Span]):
     "/spans",
     operation_id="querySpans",
     summary="Query spans with query DSL",
-    responses=add_errors_to_responses([HTTP_404_NOT_FOUND, HTTP_422_UNPROCESSABLE_ENTITY]),
+    responses=add_errors_to_responses([404, 422]),
     include_in_schema=False,
 )
 async def query_spans_handler(
@@ -467,30 +462,30 @@ async def query_spans_handler(
     except Exception as e:
         raise HTTPException(
             detail=f"Invalid query: {e}",
-            status_code=HTTP_422_UNPROCESSABLE_ENTITY,
+            status_code=422,
         )
+
     async with request.app.state.db() as session:
-        results = []
+        results: list[pd.DataFrame] = []
         for query in span_queries:
-            results.append(
-                await session.run_sync(
-                    query,
-                    project_name=project_name,
-                    start_time=normalize_datetime(
-                        request_body.start_time,
-                        timezone.utc,
-                    ),
-                    end_time=normalize_datetime(
-                        end_time,
-                        timezone.utc,
-                    ),
-                    limit=request_body.limit,
-                    root_spans_only=request_body.root_spans_only,
-                    orphan_span_as_root_span=request_body.orphan_span_as_root_span,
-                )
+            df = await session.run_sync(
+                query,
+                project_name=project_name,
+                start_time=normalize_datetime(
+                    request_body.start_time,
+                    timezone.utc,
+                ),
+                end_time=normalize_datetime(
+                    end_time,
+                    timezone.utc,
+                ),
+                limit=request_body.limit,
+                root_spans_only=request_body.root_spans_only,
+                orphan_span_as_root_span=request_body.orphan_span_as_root_span,
             )
+            results.append(df)
     if not results:
-        raise HTTPException(status_code=HTTP_404_NOT_FOUND)
+        raise HTTPException(status_code=404)
 
     if accept == "application/json":
         boundary_token = token_urlsafe(64)
@@ -574,7 +569,7 @@ def _to_any_value(value: Any) -> OtlpAnyValue:
     summary="Search spans with simple filters (no DSL)",
     description="Return spans within a project filtered by time range. "
     "Supports cursor-based pagination.",
-    responses=add_errors_to_responses([HTTP_404_NOT_FOUND, HTTP_422_UNPROCESSABLE_ENTITY]),
+    responses=add_errors_to_responses([404, 422]),
 )
 async def span_search_otlpv1(
     request: Request,
@@ -617,7 +612,7 @@ async def span_search_otlpv1(
             cursor_rowid = int(GlobalID.from_id(cursor).node_id)
             stmt = stmt.where(models.Span.id <= cursor_rowid)
         except Exception:
-            raise HTTPException(status_code=HTTP_422_UNPROCESSABLE_ENTITY, detail="Invalid cursor")
+            raise HTTPException(status_code=422, detail="Invalid cursor")
 
     stmt = stmt.limit(limit + 1)
 
@@ -711,7 +706,7 @@ async def span_search_otlpv1(
     summary="List spans with simple filters (no DSL)",
     description="Return spans within a project filtered by time range. "
     "Supports cursor-based pagination.",
-    responses=add_errors_to_responses([HTTP_404_NOT_FOUND, HTTP_422_UNPROCESSABLE_ENTITY]),
+    responses=add_errors_to_responses([404, 422]),
 )
 async def span_search(
     request: Request,
@@ -751,7 +746,7 @@ async def span_search(
         try:
             cursor_rowid = int(GlobalID.from_id(cursor).node_id)
         except Exception:
-            raise HTTPException(status_code=HTTP_422_UNPROCESSABLE_ENTITY, detail="Invalid cursor")
+            raise HTTPException(status_code=422, detail="Invalid cursor")
         stmt = stmt.where(models.Span.id <= cursor_rowid)
 
     stmt = stmt.limit(limit + 1)
@@ -850,51 +845,6 @@ async def get_spans_handler(
     return await query_spans_handler(request, request_body, project_name)
 
 
-class SpanAnnotationResult(V1RoutesBaseModel):
-    label: Optional[str] = Field(default=None, description="The label assigned by the annotation")
-    score: Optional[float] = Field(default=None, description="The score assigned by the annotation")
-    explanation: Optional[str] = Field(
-        default=None, description="Explanation of the annotation result"
-    )
-
-
-class SpanAnnotationData(V1RoutesBaseModel):
-    span_id: str = Field(description="OpenTelemetry Span ID (hex format w/o 0x prefix)")
-    name: str = Field(description="The name of the annotation")
-    annotator_kind: Literal["LLM", "CODE", "HUMAN"] = Field(
-        description="The kind of annotator used for the annotation"
-    )
-    result: Optional[SpanAnnotationResult] = Field(
-        default=None, description="The result of the annotation"
-    )
-    metadata: Optional[dict[str, Any]] = Field(
-        default=None, description="Metadata for the annotation"
-    )
-    identifier: str = Field(
-        default="",
-        description=(
-            "The identifier of the annotation. "
-            "If provided, the annotation will be updated if it already exists."
-        ),
-    )
-
-    def as_precursor(self, *, user_id: Optional[int] = None) -> Precursors.SpanAnnotation:
-        return Precursors.SpanAnnotation(
-            self.span_id,
-            models.SpanAnnotation(
-                name=self.name,
-                annotator_kind=self.annotator_kind,
-                score=self.result.score if self.result else None,
-                label=self.result.label if self.result else None,
-                explanation=self.result.explanation if self.result else None,
-                metadata_=self.metadata or {},
-                identifier=self.identifier,
-                source="API",
-                user_id=user_id,
-            ),
-        )
-
-
 class AnnotateSpansRequestBody(RequestBody[list[SpanAnnotationData]]):
     data: list[SpanAnnotationData]
 
@@ -912,9 +862,7 @@ class AnnotateSpansResponseBody(ResponseBody[list[InsertedSpanAnnotation]]):
     dependencies=[Depends(is_not_locked)],
     operation_id="annotateSpans",
     summary="Create span annotations",
-    responses=add_errors_to_responses(
-        [{"status_code": HTTP_404_NOT_FOUND, "description": "Span not found"}]
-    ),
+    responses=add_errors_to_responses([{"status_code": 404, "description": "Span not found"}]),
     response_description="Span annotations inserted successfully",
     include_in_schema=True,
 )
@@ -942,15 +890,17 @@ async def annotate_spans(
         )
     precursors = [d.as_precursor(user_id=user_id) for d in filtered_span_annotations]
     if not sync:
-        await request.state.enqueue(*precursors)
+        await request.state.enqueue_annotations(*precursors)
         return AnnotateSpansResponseBody(data=[])
 
     span_ids = {p.span_id for p in precursors}
     async with request.app.state.db() as session:
         existing_spans = {
-            span.span_id: span.id
-            async for span in await session.stream_scalars(
-                select(models.Span).filter(models.Span.span_id.in_(span_ids))
+            span_id: id_
+            async for span_id, id_ in await session.stream(
+                select(models.Span.span_id, models.Span.id).filter(
+                    models.Span.span_id.in_(span_ids)
+                )
             )
         }
 
@@ -958,7 +908,7 @@ async def annotate_spans(
         if missing_span_ids:
             raise HTTPException(
                 detail=f"Spans with IDs {', '.join(missing_span_ids)} do not exist.",
-                status_code=HTTP_404_NOT_FOUND,
+                status_code=404,
             )
         inserted_ids = []
         dialect = SupportedSQLDialect(session.bind.dialect.name)
@@ -982,6 +932,100 @@ async def annotate_spans(
     )
 
 
+class SpanNoteData(V1RoutesBaseModel):
+    span_id: Annotated[str, BeforeValidator(lambda v: v.strip() if isinstance(v, str) else v)] = (
+        Field(min_length=1, description="OpenTelemetry Span ID (hex format w/o 0x prefix)")
+    )
+    note: Annotated[str, BeforeValidator(lambda v: v.strip() if isinstance(v, str) else v)] = Field(
+        min_length=1, description="The note text to add to the span"
+    )
+
+
+class CreateSpanNoteRequestBody(RequestBody[SpanNoteData]):
+    data: SpanNoteData
+
+
+class CreateSpanNoteResponseBody(ResponseBody[InsertedSpanAnnotation]):
+    pass
+
+
+@router.post(
+    "/span_notes",
+    dependencies=[Depends(is_not_locked)],
+    operation_id="createSpanNote",
+    summary="Create a span note",
+    description=(
+        "Add a note annotation to a span. Notes are special annotations that allow "
+        "multiple entries per span (unlike regular annotations which are unique by name "
+        "and identifier). Each note gets a unique timestamp-based identifier."
+    ),
+    responses=add_errors_to_responses([{"status_code": 404, "description": "Span not found"}]),
+    response_description="Span note created successfully",
+    status_code=200,
+)
+async def create_span_note(
+    request: Request,
+    request_body: CreateSpanNoteRequestBody,
+) -> CreateSpanNoteResponseBody:
+    """
+    Create a note annotation for a span.
+
+    Notes are a special type of annotation that:
+    - Have the fixed name "note"
+    - Use a timestamp-based identifier to allow multiple notes per span
+    - Are always created with annotator_kind="HUMAN" and source="API"
+    - Store the note text in the explanation field
+    """
+    note_data = request_body.data
+
+    user_id: Optional[int] = None
+    if request.app.state.authentication_enabled and isinstance(request.user, PhoenixUser):
+        user_id = int(request.user.identity)
+
+    async with request.app.state.db() as session:
+        # Find the span by OpenTelemetry span_id
+        span_rowid = await session.scalar(
+            select(models.Span.id).where(models.Span.span_id == note_data.span_id)
+        )
+
+        if span_rowid is None:
+            raise HTTPException(
+                status_code=404,
+                detail=f"Span with ID {note_data.span_id} not found",
+            )
+
+        # Generate a unique identifier for the note using timestamp
+        timestamp = datetime.now(timezone.utc).isoformat()
+        note_identifier = f"px-span-note:{timestamp}"
+
+        # Create the annotation values
+        values = {
+            "span_rowid": span_rowid,
+            "name": "note",
+            "label": None,
+            "score": None,
+            "explanation": note_data.note,
+            "annotator_kind": "HUMAN",
+            "metadata_": {},
+            "identifier": note_identifier,
+            "source": "API",
+            "user_id": user_id,
+        }
+
+        # Insert the annotation
+        result = await session.execute(
+            sa.insert(models.SpanAnnotation).values(**values).returning(models.SpanAnnotation.id)
+        )
+        annotation_id = result.scalar_one()
+
+    # Put event on queue after successful insert
+    request.state.event_queue.put(SpanAnnotationInsertEvent((annotation_id,)))
+
+    return CreateSpanNoteResponseBody(
+        data=InsertedSpanAnnotation(id=str(GlobalID("SpanAnnotation", str(annotation_id))))
+    )
+
+
 class CreateSpansRequestBody(RequestBody[list[Span]]):
     data: list[Span]
 
@@ -1000,8 +1044,8 @@ class CreateSpansResponseBody(V1RoutesBaseModel):
         "Submit spans to be inserted into a project. If any spans are invalid or "
         "duplicates, no spans will be inserted."
     ),
-    responses=add_errors_to_responses([HTTP_404_NOT_FOUND, HTTP_400_BAD_REQUEST]),
-    status_code=HTTP_202_ACCEPTED,
+    responses=add_errors_to_responses([404, 400]),
+    status_code=202,
 )
 async def create_spans(
     request: Request,
@@ -1040,6 +1084,7 @@ async def create_spans(
         # Add back the openinference.span.kind attribute since it's stored separately in the API
         attributes = dict(api_span.attributes)
         attributes["openinference.span.kind"] = api_span.span_kind
+        attributes = unflatten(attributes.items())
 
         # Create span for insertion - note we ignore the 'id' field as it's server-generated
         return SpanForInsertion(
@@ -1058,8 +1103,23 @@ async def create_spans(
             conversation=None,  # Unused
         )
 
-    async with request.app.state.db() as session:
-        project = await _get_project_by_identifier(session, project_identifier)
+    try:
+        id_ = from_global_id_with_expected_type(
+            GlobalID.from_id(project_identifier),
+            "Project",
+        )
+    except Exception:
+        project_name = project_identifier
+    else:
+        stmt = select(models.Project).filter_by(id=id_)
+        async with request.app.state.db() as session:
+            project = await session.scalar(stmt)
+        if project is None:
+            raise HTTPException(
+                status_code=HTTP_404_NOT_FOUND,
+                detail=f"Project with ID {project_identifier} not found",
+            )
+        project_name = project.name
 
     total_received = len(request_body.data)
     duplicate_spans: list[dict[str, str]] = []
@@ -1087,7 +1147,7 @@ async def create_spans(
 
         try:
             span_for_insertion = convert_api_span_for_insertion(api_span)
-            spans_to_queue.append((span_for_insertion, project.name))
+            spans_to_queue.append((span_for_insertion, project_name))
         except Exception as e:
             invalid_spans.append(
                 {
@@ -1109,13 +1169,13 @@ async def create_spans(
             "invalid_spans": invalid_spans,
         }
         raise HTTPException(
-            status_code=HTTP_400_BAD_REQUEST,
+            status_code=400,
             detail=json.dumps(error_detail),
         )
 
     # All spans are valid, queue them all
     for span_for_insertion, project_name in spans_to_queue:
-        await request.state.queue_span_for_bulk_insert(span_for_insertion, project_name)
+        await request.state.enqueue_span(span_for_insertion, project_name)
 
     return CreateSpansResponseBody(
         total_received=total_received,
@@ -1145,7 +1205,7 @@ async def create_spans(
         **Note**: This operation is irreversible and may create orphaned spans.
         """
     ),
-    responses=add_errors_to_responses([HTTP_404_NOT_FOUND]),
+    responses=add_errors_to_responses([404]),
     status_code=204,  # No Content for successful deletion
 )
 async def delete_span(
@@ -1197,7 +1257,7 @@ async def delete_span(
 
         if target_span is None:
             raise HTTPException(
-                status_code=HTTP_404_NOT_FOUND,
+                status_code=404,
                 detail=error_detail,
             )
 

phoenix/server/api/routers/v1/traces.py

@@ -1,6 +1,6 @@
 import gzip
 import zlib
-from typing import Any, Literal, Optional
+from typing import Optional
 
 from fastapi import APIRouter, BackgroundTasks, Depends, Header, HTTPException, Path, Query
 from google.protobuf.message import DecodeError
@@ -9,48 +9,62 @@ from opentelemetry.proto.collector.trace.v1.trace_service_pb2 import (
     ExportTraceServiceResponse,
 )
 from pydantic import Field
-from sqlalchemy import delete, insert, select
+from sqlalchemy import delete, select
 from starlette.concurrency import run_in_threadpool
 from starlette.datastructures import State
 from starlette.requests import Request
 from starlette.responses import Response
-from starlette.status import (
-    HTTP_404_NOT_FOUND,
-    HTTP_415_UNSUPPORTED_MEDIA_TYPE,
-    HTTP_422_UNPROCESSABLE_ENTITY,
-)
 from strawberry.relay import GlobalID
 
 from phoenix.db import models
-from phoenix.db.insertion.helpers import as_kv
-from phoenix.db.insertion.types import Precursors
+from phoenix.db.helpers import SupportedSQLDialect
+from phoenix.db.insertion.helpers import as_kv, insert_on_conflict
+from phoenix.server.api.routers.v1.annotations import TraceAnnotationData
 from phoenix.server.api.types.node import from_global_id_with_expected_type
 from phoenix.server.authorization import is_not_locked
 from phoenix.server.bearer_auth import PhoenixUser
 from phoenix.server.dml_event import SpanDeleteEvent, TraceAnnotationInsertEvent
+from phoenix.server.prometheus import SPAN_QUEUE_REJECTIONS
 from phoenix.trace.otel import decode_otlp_span
 from phoenix.utilities.project import get_project_name
 
 from .models import V1RoutesBaseModel
-from .utils import RequestBody, ResponseBody, add_errors_to_responses
+from .utils import (
+    RequestBody,
+    ResponseBody,
+    add_errors_to_responses,
+)
 
 router = APIRouter(tags=["traces"])
 
 
+def is_not_at_capacity(request: Request) -> None:
+    if request.app.state.span_queue_is_full():
+        SPAN_QUEUE_REJECTIONS.inc()
+        raise HTTPException(
+            detail="Server is at capacity and cannot process more requests",
+            status_code=503,
+        )
+
+
 @router.post(
     "/traces",
-    dependencies=[Depends(is_not_locked)],
+    dependencies=[Depends(is_not_locked), Depends(is_not_at_capacity)],
     operation_id="addTraces",
     summary="Send traces",
     responses=add_errors_to_responses(
         [
             {
-                "status_code": HTTP_415_UNSUPPORTED_MEDIA_TYPE,
+                "status_code": 415,
                 "description": (
                     "Unsupported content type (only `application/x-protobuf` is supported)"
                 ),
             },
-            {"status_code": HTTP_422_UNPROCESSABLE_ENTITY, "description": "Invalid request body"},
+            {"status_code": 422, "description": "Invalid request body"},
+            {
+                "status_code": 503,
+                "description": "Server is at capacity and cannot process more requests",
+            },
         ]
     ),
     openapi_extra={
@@ -72,12 +86,12 @@ async def post_traces(
     if content_type != "application/x-protobuf":
         raise HTTPException(
             detail=f"Unsupported content type: {content_type}",
-            status_code=HTTP_415_UNSUPPORTED_MEDIA_TYPE,
+            status_code=415,
         )
     if content_encoding and content_encoding not in ("gzip", "deflate"):
         raise HTTPException(
             detail=f"Unsupported content encoding: {content_encoding}",
-            status_code=HTTP_415_UNSUPPORTED_MEDIA_TYPE,
+            status_code=415,
         )
     body = await request.body()
     if content_encoding == "gzip":
@@ -90,7 +104,7 @@ async def post_traces(
     except DecodeError:
         raise HTTPException(
             detail="Request body is invalid ExportTraceServiceRequest",
-            status_code=HTTP_422_UNPROCESSABLE_ENTITY,
+            status_code=422,
         )
     background_tasks.add_task(_add_spans, req, request.state)
 
@@ -104,53 +118,8 @@ async def post_traces(
     )
 
 
-class TraceAnnotationResult(V1RoutesBaseModel):
-    label: Optional[str] = Field(default=None, description="The label assigned by the annotation")
-    score: Optional[float] = Field(default=None, description="The score assigned by the annotation")
-    explanation: Optional[str] = Field(
-        default=None, description="Explanation of the annotation result"
-    )
-
-
-class TraceAnnotation(V1RoutesBaseModel):
-    trace_id: str = Field(description="OpenTelemetry Trace ID (hex format w/o 0x prefix)")
-    name: str = Field(description="The name of the annotation")
-    annotator_kind: Literal["LLM", "HUMAN"] = Field(
-        description="The kind of annotator used for the annotation"
-    )
-    result: Optional[TraceAnnotationResult] = Field(
-        default=None, description="The result of the annotation"
-    )
-    metadata: Optional[dict[str, Any]] = Field(
-        default=None, description="Metadata for the annotation"
-    )
-    identifier: str = Field(
-        default="",
-        description=(
-            "The identifier of the annotation. "
-            "If provided, the annotation will be updated if it already exists."
-        ),
-    )
-
-    def as_precursor(self, *, user_id: Optional[int] = None) -> Precursors.TraceAnnotation:
-        return Precursors.TraceAnnotation(
-            self.trace_id,
-            models.TraceAnnotation(
-                name=self.name,
-                annotator_kind=self.annotator_kind,
-                score=self.result.score if self.result else None,
-                label=self.result.label if self.result else None,
-                explanation=self.result.explanation if self.result else None,
-                metadata_=self.metadata or {},
-                identifier=self.identifier,
-                source="APP",
-                user_id=user_id,
-            ),
-        )
-
-
-class AnnotateTracesRequestBody(RequestBody[list[TraceAnnotation]]):
-    data: list[TraceAnnotation] = Field(description="The trace annotations to be upserted")
+class AnnotateTracesRequestBody(RequestBody[list[TraceAnnotationData]]):
+    data: list[TraceAnnotationData] = Field(description="The trace annotations to be upserted")
 
 
 class InsertedTraceAnnotation(V1RoutesBaseModel):
@@ -166,15 +135,12 @@ class AnnotateTracesResponseBody(ResponseBody[list[InsertedTraceAnnotation]]):
     dependencies=[Depends(is_not_locked)],
     operation_id="annotateTraces",
     summary="Create trace annotations",
-    responses=add_errors_to_responses(
-        [{"status_code": HTTP_404_NOT_FOUND, "description": "Trace not found"}]
-    ),
-    include_in_schema=False,
+    responses=add_errors_to_responses([{"status_code": 404, "description": "Trace not found"}]),
 )
 async def annotate_traces(
     request: Request,
     request_body: AnnotateTracesRequestBody,
-    sync: bool = Query(default=True, description="If true, fulfill request synchronously."),
+    sync: bool = Query(default=False, description="If true, fulfill request synchronously."),
 ) -> AnnotateTracesResponseBody:
     if not request_body.data:
         return AnnotateTracesResponseBody(data=[])
@@ -185,15 +151,17 @@ async def annotate_traces(
 
     precursors = [d.as_precursor(user_id=user_id) for d in request_body.data]
     if not sync:
-        await request.state.enqueue(*precursors)
+        await request.state.enqueue_annotations(*precursors)
         return AnnotateTracesResponseBody(data=[])
 
     trace_ids = {p.trace_id for p in precursors}
     async with request.app.state.db() as session:
         existing_traces = {
-            trace.trace_id: trace.id
-            async for trace in await session.stream_scalars(
-                select(models.Trace).filter(models.Trace.trace_id.in_(trace_ids))
+            trace_id: id_
+            async for trace_id, id_ in await session.stream(
+                select(models.Trace.trace_id, models.Trace.id).filter(
+                    models.Trace.trace_id.in_(trace_ids)
+                )
             )
         }
 
@@ -201,13 +169,19 @@ async def annotate_traces(
         if missing_trace_ids:
             raise HTTPException(
                 detail=f"Traces with IDs {', '.join(missing_trace_ids)} do not exist.",
-                status_code=HTTP_404_NOT_FOUND,
+                status_code=404,
             )
         inserted_ids = []
+        dialect = SupportedSQLDialect(session.bind.dialect.name)
         for p in precursors:
             values = dict(as_kv(p.as_insertable(existing_traces[p.trace_id]).row))
             trace_annotation_id = await session.scalar(
-                insert(models.TraceAnnotation).values(**values).returning(models.TraceAnnotation.id)
+                insert_on_conflict(
+                    values,
+                    dialect=dialect,
+                    table=models.TraceAnnotation,
+                    unique_by=("name", "trace_rowid", "identifier"),
+                ).returning(models.TraceAnnotation.id)
             )
             inserted_ids.append(trace_annotation_id)
     request.state.event_queue.put(TraceAnnotationInsertEvent(tuple(inserted_ids)))
@@ -225,7 +199,7 @@ async def _add_spans(req: ExportTraceServiceRequest, state: State) -> None:
         for scope_span in resource_spans.scope_spans:
             for otlp_span in scope_span.spans:
                 span = await run_in_threadpool(decode_otlp_span, otlp_span)
-                await state.queue_span_for_bulk_insert(span, project_name)
+                await state.enqueue_span(span, project_name)
 
 
 @router.delete(
@@ -238,7 +212,7 @@ async def _add_spans(req: ExportTraceServiceRequest, state: State) -> None:
         "2. An OpenTelemetry trace_id (hex string)\n\n"
         "This will permanently remove all spans in the trace and their associated data."
     ),
-    responses=add_errors_to_responses([HTTP_404_NOT_FOUND]),
+    responses=add_errors_to_responses([404]),
     status_code=204,  # No Content for successful deletion
 )
 async def delete_trace(
@@ -286,7 +260,7 @@ async def delete_trace(
 
         if project_id is None:
             raise HTTPException(
-                status_code=HTTP_404_NOT_FOUND,
+                status_code=404,
                 detail=error_detail,
             )