mm_metrics 0.0.0-stage → 1.0.1

package/README.md

@@ -1,3 +1,36 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# mm_metrics 指标采集模块
+
+进程内指标采集：提供 counter（计数器）、gauge（仪表盘）、histogram（直方图）三种基础指标类型，支持标签维度与快照导出。数据保存在内存中，可由 mm_monitor 等模块定期拉取上报。
+
+## 快速开始
+
+```javascript
+const { metricsAdmin } = require('mm_metrics');
+
+const metrics = metricsAdmin('os');
+
+// 计数器：请求总数（按路由维度）
+metrics.inc('http_requests_total', 1, { route: '/api/user', method: 'GET' });
+
+// 仪表盘：当前在线连接数
+metrics.gauge('ws_connections', 128);
+
+// 直方图：接口耗时观测（毫秒），默认桶 [10,50,100,500,1000,5000]
+metrics.observe('http_duration_ms', 87, { labels: { route: '/api/user' } });
+
+// 导出快照
+console.log(JSON.stringify(metrics.snapshot(), null, 2));
+```
+
+## API
+
+| 方法 | 说明 |
+| --- | --- |
+| `inc(name, value?, labels?)` | 计数器累加，value 缺省 1 且须非负 |
+| `gauge(name, value, labels?)` | 仪表盘设值，可增可减 |
+| `observe(name, value, { labels, buckets })` | 直方图观测，返回 `{ count, sum, max }` |
+| `snapshot()` | 导出全部指标（含标签与分桶明细） |
+| `reset()` | 清空全部指标 |
+
+`metricsAdmin(scope, config)` 按作用域缓存实例，相同 `scope` 返回同一实例。
+

package/index.js

@@ -0,0 +1,25 @@
+const { Metrics } = require('./lib/metrics.js');
+const Admin = require('mm_corejs').Admin;
+
+/**
+ * 指标管理 Admin 工厂
+ * 支持 os.js 调用：require('mm_metrics').admin.setServer(os) -> admin.get(scope, config)
+ */
+let admin = new Admin();
+admin.setClass(Metrics);
+
+/**
+ * 获取（或创建）指定作用域的指标实例
+ * @param {string} [scope] 作用域，缺省 'os'
+ * @param {Object} [config] 配置参数
+ * @returns {Metrics} 指标实例
+ */
+function metricsAdmin(scope, config) {
+  return admin.get(scope || 'os', config);
+}
+
+module.exports = {
+  Metrics,
+  admin,
+  metricsAdmin
+};

package/lib/metrics.js

