DatadogBridge

경고

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

Mastra 추적과 Datadog 간의 양방향 통합을 활성화합니다. 네이티브 dd-trace APM span을 실시간으로 생성하여 Tool과 프로세서 내부에서 자동 계측된 작업이 상위 Mastra span 아래에 올바르게 중첩되도록 합니다. span이 종료되면 dd-trace 파이프라인을 통해 LLM Observability 데이터를 내보냅니다.

건설자

new DatadogBridge(config?: DatadogBridgeConfig)

DatadogBridgeConfig

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

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

executeInContext<T>(spanId: string, fn: () => Promise<T>): Promise<T>

Mastra 범위의 dd-trace 컨텍스트 내에서 비동기 기능을 실행합니다. 함수(HTTP, 데이터베이스 등) 내에서 실행되는 dd-trace 자동 계측 작업은 이 범위의 상위 항목이 됩니다.

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

executeInContextSync

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

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

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

flush

async flush(): Promise<void>

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

shutdown

async shutdown(): Promise<void>

제대로 닫히지 않은 APM 범위를 강제로 종료하고, 보류 중인 LLM 관찰 데이터를 플러시하고, LLM Observability 통합을 비활성화하고, 모든 내부 상태를 지웁니다.

사용 예

기본 사용법

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 없는 모드를 활성화합니다.

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를 사용하는 편이 더 간단합니다.

추가 수출업체 포함

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

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 가이드를 참조하세요.

스팬 매핑

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로 설정됩니다.

const result = await agent.generate('Hello', {
  tracingOptions: {
    tags: ['production', 'instance_name:career-scout-api'],
  },
})

이는 다음을 생성합니다.

{
  "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 가이드- 예시가 포함된 설정 가이드
• 추적 개요- 일반적인 추적 개념
• DatadogExporter 참조- LLM 관찰만 해당, 아니요dd-trace APM