npm package: @ologstream/sdk
Description: Universal log streaming SDK for Node.js
Author: OliveLabs
Latest version: 0.2.2

# 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

```bash
npm install @ologstream/sdk
```

## Quick Start

### 기본 사용법

```javascript
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');
```

### 함수 로깅 (자동 계측)

```javascript
// 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` : '');
    },
  },
});
```

실행:
```bash
node -r ./register.js ./app.js
```

### Express 미들웨어

```javascript
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

```javascript
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

```javascript
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

```typescript
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 구조

```typescript
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;                  // 타임스탬프
}
```

### 민감 정보 자동 마스킹

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

// 로그 출력: args: ["user@example.com", "[REDACTED]"]
```

### TraceID 컨텍스트

```javascript
// 미들웨어가 요청별 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은 자동으로 성능 메트릭을 수집합니다:

```javascript
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 지원:

```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

```bash
# 의존성 설치
pnpm install

# 빌드
pnpm run build

# 테스트
pnpm run test

# 정리
pnpm run clean
```

## License

MIT

## Support

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