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

# 데이터독 브릿지

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

Datadog Bridge는 Mastra의 추적 시스템과 Datadog 간의 양방향 통합을 가능하게 합니다. 실행이 완료된 후 추적 데이터를 보내는 내보내기와 달리 브리지는 실시간으로 기본 dd-trace 범위를 생성하므로 Tool 및 프로세서 내부의 자동 계측 APM 작업(HTTP 호출, 데이터베이스 쿼리 등)이 상위 Mastra 범위 아래에 올바르게 중첩됩니다.

> **Dd-trace APM을 사용하지 않습니까?:** LLM Observability 데이터만 전송하면 되고 `dd-trace` APM 자동 계측을 사용하지 않는다면 [Datadog Exporter](https://mastra.zisheng.pro/ko/docs/observability/integrations/exporters/datadog)가 더 간단합니다. Agent 없는 모드를 지원하며 로컬 Agent 없이 Span을 Datadog로 직접 전송합니다.

## 브릿지를 사용하는 경우

다음과 같은 경우 DatadogBridge를 사용하십시오.

- 애플리케이션에서 `dd-trace` 자동 계측을 사용합니다(HTTP 서버, 데이터베이스 클라이언트 등).
- Tool, MCP Tool 또는 출력 프로세서가 수행한 APM 서비스 호출을 요청 핸들러가 아니라 상위 Mastra Span 아래에 표시하려고 합니다.
- 일관된 Trace 토폴로지를 공유하도록 APM Trace와 LLM Observability 데이터가 모두 필요합니다.
- Datadog Trace 컨텍스트를 서비스 전반에 전파해야 하는 분산 시스템을 구축하고 있습니다.

## 작동 원리

DatadogBridge는 dd-trace 파이프라인의 두 부분에 참여합니다.

**APM 컨텍스트 전파(실시간):**

- 각 Mastra Span을 생성할 때 `tracer.startSpan()`으로 dd-trace APM Span을 생성합니다.

- 실행 중 `tracer.scope().activate()`를 통해 dd-trace 범위에서 APM Span을 활성화합니다.

- 활성 범위 내에서 자동 계측된 작업은 올바른 Mastra Span의 하위 항목이 됩니다.

- 명시적인 Mastra 상위 항목이 없으면 활성 dd-trace 컨텍스트(예: 수신 요청 Span)를 상속합니다. **LLM Observability 방출(스팬 끝에서):**

- 다음을 통해 주석(Model 정보, 토큰 사용, 입출력, 오류)을 내보냅니다.`dd-trace`'s LLM Observability pipeline

- 중첩을 사용하여 Datadog LLM Observability에서 상위-하위 관계를 유지합니다.`llmobs.trace()` calls

- 동일한 데이터 형태와 범위 종류 매핑을 재사용합니다.[Datadog Exporter](https://mastra.zisheng.pro/ko/docs/observability/integrations/exporters/datadog)

## 추적 및 로그 상관관계

Bridge가 없으면 Datadog Exporter는 Trace가 완료된 후에만 LLM Observability Span을 생성합니다. 실행 중에는 범위에 활성화된 `dd-trace` Span이 없으므로 Tool이 수행한 HTTP 또는 데이터베이스 호출은 당시 활성화된 `dd-trace` Span(일반적으로 수신 요청 핸들러)을 대체 상위 항목으로 사용합니다. 그 결과 MCP Tool이나 출력 프로세서가 수행한 서비스 호출이 실제 호출한 Agent 또는 프로세서 Span이 아니라 요청 Span의 하위 항목으로 나타납니다. 브리지는 실제 dd-trace 범위를 앞에 생성하여 이 문제를 해결하므로 자동 계측이 실행될 때 범위가 정확합니다.

## 설치

**npm**:

```bash
npm install @mastra/datadog dd-trace
```

**pnpm**:

```bash
pnpm add @mastra/datadog dd-trace
```

**Yarn**:

```bash
yarn add @mastra/datadog dd-trace
```

**Bun**:

```bash
bun add @mastra/datadog dd-trace
```

Bridge를 사용하려면 `dd-trace`를 설치하고 APM 데이터를 수신할 로컬 Datadog Agent(또는 호환 OTLP 수신기)가 필요합니다. Agent 설정에 관한 자세한 내용은 Exporter 페이지의 [APM 사전 요구 사항](https://mastra.zisheng.pro/ko/docs/observability/integrations/exporters/datadog)을 참조하세요.

## 구성

DatadogBridge를 사용하려면 다음 두 단계가 필요합니다.

1. HTTP, 데이터베이스, 프레임워크 라이브러리에 자동 계측 패치를 적용하도록 `dd-trace`를 초기화합니다.
2. Mastra Observability 설정에 DatadogBridge를 추가합니다.

### 1단계: dd-trace 초기화

`dd-trace`자동 계측이 로드 시 라이브러리를 패치할 수 있도록 다른 가져오기 전에 초기화해야 합니다. 브리지는 이미 초기화된 추적 프로그램을 감지하고 이를 재사용합니다.

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

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

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

// ...
```

:::참고 다른 모든 import보다 먼저 애플리케이션 진입 파일의 맨 위에서 `dd-trace`를 가져와 초기화하세요. :::

### 2단계: 마스트라 구성

Mastra 관측 가능성 구성에 DatadogBridge를 추가합니다.

```typescript
export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'my-mastra-app',
        bridge: new DatadogBridge({
          mlApp: process.env.DD_LLMOBS_ML_APP!,
        }),
      },
    },
  }),
  bundler: {
    externals: [
      'dd-trace',
      '@datadog/native-metrics',
      '@datadog/native-appsec',
      '@datadog/native-iast-taint-tracking',
      '@datadog/pprof',
    ],
  },
})
```

```bash
DD_SERVICE=my-mastra-app
DD_ENV=production
DD_VERSION=1.0.0
DD_LLMOBS_ML_APP=my-llm-app
```

`dd-trace`가 초기화되면 APM 데이터를 `localhost:8126`의 로컬 Datadog Agent로 라우팅합니다. Bridge는 같은 Tracer 위에 LLM Observability를 활성화하므로 두 데이터 세트가 Datadog의 같은 서비스 아래에 표시됩니다. Bridge를 사용할 때는 Mastra Exporter가 필요하지 않습니다. APM 및 LLM Observability 데이터가 모두 `dd-trace`를 통과합니다. Trace를 추가 대상으로 전송하려면 Mastra Exporter를 계속 추가할 수 있습니다.

## Agent 대 Agent 없는 모드

Bridge의 기본값은 **Agent 모드**(`agentless: false`)입니다. APM 및 LLM Observability 데이터를 모두 수신하도록 로컬 Datadog Agent가 `localhost:8126`에서 실행 중이라고 가정합니다. APM 데이터는 항상 Agent를 통해 라우팅되므로 `dd-trace` 자동 계측을 사용할 때 일반적인 설정입니다. 로컬 Datadog Agent가 없고 LLM 관찰 데이터만 필요한 경우(APM 자동 계측 없음) Agent 없는 모드를 활성화하여 Datadog에 직접 데이터를 보낼 수 있습니다. 이 경우 API 키를 제공해야 합니다.

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

:::참고 대부분의 브리지 사용자에게는 Agent 모드가 올바른 선택입니다. APM 데이터는 Agent 없는 모드에서 전송할 수 없으므로 Agent 없는 모드를 활성화하면 LLM 관찰 트래픽이 APM 트래픽에서 분리됩니다. Agent 없이 LLM 관찰만 원하는 경우 다음을 사용하세요.[Datadog Exporter](https://mastra.zisheng.pro/ko/docs/observability/integrations/exporters/datadog) instead. :::

## 추적 계층 구조

DatadogBridge를 사용하면 추적이 dd-trace 및 Mastra 경계에서 적절한 계층 구조를 유지합니다. Tool 및 프로세서에 의한 서비스 요청은 올바른 Mastra 범위 아래에 표시됩니다.

```text
HTTP POST /api/chat (from web framework instrumentation)
└── agent.orchestrator (from Mastra via DatadogBridge)
    ├── chat gpt-5.4 (LLM call)
    ├── tool.execute search (tool execution)
    │   └── HTTP GET api.example.com (auto-instrumented from inside the tool)
    └── processor.guardrail (output processor)
        └── HTTP POST guardrail-service/check (auto-instrumented from inside the processor)
