@mastra/core/dist/docs/references/reference-observability-tracing-bridges-datadog.md

Mastra is a framework for building AI-powered applications and agents with a modern TypeScript stack.

# DatadogBridge

> **Warning:** The Datadog Bridge is currently **experimental**. APIs and configuration options may change in future releases.

Enables bidirectional integration between Mastra tracing and Datadog. Creates native `dd-trace` APM spans in real time so that auto-instrumented operations inside tools and processors are correctly nested under their parent Mastra span. Emits LLM Observability data through `dd-trace`'s pipeline when spans end.

## Constructor

```typescript
new DatadogBridge(config?: DatadogBridgeConfig)
```

## `DatadogBridgeConfig`

```typescript
interface DatadogBridgeConfig extends BaseExporterConfig {
  apiKey?: string
  mlApp?: string
  site?: string
  service?: string
  env?: string
  agentless?: boolean
  integrationsEnabled?: boolean
  requestContextKeys?: string[]
}
```

Extends `BaseExporterConfig`, which includes:

- `logger?: IMastraLogger` - Logger instance
- `logLevel?: LogLevel | 'debug' | 'info' | 'warn' | 'error'` - Log level (default: INFO)

## Methods

### `createSpan`

```typescript
createSpan(options: CreateSpanOptions<SpanType>): SpanIds | undefined
```

Called by the Mastra observability instance during span construction. Creates a dd-trace APM span eagerly via `tracer.startSpan()` and returns Mastra-compatible identifiers. The returned IDs are used by Mastra throughout the span's lifetime; the dd-trace span object is stored internally and used for scope activation.

**Returns:** `SpanIds | undefined` - `{ spanId, traceId, parentSpanId }`, or `undefined` if the bridge is disabled.

### `executeInContext`

```typescript
executeInContext<T>(spanId: string, fn: () => Promise<T>): Promise<T>
```

Executes an async function within the dd-trace context of a Mastra span. dd-trace auto-instrumented operations running inside the function (HTTP, database, etc.) will be parented to this span.

**Returns:** `Promise<T>` - The result of the function execution.

### `executeInContextSync`

```typescript
executeInContextSync<T>(spanId: string, fn: () => T): T
```

Executes a synchronous function within the dd-trace context of a Mastra span.

**Returns:** `T` - The result of the function execution.

### `flush`

```typescript
async flush(): Promise<void>
```

Force-flushes any buffered LLM Observability data to Datadog without shutting down the bridge. Useful in serverless environments where you need to ensure data is exported before the runtime terminates.

### `shutdown`

```typescript
async shutdown(): Promise<void>
```

Force-finishes any APM spans that weren't properly closed, flushes pending LLM Observability data, disables the LLM Observability integration, and clears all internal state.

## Usage examples

### Basic Usage

```typescript
import tracer from 'dd-trace'

tracer.init({
  service: process.env.DD_SERVICE || 'my-mastra-app',
  env: process.env.DD_ENV || 'production',
})

import { Mastra } from '@mastra/core'
import { Observability } from '@mastra/observability'
import { DatadogBridge } from '@mastra/datadog'

const mastra = new Mastra({
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'my-mastra-app',
        bridge: new DatadogBridge({
          mlApp: process.env.DD_LLMOBS_ML_APP!,
        }),
      },
    },
  }),
  agents: { myAgent },
})
```

### Agentless Mode (LLM Observability only, no local agent)

If you don't have a local Datadog Agent and only want LLM Observability data, enable agentless mode:

```typescript
new DatadogBridge({
  mlApp: process.env.DD_LLMOBS_ML_APP!,
  apiKey: process.env.DD_API_KEY!,
  agentless: true,
})
```

Note: APM data cannot be sent in agentless mode. If you only need LLM Observability data without `dd-trace` APM, the [Datadog Exporter](https://mastra.ai/reference/observability/tracing/exporters/datadog) is a simpler choice.

### With Additional Exporters

The bridge can be combined with non-Datadog exporters to send traces to additional destinations:

```typescript
import { Mastra } from '@mastra/core'
import { Observability, MastraStorageExporter } from '@mastra/observability'
import { DatadogBridge } from '@mastra/datadog'

const mastra = new Mastra({
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'my-mastra-app',
        bridge: new DatadogBridge({
          mlApp: process.env.DD_LLMOBS_ML_APP!,
        }),
        exporters: [
          new MastraStorageExporter(), // Studio access
        ],
      },
    },
  }),
})
```

> **Note:** Don't combine `DatadogBridge` with `DatadogExporter` in the same configuration — both emit to LLM Observability and would double-write the same data.

## Setup requirements

The DatadogBridge requires `dd-trace` to be initialized before any other imports so its auto-instrumentation can patch HTTP, database, and framework libraries at load time.

See the [DatadogBridge Guide](https://mastra.ai/docs/observability/tracing/bridges/datadog) for complete setup instructions, including dd-trace initialization, bundler externals, and agent configuration.

## Span mapping

Mastra span types are mapped to Datadog LLM Observability span kinds:

| Mastra SpanType    | Datadog Kind |
| ------------------ | ------------ |
| `AGENT_RUN`        | `agent`      |
| `MODEL_GENERATION` | `workflow`   |
| `MODEL_STEP`       | `llm`        |
| `TOOL_CALL`        | `tool`       |
| `MCP_TOOL_CALL`    | `tool`       |
| `WORKFLOW_RUN`     | `workflow`   |
| All other types    | `task`       |

## Tags support

`tracingOptions.tags` values become structured LLM Observability annotation tags: `key:value` entries are split into key/value pairs, and tags without a colon are set to `true`.

```typescript
const result = await agent.generate('Hello', {
  tracingOptions: {
    tags: ['production', 'instance_name:career-scout-api'],
  },
})
```

This produces:

```json
{
  "production": true,
  "instance_name": "career-scout-api"
}
```

## Environment variables

The bridge reads configuration from these environment variables:

| Variable                      | Description                                        |
| ----------------------------- | -------------------------------------------------- |
| `DD_API_KEY`                  | Datadog API key (only required for agentless mode) |
| `DD_LLMOBS_ML_APP`            | ML application name                                |
| `DD_SITE`                     | Datadog site                                       |
| `DD_ENV`                      | Environment name                                   |
| `DD_LLMOBS_AGENTLESS_ENABLED` | Set to `'true'` or `'1'` to enable agentless mode  |

## Related

- [DatadogBridge Guide](https://mastra.ai/docs/observability/tracing/bridges/datadog) - Setup guide with examples
- [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview) - General tracing concepts
- [DatadogExporter Reference](https://mastra.ai/reference/observability/tracing/exporters/datadog) - LLM Observability only, no `dd-trace` APM