데이터독 브릿지

경고

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

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

dd-trace APM을 사용하지 않습니까?

LLM Observability 데이터만 전송하면 되고 dd-trace APM 자동 계측을 사용하지 않는다면 Datadog Exporter가 더 간단합니다. 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

추적 및 로그 상관관계

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

설치

npm

npm install @mastra/datadog dd-trace

pnpm

pnpm add @mastra/datadog dd-trace

Yarn

yarn add @mastra/datadog dd-trace

Bun

bun add @mastra/datadog dd-trace

Bridge를 사용하려면 dd-trace를 설치하고 APM 데이터를 수신할 로컬 Datadog Agent(또는 호환 OTLP 수신기)가 필요합니다. Agent 설정에 관한 자세한 내용은 Exporter 페이지의 APM 사전 요구 사항을 참조하세요.

구성

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

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

1단계: dd-trace 초기화

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'
import { Observability } from '@mastra/observability'
import { DatadogBridge } from '@mastra/datadog'

// ...

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

2단계: 마스트라 구성

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

src/mastra/index.ts

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',
    ],
  },
})

.env

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 키를 제공해야 합니다.

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 instead. :::

추적 계층 구조

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

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 유형 매핑을 참조하세요.

태그 사용

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

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에서 필터링할 수 있습니다.

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 문제 해결 섹션을 참조하세요.

관련된

• 추적 개요
• Datadog 수출업체- LLM 관찰만 해당, 아니요dd-trace APM
• DatadogBridge 참조- API 문서
• Datadog APM 문서
• Datadog LLM Observability 문서