Sinks & Filters - 🌲 Sonamu

Sink는 로그를 출력할 대상을, Filter는 어떤 로그를 출력할지 결정합니다. sonamu.config.ts의 logging 옵션에서 커스텀 sink와 filter를 추가할 수 있습니다.

Sink란?

Sink는 로그가 최종적으로 출력되는 곳입니다. 예시:

콘솔 (터미널)
파일
외부 로깅 서비스 (Sentry, Datadog 등)
데이터베이스

Sink가 필요한 이유

로그는 목적에 따라 다른 곳에 기록되어야 합니다: 1. 실시간 모니터링 (콘솔)

// 개발 중 즉시 확인
logger.info("API called", { url: "/api/user" });
// → 터미널에 바로 출력

2. 영구 보관 (파일)

// 나중에 분석하기 위해
logger.error("Payment failed", { orderId });
// → errors.log 파일에 저장

3. 에러 알림 (외부 서비스)

// 심각한 문제 즉시 통보
logger.fatal("DB connection lost");
// → Sentry에 전송, 슬랙 알림

4. 통계 분석 (데이터베이스)

// 로그 데이터 분석
logger.info("User action", { action: "purchase", amount });
// → DB에 저장, 나중에 집계

여러 Sink 동시 사용

한 로그를 여러 Sink에 동시에 보낼 수 있습니다:

loggers: [
  {
    category: ["fastify"],
    sinks: ["console", "file", "sentry"], // 3곳에 동시 기록
    lowestLevel: "error",
  },
];

장점:

실시간 확인 (console)
영구 보관 (file)
즉시 알림 (sentry)

Filter란?

Filter는 로그를 선택적으로 출력하기 위한 조건입니다. 예시:

특정 카테고리만
특정 레벨 이상만
특정 URL 패턴만
시간대별로

Filter가 필요한 이유

모든 로그를 다 기록하면 문제가 발생합니다: 1. 성능 저하

// Filter 없음: 모든 요청 로깅
/favicon.ico  / /
  불필요 /
  assets /
  logo.png / // 불필요
  api /
  healthcheck / // 반복적, 불필요
  api /
  user /
  list / // 필요!
  // Filter 있음: /api만 로깅
  api /
  user /
  list; // 필요!

2. 디스크 공간 낭비

// 하루 100만 건의 요청
// Filter 없음: 100만 건 모두 기록 → 수백 MB
// Filter 있음: 10만 건만 기록 → 수십 MB

3. 가독성 저하

[로그 파일]
[INFO] /favicon.ico
[INFO] /assets/style.css
[INFO] /assets/logo.png
[INFO] /api/healthcheck
[INFO] /api/healthcheck
[INFO] /api/user/list  // ← 필요한 로그를 찾기 어려움!
[INFO] /api/healthcheck

Filter 사용 예시

filters: {
  // 중요한 것만
  "important": (record) => {
    // API 요청만
    if (!record.url.startsWith("/api")) return false;
    // healthcheck 제외
    if (record.url === "/api/healthcheck") return false;
    return true;
  },
}

Sink vs Filter 차이점

두 개념은 서로 다른 목적을 가집니다:

구분	Sink	Filter
목적	어디에 기록?	무엇을 기록?
타이밍	로그 출력 시	필터링 시
예시	콘솔, 파일, Sentry	URL 패턴, 레벨, 시간
역할	출력 형식 결정	출력 여부 결정

함께 사용하기

{
  sinks: {
    console: getConsoleSink(),      // 어디에?
    errorFile: getFileSink("..."),  // 어디에?
  },

  filters: {
    "api-only": (record) => ...,   // 무엇을?
    "errors": (record) => ...,      // 무엇을?
  },

  loggers: [
    {
      category: ["fastify"],
      sinks: ["console"],           // console에
      filters: ["api-only"],        // API 로그만
    },
    {
      category: ["fastify"],
      sinks: ["errorFile"],         // errorFile에
      filters: ["errors"],          // 에러 로그만
    },
  ],
}

언제 사용하나?

Sink를 추가할 때

1. 새로운 출력 대상이 필요할 때

// 예: Slack으로 에러 알림
sinks: {
  slack: customSlackSink,
}

2. 다른 형식으로 기록할 때

// 예: JSON 형식으로 파일 저장
sinks: {
  jsonFile: getFileSink("app.json", { formatter: jsonFormatter }),
}

3. 여러 곳에 동시 기록할 때

loggers: [
  {
    sinks: ["console", "file", "sentry"], // 3곳에 동시
  },
];

Filter를 추가할 때

1. 특정 조건의 로그만 필요할 때

// 예: 느린 요청만
filters: {
  "slow": (record) => record.responseTime > 1000,
}

2. 성능을 개선하고 싶을 때

