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

# 스튜디오 Observability

Studio에는 다음과 같은 Observability 보기가 포함되어 있습니다.

- **측정항목**집계된 성능 데이터용
- **흔적**개별요청검사용
- **로그**내부 및 애플리케이션 로그 검색용

모두 구성하려면 관측성 스토리지 백엔드가 필요합니다.

## 빠른 시작

자세한 지침은 [Observability 지침](https://mastra.zisheng.pro/ko/docs/observability/overview)을 따르세요. 빠르게 시작하려면 프로젝트에 `@mastra/observability` 패키지를 추가하고 [LibSQL](https://mastra.zisheng.pro/ko/reference/storage/libsql)과 [DuckDB](https://mastra.zisheng.pro/ko/reference/vectors/duckdb)를 사용하도록 구성하여 Trace와 메트릭을 모두 지원하는 로컬 개발 환경을 설정하세요.

**npm**:

```bash
npm install @mastra/observability @mastra/libsql @mastra/duckdb
```

**pnpm**:

```bash
pnpm add @mastra/observability @mastra/libsql @mastra/duckdb
```

**Yarn**:

```bash
yarn add @mastra/observability @mastra/libsql @mastra/duckdb
```

**Bun**:

```bash
bun add @mastra/observability @mastra/libsql @mastra/duckdb
```

그런 다음 다음을 추가하십시오.`src/mastra/index.ts`:

```ts
import { Mastra } from '@mastra/core/mastra'
import { LibSQLStore } from '@mastra/libsql'
import { DuckDBStore } from '@mastra/duckdb'
import { MastraCompositeStore } from '@mastra/core/storage'
import {
  Observability,
  MastraStorageExporter,
  MastraPlatformExporter,
  SensitiveDataFilter,
} from '@mastra/observability'

export const mastra = new Mastra({
  storage: new MastraCompositeStore({
    id: 'composite-storage',
    default: new LibSQLStore({
      id: 'mastra-storage',
      url: 'file:./mastra.db',
    }),
    domains: {
      observability: await new DuckDBStore().getStore('observability'),
    },
  }),
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'mastra',
        exporters: [
          new MastraStorageExporter(), // Persists observability events to Mastra Storage
          new MastraPlatformExporter(), // Sends observability events to Mastra platform (if MASTRA_PLATFORM_ACCESS_TOKEN is set)
        ],
        spanOutputProcessors: [
          new SensitiveDataFilter(), // Redacts sensitive data like passwords, tokens, keys
        ],
      },
    },
  }),
})
```

## 마스트라 플랫폼

프로젝트 및 배포 전반의 호스팅된 Trace, 로그, 메트릭은 [Mastra 플랫폼의 Observability](https://mastra.zisheng.pro/ko/docs/mastra-platform/observability)를 참조하세요.

## 측정항목

구성 가능한 시간 범위(지난 24시간\~30일) 동안 Agent, Workflow 및 Tool 성능을 요약하는 대시보드입니다. 맨 위 행에는 총 Agent 실행, Model 비용, 토큰 소비 및 평균 득점자 성능이 표시됩니다. 그 아래의 세부 카드에는 Model 사용량 및 Model당 비용, Agent당 토큰 사용량, 예상 비용이 포함된 시간 경과에 따른 토큰 사용량, 완료 및 오류 수가 포함된 트레이스 볼륨, 대기 시간 백분위수(p50 및 p95), 시간 경과에 따른 득점자 추세가 자세히 나와 있습니다.

자세한 내용은 [메트릭 개요](https://mastra.zisheng.pro/ko/docs/observability/metrics/overview)를 참조하세요.

> **노트:** 측정항목에는 Observability을 위해 별도의 OLAP 저장소가 필요합니다. PostgreSQL, LibSQL 등과 같은 관계형 데이터베이스는 측정항목에 지원되지 않습니다. 다시 시작하면 Memory 내 저장소가 재설정됩니다.

## 흔적

Agent 또는 Workflow를 실행할 때 Observability 탭에는 Model 호출, Tool 실행 및 Workflow 단계와 같은 주요 AI 작업을 강조하는 추적이 표시됩니다. 이러한 추적을 따라가면 데이터가 어떻게 이동하는지, 어디에서 시간이 소비되는지, 내부적으로 무슨 일이 일어나고 있는지 확인할 수 있습니다.

Trace 목록 위에서 **Columns**를 열어 입력, 엔터티, 기간, 입력 토큰, 출력 토큰, 예상 비용 및 사용자 지정 메타데이터 열을 표시하거나 숨길 수 있습니다. 사용자 지정 메타데이터를 표시하려면 `tracingOptions.metadata`에서 사용하는 최상위 키를 추가하세요. Studio는 현재 Mastra 서버와 API 접두사에 대한 선택 사항을 브라우저 스토리지에 저장합니다. 토큰 및 예상 비용 열에는 메트릭을 지원하는 Observability 저장소가 필요합니다. 여러 분기 행이 동일한 Trace에 속할 수 있으므로 이 열은 **Branches** 보기에서 사용할 수 없습니다. Trace는 하위 수준의 프레임워크 세부 정보를 필터링하여 중요한 내용에 집중하고 쉽게 읽을 수 있도록 합니다. 자세한 내용은 [추적 개요](https://mastra.zisheng.pro/ko/docs/observability/tracing/overview)를 참조하세요. Trace를 내보내려면 Trace 패널 헤더에서 **Download trace JSON**을 선택하세요. 그러면 모든 스팬과 각각의 전체 입력, 출력, 메타데이터, 속성이 포함된 전체 Trace가 `trace-<id>.json` 파일로 저장됩니다. 이를 사용하여 Trace를 공유하거나 버그 보고서에 첨부할 수 있으며, 오프라인에서 평가 데이터세트를 구축할 수도 있습니다.

## 로그

관측 가능성 스토리지로 전달된 내부 Mastra 로그를 찾아보세요. 로그는 전체 텍스트 검색(메시지 콘텐츠, 엔터티 이름 및 추적 ID 전반), 날짜 사전 설정(지난 24시간\~30일) 및 수준, 엔터티 유형 및 엔터티 이름에 대한 다중 선택 필터를 제공합니다. 로그를 선택하면 전체 메시지, 구조화된 데이터, 메타데이터를 표시하는 세부정보 패널이 열립니다. 로그가 추적과 연관되어 있는 경우 추적 및 범위 타임라인으로 직접 이동할 수 있습니다.

Observability를 구성하면 로그 전달이 기본적으로 활성화됩니다. 수준 구성, 쿼리 예제 및 사용자 지정 세부 정보는 [로깅](https://mastra.zisheng.pro/ko/docs/observability/logging)을 참조하세요.

## 관련된

- [Observability 개요](https://mastra.zisheng.pro/ko/docs/observability/overview)
- [측정항목 개요](https://mastra.zisheng.pro/ko/docs/observability/metrics/overview)
- [추적 개요](https://mastra.zisheng.pro/ko/docs/observability/tracing/overview)
- [벌채 반출](https://mastra.zisheng.pro/ko/docs/observability/logging)
- [Mastra 플랫폼 가시성](https://mastra.zisheng.pro/ko/docs/mastra-platform/observability)