Request Logs: Advanced Queries

Filter by trace ID, model spans, metadata, MCP, error type, client disconnects, and TTFT timeouts.

Advanced Use Cases

Filter by Specific Trace ID

Fetch spans of a specific traceId

TrueFoundry SDK

from truefoundry import client
from truefoundry_sdk import SortDirection

spans = client.traces.query_spans(
    data_routing_destination="default",
    start_time="2025-10-08T00:00:00.000Z",
    end_time="2025-10-08T23:59:59.999Z",
    trace_ids=[
        "0199c25e124a70989b0455584fbbf7b7"
    ],
    limit=200,
    sort_direction=SortDirection.DESC
)

# Process all spans across all pages
for span in spans:
    print(span.span_name, span.duration, span.span_attributes.get("tfy.span_type"))

Fetch all model spans

Filter spans by model spanType using the tfy.span_type span attribute filter with value Model.

TrueFoundry SDK

from truefoundry import client
from truefoundry_sdk import SortDirection, SpanAttributeFilter
from truefoundry_sdk.types.span_attribute_filter_operator import SpanAttributeFilterOperator

spans = client.traces.query_spans(
    data_routing_destination="default",
    start_time="2025-10-08T00:00:00.000Z",
    end_time="2025-10-08T23:59:59.999Z",
    filters=[
        SpanAttributeFilter(span_attribute_key="tfy.span_type", operator=SpanAttributeFilterOperator.EQUAL, value="Model"),
    ],
    limit=200,
    sort_direction=SortDirection.DESC
)

# Process all spans across all pages
for span in spans:
    print(span.span_name, span.span_attributes.get("tfy.span_type"))

Fetch requests with Gateway request metadata

Filter spans based on custom metadata keys and values that were passed to Gateway requests using the X-TFY-METADATA header.

TrueFoundry SDK

from truefoundry import client
from truefoundry_sdk import SortDirection, GatewayRequestMetadataFilter
from truefoundry_sdk.types.gateway_request_metadata_filter_operator import GatewayRequestMetadataFilterOperator

spans = client.traces.query_spans(
    data_routing_destination="default",
    start_time="2025-10-08T00:00:00.000Z",
    end_time="2025-10-08T23:59:59.999Z",
    filters=[
        GatewayRequestMetadataFilter(gateway_request_metadata_key="application", operator=GatewayRequestMetadataFilterOperator.EQUAL, value="booking-bot"),
        GatewayRequestMetadataFilter(gateway_request_metadata_key="environment", operator=GatewayRequestMetadataFilterOperator.IN, value=["staging", "production"]),
    ],
    limit=200,
    sort_direction=SortDirection.DESC
)

# Process all spans across all pages
for span in spans:
    print(span.span_name, span.span_attributes.get("tfy.span_type"))

Fetch spans with MCP in span name

Filter spans that have MCP in the span name.

TrueFoundry SDK

from truefoundry import client
from truefoundry_sdk import SortDirection, SpanFieldFilter
from truefoundry_sdk.types.span_field_filter_span_field_name import SpanFieldFilterSpanFieldName
from truefoundry_sdk.types.span_field_filter_operator import SpanFieldFilterOperator

spans = client.traces.query_spans(
    data_routing_destination="default",
    start_time="2025-10-08T00:00:00.000Z",
    end_time="2025-10-08T23:59:59.999Z",
    filters=[
        SpanFieldFilter(span_field_name=SpanFieldFilterSpanFieldName.SPAN_NAME, operator=SpanFieldFilterOperator.STRING_CONTAINS, value="MCP"),
    ],
    limit=200,
    sort_direction=SortDirection.DESC
)

# Process all spans across all pages
for span in spans:
    print(span.span_name, span.span_attributes.get("tfy.span_type"))

Filter model spans by model name

Fetch model spans by filtering with tfy.span_type span attribute filter with value Model, and then further filter by model name using the tfy.model.name span attribute filter.

TrueFoundry SDK

