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

# Oodle

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

This guide provides instructions for integrating [Oodle](https://oodle.ai) with the TrueFoundry AI Gateway to export OpenTelemetry traces and metrics.

## What is Oodle?

Oodle is a managed observability platform for metrics, logs, traces and agent traces. It is OpenTelemetry-native: one OTLP endpoint accepts every signal, with the same two headers on every request.

### Key capabilities

* **[Agent traces](https://docs.oodle.ai/integrations/opentelemetry)**: Spans that follow the OpenTelemetry GenAI semantic conventions show up as agent traces, with the transcript, token counts and cost. The AI Gateway emits these `gen_ai.*` attributes on its spans.
* **[Trace Explorer](https://docs.oodle.ai/integrations/opentelemetry)**: Search and inspect AI Gateway traces next to the rest of your services' traces.
* **[Metrics](https://docs.oodle.ai/integrations/opentelemetry)**: OTLP metrics are stored as Prometheus-compatible series and queried with PromQL.

You can also let agents query Oodle through the MCP Gateway. See [Oodle MCP Server](https://www.truefoundry.com/docs/ai-gateway/mcp/oodle-mcp-server.md).

## Prerequisites

Before integrating Oodle with TrueFoundry, ensure you have:

1. **TrueFoundry account**: Create a [TrueFoundry account](https://www.truefoundry.com/register) and follow our [Gateway Quick Start Guide](https://docs.truefoundry.com/gateway/quick-start).
2. **Oodle account**: Sign up at [Oodle](https://oodle.ai) and note your deployment, the subdomain of the URL you use to open Oodle (for example `ap1` in `https://ap1.oodle.ai`).

## Understanding the Oodle Endpoint

You need three values from Oodle:

| Value | Where to find it |
| - | - |
| **Instance ID** (`OODLE_INSTANCE`) | **Settings** → **API Keys** in Oodle. It identifies your Oodle organization; it is not the deployment name. |
| **API key** (`OODLE_API_KEY`) | **Settings** → **API Keys** in Oodle |
| **OTLP endpoint** (`OTLP_ENDPOINT`) | The **Open Telemetry** tile on the **Integrations** page in Oodle. It has the form `<OODLE_INSTANCE>-otlp.collector.oodle.ai`. |

The **TrueFoundry** tile on the **Integrations** page in Oodle shows all three values filled in for you.

Every request to Oodle must carry two headers, `X-OODLE-INSTANCE` and `X-API-KEY`. Oodle rejects requests without them with `401 Unauthorized`.

TrueFoundry does **not** auto-append signal paths, so you must supply the full path: `https://<OTLP_ENDPOINT>/v1/traces` for traces and `https://<OTLP_ENDPOINT>/v1/metrics` for metrics.

## Integration Steps

**1. Get your Oodle values**

1. Log in to Oodle and open **Settings** → **API Keys**.
2. Copy your **Instance ID**, and create or copy an **API key**.
3. Open **Integrations**, select the **Open Telemetry** tile, and copy the OTLP endpoint.

**2. Configure traces 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.
3. Enable the **Otel Traces Exporter Configuration** toggle and fill in:

| Field | Value |
| - | - |
| **Protocol** | HTTP Configuration |
| **Endpoint** | `https://<OTLP_ENDPOINT>/v1/traces` |
| **Encoding** | Proto |

4. Click **+ Add Headers** and add both headers:

| Header | Value |
| - | - |
| `X-OODLE-INSTANCE` | `<OODLE_INSTANCE>` |
| `X-API-KEY` | `<OODLE_API_KEY>` |

**3. Configure metrics export (optional)**

To send gateway metrics too, enable the **Otel Metrics Exporter Configuration** toggle and fill in:

| Field | Value |
| - | - |
| **Protocol** | HTTP Configuration |
| **Endpoint** | `https://<OTLP_ENDPOINT>/v1/metrics` |
| **Encoding** | Proto |
| **Headers** | The same `X-OODLE-INSTANCE` and `X-API-KEY` headers as for traces |

Keep **Export Delta Metrics** off. Oodle reads cumulative counters and histograms.

**4. Save and verify**

1. Click **Save**.
2. Send a few requests through the TrueFoundry AI Gateway.
3. In Oodle, open the trace explorer at `https://<deployment>.oodle.ai/traces` and look for traces from the AI Gateway.
4. Open `https://<deployment>.oodle.ai/genai/traces` to see the same requests as agent traces, with the transcript, token counts and cost.

TrueFoundry keeps its own copy of the traces, so nothing changes in the TrueFoundry UI.

## Send Traces from the Gateway Plane

In hybrid and self-hosted deployments, the OTEL buffer next to the AI Gateway can send traces to Oodle directly from your cluster, even when the control plane is briefly unreachable. The buffer sends traces only; keep the control-plane metrics export above for metrics. See [Exporting traces via Gateway Plane](https://www.truefoundry.com/docs/ai-gateway/export-opentelemetry-data.md#exporting-traces-to-otel-compatible-platforms-via-gateway-plane) for how the buffer works.

**1. Store the Oodle API key in a Secret**

```bash theme={"dark"}
kubectl create secret generic tfy-otel-buffer-sink-credentials -n truefoundry \
  --from-literal=OODLE_API_KEY='<OODLE_API_KEY>'
```

If the Secret already exists, add the `OODLE_API_KEY` key to it instead.

**2. Add Oodle as a sink**

```yaml truefoundry-values.yaml theme={"dark"}
tfy-llm-gateway:
  tfy-otel-buffer:
    additionalSinks:
      oodle:
        type: opentelemetry
        protocol:
          type: http
          uri: https://<OTLP_ENDPOINT>/v1/traces
          method: post
          compression: gzip
          encoding:
            codec: otlp
          request:
            headers:
              X-OODLE-INSTANCE: "<OODLE_INSTANCE>"
              X-API-KEY: "SECRET[additional_sink_credentials.OODLE_API_KEY]"
```

Keep `compression: gzip`. An AI Gateway span holds the full prompt and response, so an uncompressed batch can be larger than Oodle accepts in one request.

**3. Apply the values and restart the buffer**

Apply the values with your usual `helm upgrade`, then restart the buffer so it reads the new Secret:

```bash theme={"dark"}
kubectl rollout restart statefulset tfy-otel-buffer -n truefoundry
```

## Troubleshooting

> [accordion] No traces in Oodle
>
> * Check that the endpoint is the full signal URL, ending in `/v1/traces` for traces and `/v1/metrics` for metrics.
> * Check that both `X-OODLE-INSTANCE` and `X-API-KEY` are set. Oodle answers `401` without them.
> * Check that `X-OODLE-INSTANCE` is your instance ID, not your deployment name.

> [accordion] Gateway plane traces stopped after a key change
>
> The buffer reads the Secret only when it starts. After you add or rotate a key, run `kubectl rollout restart statefulset tfy-otel-buffer -n truefoundry`.

## Configuration Reference

| Configuration | Value |
| - | - |
| **Traces Endpoint** | `https://<OTLP_ENDPOINT>/v1/traces` |
| **Metrics Endpoint** | `https://<OTLP_ENDPOINT>/v1/metrics` |
| **Protocol** | HTTP |
| **Encoding** | Proto |
| **Instance Header** | `X-OODLE-INSTANCE: <OODLE_INSTANCE>` |
| **Auth Header** | `X-API-KEY: <OODLE_API_KEY>` |
| **Export Delta Metrics** | Off |

For more, see [Oodle's TrueFoundry guide](https://docs.oodle.ai/integrations/mcp/truefoundry) and [Oodle's OpenTelemetry docs](https://docs.oodle.ai/integrations/opentelemetry).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.