> ## 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. # Request Logs: Trace Inspection > Inspect a single Gateway trace and understand span hierarchy ## 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). ```python TrueFoundry SDK lines theme={"dark"} 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) ``` ```python HTTP API theme={"dark"} import requests # Fetch all spans for a specific trace ID with guardrail processing trace_id = "019a047ee43577009b6bb5b6ab9477d2" 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-21T00:00:00.000Z", "endTime": "2025-10-21T23:59:59.999Z", "traceIds": ["019a047ee43577009b6bb5b6ab9477d2"], "limit": 200, "sortDirection": "desc", "pageToken": page_token } ) response.raise_for_status() data = response.json() for span in data['data']: print(span) page_token = data['pagination'].get("nextPageToken") done = page_token is None print("Fetch spans for trace completed!") ``` 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. ```shell theme={"dark"} TraceSpan( span_id='bddb6503c0eeb940', trace_id='019a047ee43577009b6bb5b6ab9477d2', parent_span_id='', service_name='tfy-llm-gateway', span_name='ChatCompletion: openai-main/gpt-5', timestamp='2025-10-21T02:00:16.181Z', duration_ns=7087251623.0, status_code='Unset', span_attributes={ 'tfy.model.fqn': 'truefoundry:openai:openai-main:model:gpt-5', 'tfy.model.request_type': 'ChatCompletion', 'tfy.error_message': '', 'tfy.model.name': 'openai-main/gpt-5', 'tfy.model.id': 'cme6zartb0v0701pjeqk9fulg', 'tfy.triggered_guardrail_fqns': ['truefoundry:guardrail-config-group:pii-guardrails:guardrail-config:pii-redaction'], 'tfy.model.metric.inter_token_latency_in_ms': 0, 'tfy.model.metric.time_to_first_token_in_ms': 7022.75, 'tfy.model.metric.latency_in_ms': 6600.23, 'tfy.model.metric.input_tokens': 12, 'tfy.model.metric.cost_in_usd': 0.00481501, 'tfy.model.metric.output_tokens': 480, 'tfy.input': '{"model":"openai-main/gpt-5","messages":[{"role":"user","content":"I am sateesh. Hi"}],"stream":true}', 'tfy.output': '{"id":"chatcmpl-CSvxYlQKenRQWspGHQaCLRcz1MbZU","usage":{"prompt_tokens":12,"completion_tokens":480,"cache_read_tokens":0,"cache_write_tokens":0,"reasoning_tokens":448,"total_tokens":492},"object":"chat.completion","model":"gpt-5-2025-08-07","created":1761012016,"choices":[{"finish_reason":"stop","index":0,"logprobs":null,"message":{"role":"assistant","content":"Hi! Nice to meet you. What would you like me to call you, and how can I help today?","refusal":null}}]}', 'tfy.span_type': 'ChatCompletion' }, events=[], created_by_subject=Subject( subject_id='sateesh@truefoundry.com', subject_type=, subject_slug='sateesh@truefoundry.com', subject_display_name=None ) ) ``` 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. ```shell theme={"dark"} TraceSpan( span_id='d46e8d5202edc22c', trace_id='019a047ee43577009b6bb5b6ab9477d2', parent_span_id='bddb6503c0eeb940', service_name='tfy-llm-gateway', span_name='Guardrail: pii-guardrails/pii-redaction', timestamp='2025-10-21T02:00:16.183Z', duration_ns=483181280.0, status_code='Ok', span_attributes={ 'tfy.guardrail.fqn': 'truefoundry:guardrail-config-group:pii-guardrails:guardrail-config:pii-redaction', 'tfy.guardrail.name': 'pii-guardrails/pii-redaction', 'tfy.guardrail.id': 'cmd4avynw05xa01mo1oli6bsj', 'tfy.guardrail.result': 'mutation', 'tfy.guardrail.applied_on_entity.type': 'model', 'tfy.guardrail.applied_on_entity.id': 'cme6zartb0v0701pjeqk9fulg', 'tfy.guardrail.applied_on_entity.name': 'openai-main/gpt-5', 'tfy.guardrail.applied_on_entity.fqn': 'truefoundry:openai:openai-main:model:gpt-5', 'tfy.guardrail.applied_on_entity.scope': 'input', 'tfy.guardrail.metric.latency_in_ms': 482.98, 'tfy.span_type': 'Guardrail' }, events=[], created_by_subject=Subject( subject_id='sateesh@truefoundry.com', subject_type=, subject_slug='sateesh@truefoundry.com', subject_display_name=None ) ) ``` 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. ```shell theme={"dark"} TraceSpan( span_id='fb07005b3c28a98b', trace_id='019a047ee43577009b6bb5b6ab9477d2', parent_span_id='d46e8d5202edc22c', service_name='tfy-llm-gateway', span_name='POST https://bedrock-runtime.eu-central-1.amazonaws.com/guardrail/o8g71agqe4cl/version/1/apply', timestamp='2025-10-21T02:00:16.184Z', duration_ns=481350372.0, status_code='Unset', span_attributes={ 'url.path': '/guardrail/o8g71agqe4cl/version/1/apply', 'http.request.method': 'POST', 'url.scheme': 'https', 'network.peer.address': '18.194.132.160', 'url.full': 'https://bedrock-runtime.eu-central-1.amazonaws.com/guardrail/o8g71agqe4cl/version/1/apply', 'http.request.method_original': 'POST', 'user_agent.original': 'node', 'url.query': '', 'http.request.url': 'https://bedrock-runtime.eu-central-1.amazonaws.com/guardrail/o8g71agqe4cl/version/1/apply', 'server.address': 'bedrock-runtime.eu-central-1.amazonaws.com', 'server.port': 443, 'http.response.status_code': 200, 'network.peer.port': 443, }, created_by_subject=Subject( subject_id='sateesh@truefoundry.com', subject_type=, subject_slug='sateesh@truefoundry.com', subject_display_name=None ) ) ``` 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. ```shell theme={"dark"} TraceSpan( span_id='de09be32ba8e0c37', trace_id='019a047ee43577009b6bb5b6ab9477d2', parent_span_id='bddb6503c0eeb940', service_name='tfy-llm-gateway', span_name='Model: openai-main/gpt-5', timestamp='2025-10-21T02:00:16.667Z', duration_ns=6600714193.0, status_code='Ok', span_attributes={ 'tfy.model.fqn': 'truefoundry:openai:openai-main:model:gpt-5', 'tfy.model.id': 'cme6zartb0v0701pjeqk9fulg', 'tfy.model.name': 'openai-main/gpt-5', 'tfy.model.request_url': 'https://api.openai.com/v1/chat/completions', 'tfy.model.request_type': 'ChatCompletion', 'tfy.error_message': '', 'tfy.model.metric.cost_in_usd': 0.00481501, 'tfy.model.metric.inter_token_latency_in_ms': 0, 'tfy.model.metric.time_to_first_token_in_ms': 7022.75, 'tfy.model.metric.input_tokens': 12, 'tfy.model.metric.latency_in_ms': 6600.23, 'tfy.model.metric.output_tokens': 480, 'tfy.model.metric.cache_read_input_tokens': 0, 'tfy.model.metric.cache_creation_input_tokens': 0, 'tfy.model.streaming': True, 'tfy.input': '{"model":"openai-main/gpt-5","messages":[{"role":"user","content":"I am {NAME}. Hi"}],"stream":true}', 'tfy.output': '{"id":"chatcmpl-CSvxYlQKenRQWspGHQaCLRcz1MbZU","usage":{"prompt_tokens":12,"completion_tokens":480,"cache_read_tokens":0,"cache_write_tokens":0,"reasoning_tokens":448,"total_tokens":492},"object":"chat.completion","model":"gpt-5-2025-08-07","created":1761012016,"choices":[{"finish_reason":"stop","index":0,"logprobs":null,"message":{"role":"assistant","content":"Hi! Nice to meet you. What would you like me to call you, and how can I help today?","refusal":null}}]}', 'tfy.span_type': 'Model' }, created_by_subject=Subject( subject_id='sateesh@truefoundry.com', subject_type=, subject_slug='sateesh@truefoundry.com', subject_display_name=None ) ) ``` 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. ```shell theme={"dark"} TraceSpan( span_id='95794dcfbaad832a', trace_id='019a047ee43577009b6bb5b6ab9477d2', parent_span_id='de09be32ba8e0c37', service_name='tfy-llm-gateway', span_name='POST https://api.openai.com/v1/chat/completions', timestamp='2025-10-21T02:00:16.667Z', duration_ns=6599577503.0, status_code='Unset', span_attributes={ 'url.path': '/v1/chat/completions', 'http.request.method': 'POST', 'url.scheme': 'https', 'network.peer.address': '162.159.140.245', 'url.full': 'https://api.openai.com/v1/chat/completions', 'http.request.method_original': 'POST', 'user_agent.original': 'node', 'url.query': '', 'http.request.url': 'https://api.openai.com/v1/chat/completions', 'server.address': 'api.openai.com', 'server.port': 443, 'http.response.status_code': 200, 'network.peer.port': 443, }, created_by_subject=Subject( subject_id='sateesh@truefoundry.com', subject_type=, subject_slug='sateesh@truefoundry.com', subject_display_name=None ) ) ```