@howmuchhome-web/logger

Datadog 및 Sentry 로깅을 추상화한 패키지입니다. 사용법은 로깅 가이드를 참고하세요.

Logger

모든 로깅의 진입점이 되는 클래스입니다. 모든 메서드는 static입니다.


import Logger from '@howmuchhome-web/logger';

메서드

메서드	환경	설명
`Logger.log(message, options?)`	클라이언트	Datadog Browser Logs에 로그 전송
`Logger.addAction(name, context?)`	클라이언트	Datadog RUM 커스텀 액션 기록
`Logger.startView(name)`	클라이언트	Datadog RUM 뷰 전환 기록
`Logger.captureError(error, options?)`	서버/클라이언트	Sentry에 에러 전송

서버 환경에서 log, addAction, startView를 호출하면 아무 동작도 하지 않습니다 (no-op).

`Logger.log(message, options?)`

Datadog Browser Logs로 커스텀 로그를 전송합니다.


Logger.log(message: string, options?: {
  type?: 'ok' | 'info' | 'warn' | 'error' | 'debug';
  context?: any;
})

`Logger.addAction(name, context?)`

Datadog RUM에 커스텀 액션을 기록합니다.


Logger.addAction(name: string, context?: object)

`Logger.startView(name)`

Datadog RUM에 뷰 전환을 기록합니다.


Logger.startView(name: string)

`Logger.captureError(error, options?)`

Sentry에 에러를 전송하고 eventId를 반환합니다.


Logger.captureError(error: Error, options?: {
  transactionName?: string;
  level?: ErrorLevel;           // 기본값: ErrorLevel.ERROR
  tags?: Record<string, string>;
  fingerprint?: string[];
  extra?: Record<string, unknown>;
}): string

level이 ErrorLevel.IGNORE이면 Sentry에 전송되지 않습니다.

LoggerProvider

앱 루트에 마운트합니다. ServerLogger와 ClientLogger를 합성한 컴포넌트로, 다음을 모두 처리합니다.

Datadog RUM 초기화
Datadog RUM / Sentry 사용자 컨텍스트 설정
OpenTelemetry span 속성 기록 (서버)


import {LoggerProvider} from '@howmuchhome-web/logger';


<LoggerProvider user={user}>
  {children}
</LoggerProvider>

Props

프로퍼티	타입	설명
`user`	`{ id: string; email?: string; username?: string } \| null`	로그인한 사용자. `null`이면 익명 ID 자동 생성
`service`	`string`	Datadog RUM 서비스 이름 (기본값: `'howmuchhome-web'`)
`children`	`ReactElement`

ServerLogger

서버 컴포넌트. Sentry 사용자 컨텍스트 설정 및 OpenTelemetry span 속성(usr.id, enduser.id, usr.name)을 기록합니다.

ClientLogger

클라이언트 컴포넌트. 마운트 시 Datadog RUM을 초기화하고, 사용자 변경을 감지하여 Datadog RUM과 Sentry에 사용자 정보를 설정합니다. 중복 초기화는 datadogRum.getInitConfiguration() 체크로 방지합니다.

initSentry

sentry.client.config.ts, sentry.server.config.ts, sentry.edge.config.ts 전용 초기화 함수입니다. NEXT_PUBLIC_ENV === 'production'일 때만 Sentry.init을 호출합니다.

브라우저 전용 패키지 오염을 방지하기 위해 메인 패키지가 아닌 서브패스에서 import합니다.


import {initSentry} from '@howmuchhome-web/logger/sentry';
 
initSentry();

유틸리티

generateAnonymousId

비로그인 사용자를 위한 익명 ID를 생성합니다. LoggerProvider에서 내부적으로 사용됩니다.


import {generateAnonymousId} from '@howmuchhome-web/logger';
 
generateAnonymousId(); // 'anonymous-1712345678901-k3j7x2abc'

반환 형식: anonymous-{Date.now()}-{random 9자리 base36}