External Backend(NodeJS) Logger

Supports

Amplitude, Hackle, MongoDB

Need

Node.js 18 or higher to use built-in fetch

Usage

Type-safe by event schema

for example:

interface Events {
  event_1: {
    prop_a: string;
    prop_b: number;
  };
  event_2: {
    prop_c: string;
  };
}

const trackEvent = initExternalLogger<Events>(options);

// forcibly predefined schema key
trackEvent("event_1", properties /** typed properties by key */);

Options

type Option = {
  hackleKey?: string;
  amplitudeKey?: string;
  mongo?: {
    url: string;
    dbName: string;
    colName: string;
    lostColName?: string;
  };
  // user_utms 자동 부착용 별도 MongoDB connection
  userUtmsMongo?: {
    url: string;
  };
  slackWebHookUrlForFailAlarm?: string;
  getNow?: () => Date;
};

UTM 자동 부착 (with.utmLast, with.utmFirst)

서버사이드 이벤트에서 event_properties.utm_last / utm_first가 누락되는 문제를 해결합니다. 컨슈머는 옵션만 명시하면 SDK가 dbonline_v2.user_utms 컬렉션에서 actorId 기반으로 조회하여 payload에 자동 부착합니다.

사전 조건

• MONGO_URI: 현재는 sparta-online 클러스터에 모으는 것이 컨벤션입니다.
• Option.userUtmsMongo.url로 user_utms 조회용 MongoDB connection이 구성되어 있어야 합니다.
• 이벤트 호출 시 actorId가 전달되어야 합니다 (누락 시 enrichment 스킵).

사용 예시

const trackEvent = initExternalLogger<Events>({
  amplitudeKey: "...",
  mongo: { url: "...", dbName: "...", colName: "..." },
  userUtmsMongo: { url: "mongodb://..." },
});

trackEvent(
  "kdt_apply_paper_passed",
  { actorId, /* ...other props */ },
  { with: { utmLast: true, utmFirst: true } }
);

우선순위

eventProperties.utm_last (호출자 명시) > options.with.{utmLast,utmFirst} 자동 조회 > 미부착

호출자가 eventProperties에 utm_last/utm_first를 직접 넣은 경우, 자동 조회 결과를 덮어쓰지 않습니다.

실패 처리

user_utms 조회가 실패해도 트래커는 원본 payload로 정상 발화합니다. (에러는 stderr에 로깅)