Skip to main content

Documentation Index

Fetch the complete documentation index at: https://www.truefoundry.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Deep Dive: Inspect a Single Trace

Now that you’ve run a basic query, inspect one request end-to-end. The examples below fetch all spans for a specific trace_id, so you can see the full hierarchy (root request, guardrail processing, model span, and outbound HTTP calls). 
from truefoundry import client
from truefoundry_sdk import SortDirection

# Fetch all spans for a specific trace ID with guardrail processing
trace_id = "019a047ee43577009b6bb5b6ab9477d2"
spans = client.traces.query_spans(
    data_routing_destination="default",
    start_time="2025-10-21T00:00:00.000Z",
    end_time="2025-10-21T23:59:59.999Z",
    trace_ids=["019a047ee43577009b6bb5b6ab9477d2"],
    limit=200,
    sort_direction=SortDirection.DESC
)

for span in spans:
    print(span)
The following trace contains 5 spans that form a hierarchical relationship, demonstrating a request flow with PII redaction guardrail processing:

​
Span Hierarchy Breakdown

The following example demonstrates a complete trace with 5 spans that form a hierarchical relationship. Each span represents a different phase of the request processing, from the initial chat completion request through guardrail processing to the final model inference and network calls.
The ChatCompletion span with ID bddb6503c0eeb940 serves as the root span with no parent span ID (empty parent_span_id). This span represents the complete chat completion request lifecycle from the client’s perspective, capturing the total time from when the request enters the gateway until the response is sent back to the client. With a duration of 7.09 seconds, it provides the overall performance measurement for the entire request flow. The span includes the tfy.triggered_guardrail_fqns attribute showing which guardrails were triggered during processing.
The Guardrail span with ID d46e8d5202edc22c has a parent span “ChatCompletion Span (Root Span)” with ID bddb6503c0eeb940, representing the PII redaction guardrail processing. This span shows the guardrail configuration used.
The Guardrail Network Call span with ID fb07005b3c28a98b has a parent span “Guardrail Span” with ID d46e8d5202edc22c, representing the actual HTTP communication with the external guardrail service (AWS Bedrock). This span captures the network latency and external guardrail service processing time. With a duration of 0.48 seconds, it shows the time spent on the actual guardrail API call.
The Model span with ID de09be32ba8e0c37 has a parent span “ChatCompletion Span (Root Span)” with ID bddb6503c0eeb940, making it a sibling to the Guardrail span. This span contains all the detailed model metrics and represents the LLM model inference processing within the gateway. Notice how the input content has been redacted from I am sateesh. Hi to I am {NAME}. Hi, demonstrating the PII redaction working.
The Model Network Call span with ID 95794dcfbaad832a has a parent span “Model Span” with ID de09be32ba8e0c37, representing the actual HTTP communication with the external provider (OpenAI). This span captures pure network latency and external provider processing time. With a duration of 6.60 seconds, it shows the time spent on the actual API call to the external service.