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

# Sentry수출업체

OpenTelemetry 의미 체계 규칙을 사용하여 AI 추적 및 모니터링을 위해 추적 데이터를 Sentry로 보냅니다.

## 건설자

```typescript
new SentryExporter(config: SentryExporterConfig)
```

## `SentryExporterConfig`

```typescript
interface SentryExporterConfig extends BaseExporterConfig {
  dsn?: string
  environment?: string
  tracesSampleRate?: number
  release?: string
  options?: Partial<Sentry.NodeOptions>
}
```

`BaseExporterConfig`를 확장하며, 포함되는 항목은 다음과 같습니다.

- `logger?: IMastraLogger`- 로거 인스턴스
- `logLevel?: LogLevel | 'debug' | 'info' | 'warn' | 'error'`- 로그 수준(기본값: INFO)

## 행동 양식

### `exportTracingEvent`

```typescript
async exportTracingEvent(event: TracingEvent): Promise<void>
```

추적 이벤트를 Sentry로 내보냅니다. SPAN\_STARTED, SPAN\_UPDATED 및 SPAN\_ENDED 이벤트를 처리합니다.

### 플러시

```typescript
async flush(): Promise<void>
```

강제로 내보내기를 종료하지 않고 보류 중인 모든 스팬을 Sentry로 플러시합니다. 보류 중인 데이터가 전송될 때까지 최대 2초 동안 기다립니다. 런타임이 종료되기 전에 범위를 내보내야 하는 서버리스 환경에 유용합니다.

### 일시 휴업

```typescript
async shutdown(): Promise<void>
```

모든 활성 범위를 종료하고 내부 상태를 지우고 Sentry 연결을 닫습니다. 보류 중인 데이터가 전송될 때까지 최대 2초 동안 기다립니다.

## 용법

### Zero-Config(환경 변수 사용)

```typescript
import { SentryExporter } from '@mastra/sentry'

// Reads from SENTRY_DSN, SENTRY_ENVIRONMENT, SENTRY_RELEASE
const exporter = new SentryExporter()
```

### 명시적 구성

```typescript
import { SentryExporter } from '@mastra/sentry'

const exporter = new SentryExporter({
  dsn: process.env.SENTRY_DSN,
  environment: 'production',
  tracesSampleRate: 1.0,
  release: '1.0.0',
})
```

### 샘플링 포함

```typescript
const exporter = new SentryExporter({
  dsn: process.env.SENTRY_DSN,
  environment: 'production',
  tracesSampleRate: 0.1, // Send 10% of transactions to Sentry (recommended for high-load backends)
})
```

### 맞춤형 센트리 옵션 포함

```typescript
const exporter = new SentryExporter({
  dsn: process.env.SENTRY_DSN,
  environment: 'production',
  options: {
    integrations: [
      // Custom Sentry integrations
    ],
    beforeSend: event => {
      // Custom event processing
      return event
    },
  },
})
```

## 스팬 매핑

Mastra 범위 유형은 Sentry 작업에 매핑됩니다.

| 마스트라 스팬타입                   | 센트리 작전                 |
| --------------------------- | ---------------------- |
| `AGENT_RUN`                 | `gen_ai.invoke_agent`  |
| `MODEL_GENERATION`          | `gen_ai.chat`          |
| `MODEL_STEP`                | _(skipped)_            |
| `MODEL_CHUNK`               | _(skipped)_            |
| `TOOL_CALL`                 | `gen_ai.execute_tool`  |
| `MCP_TOOL_CALL`             | `gen_ai.execute_tool`  |
| `PROVIDER_TOOL_CALL`        | `gen_ai.execute_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`              |

추적 계층 구조를 단순화하기 위해 MODEL\_STEP 및 MODEL\_CHUNK 범위를 건너뜁니다. 해당 데이터는 MODEL\_GENERATION 범위로 집계됩니다.

## 환경변수

내보내기는 다음 환경 변수에서 구성을 읽습니다.

| 변수                   | 설명                                      |
| -------------------- | --------------------------------------- |
| `SENTRY_DSN`         | Data Source Name - SDK가 이벤트를 전송할 위치를 지정 |
| `SENTRY_ENVIRONMENT` | 배포 환경 이름                                |
| `SENTRY_RELEASE`     | 배포된 코드의 버전                              |

## `OpenTelemetry`속성

내보내기는 다음과 같은 표준 OpenTelemetry 속성을 설정합니다.

**공통 속성(모든 범위):**

- `sentry.origin`: `auto.ai.mastra`(Mastra에서 생성된 스팬을 식별)

- `ai.span.type`: Mastra 스팬 유형

- `gen_ai.conversation.id`: 채팅 스레드 식별자입니다. Sentry의 Conversations 보기에서 스팬을 그룹화하도록 `metadata.threadId`에서 설정됩니다. **MODEL\_GENERATION 범위:**

- `gen_ai.operation.name`: `chat`

- `gen_ai.system`: Model 제공자

- `gen_ai.request.model`: Model 식별자

- `gen_ai.request.messages`: 입력 메시지/Prompt(JSON)

- `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.usage.total_tokens`: 총 토큰

- `gen_ai.request.stream`: 스트리밍 플래그

- `gen_ai.request.temperature`: 온도 매개변수

- `gen_ai.completion_start_time`: 첫 번째 토큰 시간

**TOOL\_CALL 범위:**

- `gen_ai.operation.name`: `execute_tool`
- `gen_ai.tool.name`: Tool 식별자
- `gen_ai.tool.type`: `function`
- `gen_ai.tool.call.id`: Tool 호출 ID
- `gen_ai.tool.input`: Tool 입력
- `gen_ai.tool.output`: Tool 출력
- `tool.success`: 성공 플래그

**AGENT\_RUN 범위:**

- `gen_ai.operation.name`: `invoke_agent`
- `gen_ai.agent.name`: Agent 식별자
- `gen_ai.pipeline.name`: Agent 이름
- `gen_ai.agent.instructions`: Agent 안내
- `gen_ai.response.model`: 아동세대 Model
- `gen_ai.response.text`: 자식세대의 출력
- `gen_ai.usage.*`: 자식 세대의 토큰 사용