Request Logs: Filtering

Filter Request Logs

While fetching all Gateway request logs is useful for general monitoring, you’ll often want to filter logs based on specific criteria such as user identity, model names, etc. You can achieve this using the filters parameter in the query_spans method. The API supports the following common filter types:

Span fields filtering: Filter logs by span fields such as spanName, traceId, spanId, etc. See the Query Spans documentation to understand the supported options for spanFieldName and operator.
Span attributes filtering: Filter logs by span attributes, e.g., using tfy.model.name for model name. See Span attributes section to understand the supported options for spanAttributeKey
Gateway request metadata filtering: Filter logs based on Custom Metadata keys and values that you passed to Gateway requests.

The following example demonstrates how to retrieve request logs for OpenAI models submitted by a specific user, where custom metadata matches certain values:

from truefoundry import client
from truefoundry_sdk import SpanFieldFilter, SpanAttributeFilter, GatewayRequestMetadataFilter
from truefoundry_sdk.types.span_field_filter_span_field_name import SpanFieldFilterSpanFieldName
from truefoundry_sdk.types.span_field_filter_operator import SpanFieldFilterOperator
from truefoundry_sdk.types.span_attribute_filter_operator import SpanAttributeFilterOperator
from truefoundry_sdk.types.gateway_request_metadata_filter_operator import GatewayRequestMetadataFilterOperator

# Fetch LLM Gateway request logs with filters
spans = client.traces.query_spans(
    data_routing_destination="default",
    start_time="2025-01-21T00:00:00.000Z",
    filters=[
        SpanFieldFilter(span_field_name=SpanFieldFilterSpanFieldName.CREATED_BY_SUBJECT_SLUG, operator=SpanFieldFilterOperator.EQUAL, value="user@example.com"),
        SpanAttributeFilter(span_attribute_key="tfy.model.name", operator=SpanAttributeFilterOperator.STRING_CONTAINS, value="openai"),
        GatewayRequestMetadataFilter(gateway_request_metadata_key="foo", operator=GatewayRequestMetadataFilterOperator.IN, value=["bar1", "bar2"]),
    ]
)

for span in spans:
    print(span.span_name, span.span_attributes.get('tfy.span_type'))

import requests

page_token = None
done = False
while not done:
    # Make API request
    response = requests.post(
        "https://{control_plane_url}/api/svc/v1/spans/query",
        headers={
            "Authorization": "Bearer YOUR_API_TOKEN",
            "Content-Type": "application/json"
        },
        json={
            "dataRoutingDestination": "default",
            "startTime": "2025-10-08T20:16:54",
            "filters": [
                {"spanFieldName": "createdBySubjectSlug", "operator": "EQUAL", "value": "user@example.com"},
                {"spanAttributeKey": "tfy.model.name", "operator": "STRING_CONTAINS", "value": "openai"},
                {"gatewayRequestMetadataKey": "foo", "operator": "IN", "value": ["bar1", "bar2"]}
            ],
            "pageToken": page_token
        }
    )
    
    response.raise_for_status()
    data = response.json()

    for span in data['data']:
        print(span['spanName'], span['spanAttributes'].get('tfy.span_type', ''))
    
    page_token = data['pagination'].get("nextPageToken")
    done = page_token is None

print("Fetch spans completed!")

Trace Inspection Basic Queries

⌘I

Get Started

LLM Gateway

MCP Registry and Gateway

Skills Registry

Prompt Registry

Guardrails and Security

Observability

Deployment

Admin Guide

Chat

Messages

Embeddings

Rerank

Responses

Image

Audio

Batch

Files

Fine-tuning

Moderations

Models

Filter Request Logs

​Filter Request Logs

Filter Request Logs