> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ja/llms.txt

# DatadogBridge

> **警告:** Datadog Bridge は現在**実験的**です。API と設定オプションは今後のリリースで変更される可能性があります。

Mastra tracing と Datadog の双方向統合を可能にします。ネイティブの `dd-trace` APM Span をリアルタイムで作成し、Tool や Processor 内で自動計装された操作が親 Mastra Span の下に正しくネストされるようにします。Span の終了時に、`dd-trace` のパイプラインを通じて LLM Observability データを出力します。

## コンストラクター

```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[]
}
```

次の項目を含む `BaseExporterConfig` を拡張します。

- `logger?: IMastraLogger` - Logger インスタンス
- `logLevel?: LogLevel | 'debug' | 'info' | 'warn' | 'error'` - ログレベル（デフォルト：INFO）

## メソッド

### `createSpan`

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

Span の構築時に Mastra Observability インスタンスから呼び出されます。`tracer.startSpan()` を介して dd-trace APM Span を即座に作成し、Mastra 互換の識別子を返します。返された ID は Span の存続期間を通して Mastra によって使用されます。dd-trace Span オブジェクトは内部に保存され、スコープの有効化に使用されます。

**戻り値：** `SpanIds | undefined` - `{ spanId, traceId, parentSpanId }`。Bridge が無効な場合は `undefined`。

### `executeInContext`

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

Mastra Span の dd-trace コンテキスト内で非同期関数を実行します。関数内で実行される dd-trace 自動計装済みの操作（HTTP、データベースなど）は、この Span を親とします。

**戻り値：** `Promise<T>` - 関数の実行結果。

### `executeInContextSync`

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

Mastra Span の dd-trace コンテキスト内で同期関数を実行します。

**戻り値：** `T` - 関数の実行結果。

### `flush`

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

Bridge をシャットダウンせず、バッファー内の LLM Observability データを Datadog に強制的にフラッシュします。ランタイムの終了前にデータが確実にエクスポートされるようにする必要があるサーバーレス環境で役立ちます。

### `shutdown`

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

適切に閉じられなかった APM Span を強制終了し、保留中の LLM Observability データをフラッシュして LLM Observability 統合を無効にし、すべての内部状態を消去します。

## 使用例

### 基本的な使用方法

```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 モード（LLM Observability のみ、ローカル Agent なし）

ローカルの Datadog Agent がなく、LLM Observability データのみが必要な場合は、Agentless モードを有効にします。

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

注：Agentless モードでは APM データを送信できません。`dd-trace` APM を使わず、LLM Observability データのみが必要な場合は、[Datadog Exporter](https://mastra.zisheng.pro/ja/reference/observability/tracing/exporters/datadog)の方が簡単です。

### 追加の Exporter との併用

Bridge は Datadog 以外の exporter と組み合わせて、追加の送信先に Trace を送信できます。

```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
        ],
      },
    },
  }),
})
```

> **注記:** 同じ設定で `DatadogBridge` と `DatadogExporter` を組み合わせないでください。どちらも LLM Observability に出力するため、同じデータが二重に書き込まれます。

## セットアップ要件

DatadogBridge では、ロード時に自動計装が HTTP、データベース、フレームワークのライブラリにパッチを適用できるように、他の import より先に `dd-trace` を初期化する必要があります。

dd-trace の初期化、bundler の externals、Agent の設定を含む完全なセットアップ手順については、[DatadogBridge ガイド](https://mastra.zisheng.pro/ja/docs/observability/integrations/bridges/datadog)を参照してください。

## Span のマッピング

Mastra Span タイプは、Datadog LLM Observability Span kind に次のようにマッピングされます。

| Mastra SpanType    | Datadog Kind |
| ------------------ | ------------ |
| `AGENT_RUN`        | `agent`      |
| `MODEL_GENERATION` | `workflow`   |
| `MODEL_STEP`       | `llm`        |
| `TOOL_CALL`        | `tool`       |
| `MCP_TOOL_CALL`    | `tool`       |
| `WORKFLOW_RUN`     | `workflow`   |
| その他のすべてのタイプ        | `task`       |

## タグのサポート

`tracingOptions.tags` の値は、構造化された LLM Observability annotation タグになります。`key:value` の項目はキーと値のペアに分割され、コロンのないタグは `true` に設定されます。

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

このコードは次を生成します。

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

## 環境変数

Bridge は次の環境変数から設定を読み取ります。

| 変数                            | 説明                                           |
| ----------------------------- | -------------------------------------------- |
| `DD_API_KEY`                  | Datadog API キー（Agentless モードでのみ必須）           |
| `DD_LLMOBS_ML_APP`            | ML アプリケーション名                                 |
| `DD_SITE`                     | Datadog サイト                                  |
| `DD_ENV`                      | 環境名                                          |
| `DD_LLMOBS_AGENTLESS_ENABLED` | Agentless モードを有効にするには `'true'` または `'1'` に設定 |

## 関連項目

- [DatadogBridge ガイド](https://mastra.zisheng.pro/ja/docs/observability/integrations/bridges/datadog) - 使用例を含むセットアップガイド
- [Tracing の概要](https://mastra.zisheng.pro/ja/docs/observability/tracing/overview) - Tracing の一般概念
- [DatadogExporter リファレンス](https://mastra.zisheng.pro/ja/reference/observability/tracing/exporters/datadog) - LLM Observability のみ。`dd-trace` APM は含まれません