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

# DatadogBridge

> **경고:** Datadog Bridge는 현재 **실험적 기능**입니다. API와 구성 옵션은 향후 릴리스에서 변경될 수 있습니다.

Mastra 추적과 Datadog 간의 양방향 통합을 활성화합니다. 네이티브 `dd-trace` APM span을 실시간으로 생성하여 Tool과 프로세서 내부에서 자동 계측된 작업이 상위 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`- 로거 인스턴스
- `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 범위의 dd-trace 컨텍스트 내에서 비동기 기능을 실행합니다. 함수(HTTP, 데이터베이스 등) 내에서 실행되는 dd-trace 자동 계측 작업은 이 범위의 상위 항목이 됩니다.

**반환:** `Promise<T>` - 함수 실행 결과입니다.

### `executeInContextSync`

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

Mastra 범위의 dd-trace 컨텍스트 내에서 동기 기능을 실행합니다.

**반환:** `T` - 함수 실행 결과입니다.

### `flush`

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

브리지를 종료하지 않고 버퍼링된 모든 LLM Observability 데이터를 Datadog에 강제 플러시합니다. 런타임이 종료되기 전에 데이터를 내보내야 하는 서버리스 환경에 유용합니다.

### `shutdown`

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

제대로 닫히지 않은 APM 범위를 강제로 종료하고, 보류 중인 LLM 관찰 데이터를 플러시하고, 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 관찰만 가능, 로컬 Agent 없음)

로컬 Datadog Agent가 없고 LLM 관찰 데이터만 원하는 경우 Agent 없는 모드를 활성화합니다.

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

참고: Agent 없는 모드에서는 APM 데이터를 전송할 수 없습니다. `dd-trace` APM 없이 LLM Observability 데이터만 필요한 경우 [Datadog Exporter](https://mastra.zisheng.pro/ko/reference/observability/tracing/exporters/datadog)를 사용하는 편이 더 간단합니다.

### 추가 수출업체 포함

브리지는 Datadog이 아닌 내보내기 프로그램과 결합하여 추적을 추가 대상으로 보낼 수 있습니다.

```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, 데이터베이스 및 프레임워크 라이브러리를 패치할 수 있도록 다른 모든 항목보다 먼저 `dd-trace`를 초기화해야 합니다. dd-trace 초기화, 번들러 외부 종속성 및 Agent 구성을 포함한 전체 설정 지침은 [DatadogBridge 가이드](https://mastra.zisheng.pro/ko/docs/observability/integrations/bridges/datadog)를 참조하세요.

## 스팬 매핑

Mastra 범위 유형은 Datadog LLM Observability 범위 종류에 매핑됩니다.

| 마스트라 스팬타입          | 데이터독 종류    |
| ------------------ | ---------- |
| `AGENT_RUN`        | `agent`    |
| `MODEL_GENERATION` | `workflow` |
| `MODEL_STEP`       | `llm`      |
| `TOOL_CALL`        | `tool`     |
| `MCP_TOOL_CALL`    | `tool`     |
| `WORKFLOW_RUN`     | `workflow` |
| All other types    | `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"
}
```

## 환경변수

브리지는 다음 환경 변수에서 구성을 읽습니다.

| 변수                            | 설명                                        |
| ----------------------------- | ----------------------------------------- |
| `DD_API_KEY`                  | Datadog API 키(Agent 없는 모드에서만 필요)          |
| `DD_LLMOBS_ML_APP`            | ML 애플리케이션 이름                              |
| `DD_SITE`                     | Datadog 사이트                               |
| `DD_ENV`                      | 환경 이름                                     |
| `DD_LLMOBS_AGENTLESS_ENABLED` | Agent 없는 모드를 활성화하려면 `'true'` 또는 `'1'`로 설정 |

## 관련된

- [DatadogBridge 가이드](https://mastra.zisheng.pro/ko/docs/observability/integrations/bridges/datadog)- 예시가 포함된 설정 가이드
- [추적 개요](https://mastra.zisheng.pro/ko/docs/observability/tracing/overview)- 일반적인 추적 개념
- [DatadogExporter 참조](https://mastra.zisheng.pro/ko/reference/observability/tracing/exporters/datadog)- LLM 관찰만 해당, 아니요`dd-trace` APM