perf_hooks: move metrics under perf_hooks

Author: Qard

doc/api/metrics.md

@@ -4,20 +4,20 @@
 
 > Stability: 1 - Experimental
 
-<!-- source_link=lib/metrics.js -->
+<!-- source_link=lib/internal/perf/metrics.js -->
 
-The `node:metrics` module provides an API for application instrumentation and
+The metrics API provides an API for application instrumentation and
 performance monitoring. It offers various metric types and built-in exporters
 for popular monitoring systems.
 
-The module can be accessed using:
+The metrics API can be accessed using:
 
 ```mjs
-import * as metrics from 'node:metrics';
+import { metrics } from 'node:perf_hooks';
 ```
 
 ```cjs
-const metrics = require('node:metrics');
+const { metrics } = require('node:perf_hooks');
 ```
 
 ## Overview
@@ -30,7 +30,8 @@ flexible consumption patterns.
 ### Example
 
 ```mjs
-import { counter } from 'node:metrics';
+import { metrics } from 'node:perf_hooks';
+const { counter } = metrics;
 
 // Create counter metrics
 const apiCalls = counter('api.calls', { service: 'web' });
@@ -49,7 +50,8 @@ function handleRequest(req, res) {
 ```
 
 ```cjs
-const { counter } = require('node:metrics');
+const { metrics } = require('node:perf_hooks');
+const { counter } = metrics;
 
 // Create counter metrics
 const apiCalls = counter('api.calls', { service: 'web' });
@@ -82,7 +84,8 @@ added: REPLACEME
 Creates a counter metric that tracks cumulative values.
 
 ```mjs
-import { counter } from 'node:metrics';
+import { metrics } from 'node:perf_hooks';
+const { counter } = metrics;
 
 const errorCount = counter('errors.total', { component: 'database' });
 
@@ -105,7 +108,8 @@ added: REPLACEME
 Creates a gauge metric that represents a single value at a point in time.
 
 ```mjs
-import { gauge } from 'node:metrics';
+import { metrics } from 'node:perf_hooks';
+const { gauge } = metrics;
 import { memoryUsage } from 'node:process';
 
 const memory = gauge('memory.usage.bytes');
@@ -128,7 +132,8 @@ added: REPLACEME
 Creates a gauge that samples a value on-demand by calling the provided function.
 
 ```mjs