// 예: 불필요한 로그 제외
filters: {
  "no-healthcheck": (record) => record.url !== "/api/healthcheck",
}

3. Sink별로 다른 로그를 보내고 싶을 때

loggers: [
  {
    sinks: ["console"],
    filters: ["all"], // 콘솔: 모든 로그
  },
  {
    sinks: ["errorFile"],
    filters: ["errors"], // 파일: 에러만
  },
];

Sinks 설정 상세

sinks 옵션

logging.sinks에 커스텀 Sink를 추가합니다. 타입: Record<string, Sink>

import { defineConfig } from "sonamu";
import { getConsoleSink, getFileSink } from "@logtape/logtape";

export default defineConfig({
  logging: {
    sinks: {
      "my-console": getConsoleSink(),
      "my-file": getFileSink("logs/app.log"),
    },
  },

  server: {
    // ...
  },
});

"fastify-console" 이름은 Sonamu가 자동으로 생성하는 기본 Sink입니다. 이 이름으로 추가하면 기본 Sink를 덮어씁니다.

콘솔 Sink

터미널에 로그를 출력합니다.

import { getConsoleSink } from "@logtape/logtape";
import { getPrettyFormatter } from "@logtape/pretty";

export default defineConfig({
  logging: {
    sinks: {
      console: getConsoleSink({
        formatter: getPrettyFormatter({
          timestamp: "time",
          categoryWidth: 20,
        }),
      }),
    },
  },

  server: {
    // ...
  },
});

파일 Sink

파일에 로그를 저장합니다.

import { getFileSink } from "@logtape/logtape";

export default defineConfig({
  logging: {
    sinks: {
      accessLog: getFileSink("logs/access.log"),
      errorLog: getFileSink("logs/errors.log"),
    },

    loggers: [
      // 모든 로그는 access.log에
      {
        category: ["fastify"],
        sinks: ["accessLog"],
        lowestLevel: "info",
      },
      // 에러만 errors.log에
      {
        category: ["fastify"],
        sinks: ["errorLog"],
        lowestLevel: "error",
      },
    ],
  },

  server: {
    // ...
  },
});

스트림 Sink

Node.js 스트림에 로그를 출력합니다.

import { getStreamSink } from "@logtape/logtape";
import fs from "fs";

const stream = fs.createWriteStream("logs/app.log", { flags: "a" });

export default defineConfig({
  logging: {
    sinks: {
      stream: getStreamSink(stream),
    },
  },

  server: {
    // ...
  },
});

커스텀 Sink

직접 Sink를 구현할 수 있습니다.

import type { Sink, LogRecord } from "@logtape/logtape";
import * as Sentry from "@sentry/node";

const sentrySink: Sink = async (record: LogRecord) => {
  if (record.level >= "error") {
    Sentry.captureException(new Error(record.message.join(" ")), {
      level: record.level,
      extra: record.properties,
    });
  }
};

export default defineConfig({
  logging: {
    sinks: {
      sentry: sentrySink,
    },

    loggers: [
      {
        category: ["fastify"],
        sinks: ["fastify-console", "sentry"], // 콘솔 + Sentry
        lowestLevel: "info",
      },
    ],
  },

  server: {
    // ...
  },
});

Filters 설정

filters 옵션

로그를 선택적으로 필터링합니다. 타입: Record<string, FilterLike>

type FilterLike = Filter | string;
type Filter = (record: LogRecord) => boolean;

import type { LogRecord } from "@logtape/logtape";

export default defineConfig({
  logging: {
    filters: {
      "api-only": (record: LogRecord) => {
        const req = record.properties.req;
        return req?.url?.startsWith("/api") ?? false;
      },
    },
  },

  server: {
    // ...
  },
});

"fastify-console" 이름은 Sonamu가 자동으로 생성하는 기본 Filter입니다. 이 이름으로 추가하면 기본 Filter를 덮어씁니다.

URL 기반 필터

import type { LogRecord } from "@logtape/logtape";
import type { FastifyRequest, FastifyReply } from "fastify";

export default defineConfig({
  logging: {
    filters: {
      "user-api": (record: LogRecord) => {
        const req = record.properties.req as FastifyRequest | undefined;
        const res = record.properties.res as FastifyReply | undefined;
        const url = req?.url ?? res?.request.url;
        return url?.startsWith("/api/user") ?? false;
      },
    },

    loggers: [
      {
        category: ["fastify"],
        sinks: ["fastify-console"],
        filters: ["user-api"], // /api/user/* 만
        lowestLevel: "info",
      },
    ],
  },

  server: {
    // ...
  },
});

레벨 기반 필터

export default defineConfig({
  logging: {
    filters: {
      "error-only": (record) => record.level >= "error",
      "warning-or-higher": (record) => record.level >= "warning",
    },
  },

  server: {
    // ...
  },
});

