@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

클라이언트는 instrumentation-client.ts, 서버/엣지는 instrumentation.ts의 register()(동적 import)에서 호출하는 초기화 함수입니다. 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}

Native (Expo)

Logger 자체는 web·native 공용(packages/logger/index.ts)이라 애플리케이션 코드는 native 에서도 동일하게 Logger.log/addAction/startView/captureError 를 씁니다. 다만 이 패키지가 직접 import 하는 SDK(@datadog/browser-logs·@datadog/browser-rum·@sentry/nextjs)는 브라우저/Next 전용이라 RN 에서 그대로 못 씁니다. 공유 패키지를 수정하지 않고 apps/native-app/metro.config.js 의 커스텀 resolveRequest 가 native 번들에서만 이들을 갈아끼웁니다: Datadog 브라우저 SDK → src/shims/datadogMobile.ts(@datadog/mobile-react-native 어댑터), @sentry/nextjs → @sentry/react-native.

그 결과 native 에서 LoggerProvider/initSentry 대신 <DatadogProvider> 와 RN initSentry 로 초기화하며, RUM/Logs 는 Datadog mobile SDK 로, crash 를 포함한 에러는 Sentry(@sentry/react-native)로 갑니다. Datadog 미init 시 어댑터 호출은 조용히 no-op 되는 등 동작 차이가 있으니 자세한 내용은 native 로깅·관측을 참고하세요.