Skip to navigation
ObservabilityUsers & identifiers

Custom IDs & attributes

Tag requests with your own record IDs, conversation threads, and custom properties, then group and filter by them.

Respan indexes a few fields you can send with any request, so you can find every span that belongs to a ticket, an order, or a conversation. To tag the end user, use customer_identifier instead. See Users.

FieldUse it forWhere you use it
custom_identifierA record in your app, like a ticket, order, or document: CS-1042Users & identifiers › Custom IDs, and the Custom ID filter in Logs
thread_identifierOne conversation: conv_5d21The Threads grouping and Thread ID filter in Logs
metadataAny other key-value pairs, shown as Custom properties: {"feature": "support"}The Custom property filter in Logs

Send the fields

One request can carry all of them, plus customer_identifier.

client is the OpenAI client pointed at Respan, as in the Gateway quickstart. For other clients and headers, see Respan params.

response = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Draft a reply to ticket CS-1042."}],
    extra_body={
        "custom_identifier": "CS-1042",
        "thread_identifier": "conv_5d21",
        "metadata": {"feature": "support", "region": "us-east"},
    },
)

Logging spans with the API? These are top-level span fields. See Create span.

Send custom_identifier as its own field. A custom_identifier key inside metadata is only a custom property, and doesn’t show up under Custom IDs.

Check a span

In Observability › Logs, click a span and open the Metadata tab. The identifiers are under Properties, and your metadata is under Custom properties.

The Metadata tab of a span, showing Customer ID, Thread ID and Custom ID under Properties, and feature, team and region under Custom properties

Hover a row and click its filter icon to show only the spans with that value.

Filter Logs

In Observability › Logs:

  • Custom ID or Thread ID: click More filters, pick the field, and enter the value.
  • A custom property: click Custom property, search for the key, and pick a value.
  • A whole conversation: switch the grouping from Spans to Threads. Each row is one thread_identifier.

See Logs for filter groups and saved views.

Compare custom IDs

1

Switch to Custom IDs

Go to Observability › Users & identifiers and switch the grouping from Users to Custom IDs.

The Custom IDs view: metric cards for Requests, Tokens, Cost, Errors, TTFT avg, Latency avg and TPS avg, a timeline of the top five custom IDs, and a table of custom IDs

Each row is one custom_identifier, with its requests, tokens, cost, errors, and latency in the selected range. Click a metric card to chart the top five custom IDs by that metric.

2

Pick a time range

Use 5m, 1h, 1d, 7d or Custom above the chart. The default is 7 days, and the longest range is 31 days. Drag across the chart to zoom in. Type part of an ID in Search custom IDs… and press Enter to find it.

3

Open a custom ID

Click a row to see its Properties, Activity, Metrics and Performance. Click Open in logs (L) to see its spans in Logs for the same range.