-import { pullGauge } from 'node:metrics';
+import { metrics } from 'node:perf_hooks';
+const { pullGauge } = metrics;
 import { cpuUsage } from 'node:process';
 
 const cpu = pullGauge('cpu.usage', () => {
@@ -292,7 +297,8 @@ specific methods provided by each metric type (e.g., `increment`, `reset`,
 metadata.
 
 ```mjs
-import { gauge } from 'node:metrics';
+import { metrics } from 'node:perf_hooks';
+const { gauge } = metrics;
 
 const memoryUsage = gauge('memory.usage', { service: 'web' });
 
@@ -332,7 +338,8 @@ added: REPLACEME
 Increments the counter by the specified amount.
 
 ```mjs
-import { counter } from 'node:metrics';
+import { metrics } from 'node:perf_hooks';
+const { counter } = metrics;
 
 const apiCalls = counter('api.calls', { service: 'web' });
 
@@ -354,7 +361,8 @@ added: REPLACEME
 Decrements the counter by the specified amount.
 
 ```mjs
-import { counter } from 'node:metrics';
+import { metrics } from 'node:perf_hooks';
+const { counter } = metrics;
 
 const errorCount = counter('errors.total', { component: 'database' });
 
@@ -376,7 +384,8 @@ added: REPLACEME
 Creates a timer that will increment this counter with its duration when stopped.
 
 ```mjs
-import { counter } from 'node:metrics';
+import { metrics } from 'node:perf_hooks';
+const { counter } = metrics;
 
 const requestDuration = counter('request.duration.ms');
 
@@ -417,7 +426,8 @@ added: REPLACEME
 Sets the gauge to a specific value and reports it.
 
 ```mjs
-import { gauge } from 'node:metrics';
+import { metrics } from 'node:perf_hooks';
+const { gauge } = metrics;
 import { memoryUsage } from 'node:process';
 
 const memory = gauge('memory.usage.bytes');
@@ -439,7 +449,8 @@ added: REPLACEME
 Creates a timer that will set this gauge to its duration when stopped.
 
 ```mjs
-import { gauge } from 'node:metrics';
+import { metrics } from 'node:perf_hooks';
+const { gauge } = metrics;
 
 const responseTime = gauge('response.time.ms');
 
@@ -497,7 +508,8 @@ added: REPLACEME
 Stops the timer and reports the duration. Can only be called once.
 
 ```mjs
-import { counter } from 'node:metrics';
+import { metrics } from 'node:perf_hooks';
+const { counter } = metrics;
 
 const dbQueryDuration = counter('db.query.duration');
 
@@ -518,7 +530,8 @@ added: REPLACEME
 Allows `using` syntax to automatically stop the timer when done.
 
 ```mjs
-import { counter } from 'node:metrics';
+import { metrics } from 'node:perf_hooks';
+const { counter } = metrics;
 
 const dbQueryDuration = counter('db.query.duration');
 
@@ -553,7 +566,8 @@ added: REPLACEME
 Calls the configured function to get the current value and reports it.
 
 ```mjs
-import { pullGauge } from 'node:metrics';
+import { metrics } from 'node:perf_hooks';
+const { pullGauge } = metrics;
 import { cpuUsage } from 'node:process';
 
 const cpu = pullGauge('cpu.usage', () => {

lib/metrics.js lib/internal/perf/metrics.jslib/metrics.js renamed to lib/internal/perf/metrics.js

@@ -39,7 +39,7 @@ const {
   subscribe,
   unsubscribe,
 } = require('diagnostics_channel');
-const { performance } = require('perf_hooks');
+const { performance } = require('internal/perf/performance');
 
 const newMetricChannel = channel('metrics:new');
 

lib/perf_hooks.js

@@ -29,6 +29,8 @@ const {
 
 const monitorEventLoopDelay = require('internal/perf/event_loop_delay');
 
+const metrics = require('internal/perf/metrics');
+
 module.exports = {
   Performance,
   PerformanceEntry,
@@ -40,6 +42,7 @@ module.exports = {
   monitorEventLoopDelay,
   createHistogram,
   performance,
+  metrics,
 };
 
 ObjectDefineProperty(module.exports, 'constants', {

test/parallel/test-metrics-counter.js

@@ -4,7 +4,8 @@ const common = require('../common');
 
 const assert = require('assert');
 const { subscribe } = require('node:diagnostics_channel');
-const { counter, Counter, Metric, MetricReport } = require('node:metrics');
+const { metrics } = require('node:perf_hooks');
+const { counter, Counter, Metric, MetricReport } = metrics;
 
 const testCounter = counter('test', { base: 'test' });
 assert.ok(testCounter instanceof Counter);

test/parallel/test-metrics-gauge.js

@@ -4,7 +4,8 @@ const common = require('../common');
 
 const assert = require('assert');
 const { subscribe } = require('node:diagnostics_channel');
-const { gauge, Gauge, Metric, MetricReport } = require('node:metrics');
+const { metrics } = require('node:perf_hooks');
+const { gauge, Gauge, Metric, MetricReport } = metrics;
 
 const testGauge = gauge('test', { base: 'test' });
 assert.ok(testGauge instanceof Gauge);

test/parallel/test-metrics-metric-report.js

@@ -3,7 +3,8 @@
 require('../common');
 
 const assert = require('assert');
-const { MetricReport } = require('node:metrics');
+const { metrics } = require('node:perf_hooks');
+const { MetricReport } = metrics;
 
 const report = new MetricReport('counter', 'test-counter', 123, {
   meta: 'test'

test/parallel/test-metrics-metric.js

@@ -4,7 +4,8 @@ const common = require('../common');
 
 const assert = require('assert');
 const { subscribe } = require('node:diagnostics_channel');
-const { Metric, MetricReport } = require('node:metrics');
+const { metrics } = require('node:perf_hooks');
+const { Metric, MetricReport } = metrics;
 
 const metric = new Metric('counter', 'test-counter', { base: 'test' });
 

test/parallel/test-metrics-pull-gauge.js

@@ -0,0 +1,61 @@
+'use strict';
+
+const common = require('../common');
+
+const assert = require('assert');
+const { subscribe } = require('node:diagnostics_channel');
+const { metrics } = require('node:perf_hooks');
+const { pullGauge, PullGauge, Metric, MetricReport } = metrics;
+
+// Test values to return from the pull function
+const values = [ 1, 5, 10, 4, 6 ];
+let currentIndex = 0;
+
+const testPullGauge = pullGauge('test', () => {
+  return values[currentIndex];
+}, { base: 'test' });
+
+assert.ok(testPullGauge instanceof PullGauge);
+assert.ok(testPullGauge instanceof Metric);
+assert.strictEqual(testPullGauge.value, 0);
+
+assert.strictEqual(testPullGauge.type, 'pullGauge');
+assert.strictEqual(testPullGauge.name, 'test');
+assert.deepStrictEqual(testPullGauge.meta, { base: 'test' });
+assert.strictEqual(testPullGauge.channelName, 'metrics:pullGauge:test');
+
+// Subscribe to metric reports
+let reportCount = 0;
+subscribe(testPullGauge.channelName, common.mustCall((report) => {
+  assert.ok(report instanceof MetricReport);
+  assert.strictEqual(report.type, 'pullGauge');
+  assert.strictEqual(report.name, 'test');
+  assert.ok(report.time > 0);
+  assert.strictEqual(report.value, values[reportCount]);
+  
+  if (reportCount < values.length - 1) {
+    assert.deepStrictEqual(report.meta, { base: 'test' });
+  } else {
+    // Last sample includes additional metadata
+    assert.deepStrictEqual(report.meta, { base: 'test', extra: 'metadata' });
+  }
+  
+  reportCount++;
+}, values.length));
+
+// Test sampling
+for (let i = 0; i < values.length; i++) {
+  currentIndex = i;
+  
+  if (i === values.length - 1) {
+    // Test sampling with additional metadata
+    const value = testPullGauge.sample({ extra: 'metadata' });
+    assert.strictEqual(value, values[i]);
+  } else {
+    const value = testPullGauge.sample();
+    assert.strictEqual(value, values[i]);
+  }
+}
+
+// Verify all reports were received
+assert.strictEqual(reportCount, values.length);

test/parallel/test-metrics-timer-readonly.js

@@ -0,0 +1,51 @@
+'use strict';
+
+const common = require('../common');
+const assert = require('assert');
+const { metrics } = require('node:perf_hooks');
+const { Timer } = metrics;
+
+// Test that Timer properties are read-only
+const timer = new Timer(() => {});
+
+// Verify initial values
+assert.ok(typeof timer.start === 'number');
+assert.ok(timer.start > 0);
+assert.strictEqual(timer.end, undefined);
+assert.strictEqual(timer.duration, undefined);
+
+// Try to modify properties (should throw)
+const originalStart = timer.start;
+assert.throws(() => {
+  timer.start = 0;
+}, TypeError);
+assert.strictEqual(timer.start, originalStart); // Should remain unchanged
+
+assert.throws(() => {
+  timer.end = 123;
+}, TypeError);
+assert.strictEqual(timer.end, undefined); // Should remain undefined
+
+assert.throws(() => {
+  timer.duration = 456;
+}, TypeError);
+assert.strictEqual(timer.duration, undefined); // Should remain undefined
+
+// Stop the timer and verify values are still read-only
+timer.stop();
+assert.ok(typeof timer.end === 'number');
+assert.ok(typeof timer.duration === 'number');
+assert.ok(timer.end > timer.start);
+assert.ok(timer.duration > 0);
+
+// Try to modify after stopping (should throw)
+const stoppedEnd = timer.end;
+const stoppedDuration = timer.duration;
+assert.throws(() => {
+  timer.end = 0;
+}, TypeError);
+assert.throws(() => {
+  timer.duration = 0;
+}, TypeError);
+assert.strictEqual(timer.end, stoppedEnd);
+assert.strictEqual(timer.duration, stoppedDuration);