feat(instrumentation-runtime-node): add prom-client-metrics

plugins/node/instrumentation-runtime-node/README.md

@@ -26,7 +26,7 @@ const prometheusExporter = new PrometheusExporter({
 const sdk = new NodeSDK({
   metricReader: prometheusExporter,
   instrumentations: [new RuntimeNodeInstrumentation({
-    eventLoopUtilizationMeasurementInterval: 5000,
+    monitoringPrecision: 5000,
   })],
 });
 
@@ -44,7 +44,7 @@ Go to [`localhost:9464/metrics`](http://localhost:9464/metrics), and you should
 nodejs_performance_event_loop_utilization 0.010140079547955264
 ```
 
-> Metrics will only be exported after it has collected two ELU readings (at least approximately `RuntimeNodeInstrumentationConfig.eventLoopUtilizationMeasurementInterval` milliseconds after initialization). Otherwise, you may see:
+> Metrics will only be exported after it has collected two ELU readings (at least approximately `RuntimeNodeInstrumentationConfig.monitoringPrecision` milliseconds after initialization). Otherwise, you may see:
 >
 > ```txt
 > # no registered metrics
@@ -56,7 +56,7 @@ nodejs_performance_event_loop_utilization 0.010140079547955264
 
 | name | type | unit | default | description |
 |---|---|---|---|---|
-| [`eventLoopUtilizationMeasurementInterval`](./src/types.ts#L25) | `int` | millisecond | `5000` | The approximate number of milliseconds for which to calculate event loop utilization averages. A larger value will result in more accurate averages at the expense of less granular data. Should be set to below the scrape interval of your metrics collector to avoid duplicated data points. |
+| [`monitoringPrecision`](./src/types.ts#L25) | `int` | millisecond | `5000` | The approximate number of milliseconds for which to calculate event loop utilization averages. A larger value will result in more accurate averages at the expense of less granular data. Should be set to below the scrape interval of your metrics collector to avoid duplicated data points. |
 
 ## Supported Node.js versions
 

plugins/node/instrumentation-runtime-node/src/consts/attributes.ts

@@ -0,0 +1,18 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export const NODE_JS_VERSION_ATTRIBUTE = 'nodejsruntime.version';
+export const V8_HEAP_SIZE_STATE_ATTRIBUTE = 'heap.size.state';
+export const V8_HEAP_SIZE = 'heap.size';

plugins/node/instrumentation-runtime-node/src/instrumentation.ts

@@ -13,83 +13,81 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { EventLoopUtilization, performance } from 'node:perf_hooks';
-const { eventLoopUtilization } = performance;
-
 import { InstrumentationBase } from '@opentelemetry/instrumentation';
 
 import { VERSION } from './version';
 import { RuntimeNodeInstrumentationConfig } from './types';
+import { MetricCollector } from './types/metricCollector';
+import { EventLoopUtilizationCollector } from './metrics/eventLoopUtilizationCollector';
+import { EventLoopDelayCollector } from './metrics/eventLoopDelayCollector';
+import { GCCollector } from './metrics/gcCollector';
+import { HeapSizeAndUsedCollector } from './metrics/heapSizeAndUsedCollector';
+import { HeapSpacesSizeAndUsedCollector } from './metrics/heapSpacesSizeAndUsedCollector';
+import { ConventionalNamePrefix } from './types/ConventionalNamePrefix';
 
-const ELUS_LENGTH = 2;
 const DEFAULT_CONFIG: RuntimeNodeInstrumentationConfig = {
-  eventLoopUtilizationMeasurementInterval: 5000,
+  monitoringPrecision: 5000,
 };
 
 export class RuntimeNodeInstrumentation extends InstrumentationBase {
-  private _ELUs: EventLoopUtilization[] = [];
-  private _interval: NodeJS.Timeout | undefined;
+  private _collectors: MetricCollector[] = [];
 
   constructor(config: RuntimeNodeInstrumentationConfig = {}) {
     super(
       '@opentelemetry/instrumentation-runtime-node',
       VERSION,
       Object.assign({}, DEFAULT_CONFIG, config)
     );
-  }
-
-  private _addELU() {
-    this._ELUs.unshift(eventLoopUtilization());
-    if (this._ELUs.length > ELUS_LENGTH) {
-      this._ELUs.pop();
-    }
-  }
-
-  private _clearELU() {
-    if (!this._ELUs) {
-      this._ELUs = [];
+    this._collectors = [
+      new EventLoopUtilizationCollector(
+        this._config,
+        ConventionalNamePrefix.NodeJsRuntime
+      ),
+      new EventLoopDelayCollector(
+        this._config,
+        ConventionalNamePrefix.NodeJsRuntime
+      ),
+      new GCCollector(this._config, ConventionalNamePrefix.V8EnjineRuntime),
+      new HeapSizeAndUsedCollector(
+        this._config,
+        ConventionalNamePrefix.V8EnjineRuntime
+      ),
+      new HeapSpacesSizeAndUsedCollector(
+        this._config,
+        ConventionalNamePrefix.V8EnjineRuntime
+      ),
+    ];
+    if (this._config.enabled) {
+      for (const collector of this._collectors) {
+        collector.enable();
+      }
     }
-    this._ELUs.length = 0;
   }
 
   // Called when a new `MeterProvider` is set
   // the Meter (result of @opentelemetry/api's getMeter) is available as this.meter within this method
   override _updateMetricInstruments() {
-    this.meter
-      .createObservableGauge('nodejs.event_loop.utilization', {
-        description: 'Event loop utilization',
-        unit: '1',
-      })
-      .addCallback(async observableResult => {
-        if (this._ELUs.length !== ELUS_LENGTH) {
-          return;
-        }
-        const elu = eventLoopUtilization(...this._ELUs);
-        observableResult.observe(elu.utilization);
-      });
+    if (!this._collectors) return;
+    for (const collector of this._collectors) {
+      collector.updateMetricInstruments(this.meter);
+    }
   }
 
   init() {
     // Not instrumenting or patching a Node.js module
   }
 
   override enable() {
-    this._clearELU();
-    this._addELU();
-    clearInterval(this._interval);
-    this._interval = setInterval(
-      () => this._addELU(),
-      (this._config as RuntimeNodeInstrumentationConfig)
-        .eventLoopUtilizationMeasurementInterval
-    );
+    if (!this._collectors) return;
 
-    // unref so that it does not keep the process running if disable() is never called
-    this._interval?.unref();
+    for (const collector of this._collectors) {
+      collector.enable();
+    }
   }
 
   override disable() {
-    this._clearELU();
-    clearInterval(this._interval);
-    this._interval = undefined;
+    for (const collector of this._collectors) {
+      collector.disable();
+    }
   }
 }

plugins/node/instrumentation-runtime-node/src/metrics/baseCollector.ts

@@ -0,0 +1,81 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { MetricCollector } from '../types/metricCollector';
+import { Meter } from '@opentelemetry/api';
+import { clearInterval } from 'node:timers';
+import { RuntimeNodeInstrumentationConfig } from '../types';
+import { NODE_JS_VERSION_ATTRIBUTE } from '../consts/attributes';
+
+type VersionAttribute = { [NODE_JS_VERSION_ATTRIBUTE]: string };
+
+export abstract class BaseCollector<T> implements MetricCollector {
+  protected _config: RuntimeNodeInstrumentationConfig = {};
+
+  protected namePrefix: string;
+  private _interval: NodeJS.Timeout | undefined;
+  protected _scrapeQueue: T[] = [];
+  protected versionAttribute: VersionAttribute;
+
+  protected constructor(
+    config: RuntimeNodeInstrumentationConfig = {},
+    namePrefix: string
+  ) {
+    this._config = config;
+    this.namePrefix = namePrefix;
+    this.versionAttribute = { [NODE_JS_VERSION_ATTRIBUTE]: process.version };
+  }
+
+  public disable(): void {
+    this._clearQueue();
+    clearInterval(this._interval);
+    this._interval = undefined;
+
+    this.internalDisable();
+  }
+
+  public enable(): void {
+    this._clearQueue();
+    clearInterval(this._interval);
+    this._interval = setInterval(
+      () => this._addTask(),
+      this._config.monitoringPrecision
+    );
+
+    // unref so that it does not keep the process running if disable() is never called
+    this._interval?.unref();
+
+    this.internalEnable();
+  }
+
+  private _clearQueue() {
+    this._scrapeQueue.length = 0;
+  }
+
+  private _addTask() {
+    const taskResult = this.scrape();
+    if (taskResult) {
+      this._scrapeQueue.push(taskResult);
+    }
+  }
+
+  public abstract updateMetricInstruments(meter: Meter): void;
+
+  protected abstract internalEnable(): void;
+
+  protected abstract internalDisable(): void;
+
+  protected abstract scrape(): T;
+}