@loglayer/mixin-datadog-http-metrics 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Theo Gravity
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,62 @@
+# Datadog Metrics (HTTP) mixin for LogLayer
+
+[![NPM Version](https://img.shields.io/npm/v/%40loglayer%2Fmixin-datadog-http-metrics)](https://www.npmjs.com/package/@loglayer/mixin-datadog-http-metrics)
+[![NPM Downloads](https://img.shields.io/npm/dm/%40loglayer%2Fmixin-datadog-http-metrics)](https://www.npmjs.com/package/@loglayer/mixin-datadog-http-metrics)
+[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)
+
+Adds Datadog metrics functionality to the [LogLayer](https://loglayer.dev) logging library using [datadog-metrics](https://github.com/dbader/node-datadog-metrics).
+
+The mixin provides a fluent builder API for sending metrics to Datadog via HTTP through a `ddStats` property on LogLayer instances. Unlike the [hot-shots mixin](https://www.npmjs.com/package/@loglayer/mixin-hot-shots) which sends metrics via StatsD/UDP, this mixin sends metrics directly to Datadog's HTTP API.
+
+## Installation
+
+```bash
+npm install loglayer @loglayer/mixin-datadog-http-metrics
+```
+
+```bash
+yarn add loglayer @loglayer/mixin-datadog-http-metrics
+```
+
+```bash
+pnpm add loglayer @loglayer/mixin-datadog-http-metrics
+```
+
+## Usage
+
+```typescript
+import { LogLayer, useLogLayerMixin, ConsoleTransport } from 'loglayer';
+import { datadogMetricsMixin } from '@loglayer/mixin-datadog-http-metrics';
+
+// Register the mixin (must be called before creating LogLayer instances)
+useLogLayerMixin(datadogMetricsMixin({
+  apiKey: process.env.DATADOG_API_KEY,
+  site: process.env.DATADOG_SITE, // e.g. 'us5.datadoghq.com'
+  prefix: 'myapp.',
+  defaultTags: ['env:production'],
+}));
+
+// Create LogLayer instance
+const log = new LogLayer({
+  transport: new ConsoleTransport({
+    logger: console
+  })
+});
+
+// Use Datadog metrics through the ddStats property
+log.ddStats.increment('request.count').send();
+log.ddStats.gauge('queue.size', 42).send();
+log.ddStats.histogram('response.time', 250).send();
+log.ddStats.distribution('latency', 100).send();
+
+// Use builder pattern for advanced configuration
+log.ddStats.increment('request.count')
+  .withValue(5)
+  .withTags(['env:production', 'service:api'])
+  .withTimestamp(Date.now())
+  .send();
+```
+
+## Documentation
+
+For more details, visit [https://loglayer.dev/mixins/datadog-http-metrics](https://loglayer.dev/mixins/datadog-http-metrics).

package/dist/index.cjs

@@ -0,0 +1,526 @@
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") {
+		for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+			key = keys[i];
+			if (!__hasOwnProp.call(to, key) && key !== except) {
+				__defProp(to, key, {
+					get: ((k) => from[k]).bind(null, key),
+					enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+				});
+			}
+		}
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+let datadog_metrics = require("datadog-metrics");
+datadog_metrics = __toESM(datadog_metrics);
+let loglayer = require("loglayer");
+
+//#region src/client.ts
+let metricsClient = null;
+/**
+* Set the datadog-metrics client for the mixin.
+* Called during mixin registration.
+*
+* @param client - The BufferedMetricsLogger instance
+*/
+function setMetricsClient(client) {
+	metricsClient = client;
+}
+/**
+* Check if the client is null (no-op mode)
+*
+* @returns True if the client is null, false otherwise
+*/
+function isNoOpClient() {
+	return metricsClient === null;
+}
+/**
+* Get the datadog-metrics client.
+* Returns the configured client or null if not configured.
+*
+* @returns The BufferedMetricsLogger instance or null
+*/
+function getMetricsClient() {
+	return metricsClient;
+}
+
+//#endregion
+//#region src/CommonMetricsBuilder.ts
+/**
+* Base class for common metrics builder functionality.
+* Provides shared methods for configuring tags and timestamp.
+*/
+var CommonMetricsBuilder = class {
+	/** Tags to attach to the metric */
+	tags;
+	/** Timestamp in milliseconds since epoch */
+	timestamp;
+	/** The datadog-metrics client instance */
+	client;
+	/**
+	* Creates a new CommonMetricsBuilder instance.
+	*
+	* @param client - The datadog-metrics BufferedMetricsLogger instance
+	*/
+	constructor(client) {
+		this.client = client;
+	}
+	/**
+	* Add tags to the metric.
+	*
+	* @param tags - Tags as an array of strings (e.g., ['env:prod', 'service:api'])
+	* @returns The builder instance for method chaining
+	*/
+	withTags(tags) {
+		this.tags = tags;
+		return this;
+	}
+	/**
+	* Set the timestamp for the metric.
+	*
+	* @param timestamp - Timestamp in milliseconds since epoch
+	* @returns The builder instance for method chaining
+	*/
+	withTimestamp(timestamp) {
+		this.timestamp = timestamp;
+		return this;
+	}
+};
+
+//#endregion
+//#region src/builders/DistributionBuilder.ts
+/**
+* Builder for the distribution method.
+* Supports chaining with withTags() and withTimestamp().
+*/
+var DistributionBuilder = class extends CommonMetricsBuilder {
+	/** The metric key */
+	key;
+	/** The distribution value */
+	value;
+	/**
+	* Creates a new DistributionBuilder instance.
+	*
+	* @param client - The datadog-metrics BufferedMetricsLogger instance
+	* @param key - The metric key to record
+	* @param value - The distribution value to record
+	*/
+	constructor(client, key, value) {
+		super(client);
+		this.key = key;
+		this.value = value;
+	}
+	/**
+	* Send the distribution metric with the configured options.
+	*/
+	send() {
+		this.client.distribution(this.key, this.value, this.tags, this.timestamp);
+	}
+};
+
+//#endregion
+//#region src/builders/GaugeBuilder.ts
+/**
+* Builder for the gauge method.
+* Supports chaining with withTags() and withTimestamp().
+*/
+var GaugeBuilder = class extends CommonMetricsBuilder {
+	/** The metric key */
+	key;
+	/** The gauge value */
+	value;
+	/**
+	* Creates a new GaugeBuilder instance.
+	*
+	* @param client - The datadog-metrics BufferedMetricsLogger instance
+	* @param key - The metric key to set
+	* @param value - The value to set the gauge to
+	*/
+	constructor(client, key, value) {
+		super(client);
+		this.key = key;
+		this.value = value;
+	}
+	/**
+	* Send the gauge metric with the configured options.
+	*/
+	send() {
+		this.client.gauge(this.key, this.value, this.tags, this.timestamp);
+	}
+};
+
+//#endregion
+//#region src/builders/HistogramBuilder.ts
+/**
+* Builder for the histogram method.
+* Supports chaining with withTags(), withTimestamp(), and withHistogramOptions().
+*/
+var HistogramBuilder = class extends CommonMetricsBuilder {
+	/** The metric key */
+	key;
+	/** The histogram value */
+	value;
+	/** Optional histogram-specific options */
+	histogramOptions;
+	/**
+	* Creates a new HistogramBuilder instance.
+	*
+	* @param client - The datadog-metrics BufferedMetricsLogger instance
+	* @param key - The metric key to record
+	* @param value - The histogram value to record
+	*/
+	constructor(client, key, value) {
+		super(client);
+		this.key = key;
+		this.value = value;
+	}
+	/**
+	* Set histogram-specific options for aggregation and percentiles.
+	*
+	* @param options - Histogram options with aggregates and/or percentiles
+	* @returns The builder instance for method chaining
+	*/
+	withHistogramOptions(options) {
+		this.histogramOptions = options;
+		return this;
+	}
+	/**
+	* Send the histogram metric with the configured options.
+	*/
+	send() {
+		this.client.histogram(this.key, this.value, this.tags, this.timestamp, this.histogramOptions);
+	}
+};
+
+//#endregion
+//#region src/builders/IncrementBuilder.ts
+/**
+* Builder for the increment method.
+* Supports chaining with withValue(), withTags(), and withTimestamp().
+*/
+var IncrementBuilder = class extends CommonMetricsBuilder {
+	/** The metric key */
+	key;
+	/** The increment value (optional, defaults to 1) */
+	value;
+	/**
+	* Creates a new IncrementBuilder instance.
+	*
+	* @param client - The datadog-metrics BufferedMetricsLogger instance
+	* @param key - The metric key to increment
+	*/
+	constructor(client, key) {
+		super(client);
+		this.key = key;
+	}
+	/**
+	* Set the increment value.
+	*
+	* @param value - The value to increment by (defaults to 1 if not specified)
+	* @returns The builder instance for method chaining
+	*/
+	withValue(value) {
+		this.value = value;
+		return this;
+	}
+	/**
+	* Send the increment metric with the configured options.
+	*/
+	send() {
+		this.client.increment(this.key, this.value, this.tags, this.timestamp);
+	}
+};
+
+//#endregion
+//#region src/MetricsAPI.ts
+/**
+* Metrics API implementation that wraps datadog-metrics BufferedMetricsLogger.
+* Provides a fluent interface for sending metrics to Datadog via HTTP.
+*/
+var MetricsAPI = class {
+	/**
+	* Creates a new MetricsAPI instance.
+	*
+	* @param client - The datadog-metrics BufferedMetricsLogger instance
+	*/
+	constructor(client) {
+		this.client = client;
+	}
+	/**
+	* Increment a counter metric.
+	* Returns a builder that supports chaining with withValue(), withTags(), and withTimestamp().
+	*
+	* @param key - The metric key to increment
+	* @returns A builder instance for chaining additional options
+	*/
+	increment(key) {
+		return new IncrementBuilder(this.client, key);
+	}
+	/**
+	* Set a gauge metric to a specific value.
+	* Returns a builder that supports chaining with withTags() and withTimestamp().
+	*
+	* @param key - The metric key to set
+	* @param value - The value to set the gauge to
+	* @returns A builder instance for chaining additional options
+	*/
+	gauge(key, value) {
+		return new GaugeBuilder(this.client, key, value);
+	}
+	/**
+	* Record a histogram value.
+	* Returns a builder that supports chaining with withTags(), withTimestamp(), and withHistogramOptions().
+	*
+	* @param key - The metric key to record
+	* @param value - The histogram value to record
+	* @returns A builder instance for chaining additional options
+	*/
+	histogram(key, value) {
+		return new HistogramBuilder(this.client, key, value);
+	}
+	/**
+	* Record a distribution value (server-side calculated).
+	* Returns a builder that supports chaining with withTags() and withTimestamp().
+	*
+	* @param key - The metric key to record
+	* @param value - The distribution value to record
+	* @returns A builder instance for chaining additional options
+	*/
+	distribution(key, value) {
+		return new DistributionBuilder(this.client, key, value);
+	}
+	/**
+	* Flush all buffered metrics to Datadog immediately.
+	*
+	* @returns A promise that resolves when the flush completes
+	*/
+	flush() {
+		return this.client.flush();
+	}
+	/**
+	* Start auto-flushing metrics at the configured interval.
+	*/
+	start() {
+		this.client.start();
+	}
+	/**
+	* Stop auto-flushing and optionally flush remaining metrics.
+	*
+	* @param options - Options for stopping. `flush` defaults to true.
+	* @returns A promise that resolves when stopping completes
+	*/
+	stop(options) {
+		return this.client.stop(options);
+	}
+	/**
+	* Get the underlying BufferedMetricsLogger instance.
+	*
+	* @returns The BufferedMetricsLogger instance
+	*/
+	getClient() {
+		return this.client;
+	}
+};
+
+//#endregion
+//#region src/MockMetricsAPI.ts
+/**
+* Base class for mock metrics builders.
+* Provides no-op implementations of common builder methods.
+*/
+var MockCommonMetricsBuilder = class {
+	withTags(_tags) {
+		return this;
+	}
+	withTimestamp(_timestamp) {
+		return this;
+	}
+	send() {}
+};
+/**
+* Mock implementation of IncrementBuilder.
+* Does nothing when methods are called.
+*/
+var MockIncrementBuilder = class extends MockCommonMetricsBuilder {
+	constructor(_key) {
+		super();
+	}
+	withValue(_value) {
+		return this;
+	}
+};
+/**
+* Mock implementation of GaugeBuilder.
+* Does nothing when methods are called.
+*/
+var MockGaugeBuilder = class extends MockCommonMetricsBuilder {
+	constructor(_key, _value) {
+		super();
+	}
+};
+/**
+* Mock implementation of HistogramBuilder.
+* Does nothing when methods are called.
+*/
+var MockHistogramBuilder = class extends MockCommonMetricsBuilder {
+	constructor(_key, _value) {
+		super();
+	}
+	withHistogramOptions(_options) {
+		return this;
+	}
+};
+/**
+* Mock implementation of DistributionBuilder.
+* Does nothing when methods are called.
+*/
+var MockDistributionBuilder = class extends MockCommonMetricsBuilder {
+	constructor(_key, _value) {
+		super();
+	}
+};
+/**
+* No-op implementation of IMetricsAPI.
+* All methods return mock builder instances that do nothing when send() is called.
+* This is used when datadogMetricsMixin(null) is called, allowing the metrics API
+* to be used without actually sending any metrics.
+*/
+var MockMetricsAPI = class {
+	increment(key) {
+		return new MockIncrementBuilder(key);
+	}
+	gauge(key, value) {
+		return new MockGaugeBuilder(key, value);
+	}
+	histogram(key, value) {
+		return new MockHistogramBuilder(key, value);
+	}
+	distribution(key, value) {
+		return new MockDistributionBuilder(key, value);
+	}
+	flush() {
+		return Promise.resolve();
+	}
+	start() {}
+	stop(_options) {
+		return Promise.resolve();
+	}
+	getClient() {
+		return {
+			gauge: () => {},
+			increment: () => {},
+			histogram: () => {},
+			distribution: () => {},
+			flush: () => Promise.resolve(),
+			start: () => {},
+			stop: () => Promise.resolve()
+		};
+	}
+};
+
+//#endregion
+//#region src/LogLayer.augment.ts
+/**
+* LogLayer mixin that adds a `ddStats` property to LogLayer instances.
+* Provides access to the MetricsAPI for sending metrics to Datadog via HTTP.
+*/
+const logLayerDatadogMetricsMixin = {
+	augmentationType: loglayer.LogLayerMixinAugmentType.LogLayer,
+	augment: (prototype) => {
+		Object.defineProperty(prototype, "ddStats", {
+			get() {
+				if (!this._ddMetricsAPI) {
+					const client = getMetricsClient();
+					this._ddMetricsAPI = isNoOpClient() || !client ? new MockMetricsAPI() : new MetricsAPI(client);
+				}
+				return this._ddMetricsAPI;
+			},
+			enumerable: true,
+			configurable: true
+		});
+	},
+	augmentMock: (prototype) => {
+		Object.defineProperty(prototype, "ddStats", {
+			get() {
+				if (!this._ddMetricsAPI) {
+					const client = getMetricsClient();
+					this._ddMetricsAPI = isNoOpClient() || !client ? new MockMetricsAPI() : new MetricsAPI(client);
+				}
+				return this._ddMetricsAPI;
+			},
+			enumerable: true,
+			configurable: true
+		});
+	}
+};
+
+//#endregion
+//#region src/index.ts
+const BufferedMetricsLogger = datadog_metrics.default.BufferedMetricsLogger;
+/**
+* A reporter that discards all metrics. Useful for testing or temporarily
+* disabling metric submission without using the `enabled` flag.
+* Re-exported from the `datadog-metrics` library.
+*/
+const NullReporter = datadog_metrics.default.reporters.NullReporter;
+/**
+* The default reporter that sends metrics to Datadog's HTTP API with automatic retries.
+* Re-exported from the `datadog-metrics` library.
+*/
+const DatadogReporter = datadog_metrics.default.reporters.DatadogReporter;
+/**
+* Register the datadog-metrics mixin with LogLayer.
+* This adds a `ddStats` property to LogLayer instances,
+* providing a fluent API for sending metrics to Datadog via HTTP.
+*
+* @param options - The BufferedMetricsLogger configuration options, or null for no-op mode.
+*   Set `enabled: false` to use no-op mode while still passing options.
+* @returns A LogLayer mixin registration object
+*
+* @example
+* ```typescript
+* import { useLogLayerMixin } from 'loglayer';
+* import { datadogMetricsMixin } from '@loglayer/mixin-datadog-http-metrics';
+*
+* useLogLayerMixin(datadogMetricsMixin({
+*   apiKey: 'your-api-key',
+*   prefix: 'myapp.',
+*   enabled: process.env.NODE_ENV === 'production',
+* }));
+* ```
+*/
+function datadogMetricsMixin(options) {
+	if (options && options.enabled !== false) {
+		const { enabled: _, ...metricsOptions } = options;
+		setMetricsClient(new datadog_metrics.default.BufferedMetricsLogger({
+			flushIntervalSeconds: 5,
+			...metricsOptions
+		}));
+	} else setMetricsClient(null);
+	return {
+		mixinsToAdd: [logLayerDatadogMetricsMixin],
+		pluginsToAdd: []
+	};
+}
+
+//#endregion
+exports.BufferedMetricsLogger = BufferedMetricsLogger;
+exports.DatadogReporter = DatadogReporter;
+exports.MetricsAPI = MetricsAPI;
+exports.MockMetricsAPI = MockMetricsAPI;
+exports.NullReporter = NullReporter;
+exports.datadogMetricsMixin = datadogMetricsMixin;