FastGPT/sdk/logger

@fastgpt-sdk/logger

FastGPT 的通用日志 SDK，基于 @logtape/logtape，内置：

• Console pretty log
• OpenTelemetry OTLP log sink
• AsyncLocalStorage 上下文透传
• 兼容 FastGPT 现有 getLogger(...).info('msg', {...}) 调用风格

安装

pnpm add @fastgpt-sdk/logger

快速开始

import { configureLogger, getLogger, withContext } from '@fastgpt-sdk/logger';

await configureLogger({
  defaultCategory: ['my-app'],
  console: {
    enabled: true,
    level: 'info'
  },
  otel: {
    enabled: true,
    serviceName: 'my-app',
    url: 'http://localhost:4318/v1/logs',
    level: 'info'
  },
  sensitiveProperties: ['password', 'token']
});

const logger = getLogger(['my-app', 'worker']);

await withContext({ requestId: 'req_123' }, async () => {
  logger.info('worker started', { jobId: 'job_001' });
});

API

configureLogger(options)

type LoggerConfigureOptions = {
  defaultCategory?: readonly string[];
  console?: boolean | { enabled?: boolean; level?: LogLevel };
  otel?: false | {
    enabled?: boolean;
    level?: LogLevel;
    serviceName: string;
    url?: string;
    loggerName?: string;
  };
  sensitiveProperties?: readonly string[];
  contextLocalStorage?: AsyncLocalStorage<Record<string, unknown>>;
  loggers?: Config['loggers'];
};

• defaultCategory: 默认 category，不传时默认 ['system']
• console: 控制台输出配置
• otel: OpenTelemetry 输出配置；启用时需要 serviceName
• sensitiveProperties: 命中这些字段的日志不会发往 OTEL sink
• contextLocalStorage: 可注入自己的上下文存储实例
• loggers: 可覆盖默认的 LogTape logger 路由配置

getLogger(category?)

const logger = getLogger(['app', 'api']);

logger.info('request completed', { status: 200 });
logger.error('request failed', { error });

category 不需要预注册；传任意字符串数组即可。

withContext(context, fn)

await withContext({ requestId: 'req_123' }, async () => {
  logger.info('handling request');
});

Env Helper

如果项目已经使用环境变量管理日志配置，也可以直接用 SDK 提供的转换助手：

import { configureLoggerFromEnv } from '@fastgpt-sdk/logger';

await configureLoggerFromEnv({
  env: process.env,
  defaultCategory: ['my-app'],
  defaultServiceName: 'my-app',
  sensitiveProperties: ['password', 'token']
});

支持读取这些环境变量：

• LOG_ENABLE_CONSOLE
• LOG_CONSOLE_LEVEL
• LOG_ENABLE_OTEL
• LOG_OTEL_LEVEL
• LOG_OTEL_SERVICE_NAME
• LOG_OTEL_URL

OpenTelemetry

启用 otel 后，SDK 会创建 OTLP HTTP log exporter。

await configureLogger({
  otel: {
    enabled: true,
    serviceName: 'my-app',
    loggerName: 'my-app',
    url: 'http://localhost:4318/v1/logs'
  }
});

也可以直接从 @fastgpt-sdk/logger 导入 getOpenTelemetrySink 进行更细粒度集成。

FastGPT 迁移建议

如果你在 FastGPT 仓库内部使用：

• 通用能力放到 sdk/logger
• 业务分类常量继续放在 service 侧
• service 侧保留一层 configureLoggerFromEnv 风格的兼容封装