Astro 로거 API

추가된 버전: astro@7.0.0

로거 API는 Astro의 로깅 인프라에 대한 더 세밀한 제어를 제공합니다. 이를 통해 기본 콘솔 출력을 사용자 지정 로깅 구현체로 대체하고, 로그 집계 서비스와 연동할 수 있습니다.

이 API는 즉시 사용할 수 있는 세 가지 내장 로거를 제공하며, 자체 로거를 통합하거나 조합할 수 있는 기능도 지원합니다.

사용자 정의 로거

내장 로거 중 하나를 사용하지 않으려는 경우, 직접 만들 수 있습니다.

사용자 정의 로거는 두 가지 요소로 구성됩니다.

로거 설정: Astro에 사용할 구현체와 전달할 설정을 지정합니다.
로거 구현체: 실제 로깅 처리를 담당합니다.

사용자 정의 로거를 정의하면 Astro에서 발생하는 로그를 포함하여 모든 로그를 직접 제어하게 됩니다.

로거 설정

logger 설정은 필수 항목인 entrypoint와 선택 항목인 config를 포함하는 객체입니다.

다음 예시는 @org/custom-logger 패키지에서 내보내는 사용자 정의 로거를 설정하고 level 옵션을 전달하는 방법을 보여줍니다.

import { defineConfig } from 'astro/config';

export default defineConfig({
  logger: {
    entrypoint: "@org/custom-logger",
    config: {
      level: "warn"
    }
  }
});

로거 구현체

로거 구현체는 로깅 로직을 담당합니다. 로거 모듈에서 로거 설정을 매개변수로 받는 기본 함수를 내보내어 구현하며, 이 함수는 필수 write() 함수를 포함하는 AstroLoggerDestination 객체를 반환해야 합니다.

다음 예시는 설정의 로그 level을 반영하는 최소한의 로거 구현을 보여줍니다.

import { matchesLevel } from "astro/logger";

/**
 * 사용자 정의 로거 구현의 간단한 예입니다.
 *
 * @param {Object} [options] - 로거 옵션입니다.
 * @param {import("astro").AstroLoggerLevel} [options.level] - 출력할 로그의 최소 레벨입니다. 기본값은 `"info"`입니다.
 * @returns {import("astro").AstroLoggerDestination} 사용자 정의 로거의 출력 대상입니다.
 */
function orgLogger({ level } = { level: "info" }) {
  return {
    write(message) {
      // 메시지를 출력해야 하는지 판단하려면 이 유틸리티를 사용합니다.
      if (matchesLevel(message.level, level)) {
        // 로그 레벨을 고려하여 메시지를 원하는 위치에 기록합니다.
      }
    },
  };
}

export default orgLogger;

이제 런타임 API를 사용하여 페이지 렌더링 중에 자체 로그를 추가할 수 있습니다.

로그 레벨

레벨은 각 메시지에 할당되는 내부적으로 정의된 임의의 값입니다. 특정 레벨로 로거를 구성하면 해당 레벨과 같거나 더 높은 레벨의 메시지만 출력됩니다.

높은 심각도에서 낮은 심각도 순으로 세 가지 레벨이 있습니다.

error
warn
info

다음 예시는 JSON 로거가 warn 레벨 이상의 메시지만 출력하도록 구성합니다.

import { defineConfig, logHandlers } from 'astro/config';

export default defineConfig({
  logger: logHandlers.json({ level: "warn" })
});

astro/logger 패키지는 로그 레벨을 확인하는 matchesLevel() 헬퍼를 노출합니다. 이는 사용자 정의 로거를 만들 때 유용합니다.

import { matchesLevel } from "astro/logger";

matchesLevel("error", "info");

내장 로거

Astro는 애플리케이션에서 사용할 수 있는 내장 로거를 제공합니다.

`logHandlers.json()`

메시지를 JSON 형식으로 출력하는 로거입니다. 로그는 다음과 같은 형태로 출력됩니다:

{ "message": "<메시지>", "label": "router", "level": "info", "time": "<UNIX 타임스탬프>"  }

JSON 로거 옵션

타입: { pretty: boolean; level: AstroLoggerLevel; }
기본값: { pretty: false, level: 'info' }

추가된 버전: astro@7.0.0

json 로거는 다음 옵션을 지원합니다:

pretty: true이면 JSON 로그가 여러 줄로 출력됩니다. 기본값은 false입니다.
level: 출력할 로그의 레벨입니다.

import { defineConfig, logHandlers } from 'astro/config';