```

Datadog에서 APM 추적은 이 전체 토폴로지를 보여주고, LLM Observability 제품은 입력, 출력 및 토큰 메트릭과 함께 Agent 및 LLM 관련 범위를 보여줍니다.

## 스팬 유형 매핑

Bridge는 LLM Observability에 대해 Datadog Exporter와 동일한 Span 종류 매핑을 사용합니다. Exporter 페이지의 [Span 유형 매핑](https://mastra.zisheng.pro/ko/docs/observability/integrations/exporters/datadog)을 참조하세요.

## 태그 사용

태그는 Datadog에서 추적을 분류하고 필터링하는 데 도움이 됩니다. Agent 또는 Workflow를 실행할 때 태그를 추가합니다.

```typescript
const result = await agent.generate('Hello', {
  tracingOptions: {
    tags: ['production', 'experiment-v2', 'user-request'],
  },
})
```

`key:value` 형식의 태그(예: `instance_name:career-scout-api`)는 구조화된 태그 항목으로 분할됩니다. 콜론이 없는 태그에는 `true` 값이 설정됩니다.

## 컨텍스트 키를 플랫 태그로 승격

요청 컨텍스트나 Span 속성의 특정 키를 평면적이고 인덱싱 가능한 LLM Observability 태그로 승격하려면 `requestContextKeys`를 사용하세요. 그러면 Datadog UI에서 필터링할 수 있습니다.

```typescript
new DatadogBridge({
  mlApp: process.env.DD_LLMOBS_ML_APP!,
  requestContextKeys: ['tenantId', 'agentId'],
})
```

승격된 키는 `annotations.metadata`에서 제거되고 각 LLM Observability Span에 평면 태그로 추가됩니다.

## 문제 해결

APM 범위가 예상대로 Mastra 범위에 연결되지 않는 경우:

- `dd-trace`가 다른 모든 import보다 **먼저** 초기화되었는지 확인하세요. 로드 시 라이브러리에 패치를 적용합니다.
- 로컬 Datadog Agent가 실행 중이고 `localhost:8126`에서 연결 가능한지 확인하세요.
- Observability 설정에서 DatadogBridge가 `exporters` 항목이 아닌 `bridge`로 설정되었는지 확인하세요.
- `exporters`에 `DatadogExporter`를 추가하지 않았는지 확인하세요. 둘을 함께 사용하면 LLM Observability 데이터가 이중으로 전송됩니다. `dd-trace` 네이티브 모듈 및 번들러 외부 종속성의 호환성 문제는 [Datadog Exporter 문제 해결](https://mastra.zisheng.pro/ko/docs/observability/integrations/exporters/datadog) 섹션을 참조하세요.

## 관련된

- [추적 개요](https://mastra.zisheng.pro/ko/docs/observability/tracing/overview)
- [Datadog 수출업체](https://mastra.zisheng.pro/ko/docs/observability/integrations/exporters/datadog)- LLM 관찰만 해당, 아니요`dd-trace` APM
- [DatadogBridge 참조](https://mastra.zisheng.pro/ko/reference/observability/tracing/bridges/datadog)- API 문서
- [Datadog APM 문서](https://docs.datadoghq.com/tracing/)
- [Datadog LLM Observability 문서](https://docs.datadoghq.com/llm_observability/)