@@ -0,0 +1,178 @@
+'use strict';
+
+const { Base } = require('mm_mod');
+
+/**
+ * 指标采集类
+ *
+ * 提供计数器（counter）、仪表盘（gauge）、直方图（histogram）三种基础指标类型，
+ * 支持标签维度与快照导出，数据保存在进程内存中，可由 mm_monitor 等模块定期拉取。
+ */
+class Metrics extends Base {
+  /**
+   * 模块默认配置
+   */
+  static config = {
+    name: 'metrics',
+    title: '指标采集模块',
+    description: '进程内指标采集：counter / gauge / histogram，支持标签与快照导出'
+  };
+
+  /**
+   * 指标注册表：name -> { type, help, values: Map<labelKey, value|state> }
+   * @type {Map<string, Object>}
+   */
+  #metrics = new Map();
+
+  /**
+   * 声明并获取（或创建）一个指标
+   * @param {string} type 指标类型：counter / gauge / histogram
+   * @param {string} name 指标名称
+   * @param {Object} [options] 选项：{ help, buckets }
+   * @returns {Object} 指标记录
+   * @throws {TypeError} 类型未知或与既有同名指标类型冲突时
+   */
+  #metric(type, name, options) {
+    if (!name || typeof name !== 'string') {
+      throw new TypeError(`${this._label()} metric name must be a non-empty string`);
+    }
+    let m = this.#metrics.get(name);
+    if (m) {
+      if (m.type !== type) {
+        throw new TypeError(`${this._label()} metric "${name}" already declared as ${m.type}, not ${type}`);
+      }
+      return m;
+    }
+    m = {
+      type,
+      help: (options && options.help) || '',
+      values: new Map(),
+      buckets: (options && options.buckets) || null
+    };
+    this.#metrics.set(name, m);
+    return m;
+  }
+
+  /**
+   * 标签序列化为映射键
+   * @param {Object} labels 标签对象
+   * @returns {string} 稳定的键
+   */
+  #labelKey(labels) {
+    if (!labels || typeof labels !== 'object') {
+      return '';
+    }
+    const keys = Object.keys(labels).sort();
+    return keys.map((k) => `${k}=${String(labels[k])}`).join(',');
+  }
+
+  /**
+   * 计数器累加（只增不减）
+   * @param {string} name 指标名称
+   * @param {number} [value] 增量，默认 1，须非负
+   * @param {Object} [labels] 标签对象
+   * @returns {number} 累加后的值
+   */
+  inc(name, value, labels) {
+    const step = value === undefined ? 1 : value;
+    if (typeof step !== 'number' || !Number.isFinite(step) || step < 0) {
+      throw new TypeError(`${this._label()} counter increment must be a non-negative finite number`);
+    }
+    const m = this.#metric('counter', name);
+    const key = this.#labelKey(labels);
+    const now = m.values.get(key) || 0;
+    m.values.set(key, now + step);
+    return now + step;
+  }
+
+  /**
+   * 仪表盘设值（可增可减）
+   * @param {string} name 指标名称
+   * @param {number} value 当前值
+   * @param {Object} [labels] 标签对象
+   * @returns {number} 设置后的值
+   */
+  gauge(name, value, labels) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+      throw new TypeError(`${this._label()} gauge value must be a finite number`);
+    }
+    const m = this.#metric('gauge', name);
+    m.values.set(this.#labelKey(labels), value);
+    return value;
+  }
+
+  /**
+   * 直方图观测：记录一个样本并更新分桶与统计量
+   * @param {string} name 指标名称
+   * @param {number} value 样本值
+   * @param {Object} [options] 选项：{ labels, buckets }（buckets 首次声明后固定，缺省为默认桶）
+   * @returns {Object} 观测后的统计量 { count, sum, max }
+   */
+  observe(name, value, options) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+      throw new TypeError(`${this._label()} histogram observation must be a finite number`);
+    }
+    const buckets = (options && options.buckets) || [10, 50, 100, 500, 1000, 5000];
+    const m = this.#metric('histogram', name, { buckets: buckets });
+    const labels = (options && options.labels) || null;
+    const key = this.#labelKey(labels);
+    let state = m.values.get(key);
+    if (!state) {
+      state = { count: 0, sum: 0, max: -Infinity, buckets: new Map() };
+      m.values.set(key, state);
+    }
+    state.count += 1;
+    state.sum += value;
+    if (value > state.max) {
+      state.max = value;
+    }
+    for (const bound of m.buckets) {
+      if (value <= bound) {
+        state.buckets.set(bound, (state.buckets.get(bound) || 0) + 1);
+      }
+    }
+    return { count: state.count, sum: state.sum, max: state.max };
+  }
+
+  /**
+   * 导出全部指标快照
+   * @returns {Array<Object>} 指标快照数组，每项含 name/type/help 与 values
+   */
+  snapshot() {
+    const out = [];
+    for (const [name, m] of this.#metrics) {
+      const values = [];
+      for (const [key, value] of m.values) {
+        const item = { labels: {}, value };
+        if (key) {
+          for (const pair of key.split(',')) {
+            const idx = pair.indexOf('=');
+            item.labels[pair.slice(0, idx)] = pair.slice(idx + 1);
+          }
+        }
+        if (m.type === 'histogram' && value && value.buckets) {
+          item.value = {
+            count: value.count,
+            sum: value.sum,
+            max: value.max === -Infinity ? null : value.max,
+            buckets: Object.fromEntries(value.buckets)
+          };
+        }
+        values.push(item);
+      }
+      out.push({ name, type: m.type, help: m.help, buckets: m.buckets, values });
+    }
+    return out;
+  }
+
+  /**
+   * 清空全部指标
+   * @returns {Metrics} 当前实例
+   */
+  reset() {
+    this.#metrics.clear();
+    return this;
+  }
+}
+
+module.exports = { Metrics };

package/package.json

@@ -1,6 +1,29 @@
 {
-  "name": "mm_metrics",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "mm_metrics",
+    "version": "1.0.1",
+    "description": "超级美眉指标采集模块：counter / gauge / histogram 进程内指标，支持标签与快照导出",
+    "main": "index.js",
+    "scripts": {
+        "test": "node test.js && node --test tests/metrics.test.js"
+    },
+    "keywords": [
+        "mm_mod",
+        "mm_infra",
+        "observability",
+        "metrics",
+        "counter",
+        "gauge",
+        "histogram"
+    ],
+    "layer": "infra",
+    "group": "observability",
+    "author": "邱文武",
+    "license": "MIT",
+    "dependencies": {
+        "mm_corejs": "^1.1.4",
+        "mm_mod": "^1.0.1"
+    },
+    "engines": {
+        "node": ">=18.0.0"
+    }
+}

