npm package: @loongsuite/cms_logs
Description: ## 简介
Latest version: 1.0.0

# @loongsuite/cms_logs

## 简介

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

## 特性

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

## 安装

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

# 或使用 npm
npm install @loongsuite/cms_logs
```

## 当前功能

### 基础探测

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

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

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

## 主要导出

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

## 使用示例

### 基础用法

```typescript
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 集成

```typescript
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);
```

### 条件性日志处理

```typescript
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 设计

```typescript
// 未来可能的 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': 'user@example.com',
  '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 }
);
```

## 与追踪集成

### 当前集成方式

```typescript
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();
```

### 未来集成规划

```typescript
// 未来可能的集成方式
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. **状态监控**: 定期检查日志功能状态

```typescript
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 是否正确启动

### 调试技巧

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