@voltro/plugin-datadog 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,106 @@
+import { LogRecord } from '@voltro/logger';
+import { MetricSample } from '@voltro/runtime';
+import { VoltroPlugin } from '@voltro/protocol';
+
+export declare interface DatadogLog {
+    readonly message: string;
+    readonly status: string;
+    readonly ddsource: string;
+    readonly [attribute: string]: unknown;
+}
+
+export declare interface DatadogPayload {
+    readonly series: ReadonlyArray<DatadogSeries>;
+}
+
+export declare const datadogPlugin: (options?: DatadogPluginOptions) => VoltroPlugin;
+
+export declare interface DatadogPluginOptions {
+    /** Datadog API key. Default `DD_API_KEY` env. Needed for metrics + logs
+     *  (agentless). Traces use the Agent and don't need it. */
+    readonly apiKey?: string;
+    /** Datadog site host. Default `DD_SITE` env, else `datadoghq.com` (US1). */
+    readonly site?: string;
+    /** Metrics push interval in ms. Default 30000. */
+    readonly intervalMs?: number;
+    /** Prepended to every metric name (e.g. `voltro.`). */
+    readonly prefix?: string;
+    /** Tags added to every series + log (`["env:prod", "service:api"]`). */
+    readonly tags?: ReadonlyArray<string>;
+    /** Per-replica identity, emitted as the Datadog v2
+     *  `resources: [{ type: 'host', name }]` field on every pushed series.
+     *  Default `os.hostname()`. Without a per-replica value, N replicas
+     *  submitting the same metric+tags merge into ONE Datadog series and the
+     *  cumulative per-process counters interleave — `.as_count()`/`diff()`
+     *  rates go silently wrong. */
+    readonly host?: string;
+    /** Forward the framework log sink to Datadog logs intake. Default false. */
+    readonly logs?: boolean;
+    /** Logs flush interval in ms. Default 5000. */
+    readonly logsIntervalMs?: number;
+    /** Route the framework's OTel spans to the Datadog Agent's OTLP receiver.
+     *  Default false. */
+    readonly traces?: boolean;
+    /** Datadog Agent OTLP base url (`/v1/traces` is appended). Default
+     *  `DD_TRACE_AGENT_URL` env, else `http://localhost:4318`. */
+    readonly agentUrl?: string;
+    /** Continuous profiler via dd-trace (profiler-only mode). Default false. */
+    readonly profiling?: boolean;
+    /** `service` resource/tag (DD unified service tagging). Default `DD_SERVICE` env. */
+    readonly service?: string;
+    /** `env` resource/tag. Default `DD_ENV` env. */
+    readonly env?: string;
+    /** `version` resource/tag. Default `DD_VERSION` env. */
+    readonly version?: string;
+    /** Disambiguates multiple instances. */
+    readonly name?: string;
+}
+
+export declare interface DatadogPoint {
+    readonly timestamp: number;
+    readonly value: number;
+}
+
+/** Datadog v2 series resource — `{ type: 'host', name }` carries the
+ *  per-replica identity Datadog uses to keep same-name+tags series apart. */
+export declare interface DatadogResource {
+    readonly type: string;
+    readonly name: string;
+}
+
+export declare interface DatadogSeries {
+    readonly metric: string;
+    readonly type: 0 | 1 | 2 | 3;
+    readonly points: ReadonlyArray<DatadogPoint>;
+    readonly tags?: ReadonlyArray<string>;
+    readonly resources?: ReadonlyArray<DatadogResource>;
+}
+
+export declare const toDatadogLog: (r: LogRecord, opts?: ToLogsOptions) => DatadogLog;
+
+export declare const toDatadogLogs: (records: ReadonlyArray<LogRecord>, opts?: ToLogsOptions) => ReadonlyArray<DatadogLog>;
+
+export declare const toDatadogSeries: (samples: ReadonlyArray<MetricSample>, opts: ToSeriesOptions) => DatadogPayload;
+
+declare interface ToLogsOptions {
+    readonly service?: string;
+    /** Comma-joined into `ddtags`. */
+    readonly tags?: ReadonlyArray<string>;
+    readonly hostname?: string;
+}
+
+declare interface ToSeriesOptions {
+    /** Unix SECONDS for every point in this batch. */
+    readonly timestamp: number;
+    /** Prepended to every metric name (e.g. `voltro.`). Default none. */
+    readonly prefix?: string;
+    /** Tags added to every series. */
+    readonly globalTags?: ReadonlyArray<string>;
+    /** Per-replica identity, emitted as the v2 `resources: [{ type: 'host', name }]`
+     *  field on EVERY series. Without it, N replicas submitting the same
+     *  metric+tags merge into ONE Datadog series and the cumulative per-process
+     *  counters interleave into a meaningless sawtooth. */
+    readonly host?: string;
+}
+
+export { }

package/dist/index.js

