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

# @loongsuite/cms_core

## 简介

CMS Core 是 CMS 可观测性 SDK 的核心基础包，提供所有其他包依赖的基础类型、接口、常量和工具函数。它是整个 SDK 架构的基石，定义了追踪、上下文、传播等核心概念。

## 特性

- 🏗️ **基础架构**: 提供核心接口和抽象类
- 📝 **类型定义**: 完整的 TypeScript 类型定义
- 🔧 **工具函数**: 常用的工具函数和辅助方法
- 📊 **资源模型**: 统一的资源表示和管理
- ⏰ **时间处理**: 高精度时间戳和时钟抽象
- 🏷️ **语义约定**: OpenTelemetry 语义约定常量

## 安装

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

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

## 核心概念

### 资源 (Resource)

资源表示生成遥测数据的实体，如服务、主机、进程等。

```typescript
import { resourceFromAttributes, ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from '@loongsuite/cms_core';

const resource = resourceFromAttributes({
  [ATTR_SERVICE_NAME]: 'my-service',
  [ATTR_SERVICE_VERSION]: '1.0.0',
  'host.name': 'server-01',
  'host.arch': 'x86_64',
  'os.type': 'linux',
});

console.log(resource.attributes);
// {
//   'service.name': 'my-service',
//   'service.version': '1.0.0',
//   'host.name': 'server-01',
//   'host.arch': 'x86_64',
//   'os.type': 'linux'
// }
```

### 上下文管理 (Context)

上下文管理器负责在异步调用中传递上下文信息。

```typescript
import { IContextManager, Context } from '@loongsuite/cms_core';

// 获取当前上下文
const contextManager: IContextManager = /* ... */;
const currentContext = contextManager.active();

// 在指定上下文中执行代码
contextManager.with(newContext, () => {
  // 在此作用域内，上下文为新上下文
  const activeContext = contextManager.active();
  // activeContext === newContext
});
```

### 传播器 (Propagator)

传播器负责在服务间传播上下文信息。

```typescript
import { TextMapPropagator, Carrier } from '@loongsuite/cms_core';

const propagator: TextMapPropagator = /* ... */;
const context: Context = /* ... */;

// 注入上下文到载体
const carrier: Carrier = {};
propagator.inject(context, carrier);

// 从载体提取上下文
const extractedContext = propagator.extract(context, carrier);
```

## 主要导出

### 资源相关

```typescript
import {
  Resource,
  resourceFromAttributes,
  defaultResource,
  mergeResources
} from '@loongsuite/cms_core';

// 创建资源
const resource1 = resourceFromAttributes({
  'service.name': 'service-a',
  'service.version': '1.0.0'
});

const resource2 = resourceFromAttributes({
  'host.name': 'host-01',
  'host.arch': 'x86_64'
});

// 合并资源
const mergedResource = mergeResources([resource1, resource2]);
```

### 常量定义

```typescript
import {
  ATTR_SERVICE_NAME,
  ATTR_SERVICE_VERSION,
  ATTR_SERVICE_INSTANCE_ID,
  ATTR_HOST_NAME,
  ATTR_HOST_ARCH,
  ATTR_OS_TYPE,
  ATTR_OS_VERSION,
  SPAN_KIND_SERVER,
  SPAN_KIND_CLIENT,
  SPAN_KIND_INTERNAL,
  SPAN_KIND_PRODUCER,
  SPAN_KIND_CONSUMER
} from '@loongsuite/cms_core';
```

### 时间处理

```typescript
import { 
  HrTime, 
  hrTimeToMicroseconds, 
  hrTimeToMilliseconds,
  hrTimeToNanoseconds,
  timeInputToHrTime 
} from '@loongsuite/cms_core';

// 获取当前高精度时间
const now: HrTime = timeInputToHrTime(Date.now());

// 时间转换
const microseconds = hrTimeToMicroseconds(now);
const milliseconds = hrTimeToMilliseconds(now);
const nanoseconds = hrTimeToNanoseconds(now);
```

### 工具函数

```typescript
import {
  isValidSpanId,
  isValidTraceId,
  generateSpanId,
  generateTraceId,
  isSpanContextValid,
  createTraceState
} from '@loongsuite/cms_core';

// 验证 ID 格式
const isValidId = isValidSpanId('1234567890abcdef');
const isValidTrace = isValidTraceId('1234567890abcdef1234567890abcdef');

// 生成 ID
const spanId = generateSpanId();
const traceId = generateTraceId();

// 验证 Span 上下文
const spanContext = {
  traceId: '1234567890abcdef1234567890abcdef',
  spanId: '1234567890abcdef',
  traceFlags: 1
};
const isValid = isSpanContextValid(spanContext);
```

## 接口定义

### 核心接口

```typescript
// 上下文管理器接口
interface IContextManager {
  active(): Context;
  with<T>(context: Context, fn: () => T): T;
  bind<T>(context: Context, target: T): T;
}

// 传播器接口
interface TextMapPropagator {
  inject(context: Context, carrier: Carrier): void;
  extract(context: Context, carrier: Carrier): Context;
  fields(): string[];
}

// 追踪器管理器接口
interface BaseTracerManager {
  getTracer(name: string, version?: string): Tracer;
  shutdown(): Promise<void>;
}

// 采样器接口
interface Sampler {
  shouldSample(
    context: Context,
    traceId: string,
    spanName: string,
    spanKind: SpanKind,
    attributes: Attributes,
    links: Link[]
  ): SamplingResult;
}
```

## 使用示例

### 完整的资源配置

```typescript
import { 
  resourceFromAttributes, 
  defaultResource,
  ATTR_SERVICE_NAME,
  ATTR_SERVICE_VERSION,
  ATTR_SERVICE_INSTANCE_ID 
} from '@loongsuite/cms_core';

// 创建服务资源
const serviceResource = resourceFromAttributes({
  [ATTR_SERVICE_NAME]: 'user-service',
  [ATTR_SERVICE_VERSION]: '2.1.0',
  [ATTR_SERVICE_INSTANCE_ID]: 'user-service-01',
  'service.namespace': 'production',
  'deployment.environment': 'prod'
});

// 合并默认资源
const finalResource = mergeResources([defaultResource, serviceResource]);
```

### 上下文传播示例

```typescript
import { Context, Carrier } from '@loongsuite/cms_core';

// 模拟 HTTP 请求头
const headers: Carrier = {
  'traceparent': '00-1234567890abcdef1234567890abcdef-1234567890abcdef-01',
  'tracestate': 'vendor=value'
};

// 提取上下文
const propagator = /* ... */;
const extractedContext = propagator.extract(contextManager.active(), headers);

// 在提取的上下文中执行业务逻辑
contextManager.with(extractedContext, () => {
  // 业务逻辑
  console.log('Executing in extracted context');
});
```

## 依赖

- `import-in-the-middle`: 模块导入拦截
- `require-in-the-middle`: 模块加载拦截

## 许可证

MIT License