Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions api-docs/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -13,8 +13,9 @@ function dictToString(dict) {
}

// Extensions that only the response coverage check reads: the Python source of a
// TypedDict field, and the marker on a recursive TypedDict cut short.
const COVERAGE_EXTENSIONS = ['x-sentry-source', 'x-sentry-cycle'];
// TypedDict field, the marker on a recursive TypedDict cut short, and the marker on a
// JsonValue field.
const COVERAGE_EXTENSIONS = ['x-sentry-source', 'x-sentry-cycle', 'x-sentry-json-value'];

function stripCoverageExtensions(node: unknown) {
if (Array.isArray(node)) {
Expand Down
203 changes: 182 additions & 21 deletions src/sentry/api/endpoints/project_trace_item_details.py
Original file line number Diff line number Diff line change
@@ -1,9 +1,11 @@
import time
import uuid
from datetime import timedelta
from typing import Any, Literal, cast
from typing import Annotated, Any, Literal, NotRequired, TypedDict, cast

import sentry_sdk
from drf_spectacular.types import OpenApiTypes
from drf_spectacular.utils import OpenApiParameter, extend_schema
from google.protobuf.json_format import MessageToDict
from google.protobuf.timestamp_pb2 import Timestamp as ProtoTimestamp
from rest_framework import serializers
Expand All @@ -20,6 +22,18 @@
from sentry.api.conditional_get import CacheTier, ConditionalGetResponseMixin
from sentry.api.exceptions import BadRequest
from sentry.api.utils import get_date_range_from_params
from sentry.apidocs.constants import (
RESPONSE_BAD_REQUEST,
RESPONSE_FORBIDDEN,
RESPONSE_NOT_FOUND,
RESPONSE_UNAUTHORIZED,
)
from sentry.apidocs.descriptions import ApiDescription
from sentry.apidocs.examples.trace_item_examples import TraceItemExamples
from sentry.apidocs.formats import JsonValue
from sentry.apidocs.parameters import GlobalParams
from sentry.apidocs.response_types import ValidationErrorResponse, as_validation_errors
from sentry.apidocs.utils import inline_sentry_response_serializer
from sentry.auth.staff import is_active_staff
from sentry.auth.superuser import is_active_superuser
from sentry.exceptions import InvalidParams
Expand All @@ -46,6 +60,86 @@
from sentry.utils.dates import to_datetime
from sentry.utils.snuba_rpc import SnubaRPCBadRequest, trace_item_details_rpc


class TraceItemLinkAttribute(TypedDict):
name: Annotated[
str, ApiDescription("The name of the link attribute, such as `sentry.link.type`")
]
value: Annotated[str | int | float | bool, ApiDescription("The link attribute value")]
type: Annotated[
Literal["str", "int", "float", "bool"],
ApiDescription("The type of the link attribute value"),
]


class TraceItemLink(TypedDict):
itemId: Annotated[str, ApiDescription("The ID of the linked span")]
traceId: Annotated[str, ApiDescription("The ID of the trace the linked span belongs to")]
sampled: NotRequired[Annotated[bool, ApiDescription("Whether the linked span was sampled")]]
attributes: NotRequired[
Annotated[
list[TraceItemLinkAttribute],
ApiDescription(
"The attributes of the link. Attributes with values that aren't a string, "
"number or boolean are left out"
),
]
]


class TraceItemEvent(TypedDict):
contexts: NotRequired[
Annotated[JsonValue, ApiDescription("The contexts of the event the item came from")]
]
extra: NotRequired[
Annotated[JsonValue, ApiDescription("The extra data of the event the item came from")]
]
breadcrumbs: NotRequired[
Annotated[
JsonValue,
ApiDescription(
"The breadcrumbs of the event the item came from. Breadcrumb timestamps are "
"ISO 8601 strings"
),
]
]


class TraceItemDetailsResponse(TypedDict):
itemId: Annotated[
str,
ApiDescription("The ID of the item. For a span, this is the 16-character span ID"),
]
timestamp: Annotated[
str,
ApiDescription("When the item happened, as an RFC 3339 UTC timestamp ending in `Z`"),
]
attributes: Annotated[
list[TraceItemAttribute],
ApiDescription("The attributes of the item, sorted by type and then by name"),
]
meta: Annotated[
dict[str, JsonValue],
ApiDescription(
"Processing metadata, keyed by attribute name, for attributes that were changed "
"during ingestion, such as a value that was trimmed for length"
),
]
links: Annotated[
list[TraceItemLink] | None,
ApiDescription("The span links of the item, or null if it has none"),
]
event: NotRequired[
Annotated[
TraceItemEvent,
ApiDescription(
"Fields of the event the item came from that are stored with it. Only present "
"when at least one of them is"
),
]
]


_NUMERIC_COERCIONS: dict[str, type] = {"valFloat": float, "valDouble": float}
_VAL_TYPE_TO_COLUMN_TYPE: dict[str, ColumnType] = {
"valBool": "boolean",
Expand Down Expand Up @@ -138,7 +232,7 @@ def convert_rpc_attribute_to_json(
raise BadRequest(f"Unknown field in Response: {internal_name}")
column_type, output_value, python_scalar_type = _get_value_from_attribute(source)

if column_type is None and output_value is None:
if column_type is None or output_value is None:
continue

output_type: ScalarType | Literal["array"] = "str"
Expand Down Expand Up @@ -274,7 +368,7 @@ def extract_key(key: str) -> str | None:


# Attribute name -> `event` field name
_SERIALIZED_EVENT_ATTRIBUTES: dict[str, str] = {
_SERIALIZED_EVENT_ATTRIBUTES: dict[str, Literal["contexts", "extra", "breadcrumbs"]] = {
"sentry.event.serialized_contexts": "contexts",
"sentry.event.serialized_extra": "extra",
"sentry.event.serialized_breadcrumbs": "breadcrumbs",
Expand All @@ -299,12 +393,12 @@ def _normalize_breadcrumbs(breadcrumbs: Any) -> None:
sentry_sdk.capture_exception(e)


def serialize_event(attributes: list[dict[str, Any]]) -> dict[str, Any] | None:
def serialize_event(attributes: list[dict[str, Any]]) -> TraceItemEvent | None:
"""A few event fields (contexts, extra, breadcrumbs) are stored as
JSON-serialized strings under internal `sentry.event.serialized_*`
attributes. Parse any that are present back into JSON and return them,
wrapped in a single `event` dict."""
result: dict[str, Any] = {}
result: TraceItemEvent = {}
attribute_map = {attribute["name"]: attribute for attribute in attributes}
for attribute_name, event_key in _SERIALIZED_EVENT_ATTRIBUTES.items():
attribute = get_attribute(attribute_map, attribute_name)
Expand All @@ -329,7 +423,7 @@ def serialize_event(attributes: list[dict[str, Any]]) -> dict[str, Any] | None:
return result or None


def serialize_links(attributes: list[dict[str, Any]]) -> list[dict[str, Any]] | None:
def serialize_links(attributes: list[dict[str, Any]]) -> list[TraceItemLink] | None:
"""Links are temporarily stored in `sentry.links` so lets parse that back out and return separately"""
attribute_map = {attribute["name"]: attribute for attribute in attributes}
link_attribute = get_attribute(attribute_map, "sentry.links")
Expand All @@ -349,8 +443,8 @@ def serialize_links(attributes: list[dict[str, Any]]) -> list[dict[str, Any]] |
return None


def serialize_link(link: dict[str, Any]) -> dict[str, Any]:
clean_link = {
def serialize_link(link: dict[str, Any]) -> TraceItemLink:
clean_link: TraceItemLink = {
"itemId": link["span_id"],
"traceId": link["trace_id"],
}
Expand All @@ -368,7 +462,7 @@ def serialize_link(link: dict[str, Any]) -> dict[str, Any]:
return clean_link


def serialize_link_attribute(name: str, value: Any) -> dict[str, Any] | None:
def serialize_link_attribute(name: str, value: Any) -> TraceItemLinkAttribute | None:
"""
Serializes a single span link attribute, returning `None` for unsupported
values. The stored value shape depends on the ingest pipeline: the
Expand All @@ -386,7 +480,7 @@ def serialize_link_attribute(name: str, value: Any) -> dict[str, Any] | None:
return {"name": name, "value": value, "type": attribute_type}


def infer_type(value: Any) -> str | None:
def infer_type(value: Any) -> Literal["str", "int", "float", "bool"] | None:
"""
Attempt to infer the type of a link attribute value. Only supports a subset
of types, since realistically we only store known keys. This becomes moot
Expand Down Expand Up @@ -424,29 +518,96 @@ class ProjectTraceItemDetailsEndpointSerializer(serializers.Serializer):
)


@extend_schema(tags=["Explore"])
@cell_silo_endpoint
class ProjectTraceItemDetailsEndpoint(ConditionalGetResponseMixin, ProjectEndpoint):
owner = ApiOwner.DATA_BROWSING
publish_status = {
"GET": ApiPublishStatus.EXPERIMENTAL,
# The response shape is still changing.
"GET": ApiPublishStatus.PUBLIC_EXPERIMENTAL,
}
# Deletion, retention, and flag rollouts can still change a written item.
cache_tier = CacheTier.STABLE

@staticmethod
def get(request: Request, project: Project, item_id: str) -> Response:
@extend_schema(
operation_id="retrieveProjectTraceItem",
summary="Retrieve a Trace Item",
parameters=[
GlobalParams.ORG_ID_OR_SLUG,
GlobalParams.PROJECT_ID_OR_SLUG,
OpenApiParameter(
name="item_id",
location="path",
required=True,
type=str,
description=(
"The hexadecimal ID of the item: the 16-character span ID for a span, "
"or the 32-character item ID for other item types"
),
),
OpenApiParameter(
name="trace_id",
location="query",
required=True,
type=str,
description="The 32-character ID of the trace the item belongs to",
),
OpenApiParameter(
name="item_type",
location="query",
required=True,
type=str,
enum=[item_type.value for item_type in constants.SUPPORTED_TRACE_ITEM_TYPE_MAP],
description="The type of the item",
),
OpenApiParameter(
name="routing_hint",
location="query",
required=False,
type=str,
description=(
"The opaque `meta.routingHint` of the events response that contained "
"the item. Pass it unchanged to look the item up in the same storage. "
"When it's omitted or empty, the default storage is used"
),
),
OpenApiParameter(
name="timestamp",
location="query",
required=False,
type=OpenApiTypes.DATETIME,
description=(
"When the item happened, as an ISO 8601 timestamp or Unix seconds. The "
"lookup is narrowed to a few minutes around it, which makes it faster"
),
),
GlobalParams.STATS_PERIOD,
GlobalParams.START,
GlobalParams.END,
],
responses={
200: inline_sentry_response_serializer(
"TraceItemDetailsResponse", TraceItemDetailsResponse
),
400: RESPONSE_BAD_REQUEST,
401: RESPONSE_UNAUTHORIZED,
403: RESPONSE_FORBIDDEN,
404: RESPONSE_NOT_FOUND,
},
examples=TraceItemExamples.RETRIEVE_TRACE_ITEM,
)
def get(
self, request: Request, project: Project, item_id: str
) -> Response[TraceItemDetailsResponse] | Response[ValidationErrorResponse] | Response[str]:
"""
Retrieve a Trace Item for a project.

For example, you might ask 'give me all the details about the span/log with id 01234567'
Retrieve a span, log or other trace item of a project, with all of its attributes.

Pass the events response's meta.routingHint as routing_hint to look up an item
using the same storage. Omitted or empty hints use the default storage;
invalid hints return 400. Treat the hint as opaque and pass it unchanged.
Pass the `meta.routingHint` of the events response that listed the item as
`routing_hint`, unchanged. An invalid hint returns 400.
"""
serializer = ProjectTraceItemDetailsEndpointSerializer(data=request.GET)
if not serializer.is_valid():
return Response(serializer.errors, status=400)
return Response(as_validation_errors(serializer), status=400)

try:
start, end = get_date_range_from_params(request.GET, optional=True)
Expand Down Expand Up @@ -536,7 +697,7 @@ def get(request: Request, project: Project, item_id: str) -> Response:
include_internal = is_active_superuser(request) or is_active_staff(request)
include_internal_convention_attributes = request.user.is_staff or request.user.is_superuser

resp_dict = {
resp_dict: TraceItemDetailsResponse = {
"itemId": serialize_item_id(resp["itemId"], item_type),
"timestamp": resp["timestamp"],
"attributes": convert_rpc_attribute_to_json(
Expand Down
5 changes: 5 additions & 0 deletions src/sentry/apidocs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -105,6 +105,11 @@ concrete type that matches what the endpoint returns. A TypedDict without any
fields gets `maxProperties: 0`, so it counts as typed: use one for a response
that is always `{}`.

A few fields hold data whose shape Sentry doesn't define, such as the contexts
an SDK sent. Type those as `JsonValue` from `sentry.apidocs.formats`: the schema
lists every JSON type, and the check counts it as typed. Don't use it for a
field you can type.

When another schema already pins a field down, such as a JSON Schema the code
validates the data against, build the field's schema from it with
`Annotated[T, ApiSchema(build)]` instead of copying it into a TypedDict, so the
Expand Down
52 changes: 52 additions & 0 deletions src/sentry/apidocs/examples/trace_item_examples.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
from drf_spectacular.utils import OpenApiExample

SPAN = {
"itemId": "8873a98879faf06d",
"timestamp": "2025-01-01T12:00:00Z",
"attributes": [
{"name": "is_transaction", "type": "bool", "value": True},
{"name": "span.duration", "type": "float", "value": 132.5},
{"name": "project_id", "type": "int", "value": "4505281256090153"},
{"name": "span.op", "type": "str", "value": "http.server"},
{"name": "transaction", "type": "str", "value": "GET /api/checkout/"},
],
"meta": {},
"links": [
{
"itemId": "e3c58cb0bd2d4c89",
"traceId": "d099bf9ad5a143cf8f83a98081d0ed3b",
"sampled": True,
"attributes": [{"name": "sentry.link.type", "value": "previous_trace", "type": "str"}],
}
],
}

LOG = {
"itemId": "0197fb2a5c5e7d72a8a3a6c94e8f2b1d",
"timestamp": "2025-01-01T12:00:00Z",
"attributes": [
{"name": "severity_number", "type": "int", "value": "9"},
{"name": "message", "type": "str", "value": "Payment processed for order 1234..."},
{"name": "severity", "type": "str", "value": "info"},
{"name": "trace", "type": "str", "value": "d099bf9ad5a143cf8f83a98081d0ed3b"},
],
"meta": {"message": {"length": 300, "reason": "value too long"}},
"links": None,
}


class TraceItemExamples:
RETRIEVE_TRACE_ITEM = [
OpenApiExample(
"Retrieve a span",
value=SPAN,
response_only=True,
status_codes=["200"],
),
OpenApiExample(
"Retrieve a log",
value=LOG,
response_only=True,
status_codes=["200"],
),
]
Loading
Loading