export default defineConfig({
  logger: logHandlers.json({ pretty: true })
});

`logHandlers.console()`

console을 출력 대상으로 사용하는 로거입니다. 메시지 레벨에 따라 서로 다른 메서드를 사용합니다:

error 메시지는 console.error()를 사용합니다.
warn 메시지는 console.warn()을 사용합니다.
info 메시지는 console.info()를 사용합니다.

콘솔 로거 옵션

타입: { level: AstroLoggerLevel }
기본값: { level: 'info' }

추가된 버전: astro@7.0.0

console 로거는 다음 옵션을 허용합니다:

level: 출력할 로그의 레벨입니다.

import { defineConfig, logHandlers } from 'astro/config';

export default defineConfig({
  logger: logHandlers.console({ level: 'warn' })
});

`logHandlers.node()`

process.stdout 및 process.stderr로 메시지를 출력하는 로거입니다. error 레벨 메시지는 stderr로 출력되며, 나머지 메시지는 stdout으로 출력됩니다.

이 로거는 Astro의 기본 로거입니다.

Node 로거 옵션

타입: { level: AstroLoggerLevel }
기본값: { level: 'info' }

추가된 버전: astro@7.0.0

node 로거는 다음 옵션을 허용합니다:

level: 출력할 로그의 레벨입니다.

import { defineConfig, logHandlers } from 'astro/config';

export default defineConfig({
  logger: logHandlers.node({ level: 'warn' })
});

`logHandlers.compose()`

여러 로거를 임의의 순서로 구성할 수 있게 해주는 함수입니다. 동일한 메시지가 모든 로거로 브로드캐스트됩니다.

다음 예시는 콘솔 로거와 JSON 로거를 기본 로그 레벨로 조합합니다.

import { defineConfig, logHandlers } from 'astro/config';

export default defineConfig({
  logger: logHandlers.compose(
    logHandlers.console(),
    logHandlers.json()
  )
});

타입 참조

다음 타입들은 astro에서 가져올 수 있습니다.

`AstroRuntimeLogger`

타입: { info: (message: string) => void; warn: (message: string) => void; error: (message: string) => void; }

추가된 버전: astro@7.0.8

페이지 렌더링 중 추가 로그를 남기기 위해 런타임에 사용할 수 있는 logger 메서드를 설명합니다.

`AstroLoggerDestination`

사용자 정의 로거가 구현해야 하는 인터페이스입니다.

`AstroLoggerDestination.write()`

타입: (message: AstroLoggerMessage) => void

각 로그마다 호출되는 필수 메서드이며 AstroLoggerMessage를 인수로 전달받습니다.

`AstroLoggerDestination.flush()`

타입: () => Promise<void> | void

각 요청이 끝날 때 호출되는 선택적 함수입니다. 출력 대상과의 연결을 유지하면서 로그를 플러시해야 하는 고급 로거에 유용합니다.

`AstroLoggerDestination.close()`

타입: () => Promise<void> | void

서버가 종료되기 전에 호출되는 선택적 함수입니다. 이 함수는 일반적으로 @astrojs/node와 같은 어댑터에 의해 호출됩니다.

`AstroLoggerLevel`

타입: 'debug' | 'info' | 'warn' | 'error' | 'silent'

로그의 상세 수준을 지정합니다:

info, warn, error: 출력할 최소 로그 레벨을 정의합니다.
silent: --silent CLI 플래그와 동일하며 로그 출력을 하지 않습니다.
debug: --debug CLI 플래그와 동일하며 Vite 로깅을 포함한 상세 로깅을 활성화합니다.

`AstroLoggerMessage`

타입: { label: string | null; level: AstroLoggerLevel; message: string; newLine: boolean; }

AstroLoggerDestination.write() 함수로 전달되는 객체입니다:

message: 기록되는 메시지입니다.
level: 메시지의 레벨입니다.
label: 로그 메시지에 할당된 임의의 라벨입니다.
newLine: 이 메시지 뒤에 줄바꿈을 추가할지 여부입니다.

API 참조

다음 API는 astro/logger에서 가져올 수 있습니다.

`matchesLevel()`

타입: matchesLevel(messageLevel: AstroLoggerLevel, configuredLevel: AstroLoggerLevel) => boolean

두 개의 로그 레벨이 주어지면, 첫 번째 레벨이 두 번째 레벨과 일치하는지 여부를 반환합니다.

import { matchesLevel } from "astro/logger";

matchesLevel("error", "info"); // true
matchesLevel("info", "error"); // false

기여하기 커뮤니티 후원하기