Why Metrics Matter: A Deep Dive into Pandora.js’s Measurement System

Since Qin Shi Huang unified the six states and standardized weights and measures, the world has had a single system of measurement; similarly, in the programming world, despite diverse languages, we still need a unified way to measure code health.

Metrics Role

Many wonder why we need metrics. The answer is simple: metrics are like health check reports—without them you cannot know if something is wrong.

Monitoring and alerting are concrete applications of metrics, but metrics also help answer questions such as:

When you deploy an application, how do you know it is healthy?

When you release a new feature, how do you assess its impact?

When you upgrade a package version, how do you know it is stable?

All of this is captured by metrics.

Pandora.js’s metric system follows Spring‑Boot naming conventions, incorporates Alibaba’s Alimetrics, and adopts the OpenTracing tracing model to form a complete, inspectable, measurable, and traceable solution.

Metric Naming

Metric names aim to be self‑descriptive, using business context whenever possible. Pandora.js uses a MetricName object composed of a key and tags .

Metrics is the plural form; in code a single measurement is called a Metric, while the plural term Metrics is still used for the concept.

The key identifies the metric, e.g., application.http.request.path. Companies can further refine the key with underscores and lowercase letters.

The tags are a JSON object that, together with the key, uniquely identifies a metric, e.g., {"source":"shanghai"} or {"source":"hangzhou"}. Tags can be extended indefinitely without affecting the key.

External Data Format

Metrics are output as JSON for easy consumption. A typical metric object looks like:

{
  "metric": "sys.cpu.nice",
  "timestamp": 1346846400,
  "value": 18,
  "type": "COUNTER",
  "level": "CRITICAL",
  "tags": {
    "host": "web01",
    "dc": "lga"
  }
}

This format is emitted by the built‑in reporter to files, HTTP endpoints, etc., where external systems can store, compute, and visualize the data.

Metrics Types

Beyond naming, Pandora.js defines four basic metric types:

Gauge – instantaneous values.

Counter – cumulative counts.

Histogram – distribution measurements.

Meter – rate measurements.

Gauge and Counter cover about 80% of scenarios.

Instantaneous Metrics (Gauge)

A Gauge implements a single getValue method that returns the current numeric value, such as CPU usage.

class BaseGauge {
  getValue() {
    const startUsage = process.cpuUsage();
    return startUsage.user;
  }
}

All metrics ultimately output numeric values; string outputs use a different system.

Accumulative Metrics (Counter)

Counters record monotonically increasing values, like total request counts.

Pandora.js provides a basic BaseCounter and a BucketCounter that splits counts into time buckets.

// Obtain a BucketCounter from MetricsClient
let counter = new BucketCounter();
app.use(async (ctx, next) => {
  // Increment the counter
  counter.inc();
  await next();
});

Distribution Metrics (Histogram)

Histograms capture statistical distributions, useful for response time percentiles and Apdex calculations.

Current implementation only supports single‑node distribution.

Histograms rely on a Reservoir to store samples; Pandora.js implements Uniform and Exponentially Decaying reservoirs.

let histogram = new BaseHistogram(ReservoirType.UNIFORM, 1, 2);
app.use(async (ctx, next) => {
  histogram.update(10);
  histogram.update(20);
  await next();
});

Rate Metrics (Meter)

Meters measure throughput over time, providing 1‑minute, 5‑minute, and 15‑minute EWMA rates similar to Linux load averages.

EWMA(t) = EWMA(t-1) + alpha * (instantRate - EWMA(t-1))

Alpha (0–1) controls how quickly older data decays.

// Obtain a BaseMeter from MetricsClient
let meter = new BaseMeter();
router.get('/home', async ctx => {
  // Record a hit
  meter.mark(1);
});

Conclusion

The above only scratches the surface of Pandora.js’s metric system, which combines Alibaba’s internal metrics with industry practices to provide basic measurement capabilities for business code.

Data collection and processing will be covered in the next article.

Pandora.js project: https://github.com/midwayjs/pandora – feel free to star it!