@@ -0,0 +1,200 @@
+import { hostname as e } from "node:os";
+import { Effect as t } from "effect";
+import { pluginEnv as n } from "@voltro/env";
+import { addSink as r, createLogger as i, makeBufferedSink as a } from "@voltro/logger";
+import { definePlugin as o } from "@voltro/protocol";
+import { snapshotMetrics as s } from "@voltro/runtime";
+//#region src/format.ts
+var c = 3, l = (e) => Object.entries(e).map(([e, t]) => `${e}:${t}`), u = (e, t) => {
+	let n = t.prefix ?? "", r = t.globalTags ?? [], i = t.host === void 0 ? void 0 : [{
+		type: "host",
+		name: t.host
+	}], a = [], o = (e, o, s) => {
+		a.push({
+			metric: `${n}${e}`,
+			type: c,
+			points: [{
+				timestamp: t.timestamp,
+				value: o
+			}],
+			tags: [...r, ...s],
+			...i ? { resources: i } : {}
+		});
+	};
+	for (let t of e) {
+		let e = l(t.labels);
+		if (t.type === "counter" || t.type === "gauge") o(t.name, t.value ?? 0, e);
+		else if (t.type === "histogram") {
+			let n = t.count ?? 0, r = t.sum ?? 0;
+			o(`${t.name}.count`, n, e), o(`${t.name}.sum`, r, e), o(`${t.name}.avg`, n > 0 ? r / n : 0, e);
+		}
+	}
+	return { series: a };
+}, d = (e, t = 16) => {
+	let n = e.length > t ? e.slice(-t) : e;
+	try {
+		return BigInt(`0x${n}`).toString(10);
+	} catch {
+		return "";
+	}
+}, f = (e, t = {}) => {
+	let n = typeof e.fields.traceId == "string" ? e.fields.traceId : void 0, r = typeof e.fields.spanId == "string" ? e.fields.spanId : void 0, { traceId: i, spanId: a, ...o } = e.fields;
+	return {
+		message: e.message,
+		status: e.level,
+		ddsource: "voltro",
+		...t.service ? { service: t.service } : {},
+		...t.tags && t.tags.length > 0 ? { ddtags: t.tags.join(",") } : {},
+		...t.hostname ? { hostname: t.hostname } : {},
+		...e.scope ? { scope: e.scope } : {},
+		...o,
+		...n ? {
+			trace_id: n,
+			"dd.trace_id": d(n)
+		} : {},
+		...r ? { "dd.span_id": d(r) } : {}
+	};
+}, p = (e, t = {}) => e.map((e) => f(e, t)), m = n([
+	{
+		name: "DD_API_KEY",
+		required: !1,
+		secret: !0,
+		description: "Datadog API key for agentless metrics + logs intake; traces/profiling work without it."
+	},
+	{
+		name: "DD_SITE",
+		required: !1,
+		secret: !1,
+		description: "Datadog site host (e.g. datadoghq.com, datadoghq.eu); defaults to datadoghq.com."
+	},
+	{
+		name: "DD_SERVICE",
+		required: !1,
+		secret: !1,
+		description: "Unified service-tagging `service` resource/tag."
+	},
+	{
+		name: "DD_ENV",
+		required: !1,
+		secret: !1,
+		description: "Unified service-tagging `env` resource/tag."
+	},
+	{
+		name: "DD_VERSION",
+		required: !1,
+		secret: !1,
+		description: "Unified service-tagging `version` resource/tag."
+	},
+	{
+		name: "DD_TRACE_AGENT_URL",
+		required: !1,
+		secret: !1,
+		description: "Datadog Agent OTLP base URL for traces; defaults to http://localhost:4318."
+	}
+]), h = i({ scope: "plugin:datadog" }), g = (n = {}) => {
+	let i = m.read("DD_API_KEY", n.apiKey), c = m.read("DD_SITE", n.site) ?? "datadoghq.com", l = n.intervalMs ?? 3e4, d = n.logsIntervalMs ?? 5e3, f = m.read("DD_SERVICE", n.service), g = m.read("DD_ENV", n.env), _ = m.read("DD_VERSION", n.version), v = m.read("DD_TRACE_AGENT_URL", n.agentUrl) ?? "http://localhost:4318", y = n.host ?? e(), b = `https://api.${c}/api/v2/series`, x = `https://http-intake.logs.${c}/api/v2/logs`, S, C, w, T = async () => {
+		try {
+			let e = await t.runPromise(s);
+			if (e.length === 0) return;
+			let r = u(e, {
+				timestamp: Math.floor(Date.now() / 1e3),
+				host: y,
+				...n.prefix === void 0 ? {} : { prefix: n.prefix },
+				...n.tags === void 0 ? {} : { globalTags: n.tags }
+			}), a = await fetch(b, {
+				method: "POST",
+				headers: {
+					"content-type": "application/json",
+					"DD-API-KEY": i
+				},
+				body: JSON.stringify(r)
+			});
+			a.ok || h.warn("datadog series POST failed", {
+				status: a.status,
+				series: r.series.length
+			});
+		} catch (e) {
+			h.warn("datadog metrics flush errored", { error: String(e) });
+		}
+	}, E = async (e) => {
+		let t = p(e, {
+			...f ? { service: f } : {},
+			...n.tags ? { tags: n.tags } : {}
+		}), r = await fetch(x, {
+			method: "POST",
+			headers: {
+				"content-type": "application/json",
+				"DD-API-KEY": i
+			},
+			body: JSON.stringify(t)
+		});
+		r.ok || h.warn("datadog logs POST failed", {
+			status: r.status,
+			count: e.length
+		});
+	}, D = () => ({
+		...f ? { "service.name": f } : {},
+		...g ? { "deployment.environment": g } : {},
+		..._ ? { "service.version": _ } : {}
+	}), O = !!i, k = !!n.logs && !!i, A = (() => {
+		try {
+			return new URL(v).host;
+		} catch {
+			return "localhost";
+		}
+	})(), j = [`network:outbound:${c}`, ...n.traces || n.profiling ? [`network:outbound:${A}`] : []];
+	return o({
+		name: n.name ? `@voltro/plugin-datadog#${n.name}` : "@voltro/plugin-datadog",
+		description: "Deep Datadog integration — metrics + logs + traces (OTLP→Agent) + profiling, trace-correlated.",
+		permissions: j,
+		declaredEnv: m.declared,
+		contributeObservability: async (e) => {
+			if (n.profiling) try {
+				(await import("dd-trace")).default.init({
+					profiling: !0,
+					tracing: !1,
+					...f ? { service: f } : {},
+					...g ? { env: g } : {},
+					..._ ? { version: _ } : {}
+				});
+			} catch {
+				e.logger.warn("datadog profiling requested but dd-trace is not installed");
+			}
+			let t = D();
+			if (!n.traces) return Object.keys(t).length > 0 ? { resourceAttributes: t } : void 0;
+			try {
+				let { BatchSpanProcessor: n } = await import("@opentelemetry/sdk-trace-base"), { OTLPTraceExporter: r } = await import("@opentelemetry/exporter-trace-otlp-http"), i = new r({ url: `${v.replace(/\/$/, "")}/v1/traces` });
+				return e.logger.info("datadog traces → agent OTLP", { url: `${v}/v1/traces` }), {
+					spanProcessors: [new n(i)],
+					resourceAttributes: t
+				};
+			} catch {
+				return e.logger.warn("datadog traces requested but @opentelemetry/sdk-trace-base + @opentelemetry/exporter-trace-otlp-http are not installed — skipping span export"), Object.keys(t).length > 0 ? { resourceAttributes: t } : void 0;
+			}
+		},
+		onActivate: (e) => t.sync(() => {
+			if (O && (S = setInterval(() => void T(), l), typeof S.unref == "function" && S.unref()), k && (C = a({
+				intervalMs: d,
+				send: E,
+				maxBuffer: 5e3,
+				onError: (e) => h.warn("datadog logs flush errored", { error: String(e) })
+			}), w = r((e) => C?.push(e))), !O && !n.traces && !n.profiling) {
+				e.logger.warn("datadog inactive — no DD_API_KEY and no traces/profiling enabled");
+				return;
+			}
+			e.logger.info("datadog active", {
+				metrics: O,
+				logs: k,
+				traces: !!n.traces,
+				profiling: !!n.profiling,
+				service: f,
+				env: g
+			});
+		}),
+		onDeactivate: () => t.promise(async () => {
+			S && clearInterval(S), S = void 0, w?.(), w = void 0, await C?.dispose(), C = void 0;
+		})
+	});
+};
+//#endregion
+export { g as datadogPlugin, f as toDatadogLog, p as toDatadogLogs, u as toDatadogSeries };

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@voltro/plugin-datadog",
+  "version": "0.1.0",
+  "description": "Deep Datadog integration — agentless metrics push (unified Metrics-API → /api/v2/series) + opt-in log forwarding (dd.trace_id-correlated → /api/v2/logs) + traces (framework OTel spans → Datadog Agent OTLP) + the dd-trace continuous profiler, all correlated by the same trace id. Inert without DD_API_KEY.",
+  "keywords": [
+    "voltro",
+    "typescript",
+    "framework"
+  ],
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://voltro.dev",
+  "bugs": {
+    "email": "support@voltro.dev"
+  },
+  "author": {
+    "name": "Voltro UG",
+    "url": "https://voltro.dev"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "dependencies": {
+    "@voltro/env": "0.1.0",
+    "@voltro/logger": "0.1.0",
+    "@voltro/protocol": "0.1.0",
+    "@voltro/runtime": "0.1.0"
+  },
+  "optionalDependencies": {
+    "@opentelemetry/exporter-trace-otlp-http": "^0.220.0",
+    "@opentelemetry/sdk-trace-base": "^2.9.0",
+    "dd-trace": "^6.2.0"
+  },
+  "peerDependencies": {
+    "effect": "^3.21.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}