package/test.js

@@ -0,0 +1,20 @@
+'use strict';
+const assert = require('assert');
+const mod = require('./index.js');
+
+assert.strictEqual(typeof mod.Metrics, 'function', '应导出 Metrics 类');
+assert.strictEqual(typeof mod.metricsAdmin, 'function', '应导出 metricsAdmin 函数');
+
+const m1 = mod.metricsAdmin('smoke');
+const m2 = mod.metricsAdmin('smoke');
+assert.strictEqual(m1, m2, '相同作用域应返回同一实例');
+assert.ok(m1 instanceof mod.Metrics, '应返回 Metrics 实例');
+
+m1.reset();
+m1.inc('requests_total');
+m1.gauge('active', 5);
+m1.observe('duration_ms', 42);
+const snap = m1.snapshot();
+assert.strictEqual(snap.length, 3, '快照应包含 3 个指标');
+
+console.log('mm_metrics 模块测试通过');

package/tests/metrics.test.js

@@ -0,0 +1,72 @@
+'use strict';
+/**
+ * mm_metrics 单元测试
+ */
+const test = require('node:test');
+const assert = require('assert');
+
+const { Metrics, metricsAdmin } = require('../index.js');
+
+test('计数器：累加、标签维度与参数校验', () => {
+  const m = new Metrics();
+  assert.strictEqual(m.inc('req'), 1);
+  assert.strictEqual(m.inc('req'), 2);
+  assert.strictEqual(m.inc('req', 5), 7);
+  assert.strictEqual(m.inc('req', 1, { route: '/a' }), 1, '不同标签独立计数');
+  assert.strictEqual(m.inc('req', 2, { route: '/a' }), 3);
+  assert.throws(() => m.inc('req', -1), TypeError, '负增量应拒绝');
+  assert.throws(() => m.inc('req', NaN), TypeError);
+  assert.throws(() => m.inc(''), TypeError);
+  // 同名指标类型冲突
+  assert.throws(() => m.gauge('req', 1), TypeError);
+});
+
+test('仪表盘：设值与读取', () => {
+  const m = new Metrics();
+  m.gauge('conns', 10);
+  m.gauge('conns', 8);
+  m.gauge('conns', 3, { region: 'cn' });
+  const snap = m.snapshot().find((x) => x.name === 'conns');
+  assert.strictEqual(snap.type, 'gauge');
+  const get = (labels) => snap.values.find((v) => JSON.stringify(v.labels) === JSON.stringify(labels || {})).value;
+  assert.strictEqual(get({}), 8, '同键重复设值应覆盖');
+  assert.strictEqual(get({ region: 'cn' }), 3);
+  assert.throws(() => m.gauge('x', 'abc'), TypeError);
+});
+
+test('直方图：分桶与统计量', () => {
+  const m = new Metrics();
+  for (const v of [5, 20, 80, 300, 2000]) {
+    m.observe('dur', v);
+  }
+  const snap = m.snapshot().find((x) => x.name === 'dur');
+  assert.strictEqual(snap.type, 'histogram');
+  const val = snap.values[0].value;
+  assert.strictEqual(val.count, 5);
+  assert.strictEqual(val.sum, 2405);
+  assert.strictEqual(val.max, 2000);
+  assert.strictEqual(val.buckets['10'], 1, '<=10 的样本 1 个');
+  assert.strictEqual(val.buckets['100'], 3, '<=100 的样本 3 个');
+  assert.strictEqual(val.buckets['5000'], 5);
+  // 自定义桶
+  m.observe('lat', 7, { buckets: [5, 10, 100] });
+  const lat = m.snapshot().find((x) => x.name === 'lat');
+  assert.deepStrictEqual(lat.buckets, [5, 10, 100]);
+});
+
+test('快照导出与 reset', () => {
+  const m = new Metrics();
+  m.inc('a');
+  m.gauge('b', 1);
+  m.observe('c', 1);
+  assert.strictEqual(m.snapshot().length, 3);
+  m.reset();
+  assert.strictEqual(m.snapshot().length, 0, 'reset 后应为空');
+});
+
+test('工厂函数按作用域共享实例', () => {
+  const a = metricsAdmin('ut-metrics');
+  const b = metricsAdmin('ut-metrics');
+  assert.strictEqual(a, b);
+  assert.notStrictEqual(metricsAdmin('ut-metrics-2'), a, '不同作用域应返回不同实例');
+});