@loongsuite/cms_core

简介

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

特性

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

安装

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

# 或使用 npm
npm install @loongsuite/cms_core

核心概念

资源 (Resource)

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

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)

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

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

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

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

传播器 (Propagator)

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

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

主要导出

资源相关

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]);

常量定义

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';

时间处理

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

工具函数

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

接口定义

核心接口

// 上下文管理器接口
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;
}

使用示例

完整的资源配置

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]);

上下文传播示例

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