본문으로 건너뛰기

Datadog 수출업자

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

또한 사용 중dd-trace APM?

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

설치
설치에 대한 직접 링크

npm install @mastra/datadog@latest

구성
구성에 대한 직접 링크

전제조건
전제조건에 대한 직접 링크

  1. Datadog 계정: LLM Observability를 활성화하여 datadoghq.com에 가입하세요.
  2. API 키: Datadog 조직 설정 → API Keys에서 API 키를 받으세요.
  3. 환경 변수: 자격 증명을 설정하세요.
.env
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

제로 구성 설정
제로 구성 설정에 대한 직접 링크

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

src/mastra/index.ts
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()],
      },
    },
  }),
})

명시적 구성
명시적 구성에 대한 직접 링크

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

src/mastra/index.ts
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!,
          }),
        ],
      },
    },
  }),
})

구성 옵션
구성 옵션에 대한 직접 링크

완전한 구성
완전한 구성에 대한 직접 링크

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 사용에 대한 직접 링크

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

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_RUNagent
MODEL_GENERATIONworkflow
MODEL_STEPllm
TOOL_CALLtool
MCP_TOOL_CALLtool
WORKFLOW_RUNworkflow
Other workflow typestask
GENERICtask

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

애플리케이션 성능 모니터링
애플리케이션 성능 모니터링에 대한 직접 링크

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

전제조건
전제조건에 대한 직접 링크

  1. Datadog Agent: 같은 호스트에 Datadog Agent를 설치하거나 네트워크를 통해 접근할 수 있게 하세요. Agent는 localhost:8126에서 dd-trace의 Trace를 수신해 Datadog로 전달합니다. Agent 설치 가이드에 따라 설정하세요.
  2. dd-trace 패키지: 프로젝트에 Tracing 라이브러리를 설치합니다. 
    npm install dd-trace

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

APM 전용
APM 전용에 대한 직접 링크

다른 모든 import보다 먼저 진입 파일 맨 위에서 dd-trace를 가져와 초기화하세요.

src/mastra/index.ts
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',
    ],
  },
})

추적기 메타데이터 환경 변수를 설정합니다.

.env
DD_SERVICE=my-mastra-app
DD_ENV=production
DD_VERSION=1.0.0

dd-trace는 Mastra의 서버 어댑터를 포함해 널리 사용되는 HTTP 프레임워크를 자동으로 계측합니다. 수신 요청, 발신 HTTP 호출, 데이터베이스 쿼리가 Datadog에 APM Trace로 표시됩니다.

APM 및 LLM Observability
APM 및 LLM Observability에 대한 직접 링크

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

src/mastra/index.ts
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',
    ],
  },
})
.env
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 불일치
네이티브 모듈 ABI 불일치에 대한 직접 링크

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

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와 그 종속성을 외부 종속성으로 표시해야 할 수 있습니다.

src/mastra/index.ts
export const mastra = new Mastra({
  bundler: {
    externals: [
      'dd-trace',
      '@datadog/native-metrics',
      '@datadog/native-appsec',
      '@datadog/native-iast-taint-tracking',
      '@datadog/pprof',
    ],
  },
})
On this page