autotel 7.3.0 → 7.5.0

package/README.md

@@ -1836,6 +1836,23 @@ WHERE duration_ms > 200
 
 ### Configuration Options
 
+To keep canonical lines in a platform logger and send the same records to
+Grafana Loki over OTLP, enable both destinations. Selecting `otel: true`
+auto-configures log export from `endpoint`; an explicit `logs: false` or
+`AUTOTEL_LOGS=off` still wins.
+
+```typescript
+init({
+  service: 'my-app',
+  endpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT,
+  canonicalLogLines: {
+    enabled: true,
+    logger: [pino(), auditLogger],
+    otel: true,
+  },
+});
+```
+
 ```typescript
 init({
   service: 'my-app',

package/dist/auto.cjs

@@ -1,5 +1,5 @@
 const require_rolldown_runtime = require('./rolldown-runtime-C_NdSu1c.cjs');
-const require_init = require('./init-DmM7dprX.cjs');
+const require_init = require('./init-CNUkdwke.cjs');
 let node_module = require("node:module");
 node_module = require_rolldown_runtime.__toESM(node_module, 1);
 let import_in_the_middle = require("import-in-the-middle");

package/dist/auto.js

@@ -1,4 +1,4 @@
-import { _ as loadYamlConfig, a as init } from "./init-CsKK9vZO.js";
+import { _ as loadYamlConfig, a as init } from "./init-B2kv4bLO.js";
 import * as nodeModule from "node:module";
 import { createAddHookMessageChannel } from "import-in-the-middle";
 

package/dist/{canonical-log-line-processor-DolzdawH.cjs → canonical-log-line-processor-B-tzezhk.cjs}

@@ -233,7 +233,8 @@ const SEVERITY_NUMBERS = /* @__PURE__ */ new Map([
 * ```
 */
 var CanonicalLogLineProcessor = class {
-	logger;
+	loggers;
+	useOtel;
 	rootSpansOnly;
 	minLevel;
 	messageFormat;
@@ -245,7 +246,8 @@ var CanonicalLogLineProcessor = class {
 	pretty;
 	getOTelLogger = null;
 	constructor(options = {}) {
-		this.logger = options.logger;
+		this.loggers = options.logger ? Array.isArray(options.logger) ? options.logger.filter(Boolean) : [options.logger] : [];
+		this.useOtel = options.otel ?? this.loggers.length === 0;
 		this.rootSpansOnly = options.rootSpansOnly ?? false;
 		this.minLevel = options.minLevel ?? "info";
 		this.messageFormat = options.messageFormat ?? ((span) => `[${span.name}] Request completed`);
@@ -255,7 +257,7 @@ var CanonicalLogLineProcessor = class {
 		this.drain = options.drain;
 		this.onDrainError = options.onDrainError;
 		this.pretty = options.pretty ?? (require_values.hasProcess() && process.env.NODE_ENV === "development");
-		if (!this.logger) this.getOTelLogger = () => _opentelemetry_api_logs.logs.getLogger("autotel.canonical-log-line");
+		if (this.useOtel) this.getOTelLogger = () => _opentelemetry_api_logs.logs.getLogger("autotel.canonical-log-line");
 	}
 	buildKeepPredicate(keep) {
 		if (!keep || keep.length === 0) return void 0;
@@ -287,10 +289,12 @@ var CanonicalLogLineProcessor = class {
 		};
 		if (this.shouldEmit && !this.shouldEmit(eventContext)) return;
 		if (this.pretty) console.log(formatPrettyLogLine(eventContext));
-		if (this.logger) this.emitViaLogger(level, message, canonicalLogLine);
-		else if (this.getOTelLogger) {
+		if (this.loggers.length > 0) this.emitViaLogger(level, message, canonicalLogLine);
+		if (this.getOTelLogger) try {
 			const otelLogger = this.getOTelLogger();
 			this.emitViaOTel(level, message, canonicalLogLine, otelLogger);
+		} catch (error) {
+			this.reportInternalWarning("canonical log line OTel emission failed", error);
 		}
 		if (this.drain) Promise.resolve(this.drain(eventContext)).catch((error) => {
 			if (this.onDrainError) {
@@ -328,7 +332,11 @@ var CanonicalLogLineProcessor = class {
 		return redacted;
 	}
 	emitViaLogger(level, message, canonicalLogLine) {
-		this.logger[level](canonicalLogLine, message);
+		for (const logger of this.loggers) try {
+			logger[level](canonicalLogLine, message);
+		} catch (error) {
+			this.reportInternalWarning("canonical log line logger emission failed", error);
+		}
 	}
 	emitViaOTel(level, message, canonicalLogLine, otelLogger) {
 		const otelAttributes = {};
@@ -364,11 +372,17 @@ var CanonicalLogLineProcessor = class {
 	}
 	reportInternalWarning(message, cause) {
 		const err = cause === void 0 ? "unknown error" : require_values.toError(cause).message;
-		if (this.logger) {
-			this.logger.warn({ error: err }, `[autotel] ${message}`);
-			return;
+		if (this.loggers.length > 0) {
+			let reported = false;
+			for (const logger of this.loggers) try {
+				logger.warn({ error: err }, `[autotel] ${message}`);
+				reported = true;
+			} catch {}
+			if (reported) return;
 		}
-		console.warn(`[autotel] ${message}: ${err}`);
+		try {
+			console.warn(`[autotel] ${message}: ${err}`);
+		} catch {}
 	}
 	async forceFlush() {}
 	async shutdown() {}

package/dist/{canonical-log-line-processor-l0Aqe6yp.d.cts → canonical-log-line-processor-C0Z_N4oL.d.cts}

@@ -22,8 +22,21 @@ interface KeepCondition {
   path?: string;
 }
 interface CanonicalLogLineOptions {
-  /** Logger to use for emitting canonical log lines (defaults to OTel Logs API) */
-  logger?: Logger;
+  /**
+   * Logger(s) to emit canonical log lines through. Pass an array to fan out to
+   * several. When omitted, lines go to the OTel Logs API instead.
+   */
+  logger?: Logger | Logger[];
+  /**
+   * Also emit through the OTel Logs API (and so to an OTLP logs backend such
+   * as Loki) alongside any `logger`.
+   *
+   * Defaults to true only when no `logger` is given, which is the historical
+   * either/or behaviour. Set it explicitly to have both: a console/pino logger
+   * keeps lines in the platform's own log view while OTLP carries the same
+   * lines to your backend.
+   */
+  otel?: boolean;
   /** Only emit canonical log lines for root spans (default: false) */
   rootSpansOnly?: boolean;
   /** Minimum log level for canonical log lines (default: 'info') */
@@ -116,7 +129,8 @@ interface CanonicalLogLineOptions {
  * ```
  */
 declare class CanonicalLogLineProcessor implements SpanProcessor {
-  private logger?;
+  private loggers;
+  private useOtel;
   private rootSpansOnly;
   private minLevel;
   private messageFormat;

package/dist/{canonical-log-line-processor-hFUmS__K.js → canonical-log-line-processor-CBv-OCp4.js}

@@ -233,7 +233,8 @@ const SEVERITY_NUMBERS = /* @__PURE__ */ new Map([
 * ```
 */
 var CanonicalLogLineProcessor = class {
-	logger;
+	loggers;
+	useOtel;
 	rootSpansOnly;
 	minLevel;
 	messageFormat;
@@ -245,7 +246,8 @@ var CanonicalLogLineProcessor = class {
 	pretty;
 	getOTelLogger = null;
 	constructor(options = {}) {
-		this.logger = options.logger;
+		this.loggers = options.logger ? Array.isArray(options.logger) ? options.logger.filter(Boolean) : [options.logger] : [];
+		this.useOtel = options.otel ?? this.loggers.length === 0;
 		this.rootSpansOnly = options.rootSpansOnly ?? false;
 		this.minLevel = options.minLevel ?? "info";
 		this.messageFormat = options.messageFormat ?? ((span) => `[${span.name}] Request completed`);
@@ -255,7 +257,7 @@ var CanonicalLogLineProcessor = class {
 		this.drain = options.drain;
 		this.onDrainError = options.onDrainError;
 		this.pretty = options.pretty ?? (hasProcess() && process.env.NODE_ENV === "development");
-		if (!this.logger) this.getOTelLogger = () => logs.getLogger("autotel.canonical-log-line");
+		if (this.useOtel) this.getOTelLogger = () => logs.getLogger("autotel.canonical-log-line");
 	}
 	buildKeepPredicate(keep) {
 		if (!keep || keep.length === 0) return void 0;
@@ -287,10 +289,12 @@ var CanonicalLogLineProcessor = class {
 		};
 		if (this.shouldEmit && !this.shouldEmit(eventContext)) return;
 		if (this.pretty) console.log(formatPrettyLogLine(eventContext));
-		if (this.logger) this.emitViaLogger(level, message, canonicalLogLine);
-		else if (this.getOTelLogger) {
+		if (this.loggers.length > 0) this.emitViaLogger(level, message, canonicalLogLine);
+		if (this.getOTelLogger) try {
 			const otelLogger = this.getOTelLogger();
 			this.emitViaOTel(level, message, canonicalLogLine, otelLogger);
+		} catch (error) {
+			this.reportInternalWarning("canonical log line OTel emission failed", error);
 		}
 		if (this.drain) Promise.resolve(this.drain(eventContext)).catch((error) => {
 			if (this.onDrainError) {
@@ -328,7 +332,11 @@ var CanonicalLogLineProcessor = class {
 		return redacted;
 	}
 	emitViaLogger(level, message, canonicalLogLine) {
-		this.logger[level](canonicalLogLine, message);
+		for (const logger of this.loggers) try {
+			logger[level](canonicalLogLine, message);
+		} catch (error) {
+			this.reportInternalWarning("canonical log line logger emission failed", error);
+		}
 	}
 	emitViaOTel(level, message, canonicalLogLine, otelLogger) {
 		const otelAttributes = {};
@@ -364,11 +372,17 @@ var CanonicalLogLineProcessor = class {
 	}
 	reportInternalWarning(message, cause) {
 		const err = cause === void 0 ? "unknown error" : toError(cause).message;
-		if (this.logger) {
-			this.logger.warn({ error: err }, `[autotel] ${message}`);
-			return;
+		if (this.loggers.length > 0) {
+			let reported = false;
+			for (const logger of this.loggers) try {
+				logger.warn({ error: err }, `[autotel] ${message}`);
+				reported = true;
+			} catch {}
+			if (reported) return;
 		}
-		console.warn(`[autotel] ${message}: ${err}`);
+		try {
+			console.warn(`[autotel] ${message}: ${err}`);
+		} catch {}
 	}
 	async forceFlush() {}
 	async shutdown() {}

package/dist/{canonical-log-line-processor-cPB4Axk-.d.ts → canonical-log-line-processor-Yq4cXcD5.d.ts}

@@ -22,8 +22,21 @@ interface KeepCondition {
   path?: string;
 }
 interface CanonicalLogLineOptions {
-  /** Logger to use for emitting canonical log lines (defaults to OTel Logs API) */
-  logger?: Logger;
+  /**
+   * Logger(s) to emit canonical log lines through. Pass an array to fan out to
+   * several. When omitted, lines go to the OTel Logs API instead.
+   */
+  logger?: Logger | Logger[];
+  /**
+   * Also emit through the OTel Logs API (and so to an OTLP logs backend such
+   * as Loki) alongside any `logger`.
+   *
+   * Defaults to true only when no `logger` is given, which is the historical
+   * either/or behaviour. Set it explicitly to have both: a console/pino logger
+   * keeps lines in the platform's own log view while OTLP carries the same
+   * lines to your backend.
+   */
+  otel?: boolean;
   /** Only emit canonical log lines for root spans (default: false) */
   rootSpansOnly?: boolean;
   /** Minimum log level for canonical log lines (default: 'info') */
@@ -116,7 +129,8 @@ interface CanonicalLogLineOptions {
  * ```
  */
 declare class CanonicalLogLineProcessor implements SpanProcessor {
-  private logger?;
+  private loggers;
+  private useOtel;
   private rootSpansOnly;
   private minLevel;
   private messageFormat;

package/dist/correlation-id.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-const require_init = require('./init-DmM7dprX.cjs');
+const require_init = require('./init-CNUkdwke.cjs');
 
 exports.CORRELATION_ID_BAGGAGE_KEY = require_init.CORRELATION_ID_BAGGAGE_KEY;
 exports.generateCorrelationId = require_init.generateCorrelationId;

package/dist/correlation-id.js

@@ -1,3 +1,3 @@
-import { $ as getCorrelationStorage, Q as getCorrelationId, X as CORRELATION_ID_BAGGAGE_KEY, Z as generateCorrelationId, et as getOrCreateCorrelationId, nt as setCorrelationId, rt as setCorrelationIdInBaggage, tt as runWithCorrelationId } from "./init-CsKK9vZO.js";
+import { $ as getCorrelationStorage, Q as getCorrelationId, X as CORRELATION_ID_BAGGAGE_KEY, Z as generateCorrelationId, et as getOrCreateCorrelationId, nt as setCorrelationId, rt as setCorrelationIdInBaggage, tt as runWithCorrelationId } from "./init-B2kv4bLO.js";
 
 export { CORRELATION_ID_BAGGAGE_KEY, generateCorrelationId, getCorrelationId, getCorrelationStorage, getOrCreateCorrelationId, runWithCorrelationId, setCorrelationId, setCorrelationIdInBaggage };

package/dist/decorators.cjs

@@ -1,7 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const require_values = require('./values-DApyq53y.cjs');
 const require_config = require('./config.cjs');
-const require_init = require('./init-DmM7dprX.cjs');
+const require_init = require('./init-CNUkdwke.cjs');
 let _opentelemetry_api = require("@opentelemetry/api");
 
 //#region src/decorators.ts

package/dist/decorators.js

@@ -1,6 +1,6 @@
 import { y as splitNameOrOptions } from "./values-BenyvWKz.js";
 import { getConfig } from "./config.js";
-import { U as createTraceContext } from "./init-CsKK9vZO.js";
+import { U as createTraceContext } from "./init-B2kv4bLO.js";
 import { SpanStatusCode } from "@opentelemetry/api";
 
 //#region src/decorators.ts

package/dist/event.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-const require_init = require('./init-DmM7dprX.cjs');
+const require_init = require('./init-CNUkdwke.cjs');
 
 exports.Event = require_init.Event;
 exports.getEvents = require_init.getEvents;

package/dist/event.js

@@ -1,3 +1,3 @@
-import { d as Event, f as getEvents, p as resetEvents } from "./init-CsKK9vZO.js";
+import { d as Event, f as getEvents, p as resetEvents } from "./init-B2kv4bLO.js";
 
 export { Event, getEvents, resetEvents };

package/dist/feature-flags.cjs

@@ -0,0 +1,204 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+let _opentelemetry_api = require("@opentelemetry/api");
+let _opentelemetry_api_logs = require("@opentelemetry/api-logs");
+
+//#region src/feature-flags.ts
+/**
+* Feature flag evaluations, in the vocabulary OpenTelemetry already defined.
+*
+* A flagged rollout splits your traffic into two populations that share a
+* service name, a route and a version. Without the flag on the span there is no
+* way to ask the only question that matters during a rollout — is the new
+* branch slower, or failing more, than the old one — and the usual workaround
+* is to read it in the flag vendor's own dashboard, where the latency and the
+* errors are not.
+*
+* The specification covers this: `feature_flag.key`, `.result.value`,
+* `.result.variant`, `.result.reason`, `.provider.name`, `.context.id`, plus a
+* `feature_flag.evaluation` event. Emitting those means any backend can split
+* any metric by variant, with no vendor in the path.
+*
+* ## Attributes and events both
+*
+* Span attributes hold one flag: a second call overwrites the first. A request
+* that branched on three flags needs one event each, which is what the
+* `feature_flag.evaluation` event is for. Both are recorded — attributes so a
+* single-flag span is filterable without unpacking events, events so a
+* many-flag span keeps them all.
+*
+* ## Record what you branched on
+*
+* Record a flag where the code *reads* it, not where it is fetched. A flag
+* evaluated and ignored explains nothing; the value the request actually took a
+* branch on is the one that explains its behaviour.
+*/
+/** Canonical `feature_flag.*` attribute keys. */
+const FEATURE_FLAG = {
+	KEY: "feature_flag.key",
+	RESULT_VALUE: "feature_flag.result.value",
+	RESULT_VARIANT: "feature_flag.result.variant",
+	RESULT_REASON: "feature_flag.result.reason",
+	PROVIDER_NAME: "feature_flag.provider.name",
+	CONTEXT_ID: "feature_flag.context.id",
+	SET_ID: "feature_flag.set.id",
+	VERSION: "feature_flag.version",
+	/**
+	* Why an evaluation failed. `feature_flag.evaluation.error.message` is the
+	* deprecated spelling of this and is deliberately not emitted — writing both
+	* would double the cardinality to no benefit.
+	*/
+	ERROR_MESSAGE: "feature_flag.error.message"
+};
+/** Canonical event name for one evaluation. */
+const FEATURE_FLAG_EVALUATION_EVENT = "feature_flag.evaluation";
+/**
+* Canonical `feature_flag.result.reason` values. The registry defines them in
+* lower snake case; OpenFeature and most SDKs report them upper-cased, and
+* forwarding that splits every group-by into two buckets meaning the same
+* thing.
+*/
+const FEATURE_FLAG_REASON = [
+	"static",
+	"default",
+	"targeting_match",
+	"split",
+	"cached",
+	"disabled",
+	"unknown",
+	"stale",
+	"error"
+];
+/**
+* A flag value as an attribute.
+*
+* Booleans and numbers are kept as they are: `feature_flag.result.value`
+* permits typed values, and stringifying `true` makes a boolean flag
+* uncomparable with the numeric one next to it. Only a structured value — which
+* no attribute type can hold — is serialised.
+*/
+function asAttributeValue(value) {
+	if (typeof value === "string" || typeof value === "boolean" || typeof value === "number" && Number.isFinite(value)) return value;
+	try {
+		return JSON.stringify(value) ?? String(value);
+	} catch {
+		return String(value);
+	}
+}
+/** Canonical attributes for one evaluation. Absent fields are omitted. */
+function featureFlagAttributes(evaluation) {
+	const attributes = {
+		[FEATURE_FLAG.KEY]: evaluation.key,
+		[FEATURE_FLAG.RESULT_VALUE]: asAttributeValue(evaluation.value)
+	};
+	const optional = [
+		[FEATURE_FLAG.RESULT_VARIANT, evaluation.variant],
+		[FEATURE_FLAG.RESULT_REASON, evaluation.reason === void 0 ? void 0 : evaluation.reason.toLowerCase()],
+		[FEATURE_FLAG.PROVIDER_NAME, evaluation.provider],
+		[FEATURE_FLAG.CONTEXT_ID, evaluation.contextId],
+		[FEATURE_FLAG.SET_ID, evaluation.setId],
+		[FEATURE_FLAG.VERSION, evaluation.version],
+		[FEATURE_FLAG.ERROR_MESSAGE, evaluation.errorMessage]
+	];
+	for (const [key, value] of optional) if (value !== void 0) attributes[key] = value;
+	return attributes;
+}
+/**
+* Record a flag evaluation on `sink` — as attributes and as a
+* `feature_flag.evaluation` event.
+*
+* A missing sink is a no-op: instrumentation must never be the reason a branch
+* throws, and a flag read outside any span is a legitimate thing to do.
+*/
+function recordFeatureFlag(sink, evaluation) {
+	if (!sink) return;
+	const attributes = featureFlagAttributes(evaluation);
+	sink.setAttributes(attributes);
+	sink.track?.(FEATURE_FLAG_EVALUATION_EVENT, attributes);
+}
+/**
+* Emit the evaluation as an OpenTelemetry **log record**.
+*
+* This is the Logs API model the repository emits events through. The obvious
+* shortcut — `Span.addEvent` on the active span — puts the evaluation somewhere
+* no log or event pipeline will ever look, which is exactly the failure the
+* invariant exists to prevent. `correlated-events` is not a way around it
+* either: that helper prefers `addEvent` when the target has one, so routing
+* through it lands in the same place with more indirection.
+*
+* `logs.getLogger` returns a no-op logger when no `LoggerProvider` is
+* registered, so this costs nothing in an application that exports no logs.
+*/
+function emitEvaluationRecord(attributes) {
+	_opentelemetry_api_logs.logs.getLogger("autotel").emit({
+		eventName: FEATURE_FLAG_EVALUATION_EVENT,
+		attributes
+	});
+}
+function evaluationFrom(hookContext, value, extra) {
+	return {
+		key: hookContext.flagKey,
+		value,
+		provider: hookContext.providerMetadata?.name,
+		contextId: hookContext.context?.targetingKey,
+		setId: hookContext.clientMetadata?.name,
+		...extra
+	};
+}
+/**
+* An OpenFeature hook that records every evaluation under the canonical
+* `feature_flag.*` convention.
+*
+* This is the zero-config path: OpenFeature already sits between the
+* application and whichever flag vendor it uses, and it already fires on every
+* evaluation — which is exactly the moment worth recording, because it is the
+* moment the code branched.
+*
+* ```ts
+* import { OpenFeature } from '@openfeature/server-sdk';
+* import { autotelOpenFeatureHook } from 'autotel/feature-flags';
+*
+* OpenFeature.addHooks(autotelOpenFeatureHook());
+* ```
+*
+* A failed evaluation is still recorded, with the default value the code
+* actually used and `reason: 'ERROR'`. The default is what the request behaved
+* as; the failure is why.
+*/
+function autotelOpenFeatureHook(options = {}) {
+	const getSpan = options.getSpan ?? (() => _opentelemetry_api.trace.getActiveSpan());
+	const emitLogRecord = options.emitLogRecord ?? emitEvaluationRecord;
+	/**
+	* Attributes onto the span that branched, and the event wherever the sink
+	* says. A sink with no `track` of its own gets a log record — including when
+	* there is no span at all, because the evaluation still happened.
+	*/
+	const record = (evaluation) => {
+		const sink = getSpan();
+		const attributes = featureFlagAttributes(evaluation);
+		sink?.setAttributes(attributes);
+		if (sink?.track) sink.track(FEATURE_FLAG_EVALUATION_EVENT, attributes);
+		else emitLogRecord(attributes);
+	};
+	return {
+		after(hookContext, details) {
+			record(evaluationFrom(hookContext, details.value, {
+				variant: details.variant,
+				reason: details.reason
+			}));
+		},
+		error(hookContext, error) {
+			record(evaluationFrom(hookContext, hookContext.defaultValue, {
+				reason: "error",
+				errorMessage: error instanceof Error ? error.message : String(error)
+			}));
+		}
+	};
+}
+
+//#endregion
+exports.FEATURE_FLAG = FEATURE_FLAG;
+exports.FEATURE_FLAG_EVALUATION_EVENT = FEATURE_FLAG_EVALUATION_EVENT;
+exports.FEATURE_FLAG_REASON = FEATURE_FLAG_REASON;
+exports.autotelOpenFeatureHook = autotelOpenFeatureHook;
+exports.featureFlagAttributes = featureFlagAttributes;
+exports.recordFeatureFlag = recordFeatureFlag;