Observability 개요

Mastra의 관찰 시스템은 모든 Agent 실행, Workflow 단계, Tool 호출 및 Model 상호 작용에 대한 가시성을 제공합니다. Agent 동작은 Model 응답, Prompt, Tool, Memory 및 Workflow 상태에 따라 달라지므로 관찰 기능은 첫날부터 런타임 결정을 검사하는 데 도움이 됩니다. 이는 애플리케이션이 수행하는 작업과 이유를 이해하는 데 도움이 되는 상호 보완적인 신호를 캡처합니다.

• 구성: 추적, 로그, 지표, 피드백에 대해 Observability을 한 번 구성합니다.
• 저장: 지속적인 추적, 로그, 지표 집계 및 피드백 쿼리를 위한 스토리지 백엔드를 선택합니다.
• 트레이싱: 모든 작업을 범위의 계층적 타임라인으로 기록하고 입력, 출력, 토큰 사용 및 타이밍을 캡처합니다.
• 벌채 반출: 애플리케이션 및 Mastra 내부의 구조화된 로그 항목을 Observability 스토리지로 전달하고 자동으로 추적과 연관시킵니다.
• 측정항목: 추적 사용량 및 비용 데이터를 추출합니다. 추가 계측이 필요하지 않습니다.
• 피드백: 트레이스 및 범위에 연결된 등급, 설명, 수정 사항 및 기타 검토 신호를 저장합니다.
• 통합: Studio, 호스팅 또는 외부 관찰 Workflow를 위한 내보내기, 브리지 및 스팬 프로세서를 선택합니다.

관측성을 사용해야 하는 경우

• 전체 결정 경로, Tool 호출, Model 응답을 검사하여 예상치 못한 Agent 동작을 디버깅합니다.
• Agent, Workflow, Tool 전반의 대기 시간을 모니터링하여 병목 현상을 식별합니다.
• 시간 경과에 따른 토큰 소비 및 예상 비용을 추적하여 지출을 통제하세요.
• 각 단계의 실행을 추적하여 Workflow 오류를 진단합니다.
• Prompt나 Model 변경 전후의 Agent 성과를 비교하세요.

조각들이 어떻게 조화를 이루는가

Trace는 기반이 되는 요소입니다. Observability를 구성하면 모든 Agent 실행, Workflow 실행, Tool 호출 및 Model 상호 작용이 스팬을 생성합니다. 스팬은 전체 요청 수명 주기를 계층적 타임라인으로 보여 주는 Trace로 구성됩니다. 측정항목은 추적에서 자동으로 파생됩니다. 범위가 종료되면 Mastra는 추가 코드 없이 기간, 토큰 수 및 비용 견적을 추출합니다. 이러한 지표는 대시보드를 강화합니다.Studio.

로그는 Trace와 자동으로 연관됩니다. Trace 컨텍스트 내의 모든 logger.info(), logger.warn(), logger.error() 호출에는 현재 Trace 및 스팬 ID가 태그로 지정됩니다. 로그 항목에서 해당 로그를 생성한 Trace로 바로 이동할 수 있습니다. 피드백은 평점, 의견, 수정 사항과 같은 사람의 검토 신호를 기록합니다. 피드백은 추적 및 범위에 연결된 다음 측정항목에 사용되는 것과 동일한 관측 가능성 저장소로 쿼리될 수 있습니다.

이러한 신호는 추적 ID, 범위 ID, 엔터티 유형, 엔터티 이름과 같은 상관 관계 ID를 공유합니다. 이를 사용하여 측정항목 급증에서 추적, 로그 및 관련 피드백으로 이동할 수 있습니다.

빠른 시작

@mastra/observability와 Trace 및 측정항목을 지원하는 스토리지 백엔드를 설치하세요.

npm

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

pnpm

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

Yarn

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

Bun

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

그런 다음 Mastra 인스턴스에서 Observability을 구성합니다. 다음 예에서는 복합 스토리지를 사용하여 관측 가능성 데이터를 DuckDB(메트릭 집계 지원)로 라우팅하는 동시에 다른 모든 것을 LibSQL에 유지합니다.

src/mastra/index.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
        ],
        logging: {
          enabled: true,
          level: 'info',
        },
      },
    },
  }),
})

Trace, 로그 전달 및 측정항목을 활성화합니다. Mastra는 Langfuse, Datadog 및 모든 OpenTelemetry 호환 플랫폼과 같은 외부 Trace Provider도 지원합니다. 외부 Provider로 데이터를 보내면서 Mastra Studio 접근을 유지하려면 Studio 접근 유지를 참조하세요.

구성

Observability은 Mastra 인스턴스에서 한 번 구성되며 추적, 로그 및 지표에 걸쳐 적용됩니다.

기본 구성

관측 가능성 구성에는 일반적으로 다음이 포함됩니다.

• serviceName: 내보낸 관측 가능성 데이터에 첨부된 서비스 식별자입니다.
• exporters: 추적, 로그 및 파생 측정항목에 대한 하나 이상의 대상입니다.
• spanOutputProcessors: 범위를 내보내기 전에 실행되는 변환입니다.
• logging: 관측 가능성 저장소에 대한 로그 전달 설정입니다.

