> ## 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.

# Pydantic Logfire

> Learn how to export LLM Gateway traces and metrics to Pydantic Logfire using OpenTelemetry integration.

This guide provides instructions for integrating [Pydantic Logfire](https://pydantic.dev/logfire) with the TrueFoundry AI Gateway to export OpenTelemetry traces and metrics.

## What is Pydantic Logfire?

Pydantic Logfire is an observability platform built on OpenTelemetry that accepts OTLP traces and metrics over HTTP. It provides an LLM-aware interface that automatically detects GenAI semantic conventions and renders conversation replays, token usage, and cost breakdowns for AI workloads. It is offered as a managed cloud service with US and EU regions.

### Key Features of Pydantic Logfire

* **[LLM & AI Observability](https://pydantic.dev/docs/logfire/get-started/ai-observability/)**: Automatically detects GenAI span attributes and renders conversation replay, token usage, and cost data — no custom configuration needed.
* **[OpenTelemetry Native](https://pydantic.dev/docs/logfire/guides/alternative-clients/)**: Built on the OTLP standard, meaning any OTLP-compatible exporter can send traces and metrics to Logfire without using the Logfire SDK.
* **[Multi-region Ingestion](https://pydantic.dev/docs/logfire/guides/alternative-clients/)**: Provides dedicated ingestion endpoints for the US and EU regions to meet data residency requirements.

## Prerequisites

Before integrating Pydantic Logfire with TrueFoundry, ensure you have:

1. **TrueFoundry Account**: Create a [TrueFoundry account](https://www.truefoundry.com/register) and follow the instructions in our [Gateway Quick Start Guide](https://docs.truefoundry.com/gateway/quick-start).
2. **Pydantic Logfire Account**: Sign up at [logfire.pydantic.dev](https://logfire.pydantic.dev) and create a project to obtain a write token.

## Understanding the Logfire Endpoint

Logfire provides two regional base URLs:

| Region | Base URL                          |
| ------ | --------------------------------- |
| US     | `https://logfire-us.pydantic.dev` |
| EU     | `https://logfire-eu.pydantic.dev` |

You must append the signal path to the base URL yourself — TrueFoundry does not auto-append these paths:

* Traces: `https://logfire-us.pydantic.dev/v1/traces`
* Metrics: `https://logfire-us.pydantic.dev/v1/metrics`

Choose the region that matches where your Logfire project was created. You can confirm your region from the URL shown in your Logfire dashboard after logging in.

## Integration Steps

<Steps>
  <Step title="Create a Write Token in Logfire">
    1. Log into [logfire.pydantic.dev](https://logfire.pydantic.dev) and open your project.
    2. Navigate to **Project Settings** → **Write Tokens**.
    3. Click **Create Write Token**, give it a name, and copy the token value immediately — it is shown only once.

    <Frame>
      <img src="https://mintcdn.com/truefoundry/QX_uR8dHb5uTToG0/images/pydantic-logfire-write-tokens.png?fit=max&auto=format&n=QX_uR8dHb5uTToG0&q=85&s=3da079545673aadc259f6dda0446ee8a" alt="Pydantic Logfire Project Settings page showing the Write Tokens section" width="3024" height="1718" data-path="images/pydantic-logfire-write-tokens.png" />
    </Frame>

    <Tip>
      Store the write token in a secrets manager. Enter it directly as the **Authorization** header value in TrueFoundry — the Logfire OTLP endpoint accepts the raw write token without a `Bearer ` prefix.
    </Tip>
  </Step>

  <Step title="Configure OTEL Export in TrueFoundry">
    1. Go to **AI Gateway** → **Controls** → **Settings** in the TrueFoundry dashboard.
    2. Scroll down to the **OTEL Config** section and click the edit (✏️) button.

    <Frame>
      <img src="https://mintcdn.com/truefoundry/QX_uR8dHb5uTToG0/images/pydantic-logfire-otel-config-section.png?fit=max&auto=format&n=QX_uR8dHb5uTToG0&q=85&s=1f20f0ecb70600dd0c735158ba299a06" alt="TrueFoundry AI Gateway Settings page showing the OTEL Config section" width="2998" height="1712" data-path="images/pydantic-logfire-otel-config-section.png" />
    </Frame>

    3. Enable the **Otel Traces Exporter Configuration** toggle and fill in:

    | Field            | Value                                       |
    | ---------------- | ------------------------------------------- |
    | **Toggle**       | Enabled                                     |
    | **Protocol**     | HTTP Configuration                          |
    | **Endpoint**     | `https://logfire-us.pydantic.dev/v1/traces` |
    | **Encoding**     | Proto                                       |
    | **Header Key**   | `Authorization`                             |
    | **Header Value** | `<your-logfire-write-token>`                |

    <Frame>
      <img src="https://mintcdn.com/truefoundry/QX_uR8dHb5uTToG0/images/pydantic-logfire-otel-traces-exporter.png?fit=max&auto=format&n=QX_uR8dHb5uTToG0&q=85&s=34e1cf04b8136b99d1732f7bc544e5a3" alt="TrueFoundry OTEL Traces Exporter Configuration showing Logfire endpoint and Authorization header" width="1538" height="1326" data-path="images/pydantic-logfire-otel-traces-exporter.png" />
    </Frame>

    4. Enable the **Otel Metrics Exporter Configuration** toggle and fill in:

    | Field            | Value                                        |
    | ---------------- | -------------------------------------------- |
    | **Toggle**       | Enabled                                      |
    | **Protocol**     | HTTP Configuration                           |
    | **Endpoint**     | `https://logfire-us.pydantic.dev/v1/metrics` |
    | **Encoding**     | Proto                                        |
    | **Header Key**   | `Authorization`                              |
    | **Header Value** | `<your-logfire-write-token>`                 |

    5. Click **Save** to apply the configuration.

    <Note>
      If your Logfire project is in the EU region, replace `logfire-us.pydantic.dev` with `logfire-eu.pydantic.dev` in both the traces and metrics endpoint fields.
    </Note>
  </Step>

  <Step title="Verify the Integration">
    1. Make a request through the TrueFoundry AI Gateway.
    2. Log into [logfire.pydantic.dev](https://logfire.pydantic.dev) and open your project.
    3. Navigate to the **Live** view and confirm spans with **service.name** `tfy-llm-gateway` are appearing.

    <Frame>
      <img src="https://mintcdn.com/truefoundry/QX_uR8dHb5uTToG0/images/pydantic-logfire-live-view-traces.png?fit=max&auto=format&n=QX_uR8dHb5uTToG0&q=85&s=f524a19cc4e97b369076e74f235ed56b" alt="Pydantic Logfire Live view showing LLM call traces from TrueFoundry AI Gateway" width="3024" height="1726" data-path="images/pydantic-logfire-live-view-traces.png" />
    </Frame>

    4. Open the **Dashboards** → **Usage Overview** view to confirm gateway metrics are flowing in.

    <Frame>
      <img src="https://mintcdn.com/truefoundry/QX_uR8dHb5uTToG0/images/pydantic-logfire-usage-overview.png?fit=max&auto=format&n=QX_uR8dHb5uTToG0&q=85&s=535998981e77eecb2a163493ab8419b8" alt="Pydantic Logfire Usage Overview dashboard showing gateway metrics from TrueFoundry AI Gateway" width="3024" height="1714" data-path="images/pydantic-logfire-usage-overview.png" />
    </Frame>

    <Tip>
      Logfire automatically recognizes `gen_ai.*` span attributes emitted by the TrueFoundry gateway and renders them in its LLM panel — showing token usage, model names, and request/response content without any extra configuration.
    </Tip>
  </Step>
</Steps>

## Configuration Reference

| Configuration             | Value                                                 |
| ------------------------- | ----------------------------------------------------- |
| **Traces Endpoint (US)**  | `https://logfire-us.pydantic.dev/v1/traces`           |
| **Traces Endpoint (EU)**  | `https://logfire-eu.pydantic.dev/v1/traces`           |
| **Metrics Endpoint (US)** | `https://logfire-us.pydantic.dev/v1/metrics`          |
| **Metrics Endpoint (EU)** | `https://logfire-eu.pydantic.dev/v1/metrics`          |
| **Protocol**              | HTTP                                                  |
| **Encoding**              | Proto                                                 |
| **Auth Header Key**       | `Authorization`                                       |
| **Auth Header Value**     | Your Logfire write token (no `Bearer ` prefix needed) |