> ## Documentation Index
> Fetch the complete documentation index at: https://docs.braintrust.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Correlate Mixpanel events with LLM traces

> Correlate Mixpanel events with LLM traces using custom spans and OpenTelemetry, and investigate external analytics with Loop MCP tools.

> [!NOTE]
>
> **Applies to:**
>
> * Plan - Any
> * Deployment - Any
> *
> * Use case - Correlate client analytics with LLM activity

## Summary

You can correlate Mixpanel-style client events with LLM traces by sending analytics as spans or by exporting your app traces via OpenTelemetry. Create user-action spans and nest LLM and tool calls beneath them. If your analytics service exposes an MCP server, Loop can query it for investigation context.

## What is happening

Client analytics live in a separate system from LLM traces. To view both in Braintrust, emit analytics as trace data or convert exported analytics events into spans. Loop can query external analytics through MCP tools, but those queries do not ingest events into traces or add attributes to trace views.

## Fix or suggestion

### Option 1: emit analytics as custom spans (recommended)

1. Create a short-lived span around each user action. Include stable keys such as `user_id`, `session_id`, `request_id`, and a precise timestamp as attributes. Use the Braintrust SDK tracer or your OpenTelemetry tracer.
2. Make LLM and tool calls as child spans of the user-action span. This creates a single trace that contains both UI events and LLM activity. Across client and server boundaries, [propagate trace context](https://docs.braintrust.dev/integrations/sdk-integrations/opentelemetry/link-spans.md#propagate-context-across-services). Matching `user_id` or `session_id` attributes alone does not make spans part of the same trace.
3. Add meaningful `event_type` and any product attributes you need to correlate with Mixpanel events.

First [configure an OpenTelemetry provider and export to Braintrust](https://docs.braintrust.dev/integrations/sdk-integrations/opentelemetry/send-traces-and-logs.md#braintrust-span-processor). Keep `filterAISpans` disabled so user-action spans are included.

In Node.js, use the `NodeSDK` setup linked above, which registers a context manager to preserve the active span across asynchronous calls. If you use `BasicTracerProvider` directly, [register an OpenTelemetry context manager](https://opentelemetry.io/docs/languages/js/context/#context-manager), such as `AsyncLocalStorageContextManager` from `@opentelemetry/context-async-hooks`, before creating spans. Without a context manager, LLM calls can become separate root traces instead of children of the user-action span.

The example below uses `@opentelemetry/api`. Pass your instrumented LLM call as `runLlmCall`. If it uses Braintrust SDK spans, [configure context sharing](https://docs.braintrust.dev/integrations/sdk-integrations/opentelemetry/link-spans.md#share-context-within-a-process) first.

```javascript theme={null}
import { trace } from "@opentelemetry/api";

const tracer = trace.getTracer("product-analytics");

export async function traceUserAction(runLlmCall, { userId, sessionId, requestId }) {
  return tracer.startActiveSpan(
    "user-action",
    {
      attributes: {
        user_id: userId,
        session_id: sessionId,
        request_id: requestId,
        event_type: "button_click",
      },
    },
    async (span) => {
      try {
        return await runLlmCall();
      } finally {
        span.end();
      }
    },
  );
}
```

### Option 2: export Mixpanel events into OpenTelemetry

1. Export Mixpanel events using an export method supported by your Mixpanel setup, or emit OpenTelemetry spans alongside Mixpanel events in your application.
2. Implement a processing step that converts exported events into spans. Preserve the event timestamps and use the same attributes: `user_id`, `session_id`, `request_id`, and `event_type`. Shared attributes let you correlate records, but do not merge separate traces.
3. Send traces to Braintrust using an [OTLP trace exporter](https://docs.braintrust.dev/integrations/sdk-integrations/opentelemetry/send-traces-and-logs.md#otlp-trace-exporter) configured with your endpoint, API key, and parent project.

### Option 3: query external analytics with Loop MCP

> [!WARNING]
>
> External MCP connections in Loop are in [public preview](https://docs.braintrust.dev/feature-lifecycle.md) and can change before reaching general availability.

This option requires an analytics MCP server with tools that can query the events you need. The server must support Streamable HTTP and OAuth or bearer API key authentication. On BYOC, external MCP connections require the Loop runtime, and the server must be reachable from it. See [BYOC Loop availability](https://docs.braintrust.dev/admin/deployment/byoc/manage.md#loop-availability).

1. [Connect the analytics MCP server to Loop](https://docs.braintrust.dev/loop/mcp.md) and test the connection.
2. Ask Loop to query analytics for a known `user_id`, `session_id`, or time range and compare the results with relevant Braintrust traces.
3. Verify the investigation includes the requested analytics context. The available queries depend on the tools your server exposes. This workflow does not merge external events into Braintrust traces.

## How to confirm it worked

* For option 1, query traces for a known `request_id`. You should see a `user-action` span and child LLM or tool spans in the same trace.
* For option 2, verify analytics-derived spans contain the original event timestamps and attributes such as `user_id` and `session_id`.
* For option 3, confirm Loop can query the analytics server and use the returned context in its investigation.

## Notes

* When exporting Mixpanel data, prefer stable identifiers and synchronized timestamps to avoid mismatches. Convert Mixpanel timestamps to UTC for consistency.
* To learn more about Loop MCP configuration, see [Loop MCP](https://docs.braintrust.dev/loop/mcp.md).


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