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

# DatadogBridge

> **注意:** Datadog Bridge 目前仍屬**實驗性質**。API 及設定選項可能會在日後版本中變更。

在 Mastra tracing 與 Datadog 之間提供雙向整合。它會即時建立原生 `dd-trace` APM span，讓 Tool 及處理器內自動檢測的操作正確地置於其父 Mastra span 之下。span 結束時，會透過 `dd-trace` 的 pipeline 發出 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
```

Mastra 可觀測性實例會在建構 span 時呼叫此方法。此方法會透過 `tracer.startSpan()` 立即建立 dd-trace APM span，並傳回與 Mastra 兼容的識別符。Mastra 會在 span 的整個生命週期中使用傳回的 ID。dd-trace span 物件會儲存於內部，供啟用 scope 時使用。

**傳回：** `SpanIds | undefined` - `{ spanId, traceId, parentSpanId }`；如果 bridge 已停用，則為 `undefined`。

### `executeInContext`

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

在 Mastra span 的 dd-trace context 中執行非同步函式。函式內執行並由 dd-trace 自動檢測的操作（HTTP、資料庫等）會以此 span 作為父項。

**傳回：** `Promise<T>` - 函式的執行結果。

### `executeInContextSync`

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

在 Mastra span 的 dd-trace context 中執行同步函式。

**傳回：** `T` - 函式的執行結果。

### `flush`

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

在不關閉 bridge 的情況下，強制將所有已緩衝的 LLM Observability 資料清空至 Datadog。這適用於無伺服器環境，讓你可確保資料在 runtime 終止前匯出。

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

### 無 Agent 模式（只使用 LLM Observability，不使用本機 Agent）

如果你沒有本機 Datadog Agent，而且只需要 LLM Observability 資料，請啟用無 Agent 模式：

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

注意：無 Agent 模式無法傳送 APM 資料。如果你只需要 LLM Observability 資料而不使用 `dd-trace` APM，[Datadog Exporter](https://mastra.zisheng.pro/zh-HK/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 要求先初始化 `dd-trace`，然後才進行任何其他 import，讓其自動檢測功能可在載入時修補 HTTP、資料庫及框架函式庫。

如需完整設定指引，包括 dd-trace 初始化、bundler external 及 Agent 設定，請參閱 [DatadogBridge 指南](https://mastra.zisheng.pro/zh-HK/docs/observability/integrations/bridges/datadog)。

## Span 對應

Mastra span 類型會對應至 Datadog LLM Observability span 種類：

| Mastra SpanType    | Datadog 種類 |
| ------------------ | ---------- |
| `AGENT_RUN`        | `agent`    |
| `MODEL_GENERATION` | `workflow` |
| `MODEL_STEP`       | `llm`      |
| `TOOL_CALL`        | `tool`     |
| `MCP_TOOL_CALL`    | `tool`     |
| `WORKFLOW_RUN`     | `workflow` |
| 所有其他類型             | `task`     |

## 標籤支援

`tracingOptions.tags` 的值會成為結構化 LLM Observability 註解標籤：`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 金鑰（只有無 Agent 模式才需要）   |
| `DD_LLMOBS_ML_APP`            | ML 應用程式名稱                         |
| `DD_SITE`                     | Datadog 網站                        |
| `DD_ENV`                      | 環境名稱                              |
| `DD_LLMOBS_AGENTLESS_ENABLED` | 設為 `'true'` 或 `'1'` 以啟用無 Agent 模式 |

## 相關內容

- [DatadogBridge 指南](https://mastra.zisheng.pro/zh-HK/docs/observability/integrations/bridges/datadog) - 附有範例的設定指南
- [Tracing 概覽](https://mastra.zisheng.pro/zh-HK/docs/observability/tracing/overview) - 一般 tracing 概念
- [DatadogExporter 參考](https://mastra.zisheng.pro/zh-HK/reference/observability/tracing/exporters/datadog) - 只使用 LLM Observability，不使用 `dd-trace` APM