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

# Datadog 수출업자

[데이터독](https://datadoghq.com/)전용 LLM 관찰 기능을 갖춘 완벽한 모니터링 플랫폼입니다. Datadog 내보내기 Tool은 추적을 Datadog의 LLM Observability 제품으로 보내 Model 성능, 토큰 사용, 대화 흐름에 대한 통찰력을 제공합니다.

> **또한 사용 중dd-trace APM?:** `dd-trace` APM 자동 계측도 사용한다면 [Datadog Bridge](https://mastra.zisheng.pro/ko/docs/observability/integrations/bridges/datadog)를 대신 고려하세요. Bridge는 `dd-trace` Span을 실시간으로 생성하므로 Tool 및 프로세서 내부의 HTTP 및 데이터베이스 호출이 상위 Mastra Span 아래에 올바르게 중첩됩니다. Exporter는 실행이 완료된 후 자체적으로 LLM Observability 데이터를 전송하므로 자동 계측된 APM Span은 요청 핸들러를 대체 상위 항목으로 사용합니다.

## 설치

**npm**:

```bash
npm install @mastra/datadog@latest
```

**pnpm**:

```bash
pnpm add @mastra/datadog@latest
```

**Yarn**:

```bash
yarn add @mastra/datadog@latest
```

**Bun**:

```bash
bun add @mastra/datadog@latest
```

## 구성

### 전제조건

1. **Datadog 계정**: LLM Observability를 활성화하여 [datadoghq.com](https://datadoghq.com/)에 가입하세요.
2. **API 키**: Datadog 조직 설정 → API Keys에서 API 키를 받으세요.
3. **환경 변수**: 자격 증명을 설정하세요.

```bash
DD_API_KEY=your-datadog-api-key
DD_LLMOBS_ML_APP=my-llm-app
DD_SITE=datadoghq.com  # Optional: defaults to datadoghq.com
DD_ENV=production      # Optional: environment name
```

### 제로 구성 설정

환경 변수가 설정된 경우 구성 없이 내보내기를 사용합니다.

```typescript
import { Mastra } from '@mastra/core'
import { Observability } from '@mastra/observability'
import { DatadogExporter } from '@mastra/datadog'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      datadog: {
        serviceName: 'my-service',
        exporters: [new DatadogExporter()],
      },
    },
  }),
})
```

### 명시적 구성

자격 증명을 직접 전달할 수도 있습니다(환경 변수보다 우선 적용됨).

```typescript
import { Mastra } from '@mastra/core'
import { Observability } from '@mastra/observability'
import { DatadogExporter } from '@mastra/datadog'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      datadog: {
        serviceName: 'my-service',
        exporters: [
          new DatadogExporter({
            mlApp: process.env.DD_LLMOBS_ML_APP!,
            apiKey: process.env.DD_API_KEY!,
          }),
        ],
      },
    },
  }),
})
```

## 구성 옵션

### 완전한 구성

```typescript
new DatadogExporter({
  // Required settings
  mlApp: process.env.DD_LLMOBS_ML_APP!, // Groups traces under this ML app name
  apiKey: process.env.DD_API_KEY!, // Required for agentless mode (default)

  // Optional settings
  site: 'datadoghq.com', // Datadog site (datadoghq.eu, us3.datadoghq.com, etc.)
  service: 'my-service', // Service name (defaults to mlApp)
  env: 'production', // Environment name
  agentless: true, // true = direct HTTPS, false = local Datadog Agent

  // Advanced settings
  integrationsEnabled: false, // Enable dd-trace auto-instrumentation

  // Diagnostic logging
  logLevel: 'info', // debug | info | warn | error
})
```

### 로컬 Datadog Agent 사용

로컬로 실행 중인 Datadog Agent가 있는 경우 직접 HTTPS 대신 이를 통해 추적을 라우팅할 수 있습니다.

```typescript
new DatadogExporter({
  mlApp: process.env.DD_LLMOBS_ML_APP!,
  agentless: false, // Use local Datadog Agent
  env: 'production',
})
```

참고: Agent 모드를 사용하는 경우 로컬 Agent 구성에서 API 키를 읽습니다.

## 스팬 유형 매핑

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

| 마스트라 스팬타입            | 데이터독 종류    |
| -------------------- | ---------- |
| `AGENT_RUN`          | `agent`    |
| `MODEL_GENERATION`   | `workflow` |
| `MODEL_STEP`         | `llm`      |
| `TOOL_CALL`          | `tool`     |
| `MCP_TOOL_CALL`      | `tool`     |
| `WORKFLOW_RUN`       | `workflow` |
| Other workflow types | `task`     |
| `GENERIC`            | `task`     |

기타/향후 Mastra 범위 유형은 지정하지 않는 한 매핑 시 기본적으로 '작업'으로 설정됩니다.

## 애플리케이션 성능 모니터링

위 섹션에서는 Mastra의 [LLM Observability](https://docs.datadoghq.com/llm_observability/) 통합을 설명합니다. Mastra HTTP 서버 라우트(요청 지연 시간, 오류 추적, 서비스 맵)를 추적하려면 Datadog Application Performance Monitoring(APM)에 `dd-trace`를 직접 사용하세요.

### 전제조건

1. **Datadog Agent**: 같은 호스트에 [Datadog Agent](https://docs.datadoghq.com/agent/)를 설치하거나 네트워크를 통해 접근할 수 있게 하세요. Agent는 `localhost:8126`에서 `dd-trace`의 Trace를 수신해 Datadog로 전달합니다. [Agent 설치 가이드](https://docs.datadoghq.com/agent/)에 따라 설정하세요.

2. **dd-trace 패키지**: 프로젝트에 Tracing 라이브러리를 설치합니다.

   **npm**:

   ```bash
   npm install dd-trace
   ```

   **pnpm**:

   ```bash
   pnpm add dd-trace
   ```

   **Yarn**:

   ```bash
   yarn add dd-trace
   ```

   **Bun**:

   ```bash
   bun add dd-trace
   ```

:::참고 APM 추적은 항상 Datadog Agent를 통해 라우팅됩니다. 이는 Agent 없는 모드(HTTPS에서 Datadog으로 직접 연결)를 지원하는 LLM Observability와 다릅니다. :::

### APM 전용

다른 모든 import보다 먼저 진입 파일 맨 위에서 `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'

export const mastra = new Mastra({
  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-trace`는 Mastra의 [서버 어댑터](https://mastra.zisheng.pro/ko/docs/server/server-adapters)를 포함해 널리 사용되는 HTTP 프레임워크를 자동으로 계측합니다. 수신 요청, 발신 HTTP 호출, 데이터베이스 쿼리가 Datadog에 APM Trace로 표시됩니다.

### APM 및 LLM Observability

Mastra 인스턴스를 생성하기 전에 `dd-trace`를 가져와 초기화하세요. `DatadogExporter`는 기존 Tracer를 감지해 재초기화를 건너뛰고 APM 설정 위에 LLM Observability를 추가합니다.

```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 { DatadogExporter } from '@mastra/datadog'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      datadog: {
        serviceName: 'my-mastra-app',
        exporters: [
          new DatadogExporter({
            mlApp: process.env.DD_LLMOBS_ML_APP!,
            apiKey: process.env.DD_API_KEY!,
          }),
        ],
      },
    },
  }),
  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_API_KEY=your-datadog-api-key
DD_LLMOBS_ML_APP=my-llm-app
```

서버 경로는 APM 추적으로 표시되고 LLM 호출은 LLM 관찰 범위로 표시되며 모두 Datadog의 동일한 서비스 아래에 있습니다.

:::참고 다른 모든 모듈보다 먼저 `dd-trace`를 가져와 초기화하세요. 그러면 자동 계측이 로드 시 HTTP, 데이터베이스, 프레임워크 라이브러리에 패치를 적용할 수 있습니다. :::

## 문제 해결

### 네이티브 모듈 ABI 불일치

다음과 같은 오류가 표시되는 경우:

```text
Error: No native build was found for runtime=node abi=137 platform=linuxglibc arch=x64
```

이는 `dd-trace`의 네이티브 모듈과 관련된 Node.js 버전 호환성 문제를 나타냅니다. 이러한 네이티브 모듈은 성능 모니터링 기능을 제공하는 **선택적** 모듈입니다. **솔루션:**

1. **Node.js 22.x 사용**: 네이티브 모듈은 Node.js 22.x와 가장 잘 호환됩니다.

2. **네이티브 모듈 경고 무시**: 네이티브 모듈(`@datadog/native-metrics`, `@datadog/native-appsec` 등)은 선택 사항입니다. 로드하지 못해도 핵심 Tracing 기능은 계속 작동합니다.

### 번들러 외부 구성

esbuild, webpack 또는 Mastra CLI 번들러 같은 번들러를 사용한다면 `dd-trace`와 그 종속성을 외부 종속성으로 표시해야 할 수 있습니다.

```typescript
export const mastra = new Mastra({
  bundler: {
    externals: [
      'dd-trace',
      '@datadog/native-metrics',
      '@datadog/native-appsec',
      '@datadog/native-iast-taint-tracking',
      '@datadog/pprof',
    ],
  },
})
```

## 관련된

- [추적 개요](https://mastra.zisheng.pro/ko/docs/observability/tracing/overview)
- [Datadog LLM Observability 문서](https://docs.datadoghq.com/llm_observability/)
- [Datadog APM 문서](https://docs.datadoghq.com/tracing/)