시간 기반 필터

export default defineConfig({
  logging: {
    filters: {
      "business-hours": (record) => {
        const hour = new Date().getHours();
        return hour >= 9 && hour < 18; // 09:00 - 18:00만
      },
    },
  },

  server: {
    // ...
  },
});

프로퍼티 기반 필터

export default defineConfig({
  logging: {
    filters: {
      "slow-requests": (record) => {
        const responseTime = record.properties.responseTime as number | undefined;
        return responseTime ? responseTime > 1000 : false; // 1초 이상만
      },
    },
  },

  server: {
    // ...
  },
});

실전 예시

개발 vs 프로덕션

import { defineConfig } from "sonamu";
import { getConsoleSink, getFileSink } from "@logtape/logtape";
import { getPrettyFormatter } from "@logtape/pretty";

const isDev = process.env.NODE_ENV === "development";

export default defineConfig({
  logging: {
    sinks: {
      console: getConsoleSink({
        formatter: getPrettyFormatter({
          timestamp: isDev ? "time" : "rfc3339",
        }),
      }),
      ...(isDev
        ? {}
        : {
            file: getFileSink("logs/app.log"),
            errorFile: getFileSink("logs/errors.log"),
          }),
    },

    loggers: [
      {
        category: ["fastify"],
        sinks: isDev ? ["console"] : ["console", "file"],
        lowestLevel: isDev ? "debug" : "info",
      },
      ...(!isDev
        ? [
            {
              category: ["fastify"] as const,
              sinks: ["errorFile"] as const,
              lowestLevel: "error" as const,
            },
          ]
        : []),
    ],
  },

  server: {
    listen: { port: 34900 },
  },
});

다중 Sink & Filter

import { defineConfig } from "sonamu";
import { getConsoleSink, getFileSink } from "@logtape/logtape";
import type { LogRecord } from "@logtape/logtape";
import type { FastifyRequest, FastifyReply } from "fastify";

export default defineConfig({
  logging: {
    sinks: {
      console: getConsoleSink(),
      accessLog: getFileSink("logs/access.log"),
      errorLog: getFileSink("logs/error.log"),
    },

    filters: {
      "api-requests": (record: LogRecord) => {
        const req = record.properties.req as FastifyRequest | undefined;
        const res = record.properties.res as FastifyReply | undefined;
        const url = req?.url ?? res?.request.url;
        return url?.startsWith("/api") ?? false;
      },
      "errors-only": (record: LogRecord) => record.level >= "error",
    },

    loggers: [
      // 콘솔: 모든 로그
      {
        category: ["fastify"],
        sinks: ["console"],
        lowestLevel: "info",
      },
      // access.log: /api 요청만
      {
        category: ["fastify"],
        sinks: ["accessLog"],
        filters: ["api-requests"],
        lowestLevel: "info",
      },
      // error.log: 에러만
      {
        category: ["fastify"],
        sinks: ["errorLog"],
        filters: ["errors-only"],
        lowestLevel: "error",
      },
    ],
  },

  server: {
    listen: { port: 34900 },
  },
});

외부 서비스 통합

import { defineConfig } from "sonamu";
import { getConsoleSink } from "@logtape/logtape";
import type { Sink, LogRecord } from "@logtape/logtape";
import * as Sentry from "@sentry/node";

Sentry.init({ dsn: process.env.SENTRY_DSN });

const sentrySink: Sink = async (record: LogRecord) => {
  if (record.level >= "error") {
    Sentry.captureException(new Error(record.message.join(" ")), {
      level: record.level,
      extra: {
        category: record.category,
        properties: record.properties,
      },
    });
  }
};

export default defineConfig({
  logging: {
    sinks: {
      console: getConsoleSink(),
      sentry: sentrySink,
    },

    loggers: [
      {
        category: ["fastify"],
        sinks: ["console", "sentry"],
        lowestLevel: "info",
      },
    ],
  },

  server: {
    listen: { port: 34900 },
  },
});

URL 패턴별 로깅

import { defineConfig } from "sonamu";
import { getConsoleSink, getFileSink } from "@logtape/logtape";
import type { LogRecord } from "@logtape/logtape";
import type { FastifyRequest, FastifyReply } from "fastify";

