LogStream SDK

Version 0.2.0

Node.js 애플리케이션을 위한 실시간 로그 스트리밍 SDK입니다. 콘솔 로그 자동 수집, 함수 로깅, HTTP 요청/응답 추적 기능을 제공합니다.

Features

• Zero-Config Console Logging: console.log/error/warn 자동 캡처
• Function Logging: 자동 함수 계측 (입력/출력/에러/실행시간)
• Network Tracking: Outbound/Inbound HTTP 요청 모니터링
• Performance Monitoring: CPU, Memory, Network 메트릭 수집
• Winston & Pino Integration: 인기 로깅 라이브러리 지원
• Batch Processing: 설정 가능한 배치 크기로 효율적 로그 집계
• Failure Resilient: Circuit Breaker 패턴으로 자동 복구
• TypeScript: 완전한 타입 지원

Installation

npm install @ologstream/sdk

Quick Start

기본 사용법

const LogStream = require('@ologstream/sdk').default;

// 초기화
LogStream.init({
  apiKey: 'YOUR_API_KEY',
  collectMetrics: true,
  collectNetwork: true,
});

// 모든 console 로그가 자동으로 캡처됩니다
console.log('Hello from Node.js');
console.error('An error occurred');

함수 로깅 (자동 계측)

// register.js - 앱의 가장 첫 번째 import로 실행
const LogStream = require('@ologstream/sdk').default;

LogStream.init({
  apiKey: 'YOUR_API_KEY',
  endpoint: 'http://localhost:3000/v1',
  functionLogging: {
    enabled: true,
    // include 없으면 모든 사용자 모듈 계측 (node_modules 기본 제외)
    onFunctionLog: (entry) => {
      console.log(`[${entry.functionName}] ${entry.event}`, entry.duration ? `${entry.duration}ms` : '');
    },
  },
});

실행:

node -r ./register.js ./app.js

Express 미들웨어

const express = require('express');
const LogStream = require('@ologstream/sdk').default;

LogStream.init({
  apiKey: 'YOUR_API_KEY',
  functionLogging: { enabled: true },
  networkLogging: { enableInboundHttpLogging: true },
});

const app = express();

// 미들웨어 추가 - 요청별 TraceID 생성 및 Inbound HTTP 로깅
app.use(LogStream.middleware());

app.get('/users', (req, res) => {
  // 이 요청 내 모든 함수 로그가 동일한 traceId를 공유합니다
  const traceId = LogStream.getTraceId();
  res.json({ users: [], traceId });
});

Winston Integration

const winston = require('winston');
const LogStream = require('@ologstream/sdk').default;

LogStream.init({ apiKey: 'YOUR_API_KEY' });

const logger = winston.createLogger({
  transports: [
    new winston.transports.Console(),
    LogStream.winstonTransport(),
  ],
});

logger.info('Winston log');
logger.error('Winston error');

Pino Integration

const pino = require('pino');
const LogStream = require('@ologstream/sdk').default;

LogStream.init({ apiKey: 'YOUR_API_KEY' });

const logger = pino({
  transport: {
    targets: [
      { target: 'pino-pretty', level: 'info' },
      LogStream.pinoStream(),
    ],
  },
});

logger.info('Pino log');

Configuration Options

