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

# 벌채 반출

Mastra의 로깅 시스템은 함수 실행, 입력 데이터 및 출력 응답을 구조화된 형식으로 캡처합니다.

Mastra 플랫폼에 배포하면 대시보드에 로그가 표시됩니다. 자체 호스팅 또는 사용자 지정 환경에서는 구성된 전송에 따라 로그를 파일이나 외부 서비스로 보낼 수 있습니다.

**AI Agent의 경우:**달리다`npx mastra api log list '{"level":"error","page":0,"perPage":50}'` 을 사용하면 Studio를 열거나 임시 스크립트를 작성하지 않고도 최근 오류 로그를 직접 검사할 수 있습니다. 이 명령을 사용하려면 Observability 로깅이 구성된 Mastra 서버가 실행 중이어야 합니다. `npx mastra dev`, 또는 연결 가능한 서버의 기본 URL을 다음과 함께 전달합니다.`--url`. 달리다`npx mastra api log list --schema`다른 필터를 구성하기 전에. 마스트라의 스킬을 설치하세요.`npx skills add mastra-ai/skills --skill mastra`완전한 API CLI 검색, 타겟팅, 스키마, 인증 및 오류 처리 지침을 제공합니다.

## 다음을 사용하여 로그 구성`PinoLogger`

언제[initializing a new Mastra project](https://mastra.zisheng.pro/ko/guides/getting-started/quickstart) using the CLI, `PinoLogger` is included by default.

```typescript
import { Mastra } from '@mastra/core/mastra'
import { PinoLogger } from '@mastra/loggers'

export const mastra = new Mastra({
  logger: new PinoLogger({
    name: 'Mastra',
    level: 'info',
  }),
})
```

방문하다[PinoLogger](https://mastra.zisheng.pro/ko/reference/logging/pino-logger) for all available configuration options.

## 관측 가능성 스토리지에 로깅

언제[observability](https://mastra.zisheng.pro/ko/docs/observability/overview) 을 사용하여 로컬 서버를 시작하세요. 구성이 완료되면 모든 로거 호출이 Observability 스토리지로 자동 전달됩니다. 즉, 애플리케이션과 Mastra 내부 컴포넌트의 모든 `debug`, `info`, `warn`, `error`, and `trackException` 호출이 Trace와 함께 저장됩니다.

코드 변경이 필요하지 않습니다. Mastra는 원래 로거(콘솔, 파일 또는 사용자 정의 전송)와 관찰 시스템 모두에 동시에 쓸 수 있도록 구성된 로거를 래핑합니다.

### 관측 가능성 로그 수준 구성

콘솔 로거와 독립적으로 Observability 저장소에 도달하는 로그 수준을 제어할 수 있습니다. 추가`logging` option to your observability instance configuration:

```typescript
import { Mastra } from '@mastra/core/mastra'
import { PinoLogger } from '@mastra/loggers'
import { Observability, MastraStorageExporter } from '@mastra/observability'

export const mastra = new Mastra({
  logger: new PinoLogger({ name: 'Mastra', level: 'debug' }),
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'my-app',
        exporters: [new MastraStorageExporter()],
        logging: {
          enabled: true, // set to false to disable log forwarding
          level: 'info', // minimum level: 'debug' | 'info' | 'warn' | 'error' | 'fatal'
        },
      },
    },
  }),
})
```

이 예에서 콘솔 로거는 다음부터 시작하는 모든 레벨을 출력합니다.`debug`, but only `info` 이상은 Observability 스토리지에 기록됩니다. 이렇게 하면 개발 중에는 상세한 콘솔 출력을 유지하면서 스토리지를 깔끔하게 관리할 수 있습니다.

| 옵션        | 유형         | 기본값       | 설명                                                            |
| --------- | ---------- | --------- | ------------------------------------------------------------- |
| `enabled` | `boolean`  | `true`    | Set to `false` 로 설정하면 Observability 스토리지로의 모든 로그 전달이 비활성화됩니다. |
| `level`   | `LogLevel` | `'debug'` | 최소 심각도 수준입니다. 이 수준보다 낮은 로그는 삭제됩니다.                            |

### 로그 쿼리 중

관측 가능성 저장소에 기록된 로그는 Mastra 클라이언트 SDK를 통해 쿼리할 수 있습니다.

```typescript
import { MastraClient } from '@mastra/client-js'

const client = new MastraClient()

const logs = await client.listLogsVNext({
  filters: { level: 'error' },
  pagination: { page: 1, perPage: 50 },
  orderBy: { field: 'timestamp', direction: 'desc' },
})
```

DuckDB 또는 ClickHouse와 같은 영구 스토리지 백엔드를 사용하는 경우 로그는 다시 시작해도 유지되며 기록 분석에 사용할 수 있습니다.

## 로그 맞춤설정

Mastra는 다음을 통해 로거 인스턴스에 대한 액세스를 제공합니다.`mastra.getLogger()` 메서드는 Workflow 단계와 Tool 모두에서 사용할 수 있습니다. 로거는 표준 심각도 수준을 지원합니다: `debug`, `info`, `warn`, and `error`.

### Workflow 단계에서 로깅

Workflow 단계 내에서 다음을 통해 로거에 액세스합니다.`mastra` parameter inside the `execute` 함수입니다. 단계 실행과 관련된 메시지를 기록할 수 있습니다.

```typescript
import { createWorkflow, createStep } from "@mastra/core/workflows";
import { z } from "zod";

const step1 = createStep({
  execute: async ({ mastra }) => {
    const logger = mastra.getLogger();
    logger.info("workflow info log");

    return {
      output: ""
    };
  }
});

export const testWorkflow = createWorkflow({...})
  .then(step1)
  .commit();
```

### Tool에서 로깅

마찬가지로 Tool은 다음을 통해 로거 인스턴스에 액세스할 수 있습니다.`mastra` 매개변수입니다. 이를 사용하여 실행 중 Tool별 활동을 기록할 수 있습니다.

```typescript
import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

export const testTool = createTool({
  execute: async (inputData, context) => {
    const logger = context?.mastra.getLogger()
    logger?.info('tool info log')

    return {
      output: '',
    }
  },
})
```

### 추가 데이터로 로깅

로거 메소드는 추가 데이터에 대한 선택적인 두 번째 인수를 허용합니다. 관측 가능성 저장소에서 로그를 필터링할 수 있도록 구조화된 개체를 전달합니다.

```typescript
import { createWorkflow, createStep } from "@mastra/core/workflows";
import { z } from "zod";

const step1 = createStep({
  execute: async ({ mastra }) => {
    const testAgent = mastra.getAgent("testAgent");
    const logger = mastra.getLogger();

    logger.info("workflow info log", { agent: testAgent });

    return {
      output: ""
    };
  }
});

export const testWorkflow = createWorkflow({...})
  .then(step1)
  .commit();
```