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

# 스팬

## `BaseSpan`

모든 범위 유형에 대한 기본 인터페이스입니다.

```typescript
interface BaseSpan<TType extends SpanType> {
  /** Unique span identifier */
  id: string

  /** OpenTelemetry-compatible trace ID (32 hex chars) */
  traceId: string

  /** Name of the span */
  name: string

  /** Type of the span */
  type: TType

  /** When span started */
  startTime: Date

  /** When span ended */
  endTime?: Date

  /** Type-specific attributes */
  attributes?: SpanTypeMap[TType]

  /** User-defined metadata */
  metadata?: Record<string, any>

  /** Input passed at the start of the span */
  input?: any

  /** Output generated at the end of the span */
  output?: any

  /** Error information if span failed */
  errorInfo?: {
    message: string
    id?: string
    domain?: string
    category?: string
    details?: Record<string, any>
  }

  /** Snapshot of the RequestContext */
  requestContext?: Record<string, any>
  /** Is an event span? (occurs at startTime, has no endTime) */
  isEvent: boolean
}
```

## 기간

추적을 위해 내부적으로 사용되는 Span 인터페이스입니다. 수명 주기 메서드 및 속성을 사용하여 BaseSpan을 확장합니다.

```typescript
interface Span<TType extends SpanType> extends BaseSpan<TType> {
  /** Is an internal span? (spans internal to the operation of mastra) */
  isInternal: boolean

  /** Parent span reference (undefined for root spans) */
  parent?: AnySpan

  /** Pointer to the ObservabilityInstance instance */
  observabilityInstance: ObservabilityInstance
}
```

### 속성

```typescript
/** Returns TRUE if the span is the root span of a trace */
get isRootSpan(): boolean

/** Returns TRUE if the span is a valid span (not a NO-OP Span) */
get isValid(): boolean

/** Get the closest parent spanId that isn't an internal span */
getParentSpanId(includeInternalSpans?: boolean): string | undefined

/** Returns a lightweight span ready for export */
exportSpan(includeInternalSpans?: boolean): ExportedSpan<TType> | undefined
```

### 행동 양식

#### 끝

```typescript
end(options?: EndSpanOptions<TType>): void
```

스팬을 종료하고 구성된 내보내기 도구로 내보내기를 트리거합니다. `endTime`을 설정하며 선택적으로 `output`, `metadata`, `attributes`를 업데이트합니다.

#### 오류

```typescript
error(options: ErrorSpanOptions<TType>): void
```

스팬에 오류를 기록합니다. `errorInfo` 필드를 설정하며 선택적으로 스팬을 종료할 수 있습니다.

#### 업데이트

```typescript
update(options: UpdateSpanOptions<TType>): void
```

활성 상태인 동안 스팬 데이터를 업데이트합니다. `input`, `output`, `metadata`, `attributes`를 수정할 수 있습니다.

#### `createChildSpan`

```typescript
createChildSpan<TChildType extends SpanType>(
  options: ChildSpanOptions<TChildType>
): Span<TChildType>
```

이 범위 아래에 하위 범위를 만듭니다. 하위 범위는 하위 작업을 추적하고 추적 컨텍스트를 상속합니다.

#### `createEventSpan`

```typescript
createEventSpan<TChildType extends SpanType>(
  options: ChildEventOptions<TChildType>
): Span<TChildType>
```

이 범위 아래에 이벤트 범위를 만듭니다. 이벤트 범위는 기간이 없는 특정 시점 발생을 나타냅니다.

## `ExportedSpan`

내보내기 추적에 사용되는 내보낸 Span 인터페이스입니다. 메서드나 순환 참조가 없는 경량 버전의 Span입니다.

```typescript
interface ExportedSpan<TType extends SpanType> extends BaseSpan<TType> {
  /** Parent span id reference (undefined for root spans) */
  parentSpanId?: string

  /** TRUE if the span is the root span of a trace */
  isRootSpan: boolean
}
```

## 스팬 수명주기 이벤트

범위 수명 주기 동안 발생하는 이벤트입니다.

### `TracingEventType`

```typescript
enum TracingEventType {
  /** Emitted when a span is created and started */
  SPAN_STARTED = 'span_started',

  /** Emitted when a span is updated via update() */
  SPAN_UPDATED = 'span_updated',

  /** Emitted when a span is ended via end() or error() */
  SPAN_ENDED = 'span_ended',
}
```

### `TracingEvent`

```typescript
type TracingEvent =
  | { type: 'span_started'; exportedSpan: AnyExportedSpan }
  | { type: 'span_updated'; exportedSpan: AnyExportedSpan }
  | { type: 'span_ended'; exportedSpan: AnyExportedSpan }
```

내보내기는 추적 데이터를 처리하고 관찰 플랫폼으로 전송하기 위해 이러한 이벤트를 수신합니다.

## 유니온 유형

### `AnySpan`

```typescript
type AnySpan = Span<keyof SpanTypeMap>
```

모든 스팬 유형을 처리해야 하는 경우를 위한 유니온 유형입니다.

### `AnyExportedSpan`

```typescript
type AnyExportedSpan = ExportedSpan<keyof SpanTypeMap>
```

내보낸 범위 유형을 처리해야 하는 경우의 통합 유형입니다.

## NO-OP 범위

추적이 비활성화되면(샘플링이 false를 반환함) NO-OP 범위가 반환됩니다.

### `NoOpSpan`

```typescript
class NoOpSpan<TType extends SpanType> extends BaseSpan<TType>
```

작업을 수행하지 않는 범위입니다. 모든 방법은 작동하지 않습니다.

- `id`보고`'no-op'`
- `traceId`보고`'no-op-trace'`
- `isValid`보고`false`
- `end()`, `error()`, `update()` do nothing
- `createChildSpan()`또 다른 NO-OP 범위를 반환합니다.

## 또한보십시오

### 선적 서류 비치

- [추적 개요](https://mastra.zisheng.pro/ko/docs/observability/tracing/overview): 개념 및 사용법
- [하위 범위 만들기](https://mastra.zisheng.pro/ko/docs/observability/tracing/overview): 실제 사례
- [추적 ID 검색](https://mastra.zisheng.pro/ko/docs/observability/tracing/overview): 추적 ID 사용

### 참조

- [추적 클래스](https://mastra.zisheng.pro/ko/reference/observability/tracing/instances): 핵심 추적 클래스
- [인터페이스](https://mastra.zisheng.pro/ko/reference/observability/tracing/interfaces): 완전한 유형 참조
- [구성](https://mastra.zisheng.pro/ko/reference/observability/tracing/configuration): 구성 옵션