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

# Lunary

> Learn how to export LLM Gateway traces to Lunary using OpenTelemetry integration.

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

## What is Lunary?

[Lunary](https://lunary.ai/) is an open source observability platform for LLM applications. It helps teams capture traces, inspect prompts and responses, monitor agent behavior, and track costs across production GenAI workloads.

### Key Features of Lunary

* **Agent and LLM tracing**: End-to-end visibility into chains, agents, tool calls, and model responses
* **OpenTelemetry ingestion**: Accepts OTLP/HTTP traces so you can send spans from gateways, SDKs, and custom instrumentation
* **Session-level monitoring**: Track conversations, users, and performance across chatbot and RAG workflows
* **Evaluation and analytics**: Analyze runs, categorize outputs, and iterate on prompts with measurable feedback loops

This guide documents **OTLP over HTTP** from the TrueFoundry AI Gateway ([Integration Steps](#integration-steps)). Lunary also supports SDK-based instrumentation and additional OTLP configuration options; see [Lunary's documentation](https://docs.lunary.ai/) for framework-specific guides.

<Note>
  TrueFoundry exports **OTEL traces only** through this configuration. OTEL metrics are not included. Leave the **Otel Metrics Exporter Configuration** toggle disabled unless you configure a separate metrics destination.
</Note>

## Prerequisites

Before integrating Lunary 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. **Lunary Account**: Sign up at [lunary.ai](https://lunary.ai/)
3. **Lunary project public key**: Copy the **Project ID / Public Key** from your Lunary project settings

<Frame>
  <img src="https://mintcdn.com/truefoundry/Mvt9Ivot6GPiEBtY/images/Lunary-public-key.png?fit=max&auto=format&n=Mvt9Ivot6GPiEBtY&q=85&s=837afe63827098485c6ba2f3be174ddb" alt="Lunary project settings showing Project ID and Public Key with copy button for trace ingestion credentials" width="2998" height="1638" data-path="images/Lunary-public-key.png" />
</Frame>

## Integration Steps

TrueFoundry AI Gateway can export OpenTelemetry traces to Lunary over HTTP so you can analyze gateway traffic alongside the rest of your stack.

<Steps>
  <Step title="Get your Lunary public key">
    1. Log into the [Lunary dashboard](https://app.lunary.ai/).
    2. Open your project and go to **Settings** → **API Keys** (or the project keys section).
    3. Copy the **Project ID / Public Key**. Store it securely — treat it like a credential used for trace ingestion.

    <Tip>
      Lunary projects include both a public and private key. For OTLP trace export from TrueFoundry, use the **public key** in the `Authorization` header as shown below.
    </Tip>
  </Step>

  <Step title="Configure OTEL export in TrueFoundry">
    1. In the TrueFoundry dashboard, go to **Settings** → **Organisation** → **OTEL Config** (under **AI Gateway**).

    <Frame>
      <img src="https://mintcdn.com/truefoundry/Mvt9Ivot6GPiEBtY/images/Lunary-tfy-otel.png?fit=max&auto=format&n=Mvt9Ivot6GPiEBtY&q=85&s=67a35e78731db54753b051efc8bc76bf" alt="TrueFoundry Settings Organisation OTEL Config showing HTTP traces endpoint https://api.lunary.ai/v1/traces and Authorization header" width="3022" height="1726" data-path="images/Lunary-tfy-otel.png" />
    </Frame>

    2. Click **edit** on the **OTEL Config** section to open the exporter form (if it is not already open).
    3. Enable the **OTEL Traces Exporter Configuration** toggle.
    4. Select **HTTP Configuration**.
    5. Enter the Lunary traces endpoint: `https://api.lunary.ai/v1/traces`
    6. Set **Encoding** to `Proto`.
  </Step>

  <Step title="Configure headers">
    Enable **Headers** and add Lunary authentication:

    | Header          | Value                        |
    | --------------- | ---------------------------- |
    | `Authorization` | `Bearer <LUNARY_PUBLIC_KEY>` |

    Replace `<LUNARY_PUBLIC_KEY>` with the public key from the first step.

    <Frame>
      <img src="https://mintcdn.com/truefoundry/Mvt9Ivot6GPiEBtY/images/Lunary-otel-config.png?fit=max&auto=format&n=Mvt9Ivot6GPiEBtY&q=85&s=04f7eb493ee5d9161d2abb14db9784b0" alt="TrueFoundry OTEL Traces Exporter Configuration with HTTP endpoint https://api.lunary.ai/v1/traces, Proto encoding, and Authorization Bearer header for Lunary" width="1574" height="1714" data-path="images/Lunary-otel-config.png" />
    </Frame>

    Click **Save** to apply your configuration.
  </Step>

  <Step title="Verify the integration">
    1. Send a few requests through the TrueFoundry AI Gateway (via the Playground or any API call).
    2. In TrueFoundry, open **Monitor** and confirm traces are being generated for those requests.
    3. In Lunary, open **Explore** → **Traces** and confirm new spans appear with the expected hierarchy, token usage, and latency details.

    <Frame>
      <img src="https://mintcdn.com/truefoundry/Mvt9Ivot6GPiEBtY/images/Lunary-traces.png?fit=max&auto=format&n=Mvt9Ivot6GPiEBtY&q=85&s=f181963e3541605b43d4d8952bcc315b" alt="Lunary Traces dashboard showing gateway span hierarchy with MCP and model call details, metadata, and input and output panels" width="3012" height="1592" data-path="images/Lunary-traces.png" />
    </Frame>

    <Tip>
      Lunary ingests OTLP spans asynchronously. Allow a short delay after your first gateway request before checking the Traces view.
    </Tip>
  </Step>
</Steps>

## Configuration summary

| Configuration       | Value                                       |
| ------------------- | ------------------------------------------- |
| **Traces endpoint** | `https://api.lunary.ai/v1/traces`           |
| **Protocol**        | HTTP                                        |
| **Encoding**        | `Proto`                                     |
| **Authentication**  | `Authorization: Bearer <LUNARY_PUBLIC_KEY>` |

<Note>
  The table above matches **HTTP** OTLP fields in TrueFoundry. For SDK-based instrumentation, self-hosted Lunary, or additional OpenTelemetry setup options, see [Lunary's documentation](https://docs.lunary.ai/).
</Note>