@loongsuite/cms_logs

简介

CMS Logs 是 CMS 可观测性 SDK 的日志能力包。目前提供基础的日志功能探测，为未来的日志管线实现预留接口。这是可观测性三大支柱（追踪、指标、日志）中日志部分的实现基础。

特性

• 📝 日志基础: 提供日志功能的基础接口
• 🔍 可用性探测: 检测日志功能是否可用
• 🚀 未来扩展: 为完整的日志管线实现预留接口
• 🔧 类型安全: 完整的 TypeScript 类型支持
• 📊 标准化: 遵循 OpenTelemetry 日志规范

安装

# 使用 anpm (推荐)
anpm add @loongsuite/cms_logs

# 或使用 npm
npm install @loongsuite/cms_logs

当前功能

基础探测

目前主要提供日志功能的可用性检测：

import { info } from '@loongsuite/cms_logs';

// 检测日志功能是否可用
const status = info();
console.log(status); // 输出: 'cms_logs ready'

主要导出

import {
  info,
  // 未来可能添加的导出
  Logger,
  LogRecord,
  LogRecordProcessor,
  LogExporter
} from '@loongsuite/cms_logs';

使用示例

基础用法

import { info } from '@loongsuite/cms_logs';

// 检查日志功能状态
const logStatus = info();
console.log('Log functionality status:', logStatus);

// 在应用启动时检查
if (logStatus === 'cms_logs ready') {
  console.log('Logging system is ready');
} else {
  console.warn('Logging system is not available');
}

与 NodeSDK 集成

import { NodeSDK } from '@loongsuite/cms_node_sdk';
import { info } from '@loongsuite/cms_logs';

const sdk = new NodeSDK({
  serviceName: 'my-service'
});

// 启动前检查日志功能
const logStatus = info();
console.log('Log status before SDK start:', logStatus);

sdk.start();

// 启动后再次检查
const postStartStatus = info();
console.log('Log status after SDK start:', postStartStatus);

条件性日志处理

import { info } from '@loongsuite/cms_logs';

class ApplicationLogger {
  private isLoggingAvailable: boolean;

  constructor() {
    this.isLoggingAvailable = info() === 'cms_logs ready';
  }

  log(level: string, message: string, attributes?: Record<string, any>) {
    if (this.isLoggingAvailable) {
      // 使用 CMS 日志系统
      this.logWithCMS(level, message, attributes);
    } else {
      // 降级到控制台输出
      console.log(`[${level}] ${message}`, attributes);
    }
  }

  private logWithCMS(level: string, message: string, attributes?: Record<string, any>) {
    // 未来实现 CMS 日志记录
    console.log(`[CMS-${level}] ${message}`, attributes);
  }
}

// 使用示例
const logger = new ApplicationLogger();
logger.log('INFO', 'Application started', { version: '1.0.0' });
logger.log('ERROR', 'Database connection failed', { error: 'timeout' });

未来规划

计划中的功能

1. Logger 接口: 提供标准化的日志记录接口
2. LogRecord: 结构化的日志记录对象
3. LogProcessor: 日志处理管道
4. LogExporter: 日志导出器（控制台、OTLP 等）
5. 自动关联: 与追踪数据的自动关联

预期 API 设计

// 未来可能的 API 设计
import { 
  Logger, 
  LogRecord, 
  BatchLogProcessor,
  ConsoleLogExporter 
} from '@loongsuite/cms_logs';

// 创建日志记录器
const logger = new Logger('my-service', '1.0.0');

// 记录日志
logger.info('User login successful', {
  'user.id': '12345',
  'user.email': '[email protected]',
  'login.method': 'password'
});

logger.error('Database connection failed', {
  'db.host': 'localhost',
  'db.port': 5432,
  'error.message': 'Connection timeout'
});

// 配置日志处理器
const logProcessor = new BatchLogProcessor(
  new ConsoleLogExporter(),
  { scheduledDelayMillis: 1000 }
);

与追踪集成

当前集成方式

import { info } from '@loongsuite/cms_logs';
import { NodeSDK } from '@loongsuite/cms_node_sdk';

const sdk = new NodeSDK({
  serviceName: 'my-service'
});

sdk.start();

// 在追踪上下文中记录日志状态
const tracer = sdk.getTracerManager().getTracer('my-service');
const span = tracer.startSpan('log-check');

span.setAttributes({
  'log.status': info(),
  'log.available': info() === 'cms_logs ready'
});

span.end();

未来集成规划

// 未来可能的集成方式
import { Logger } from '@loongsuite/cms_logs';
import { NodeSDK } from '@loongsuite/cms_node_sdk';

const sdk = new NodeSDK({
  serviceName: 'my-service'
});

sdk.start();

// 自动关联追踪上下文
const logger = new Logger('my-service', '1.0.0');

// 日志会自动包含当前 span 信息
logger.info('Processing request', {
  'http.method': 'GET',
  'http.url': '/api/users'
});

最佳实践

当前最佳实践

1. 启动时检查: 在应用启动时检查日志功能可用性
2. 降级处理: 提供日志功能不可用时的降级方案
3. 状态监控: 定期检查日志功能状态

import { info } from '@loongsuite/cms_logs';

class LoggingMonitor {
  private checkInterval: NodeJS.Timeout;

  start() {
    // 定期检查日志功能状态
    this.checkInterval = setInterval(() => {
      const status = info();
      if (status !== 'cms_logs ready') {
        console.warn('Logging system status changed:', status);
      }
    }, 30000); // 每30秒检查一次
  }

  stop() {
    if (this.checkInterval) {
      clearInterval(this.checkInterval);
    }
  }
}

未来最佳实践

1. 结构化日志: 使用结构化的日志格式
2. 日志级别: 合理使用不同的日志级别
3. 性能考虑: 避免在高频路径中记录过多日志

故障排除

常见问题

1. 功能不可用: 检查是否正确安装和导入
2. 状态异常: 检查 NodeSDK 是否正确启动

调试技巧

import { info } from '@loongsuite/cms_logs';

// 详细的状态检查
function checkLoggingStatus() {
  const status = info();
  console.log('Logging status check:', {
    status,
    timestamp: new Date().toISOString(),
    nodeVersion: process.version,
    environment: process.env.NODE_ENV
  });
  
  return status === 'cms_logs ready';
}

// 在关键点检查状态
checkLoggingStatus();

依赖

• @loongsuite/cms_core: 核心类型和接口定义（未来可能）

许可证

MIT License