from truefoundry import client
from truefoundry_sdk import SortDirection, SpanAttributeFilter
from truefoundry_sdk.types.span_attribute_filter_operator import SpanAttributeFilterOperator

spans = client.traces.query_spans(
    data_routing_destination="default",
    start_time="2025-10-08T00:00:00.000Z",
    end_time="2025-10-08T23:59:59.999Z",
    filters=[
        SpanAttributeFilter(span_attribute_key="tfy.model.name", operator=SpanAttributeFilterOperator.EQUAL, value="openai-main/gpt-4"),
        SpanAttributeFilter(span_attribute_key="tfy.span_type", operator=SpanAttributeFilterOperator.EQUAL, value="Model"),
    ],
    limit=200,
    sort_direction=SortDirection.DESC
)

# Process all spans across all pages
for span in spans:
    print(span.span_name, span.span_attributes.get("tfy.model.name"))

Filter missing-model vs forbidden spans

Requests for a model that does not exist and requests the caller is not allowed to use both return HTTP 403 with the same client message. Filter on tfy.error_type (tfy-model-not-found vs tfy-forbidden). The attribute is on the Model span. See Authorization vs missing model.

TrueFoundry SDK

from truefoundry import client
from truefoundry_sdk import SortDirection, SpanAttributeFilter
from truefoundry_sdk.types.span_attribute_filter_operator import SpanAttributeFilterOperator

spans = client.traces.query_spans(
    data_routing_destination="default",
    start_time="2025-10-08T00:00:00.000Z",
    end_time="2025-10-08T23:59:59.999Z",
    filters=[
        SpanAttributeFilter(
            span_attribute_key="tfy.error_type",
            operator=SpanAttributeFilterOperator.EQUAL,
            value="tfy-model-not-found",
        ),
    ],
    limit=200,
    sort_direction=SortDirection.DESC,
)

for span in spans:
    print(span.span_name, span.span_attributes.get("tfy.error_type"))

Filter client-disconnected spans

A client that hangs up mid-stream is recorded as tfy.error_type=client-disconnected with HTTP 499, and may still carry cost. Filter on the Model span. See Cancelled and disconnected streams.

TrueFoundry SDK

from truefoundry import client
from truefoundry_sdk import SortDirection, SpanAttributeFilter
from truefoundry_sdk.types.span_attribute_filter_operator import SpanAttributeFilterOperator

spans = client.traces.query_spans(
    data_routing_destination="default",
    start_time="2026-10-08T00:00:00.000Z",
    end_time="2026-10-08T23:59:59.999Z",
    filters=[
        SpanAttributeFilter(
            span_attribute_key="tfy.error_type",
            operator=SpanAttributeFilterOperator.EQUAL,
            value="client-disconnected",
        ),
    ],
    limit=200,
    sort_direction=SortDirection.DESC,
)

for span in spans:
    print(
        span.span_name,
        span.span_attributes.get("tfy.error_type"),
        span.span_attributes.get("tfy.model.tokens_estimated"),
        span.span_attributes.get("tfy.model.metric.cost_in_usd"),
    )

Filter TTFT timeout spans

A streaming request that never produced a first chunk within x-tfy-ttft-timeout-ms is recorded as tfy.error_type=ttft-timeout with HTTP 408. Filter on the Model span. See First Chunk Gate.

TrueFoundry SDK

from truefoundry import client
from truefoundry_sdk import SortDirection, SpanAttributeFilter
from truefoundry_sdk.types.span_attribute_filter_operator import SpanAttributeFilterOperator

spans = client.traces.query_spans(
    data_routing_destination="default",
    start_time="2026-10-08T00:00:00.000Z",
    end_time="2026-10-08T23:59:59.999Z",
    filters=[
        SpanAttributeFilter(
            span_attribute_key="tfy.error_type",
            operator=SpanAttributeFilterOperator.EQUAL,
            value="ttft-timeout",
        ),
    ],
    limit=200,
    sort_direction=SortDirection.DESC,
)

for span in spans:
    print(span.span_name, span.span_attributes.get("tfy.error_type"))