export default defineConfig({
  logging: {
    sinks: {
      console: getConsoleSink(),
      adminLog: getFileSink("logs/admin.log"),
      userLog: getFileSink("logs/user.log"),
    },

    filters: {
      "admin-routes": (record: LogRecord) => {
        const req = record.properties.req as FastifyRequest | undefined;
        const res = record.properties.res as FastifyReply | undefined;
        const url = req?.url ?? res?.request.url;
        return url?.startsWith("/api/admin") ?? false;
      },
      "user-routes": (record: LogRecord) => {
        const req = record.properties.req as FastifyRequest | undefined;
        const res = record.properties.res as FastifyReply | undefined;
        const url = req?.url ?? res?.request.url;
        return url?.startsWith("/api/user") ?? false;
      },
    },

    loggers: [
      {
        category: ["fastify"],
        sinks: ["console", "adminLog"],
        filters: ["admin-routes"],
        lowestLevel: "info",
      },
      {
        category: ["fastify"],
        sinks: ["console", "userLog"],
        filters: ["user-routes"],
        lowestLevel: "info",
      },
    ],
  },

  server: {
    listen: { port: 34900 },
  },
});

LogRecord 구조

Filter와 커스텀 Sink에서 사용하는 LogRecord 타입:

type LogRecord = {
  category: readonly string[];
  level: LogLevel;
  message: unknown[];
  timestamp: Date;
  properties: Record<string, unknown>;
};

주요 프로퍼티:

category: 로그 카테고리 (예: ["fastify"])
level: 로그 레벨 ("debug" | "info" | "warning" | "error" | "fatal")
message: 로그 메시지 배열
timestamp: 로그 발생 시간
properties: 추가 정보 (Fastify의 경우 req, res 등)

Fastify의 properties:

{
  req?: FastifyRequest;
  res?: FastifyReply;
  responseTime?: number;
}

주의사항

1. Sink 이름 충돌

// ❌ 나쁜 예: 기본 Sink 덮어씀
logging: {
  sinks: {
    "fastify-console": getConsoleSink(),  // 기본 설정 손실
  },
}

// ✅ 좋은 예: 다른 이름 사용
logging: {
  sinks: {
    "my-console": getConsoleSink(),
  },
}

2. Filter 성능

// ❌ 나쁜 예: 무거운 작업
filters: {
  "db-check": async (record) => {
    const result = await db.query("...");  // 매 로그마다 DB 조회!
    return result;
  },
}

// ✅ 좋은 예: 빠른 체크
filters: {
  "level-check": (record) => record.level >= "error",
}

3. 비동기 Sink

// ✅ Sink는 비동기 가능
const externalSink: Sink = async (record) => {
  await sendToExternalService(record);
};

4. Filter는 동기만

// ❌ Filter는 비동기 불가
filters: {
  "async-filter": async (record) => {  // 작동 안 함!
    return await someAsyncCheck();
  },
}

// ✅ 동기 함수만
filters: {
  "sync-filter": (record) => {
    return someCheck(record);
  },
}

다음 단계

카테고리 로깅

카테고리 시스템으로 로그를 체계적으로 관리하세요

Fastify 로깅

HTTP 요청/응답 로깅을 커스터마이징하세요

LogTape 설정

기본 로깅 설정과 개념을 학습하세요

LogTape 공식 문서

LogTape의 고급 기능과 API를 확인하세요

​Sink란?

​Sink가 필요한 이유

​여러 Sink 동시 사용

​Filter란?

​Filter가 필요한 이유

​Filter 사용 예시

​Sink vs Filter 차이점

​함께 사용하기

​언제 사용하나?

​Sink를 추가할 때

​Filter를 추가할 때

​Sinks 설정 상세

​sinks 옵션

​콘솔 Sink

​파일 Sink

​스트림 Sink

​커스텀 Sink

​Filters 설정

​filters 옵션

​URL 기반 필터

​레벨 기반 필터

​시간 기반 필터

​프로퍼티 기반 필터

​실전 예시

​개발 vs 프로덕션

​다중 Sink & Filter

​외부 서비스 통합

​URL 패턴별 로깅

​LogRecord 구조

​주의사항

​1. Sink 이름 충돌

​2. Filter 성능

​3. 비동기 Sink

​4. Filter는 동기만

​다음 단계

카테고리 로깅

Fastify 로깅

LogTape 설정

LogTape 공식 문서

Sink란?

Sink가 필요한 이유

여러 Sink 동시 사용

Filter란?

Filter가 필요한 이유

Filter 사용 예시

Sink vs Filter 차이점

함께 사용하기

언제 사용하나?

Sink를 추가할 때

Filter를 추가할 때

Sinks 설정 상세

sinks 옵션

콘솔 Sink

파일 Sink

스트림 Sink

커스텀 Sink

Filters 설정

filters 옵션

URL 기반 필터

레벨 기반 필터

시간 기반 필터

프로퍼티 기반 필터

실전 예시

개발 vs 프로덕션

다중 Sink & Filter

외부 서비스 통합

URL 패턴별 로깅

LogRecord 구조

주의사항

1. Sink 이름 충돌

2. Filter 성능

3. 비동기 Sink

4. Filter는 동기만

다음 단계