대상 및 프로세서에 대해서는 다음을 참조하세요.Integrations overview.

Studio 액세스 유지

외부 내보내기를 추가하는 경우 Studio Observability에는 MastraStorageExporter를, 호스팅된 Mastra 플랫폼 Observability에는 MastraPlatformExporter를 함께 추가하세요. 다음 예시에서는 관측 가능성 구성만 보여줍니다. 저장소를 별도로 구성하십시오.

src/mastra/observability.ts

import { Observability, MastraStorageExporter, MastraPlatformExporter } from '@mastra/observability'
import { ArizeExporter } from '@mastra/arize'

export const observability = new Observability({
  configs: {
    production: {
      serviceName: 'my-service',
      exporters: [
        new ArizeExporter({
          endpoint: process.env.PHOENIX_COLLECTOR_ENDPOINT,
          apiKey: process.env.PHOENIX_API_KEY,
        }),
        new MastraStorageExporter(),
        new MastraPlatformExporter(),
      ],
    },
  },
})

서버리스 환경에서 플러시

서버리스 환경에서는 런타임이 일시 중지되거나 종료되기 전에 관측 가능성 내보내기를 플러시합니다.

await mastra.observability.flush()

서버리스 환경에서는 로컬 파일 스토리지 대신 외부 스토리지를 사용하세요. 스토리지 선택 및 라우팅에 대해서는 스토리지를 참조하세요.

다중 구성 설정

다양한 환경이나 요청 유형에 다양한 내보내기 또는 샘플링 동작이 필요한 경우 여러 구성을 사용하세요. 다음을 사용하여 런타임 시 활성 구성을 선택합니다.configSelector.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { Observability, MastraStorageExporter } from '@mastra/observability'
import { LangfuseExporter } from '@mastra/langfuse'

const storageExporter = new MastraStorageExporter()
const langfuseExporter = new LangfuseExporter()

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      development: {
        serviceName: 'my-service-dev',
        exporters: [storageExporter],
      },
      production: {
        serviceName: 'my-service-prod',
        exporters: [storageExporter, langfuseExporter],
      },
    },
    configSelector: () => process.env.NODE_ENV || 'development',
  }),
})

추적 샘플링은 다음을 참조하세요.Tracing.

저장

스토리지는 어떤 관측 가능성 신호가 지속되는지, 어떤 쿼리가 사용 가능한지, 측정항목 집계가 작동하는지 여부를 결정합니다. 기본 애플리케이션 스토어 대신 전용 Observability 스토어를 사용하세요.

신호 지원

스토리지 지원 범위는 신호와 워크로드에 따라 다릅니다. MastraStorageExporter는 Trace를 ClickHouse, PostgreSQL, MSSQL, MongoDB 및 LibSQL에 영구 저장할 수 있습니다. 측정항목에는 분석 지원 스토리지가 필요합니다.

• DuckDB: 로컬 테스트 및 개발에 권장됩니다.
• ClickHouse: 대용량 프로덕션 Observability에 권장됩니다.
• PostgresStoreVNext: Observability 도메인이 활성화된 경우 측정항목을 지원합니다. 전체 파티션 스캔을 방지하려면 항상 시간 범위를 제공하세요.
• Mastra 플랫폼: 백엔드를 직접 관리하지 않고 호스팅된 Observability를 사용하려면 MastraPlatformExporter를 사용하세요. 전체 Provider 목록과 지원되는 Trace 전략은 Mastra Storage 내보내기를 참조하세요. 기본 스토리지가 Observability를 지원하지 않거나 워크로드를 독립적으로 확장해야 하는 경우 복합 스토리지를 사용하여 observability 도메인을 별도로 라우팅하세요.

지역 발전

로컬 개발의 경우 다음을 사용하십시오.

• LibSQLStore기본 애플리케이션 스토리지용
• DuckDBStore에 대한observability domain
• MastraStorageExporter로컬 스튜디오 액세스용

프로덕션 배포

Observability 트래픽은 일반적으로 애플리케이션의 나머지 부분보다 쓰기가 더 많습니다. 생산 중:

• 자체 스토리지에 Observability를 유지하려면 observability 도메인에 ClickHouse와 함께 MastraStorageExporter를 사용하세요.
• 백엔드를 직접 관리하는 대신 호스팅된 Mastra 플랫폼 Observability를 사용하려면 MastraPlatformExporter를 사용하세요.
• Observability에 기본 애플리케이션 데이터와 다른 백엔드 또는 확장 정책이 필요하다면 복합 스토리지를 사용하세요. 백엔드 호환성 세부정보 및 내보내기 일괄 처리 동작은 다음을 참조하세요.Mastra Storage exporter.

마스트라 플랫폼

프로젝트 및 배포 전반의 호스팅된 Trace, 로그 및 측정항목에 대해서는 Mastra 플랫폼의 Observability를 참조하세요.

다음 단계

• 트레이싱
• 벌채 반출
• 측정항목
• 피드백
• 통합 개요
• 마스트라 스튜디오
• 자동 측정항목 참조
• Mastra 플랫폼 가시성