Update @instrumented decorator and other type tweaks (#3)

* Tweak `instrumented` to take in meter name

* Type rename, export plus tsdoc updates

* Support passing of attributes for `instrument`

src/instruments/counter.ts

@@ -3,11 +3,16 @@ import { acquireMeter } from "../lib/meter";
 
 const counters: Record<string, Counter<Attributes>> = {};
 
-type OperationParams = {
+type CounterOperationParams = {
+  /** OTel meter name */
   meter: string;
+  /** Metric name being instrumented */
   name: string;
+  /** Value by which counter is incremented, defaults to 1 */
   inc?: number;
+  /** MetricOptions such as unit */
   counterOptions?: MetricOptions;
+  /** Metric Attributes in the form of key value pairs */
   counterAttributes?: Attributes;
 };
 
@@ -17,7 +22,7 @@ const incrementCounter = ({
   inc = 1,
   counterOptions,
   counterAttributes,
-}: OperationParams) => {
+}: CounterOperationParams) => {
   let counter = counters[name];
   if (counter === undefined) {
     const _otelMeter = acquireMeter(meter);
@@ -26,4 +31,4 @@ const incrementCounter = ({
   counter.add(inc, counterAttributes);
 };
 
-export { incrementCounter };
+export { incrementCounter, type CounterOperationParams };

src/instruments/gauge.ts

@@ -7,11 +7,16 @@ import { acquireMeter } from "../lib/meter";
 
 const gauges: Record<string, ObservableGauge<Attributes>> = {};
 
-type OperationParams = {
+type GaugeOperationParams = {
+  /** OTel meter name */
   meter: string;
+  /** Metric name being instrumented */
   name: string;
+  /** Non-additive value observed at a point in time */
   val: number;
+  /** MetricOptions such as unit */
   gaugeOptions?: MetricOptions;
+  /** Metric Attributes in the form of key value pairs */
   gaugeAttributes?: Attributes;
 };
 
@@ -21,7 +26,7 @@ const observeGauge = ({
   val,
   gaugeOptions,
   gaugeAttributes,
-}: OperationParams) => {
+}: GaugeOperationParams) => {
   let gauge = gauges[name];
   if (gauge === undefined) {
     const _otelMeter = acquireMeter(meter);
@@ -32,4 +37,4 @@ const observeGauge = ({
   });
 };
 
-export { observeGauge };
+export { observeGauge, type GaugeOperationParams };

src/instruments/histogram.ts

@@ -3,11 +3,16 @@ import { acquireMeter } from "../lib/meter";
 
 const histograms: Record<string, Histogram<Attributes>> = {};
 
-type OperationParams = {
+type HistogramOperationParams = {
+  /** OTel meter name */
   meter: string;
+  /** Metric name being instrumented */
   name: string;
+  /** Value to be recorded  */
   val: number;
+  /** MetricOptions such as unit */
   histogramOptions?: MetricOptions;
+  /** Metric Attributes in the form of key value pairs */
   histogramAttributes?: Attributes;
 };
 
@@ -17,7 +22,7 @@ const recordHistogram = ({
   val,
   histogramOptions,
   histogramAttributes,
-}: OperationParams) => {
+}: HistogramOperationParams) => {
   let histogram = histograms[name];
   if (histogram === undefined) {
     const _otelMeter = acquireMeter(meter);
@@ -29,4 +34,4 @@ const recordHistogram = ({
   histogram.record(val, histogramAttributes);
 };
 
-export { recordHistogram };
+export { recordHistogram, type HistogramOperationParams };

src/instruments/index.ts

@@ -1,5 +1,5 @@
-export { incrementCounter } from "./counter";
-export { observeGauge } from "./gauge";
-export { recordHistogram } from "./histogram";
-export { recordTimer } from "./timer";
-export { instrument, instrumented } from "./instrument";
+export * from "./counter";
+export * from "./gauge";
+export * from "./histogram";
+export * from "./timer";
+export * from "./instrument";

src/instruments/instrument.ts

@@ -1,13 +1,16 @@
+import type { Attributes } from "@opentelemetry/api";
 import { incrementCounter } from "./counter";
 import { recordTimer } from "./timer";
 
-type InstrumentParams = {
+type InstrumentOperationParams = {
   /** OTel meter name */
   meter: string;
   /** Function name being instrumented */
   name: string;
   /** Handle to execute the function */
   delegate: () => unknown;
+  /** Metric Attributes in the form of key value pairs  */
+  instrumentAttributes?: Attributes;
 };
 
 /**
@@ -16,15 +19,20 @@ type InstrumentParams = {
  * @param operationParams
  */
 
-async function instrument({ meter, name, delegate }: InstrumentParams) {
+async function instrument({
+  meter,
+  name,
+  delegate,
+  instrumentAttributes,
+}: InstrumentOperationParams) {
   const start = process.hrtime();
   try {
     return await delegate();
   } catch (err) {
     incrementCounter({
       meter,
       name: "function.errors",
-      counterAttributes: { function: name },
+      counterAttributes: { function: name, ...instrumentAttributes },
     });
     throw err;
   } finally {
@@ -34,44 +42,43 @@ async function instrument({ meter, name, delegate }: InstrumentParams) {
       meter,
       name: "function.executionTime",
       val: elapsedNanos,
-      timerAttributes: { function: name },
+      timerAttributes: { function: name, ...instrumentAttributes },
     });
   }
 }
 
 /**
  * Decorator that instruments a class method
+ *
+ * @param meter - Name of OTel meter
  */
-function instrumented(
-  meter: string,
-  target: any,
-  key: string,
-  descriptor?: PropertyDescriptor
-) {
-  if (descriptor === undefined) {
-    descriptor = Object.getOwnPropertyDescriptor(target, key);
-  }
-  if (descriptor === undefined) {
-    return descriptor;
-  }
+function instrumented(meter: string) {
+  return function (target: any, key: string, descriptor?: PropertyDescriptor) {
+    if (descriptor === undefined) {
+      descriptor = Object.getOwnPropertyDescriptor(target, key);
+    }
+    if (descriptor === undefined) {
+      return descriptor;
+    }
 
-  const originalMethod = descriptor.value;
-  const klass = target.constructor.name;
+    const originalMethod = descriptor.value;
+    const klass = target.constructor.name;
 
-  // this needs to be a non-arrow function or we'll get the wrong `this`
-  function overrideMethod(this: unknown, ...args: any[]) {
-    return instrument({
-      meter,
-      name: `${klass}.${key}`,
-      delegate: async () => {
-        return await originalMethod.apply(this, args);
-      },
-    });
-  }
+    // this needs to be a non-arrow function or we'll get the wrong `this`
+    function overrideMethod(this: unknown, ...args: any[]) {
+      return instrument({
+        meter,
+        name: `${klass}.${key}`,
+        delegate: async () => {
+          return await originalMethod.apply(this, args);
+        },
+      });
+    }
 
-  descriptor.value = overrideMethod;
+    descriptor.value = overrideMethod;
 
-  return descriptor;
+    return descriptor;
+  };
 }
 
-export { instrument, instrumented };
+export { instrument, instrumented, type InstrumentOperationParams };

src/instruments/timer.ts

@@ -3,11 +3,16 @@ import { acquireMeter } from "../lib/meter";
 
 const timers: Record<string, Histogram<Attributes>> = {};
 
-type OperationParams = {
+type TimerOperationParams = {
+  /** OTel meter name */
   meter: string;
+  /** Metric name being instrumented */
   name: string;
+  /** Timer value to be recorded */
   val: number;
+  /** MetricOptions such as unit */
   timerOptions?: MetricOptions;
+  /** Metric Attributes in the form of key value pairs */
   timerAttributes?: Attributes;
 };
 
@@ -17,7 +22,7 @@ const recordTimer = ({
   val,
   timerOptions,
   timerAttributes,
-}: OperationParams) => {
+}: TimerOperationParams) => {
   let timer = timers[name];
   if (timer === undefined) {
     const _otelMeter = acquireMeter(meter);
@@ -29,4 +34,4 @@ const recordTimer = ({
   timer.record(val, timerAttributes);
 };
 
-export { recordTimer };
+export { recordTimer, type TimerOperationParams };