센트리 수출업체

보초AI별 추적 기능을 갖춘 애플리케이션 모니터링 플랫폼입니다. Sentry 내보내기는 OpenTelemetry 의미론적 규칙을 사용하여 추적을 Sentry로 보내 Model 성능, 토큰 사용, Tool 실행에 대한 통찰력을 제공합니다.

설치

npm

npm install @mastra/sentry@latest

pnpm

pnpm add @mastra/sentry@latest

Yarn

yarn add @mastra/sentry@latest

Bun

bun add @mastra/sentry@latest

구성

전제조건

1. Sentry 계정: sentry.io에서 가입합니다.
2. DSN: Project Settings → Client Keys에서 Data Source Name을 가져옵니다.
3. 환경 변수: 구성을 설정합니다.

.env

SENTRY_DSN=https://...@...sentry.io/...

# Optional
SENTRY_ENVIRONMENT=production
SENTRY_RELEASE=1.0.0

제로 구성 설정

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

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { Observability } from '@mastra/observability'
import { SentryExporter } from '@mastra/sentry'

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

명시적 구성

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

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { Observability } from '@mastra/observability'
import { SentryExporter } from '@mastra/sentry'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      sentry: {
        serviceName: 'my-service',
        exporters: [
          new SentryExporter({
            dsn: process.env.SENTRY_DSN!,
            environment: 'production',
            tracesSampleRate: 1.0, // Send 100% of transactions to Sentry
          }),
        ],
      },
    },
  }),
})

구성 옵션

완전한 구성

new SentryExporter({
  // Required settings
  dsn: process.env.SENTRY_DSN!, // Data Source Name - tells the SDK where to send events

  // Optional settings
  environment: 'production', // Deployment environment (enables filtering issues and alerts by environment)
  tracesSampleRate: 1.0, // Percentage of transactions sent to Sentry (0.0 = 0%, 1.0 = 100%)
  release: '1.0.0', // Version of your code deployed (helps identify regressions and track deployments)

  // Advanced Sentry options
  options: {
    // Any additional Sentry.NodeOptions
    integrations: [],
    beforeSend: event => event,
    // ... other Sentry SDK options
  },

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

샘플링 구성

Sentry로 전송되는 트랜잭션의 비율을 제어합니다. 이는 대용량 애플리케이션에 유용합니다.

new SentryExporter({
  dsn: process.env.SENTRY_DSN!,
  tracesSampleRate: 0.1, // Send 10% of transactions to Sentry (recommended for high-load backends)
})

팁

개발 환경에서는 1.0(100%), 부하가 높은 프로덕션 애플리케이션에서는 0.10.2(1020%)로 설정하세요. Trace를 완전히 비활성화하려면 0으로 설정하지 말고 tracesSampleRate 자체를 설정하지 마세요.

스팬 유형 매핑

Mastra 스팬 유형은 Sentry 작업에 자동으로 매핑됩니다.

Mastra 스팬 유형	Sentry 작업	참고
AGENT_RUN	gen_ai.invoke_agent	하위 MODEL_GENERATION 스팬의 토큰 포함
MODEL_GENERATION	gen_ai.chat	사용량 통계 및 스트리밍 데이터 포함
MODEL_STEP	(건너뜀)	Trace 계층 구조를 단순화하기 위해 건너뜀
MODEL_CHUNK	(건너뜀)	MODEL_GENERATION에 데이터 집계
TOOL_CALL	gen_ai.execute_tool	입력/출력을 포함한 Tool 실행
MCP_TOOL_CALL	gen_ai.execute_tool	MCP Tool 실행
WORKFLOW_RUN	workflow.run
WORKFLOW_STEP	workflow.step
WORKFLOW_CONDITIONAL	workflow.conditional
WORKFLOW_CONDITIONAL_EVAL	workflow.conditional
WORKFLOW_PARALLEL	workflow.parallel
WORKFLOW_LOOP	workflow.loop
WORKFLOW_SLEEP	workflow.sleep
WORKFLOW_WAIT_EVENT	workflow.wait
PROCESSOR_RUN	ai.processor
GENERIC	ai.span

OpenTelemetry 의미 규칙

내보내기는 Sentry 관련 속성과 함께 표준 GenAI 의미 규칙을 사용합니다.

MODEL_GENERATION 범위의 경우:

• gen_ai.system: Model 제공자(예:openai, anthropic)
• gen_ai.request.model: Model 식별자(예:gpt-5.4)
• gen_ai.response.model: 응답 Model
• gen_ai.response.text: 출력 텍스트 응답
• gen_ai.response.tool_calls: 생성 중 발생한 Tool 호출(JSON 배열)
• gen_ai.usage.input_tokens: 입력 토큰 개수
• gen_ai.usage.output_tokens: 출력 토큰 개수
• gen_ai.request.temperature: 온도 매개변수
• gen_ai.request.stream: 스트리밍 요청 여부
• gen_ai.request.messages: 입력 메시지/Prompt(JSON)
• gen_ai.completion_start_time: 첫 번째 토큰이 도착한 시간

TOOL_CALL 범위의 경우:

• gen_ai.tool.name: Tool 식별자
• gen_ai.tool.type: function
• gen_ai.tool.call.id: Tool 호출 ID
• gen_ai.tool.input: Tool 입력(JSON)
• gen_ai.tool.output: Tool 출력(JSON)
• tool.success: Tool 호출 성공 여부

AGENT_RUN 범위의 경우:

• gen_ai.agent.name: Agent 식별자
• gen_ai.pipeline.name: Agent 이름(Sentry AI 보기용)
• gen_ai.agent.instructions: Agent 안내
• gen_ai.response.model: 아동세대 Model
• gen_ai.response.text: 자식 세대의 출력 텍스트
• gen_ai.usage.*: 자식 세대의 토큰 사용

특징

• 계층적 추적: 부모-자식 관계를 유지합니다.
• 토큰 추적: 세대별 토큰 사용량 자동 추적
• Tool 호출 추적: 입력/출력을 통해 Tool 실행을 캡처합니다.
• 스트리밍 지원: 스트리밍 응답을 집계합니다.
• 오류 추적: 자동 오류 상태 및 예외 캡처
• Workflow 지원: Workflow 실행 단계를 추적합니다.
• 단순화된 계층 구조: 노이즈를 줄이기 위해 MODEL_STEP 및 MODEL_CHUNK 범위를 건너뜁니다.

관련된

• 추적 개요
• 센트리 문서
• OpenTelemetry 의미 체계 규칙