LogStream.init({
  // === 기본 설정 ===
  apiKey: 'YOUR_API_KEY',              // 필수
  endpoint: 'http://localhost:3000/v1', // 기본값
  enabled: true,                        // SDK 활성화 여부

  // === 배치 설정 ===
  batchSize: 50,                        // 배치당 로그 수
  flushInterval: 1000,                  // 배치 전송 주기 (ms)
  maxBufferSize: 10000,                 // 최대 버퍼 크기

  // === 샘플링 ===
  sampleRate: 1.0,                      // 샘플링 비율 (0.0 ~ 1.0)

  // === 재시도 및 타임아웃 ===
  maxRetries: 5,                        // 최대 재시도 횟수
  recoveryTimeout: 30000,               // 실패 후 복구 대기 시간 (ms)
  transportTimeout: 5000,               // HTTP 요청 타임아웃 (ms)

  // === 메트릭 ===
  collectMetrics: true,                 // 성능 메트릭 수집
  metricsInterval: 30000,               // 메트릭 수집 주기 (ms)

  // === 네트워크 ===
  collectNetwork: true,                 // Outbound HTTP 추적

  // === 함수 로깅 ===
  functionLogging: {
    enabled: true,                      // 함수 로깅 활성화
    include: [/src\//],                 // 포함할 경로 패턴
    exclude: [/node_modules/],          // 제외할 경로 패턴
    excludeFunctions: [/^_/],           // 제외할 함수명 패턴
    wrapNestedObjects: true,            // 중첩 객체 함수도 래핑
    wrapGettersSetters: true,           // getter/setter 래핑
    enableAutoMasking: true,            // 자동 민감정보 마스킹
    sensitiveKeywords: ['secret'],      // 추가 민감 키워드
    onFunctionLog: (entry) => {},       // 함수 로그 콜백
    onRequest: (info) => {},            // 요청 시작 콜백
    onResponse: (info) => {},           // 응답 완료 콜백
  },

  // === 네트워크 로깅 ===
  networkLogging: {
    enableInboundHttpLogging: true,     // Inbound HTTP 로깅 (미들웨어 필요)
  },

  // === 에러 리포팅 ===
  errorReporting: {
    enabled: true,                      // SDK 내부 에러 리포팅
    debug: false,                       // 디버그 모드 (콘솔 출력)
  },

  // === 메타데이터 ===
  metadata: {
    service: 'my-app',
    environment: 'production',
  },

  // === 에러 핸들러 ===
  onError: (error) => {
    console.error('LogStream Error:', error);
  },
});

Function Logging 상세

FunctionLogEntry 구조

interface FunctionLogEntry {
  event: 'start' | 'end' | 'error';  // 이벤트 타입
  functionName: string;               // 함수 이름
  modulePath?: string;                // 모듈 경로
  traceId?: string;                   // 추적 ID
  args?: unknown[];                   // 함수 인자 (start)
  result?: unknown;                   // 반환값 (end)
  error?: string;                     // 에러 메시지 (error)
  duration?: number;                  // 실행 시간 (ms)
  timestamp: number;                  // 타임스탬프
}

민감 정보 자동 마스킹

// password, token, secret 등이 포함된 파라미터는 자동으로 마스킹됩니다
function login(email, password) {
  // ...
}

// 로그 출력: args: ["[email protected]", "[REDACTED]"]

TraceID 컨텍스트

// 미들웨어가 요청별 TraceID를 생성합니다
app.use(LogStream.middleware());

app.get('/api/users', async (req, res) => {
  // 현재 요청의 TraceID 조회
  const traceId = LogStream.getTraceId();

  // 커스텀 컨텍스트에서 실행
  LogStream.runWithContext({ traceId: 'custom-trace-id' }, () => {
    // 이 블록 내 모든 함수 로그는 'custom-trace-id'를 사용합니다
    doSomething();
  });
});

Performance Monitoring

LogStream은 자동으로 성능 메트릭을 수집합니다:

const stats = LogStream.getStats();
console.log(stats);

// {
//   bufferSize: 15,
//   isHealthy: true,
//   failureCount: 0,
//   metrics: {
//     timestamp: 1234567890,
//     platform: 'node',
//     cpu: { usage: 45.2, cores: 8 },
//     memory: {
//       used: 125829120,
//       total: 16777216000,
//       percentage: 0.75
//     },
//     network: {
//       requests: { total: 150, success: 148, failed: 2, pending: 0 },
//       traffic: { sent: 52480, received: 1048576 },
//       avgResponseTime: 245.6
//     }
//   }
// }

수집 메트릭

| Metric | Description | |--------|-------------| | CPU Usage | 프로세스 CPU 사용률 | | Memory Usage | 메모리 사용량/비율 | | Network In/Out | 송수신 트래픽 | | Request Success/Failure | HTTP 요청 성공/실패 | | Avg Response Time | 평균 응답 시간 |

API Reference

초기화

init(config: ExtendedLogStreamConfig): LogStream

SDK를 초기화합니다.

isInitialized(): boolean

SDK 초기화 여부를 확인합니다.

destroy(): void

SDK를 정리하고 원래 console 메서드를 복원합니다.

로깅

flush(): void

버퍼의 로그를 즉시 전송합니다.

getStats(): Stats | null

현재 버퍼 상태와 메트릭을 반환합니다.

로거 통합

winstonTransport(): WinstonTransport

Winston transport 인스턴스를 반환합니다.

pinoStream(): PinoStream

Pino stream 인스턴스를 반환합니다.

함수 로깅

middleware(): MiddlewareFunction

Express/Connect 호환 미들웨어를 반환합니다. 요청별 TraceID 생성 및 Inbound HTTP 로깅을 담당합니다.

getTraceId(): string | undefined

현재 컨텍스트의 TraceID를 반환합니다.

getContext(): FunctionLogContext | undefined

현재 컨텍스트를 반환합니다.

runWithContext<T>(context: FunctionLogContext, callback: () => T): T

지정된 컨텍스트 내에서 콜백을 실행합니다.

getFunctionLogs(limit?: number): FunctionLogEntry[]

최근 함수 로그를 반환합니다 (기본값: 100개).

clearFunctionLogs(): void

함수 로그 버퍼를 비웁니다.

isFunctionLoggingActive(): boolean

함수 로깅 활성화 여부를 확인합니다.

PM2 Support

PM2와 자동으로 호환됩니다. 로그에 PM2 메타데이터가 포함됩니다:

• pm2: boolean
• pm2_instance: 인스턴스 ID
• pid: 프로세스 ID

Error Handling

SDK는 애플리케이션 크래시를 유발하지 않도록 설계되었습니다:

• Circuit Breaker: 5회 연속 실패 시 자동 비활성화
• Auto Recovery: 30초 후 자동 재활성화
• Buffer Limits: 설정 가능한 최대 버퍼 크기로 메모리 오버플로우 방지
• Timeout Protection: 모든 네트워크 요청에 타임아웃 적용 (기본 5초)
• Graceful Degradation: SDK 실패 시에도 정상 로깅 유지

TypeScript

완전한 TypeScript 지원:

import LogStream, {
  ExtendedLogStreamConfig,
  FunctionLogEntry,
  FunctionLoggingConfig,
} from '@ologstream/sdk';

const config: ExtendedLogStreamConfig = {
  apiKey: 'YOUR_API_KEY',
  functionLogging: {
    enabled: true,
    onFunctionLog: (entry: FunctionLogEntry) => {
      console.log(entry.functionName, entry.duration);
    },
  },
};

LogStream.init(config);

Platform Requirements

• Node.js: >= 22.0.0
• Module System: CommonJS (CJS)

Build from Source

# 의존성 설치
pnpm install

# 빌드
pnpm run build

# 테스트
pnpm run test

# 정리
pnpm run clean

License

MIT

Support

이슈 및 질문: https://github.com/olivelabs/logstream-sdk