better-effect 0.13.0 → 0.14.0

package/dist/opentelemetry.mjs

@@ -1,4 +1,354 @@
 import { ROOT_CONTEXT, SpanStatusCode, context, trace } from "@opentelemetry/api";
+//#region src/opentelemetry/lifecycle.ts
+const readMonotonicTime$1 = () => {
+	try {
+		return performance.now();
+	} catch {
+		return Date.now();
+	}
+};
+const eventName$1 = (phase) => `better-effect.lifecycle.${phase}`;
+const callSpan$2 = (operation) => {
+	try {
+		Promise.resolve(operation()).catch(() => {});
+	} catch {}
+};
+const finishSpan$1 = (span, status, details) => {
+	callSpan$2(() => span.setStatus({ code: status === "failure" ? SpanStatusCode.ERROR : SpanStatusCode.OK }));
+	if (details !== void 0) {
+		const message = details.message;
+		if (message !== void 0) callSpan$2(() => span.recordException(message));
+		if (Object.keys(details.attributes).length > 0) callSpan$2(() => span.addEvent("better-effect.failure", details.attributes));
+	}
+	callSpan$2(() => span.end());
+};
+const failureCause = (event) => {
+	if (event.error !== void 0) return event.error;
+	return event.outcome.status === "failure" ? event.outcome.cause : void 0;
+};
+const eventStatus = (event) => "error" in event && event.error !== void 0 ? "failure" : event.outcome.status;
+/** Internal lifecycle state machine for the OpenTelemetry Runtime observer. */
+var LifecycleTelemetry = class {
+	options;
+	states = /* @__PURE__ */ new Map();
+	disposed = false;
+	constructor(options) {
+		this.options = options;
+	}
+	onStart(event) {
+		if (this.disposed || this.options.mode === "off" || this.states.has(event.lifecycleId)) return;
+		const state = {
+			lifecycleId: event.lifecycleId,
+			startedAt: readMonotonicTime$1(),
+			parentContext: this.options.getParentContext(),
+			starting: true,
+			carrier: void 0,
+			activationSpan: void 0,
+			activationEnded: false,
+			activationReported: false,
+			pendingActivationEnd: void 0
+		};
+		this.states.set(event.lifecycleId, state);
+		const span = this.options.startSpan(this.options.mode === "events" ? "better-effect.lifecycle" : eventName$1("activate"), this.options.makeAttributes(event, "activate", void 0, void 0), state.parentContext);
+		if (!this.states.has(event.lifecycleId)) {
+			if (span !== void 0) callSpan$2(() => span.end());
+			return;
+		}
+		state.starting = false;
+		if (this.options.mode === "events") {
+			state.carrier = span;
+			if (span !== void 0) callSpan$2(() => span.addEvent(eventName$1("activate"), this.options.makeAttributes(event, "activate", void 0, void 0)));
+		} else state.activationSpan = span;
+		const pendingEnd = state.pendingActivationEnd;
+		if (pendingEnd !== void 0) {
+			state.pendingActivationEnd = void 0;
+			this.onEnd(pendingEnd);
+		}
+	}
+	onEnd(event) {
+		if (this.options.mode === "off") return;
+		const state = this.states.get(event.lifecycleId);
+		if (state === void 0 || state.activationReported) return;
+		const durationMs = Math.max(0, readMonotonicTime$1() - state.startedAt);
+		const status = eventStatus(event);
+		if (this.options.mode === "events") {
+			const span = state.carrier;
+			if (span === void 0) {
+				if (state.starting) {
+					state.pendingActivationEnd = event;
+					return;
+				}
+				state.activationReported = true;
+				if (status === "failure") this.states.delete(event.lifecycleId);
+				return;
+			}
+			state.activationReported = true;
+			state.activationEnded = true;
+			if (status === "failure") this.states.delete(event.lifecycleId);
+			callSpan$2(() => span.addEvent(eventName$1("activate"), this.options.makeAttributes(event, "activate", status, durationMs)));
+			if (status === "failure" && this.options.recordFailures) {
+				const details = this.options.getFailureDetails(failureCause(event));
+				if (details !== void 0) finishDetails(span, details);
+			}
+			if (status === "failure") {
+				callSpan$2(() => span.setStatus({ code: SpanStatusCode.ERROR }));
+				callSpan$2(() => span.end());
+			}
+			return;
+		}
+		const span = state.activationSpan;
+		if (span === void 0) {
+			if (state.starting) {
+				state.pendingActivationEnd = event;
+				return;
+			}
+			state.activationReported = true;
+			if (status === "failure") this.states.delete(event.lifecycleId);
+			return;
+		}
+		state.activationReported = true;
+		if (status === "failure") this.states.delete(event.lifecycleId);
+		state.activationEnded = true;
+		finishSpan$1(span, status, status === "failure" && this.options.recordFailures ? this.options.getFailureDetails(failureCause(event)) : void 0);
+	}
+	onRelease(event) {
+		if (this.options.mode === "off") return;
+		const state = this.states.get(event.lifecycleId);
+		if (state === void 0) return;
+		this.states.delete(event.lifecycleId);
+		const status = eventStatus(event);
+		const attributes = this.options.makeAttributes(event, "release", status, void 0);
+		const details = status === "failure" && this.options.recordFailures ? this.options.getFailureDetails(failureCause(event)) : void 0;
+		if (this.options.mode === "events") {
+			if (state.carrier === void 0) return;
+			callSpan$2(() => state.carrier.addEvent(eventName$1("release"), attributes));
+			if (details !== void 0) finishDetails(state.carrier, details);
+			finishSpan$1(state.carrier, status, void 0);
+			return;
+		}
+		const span = this.options.startSpan(eventName$1("release"), attributes, state.parentContext);
+		if (span !== void 0) finishSpan$1(span, status, details);
+	}
+	dispose() {
+		if (this.disposed) return;
+		this.disposed = true;
+		const pending = [...this.states.values()];
+		this.states.clear();
+		for (const state of pending) {
+			if (state.carrier !== void 0) callSpan$2(() => state.carrier.end());
+			if (state.activationSpan !== void 0 && !state.activationEnded) callSpan$2(() => state.activationSpan.end());
+		}
+	}
+};
+const finishDetails = (span, details) => {
+	const message = details.message;
+	if (message !== void 0) callSpan$2(() => span.recordException(message));
+	if (Object.keys(details.attributes).length > 0) callSpan$2(() => span.addEvent("better-effect.failure", details.attributes));
+};
+//#endregion
+//#region src/opentelemetry/shutdown.ts
+const callSpan$1 = (operation) => {
+	try {
+		Promise.resolve(operation()).catch(() => {});
+	} catch {}
+};
+const readMonotonicTime = () => {
+	try {
+		return performance.now();
+	} catch {
+		return Date.now();
+	}
+};
+const boundedDuration$1 = (value) => value !== void 0 && Number.isFinite(value) && value >= 0 ? Math.min(value, 2 ** 31 - 1) : void 0;
+const phaseOf = (phase) => {
+	switch (phase) {
+		case "shutdown-requested": return "requested";
+		case "quiesce-start":
+		case "quiesce-end": return "quiesce";
+		case "drain-start":
+		case "drain-end": return "drain";
+		case "abort-active": return "abort";
+		case "release-start":
+		case "release-end": return "release";
+		case "shutdown-complete":
+		case "shutdown-failure": return "complete";
+	}
+};
+const eventName = (phase) => `better-effect.shutdown.${phase}`;
+const isStart = (phase) => phase === "quiesce-start" || phase === "drain-start" || phase === "release-start";
+const isEnd = (phase) => phase === "quiesce-end" || phase === "drain-end" || phase === "release-end";
+const isTerminal = (phase) => phase === "shutdown-complete" || phase === "shutdown-failure";
+const finishSpan = (span, status, details) => {
+	callSpan$1(() => span.setStatus({ code: status === "failure" ? SpanStatusCode.ERROR : SpanStatusCode.OK }));
+	if (details !== void 0) {
+		const message = details.message;
+		if (message !== void 0) callSpan$1(() => span.recordException(message));
+		if (Object.keys(details.attributes).length > 0) callSpan$1(() => span.addEvent("better-effect.failure", details.attributes));
+	}
+	callSpan$1(() => span.end());
+};
+/** Internal shutdown state machine for the OpenTelemetry Runtime observer. */
+var ShutdownTelemetry = class {
+	options;
+	states = /* @__PURE__ */ new Map();
+	disposed = false;
+	constructor(options) {
+		this.options = options;
+	}
+	onEvent(event) {
+		if (this.disposed || this.options.mode === "off") return;
+		if (event.phase === "shutdown-requested") {
+			this.start(event);
+			return;
+		}
+		const state = this.states.get(event.reason);
+		if (state === void 0) return;
+		if (state.span === void 0 && state.starting) {
+			state.pendingEvents.push(event);
+			return;
+		}
+		if (state.span === void 0 && isTerminal(event.phase)) {
+			this.states.delete(event.reason);
+			state.pendingEvents.length = 0;
+			return;
+		}
+		if (state.span !== void 0) this.process(state, event);
+	}
+	start(event) {
+		if (this.states.has(event.reason)) return;
+		const state = {
+			reason: event.reason,
+			starting: true,
+			span: void 0,
+			phaseSpans: /* @__PURE__ */ new Map(),
+			phaseStartedAt: /* @__PURE__ */ new Map(),
+			pendingPhaseEnds: /* @__PURE__ */ new Map(),
+			pendingEvents: []
+		};
+		this.states.set(event.reason, state);
+		const span = this.options.startSpan("better-effect.shutdown", this.options.makeAttributes(event, "requested", void 0), this.options.rootContext);
+		if (!this.states.has(event.reason)) {
+			if (span !== void 0) callSpan$1(() => span.end());
+			return;
+		}
+		state.starting = false;
+		state.span = span;
+		if (span !== void 0) this.addEvent(state, event);
+		const pendingEvents = state.pendingEvents.splice(0);
+		for (const pendingEvent of pendingEvents) this.process(state, pendingEvent);
+	}
+	process(state, event) {
+		const phase = phaseOf(event.phase);
+		if (isStart(event.phase)) {
+			this.startPhase(state, event, phase);
+			return;
+		}
+		if (isEnd(event.phase)) {
+			if (!state.phaseStartedAt.has(phase)) return;
+			if (this.options.mode === "spans" && !state.phaseSpans.has(phase)) {
+				state.pendingPhaseEnds.set(phase, event);
+				return;
+			}
+			this.finishPhase(state, event, phase);
+			return;
+		}
+		if (event.phase === "abort-active") {
+			if (state.phaseStartedAt.has("abort")) return;
+			state.phaseStartedAt.set("abort", readMonotonicTime());
+			if (this.options.mode === "events") {
+				this.addEvent(state, event);
+				state.phaseStartedAt.delete("abort");
+			} else {
+				const span = this.startPhaseSpan(state, event, "abort");
+				if (span !== void 0) {
+					state.phaseStartedAt.delete("abort");
+					finishSpan(span, "success", void 0);
+				}
+			}
+			return;
+		}
+		if (isTerminal(event.phase)) this.finish(state, event);
+	}
+	startPhase(state, event, phase) {
+		if (state.phaseStartedAt.has(phase)) return;
+		state.phaseStartedAt.set(phase, readMonotonicTime());
+		if (this.options.mode === "events") {
+			this.addEvent(state, event);
+			return;
+		}
+		const span = this.startPhaseSpan(state, event, phase);
+		if (!this.states.has(state.reason)) {
+			if (span !== void 0) callSpan$1(() => span.end());
+			return;
+		}
+		if (span !== void 0) {
+			state.phaseSpans.set(phase, span);
+			const pendingEnd = state.pendingPhaseEnds.get(phase);
+			if (pendingEnd !== void 0) {
+				state.pendingPhaseEnds.delete(phase);
+				this.finishPhase(state, pendingEnd, phase);
+			}
+		}
+	}
+	startPhaseSpan(state, event, phase) {
+		let parent = this.options.rootContext;
+		if (state.span !== void 0) try {
+			parent = trace.setSpan(this.options.rootContext, state.span);
+		} catch {
+			parent = this.options.rootContext;
+		}
+		return this.options.startSpan(eventName(phase), this.options.makeAttributes(event, phase, void 0), parent);
+	}
+	addEvent(state, event, durationMsOverride) {
+		const span = state.span;
+		if (span === void 0) return;
+		const phase = phaseOf(event.phase);
+		const startedAt = state.phaseStartedAt.get(phase);
+		const durationMs = durationMsOverride ?? (startedAt === void 0 ? void 0 : Math.max(0, readMonotonicTime() - startedAt));
+		callSpan$1(() => span.addEvent(eventName(phase), this.options.makeAttributes(event, phase, durationMs)));
+	}
+	finishPhase(state, event, phase) {
+		const span = state.phaseSpans.get(phase);
+		const startedAt = state.phaseStartedAt.get(phase);
+		const durationMs = startedAt === void 0 ? event.durationMs : Math.max(0, readMonotonicTime() - startedAt);
+		state.phaseSpans.delete(phase);
+		state.phaseStartedAt.delete(phase);
+		state.pendingPhaseEnds.delete(phase);
+		if (this.options.mode === "events") {
+			this.addEvent(state, event, durationMs);
+			return;
+		}
+		if (span !== void 0) {
+			callSpan$1(() => span.setAttribute("better_effect.duration_ms", boundedDuration$1(durationMs) ?? 0));
+			finishSpan(span, "success", void 0);
+		}
+	}
+	finish(state, event) {
+		if (this.states.get(state.reason) !== state) return;
+		this.states.delete(state.reason);
+		const status = event.phase === "shutdown-failure" ? "failure" : "success";
+		const details = status === "failure" && this.options.recordFailures ? this.options.getFailureDetails(event.error) : void 0;
+		for (const span of state.phaseSpans.values()) callSpan$1(() => span.end());
+		state.phaseSpans.clear();
+		state.phaseStartedAt.clear();
+		state.pendingPhaseEnds.clear();
+		state.pendingEvents.length = 0;
+		if (state.span === void 0) return;
+		this.addEvent(state, event);
+		finishSpan(state.span, status, details);
+	}
+	dispose() {
+		if (this.disposed) return;
+		this.disposed = true;
+		const pending = [...this.states.values()];
+		this.states.clear();
+		for (const state of pending) {
+			for (const span of state.phaseSpans.values()) callSpan$1(() => span.end());
+			if (state.span !== void 0) callSpan$1(() => state.span.end());
+		}
+	}
+};
+//#endregion
 //#region src/opentelemetry/index.ts
 const DEFAULT_TRACER_NAME = "better-effect";
 const DEFAULT_EXECUTION_SPAN_NAME = "better-effect.execution";
@@ -17,11 +367,47 @@ const SERVICE_TAG_ATTRIBUTE = "better_effect.service_tag";
 const RESOLUTION_PATH_ATTRIBUTE = "better_effect.resolution_path";
 const RESOLUTION_PATH_TRUNCATED_ATTRIBUTE = "better_effect.resolution_path_truncated";
 const LIBRARY_ATTRIBUTE = "better_effect.library";
+const LIFECYCLE_NAME_ATTRIBUTE = "better_effect.lifecycle_name";
+const LIFECYCLE_PHASE_ATTRIBUTE = "better_effect.lifecycle_phase";
+const SHUTDOWN_PHASE_ATTRIBUTE = "better_effect.shutdown_phase";
+const SHUTDOWN_REASON_ATTRIBUTE = "better_effect.shutdown_reason";
+const SHUTDOWN_SIGNAL_ATTRIBUTE = "better_effect.shutdown_signal";
+const DURATION_ATTRIBUTE = "better_effect.duration_ms";
 const FAILURE_EVENT_NAME = "better-effect.failure";
 const serviceEventStatus = (event) => "error" in event && event.error !== void 0 ? "failure" : event.outcome.status;
 const executionEventStatus = (event) => event.cleanupFailure !== void 0 ? "failure" : event.outcome.status;
 const isStartedExecutionSpan = (execution) => execution.span !== void 0;
 const isActiveExecutionSpan = (execution) => isStartedExecutionSpan(execution) && execution.executionContext !== void 0;
+const isTelemetryMode = (value) => value === "off" || value === "events" || value === "spans";
+const boundedDuration = (value) => value !== void 0 && Number.isFinite(value) && value >= 0 ? Math.min(value, 2 ** 31 - 1) : void 0;
+const addOutcomeAttribute = (attributes, outcome, limit) => {
+	if (outcome !== void 0) addAttribute(attributes, OUTCOME_ATTRIBUTE, outcome, limit);
+};
+const addDurationAttribute = (attributes, durationMs, limit) => {
+	const duration = boundedDuration(durationMs);
+	if (duration !== void 0) addAttribute(attributes, DURATION_ATTRIBUTE, duration, limit);
+};
+const makeLifecycleAttributes = (event, phase, outcome, durationMs, limits) => {
+	const attributes = {};
+	const name = boundedNonEmptyString(event.name, limits.maxAttributeLength);
+	if (name !== void 0) addAttribute(attributes, LIFECYCLE_NAME_ATTRIBUTE, name, limits.maxAttributeCount);
+	addAttribute(attributes, LIFECYCLE_PHASE_ATTRIBUTE, phase, limits.maxAttributeCount);
+	addOutcomeAttribute(attributes, outcome, limits.maxAttributeCount);
+	addDurationAttribute(attributes, durationMs, limits.maxAttributeCount);
+	return attributes;
+};
+const makeShutdownAttributes = (event, phase, durationMs, limits) => {
+	const attributes = {};
+	const reason = event.reason;
+	addAttribute(attributes, SHUTDOWN_PHASE_ATTRIBUTE, phase, limits.maxAttributeCount);
+	addAttribute(attributes, SHUTDOWN_REASON_ATTRIBUTE, reason.kind, limits.maxAttributeCount);
+	if (reason.signal === "SIGINT" || reason.signal === "SIGTERM") addAttribute(attributes, SHUTDOWN_SIGNAL_ATTRIBUTE, reason.signal, limits.maxAttributeCount);
+	if (event.activeExecutions !== void 0 && Number.isSafeInteger(event.activeExecutions)) addAttribute(attributes, "better_effect.active_executions", Math.max(0, event.activeExecutions), limits.maxAttributeCount);
+	addDurationAttribute(attributes, durationMs ?? event.durationMs, limits.maxAttributeCount);
+	if (event.phase === "shutdown-complete") addOutcomeAttribute(attributes, "success", limits.maxAttributeCount);
+	else if (event.phase === "shutdown-failure") addOutcomeAttribute(attributes, "failure", limits.maxAttributeCount);
+	return attributes;
+};
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const isSpan = (value) => isRecord(value) && typeof value.end === "function";
 const isTracer = (value) => isRecord(value) && typeof value.startSpan === "function";
@@ -259,6 +645,8 @@ var OpenTelemetryRuntimeObserver = class OpenTelemetryRuntimeObserver {
 	limits;
 	executionSpans = /* @__PURE__ */ new Map();
 	serviceResolution;
+	lifecycleTelemetry;
+	shutdownTelemetry;
 	recordFailures;
 	disposed = false;
 	constructor(options) {
@@ -267,11 +655,27 @@ var OpenTelemetryRuntimeObserver = class OpenTelemetryRuntimeObserver {
 		this.limits = normalizeLimits(options);
 		this.serviceResolution = options.serviceResolution ?? "off";
 		this.recordFailures = options.recordFailures === true;
-		if (![
-			"off",
-			"events",
-			"spans"
-		].includes(this.serviceResolution)) throw new TypeError("serviceResolution must be off, events, or spans");
+		if (!isTelemetryMode(this.serviceResolution)) throw new TypeError("serviceResolution must be off, events, or spans");
+		const lifecycle = options.lifecycle ?? "off";
+		if (!isTelemetryMode(lifecycle)) throw new TypeError("lifecycle must be off, events, or spans");
+		const shutdown = options.shutdown ?? "off";
+		if (!isTelemetryMode(shutdown)) throw new TypeError("shutdown must be off, events, or spans");
+		this.lifecycleTelemetry = new LifecycleTelemetry({
+			mode: lifecycle,
+			recordFailures: this.recordFailures,
+			getParentContext: () => readActiveContext() ?? ROOT_CONTEXT,
+			startSpan: this.startSpan.bind(this),
+			makeAttributes: (event, phase, outcome, durationMs) => makeLifecycleAttributes(event, phase, outcome, durationMs, this.limits),
+			getFailureDetails: (cause) => makeFailureDetails(cause, this.options.sanitizeFailure, this.limits)
+		});
+		this.shutdownTelemetry = new ShutdownTelemetry({
+			mode: shutdown,
+			recordFailures: this.recordFailures,
+			rootContext: ROOT_CONTEXT,
+			startSpan: this.startSpan.bind(this),
+			makeAttributes: (event, phase, durationMs) => makeShutdownAttributes(event, phase, durationMs, this.limits),
+			getFailureDetails: (cause) => makeFailureDetails(cause, this.options.sanitizeFailure, this.limits)
+		});
 	}
 	static make(options) {
 		return new OpenTelemetryRuntimeObserver(options);
@@ -291,6 +695,18 @@ var OpenTelemetryRuntimeObserver = class OpenTelemetryRuntimeObserver {
 	onResourceRelease = (event) => {
 		this.safely(() => this.observeService("better-effect.service.release", event));
 	};
+	onLifecycleStart = (event) => {
+		this.safely(() => this.lifecycleTelemetry.onStart(event));
+	};
+	onLifecycleEnd = (event) => {
+		this.safely(() => this.lifecycleTelemetry.onEnd(event));
+	};
+	onLifecycleRelease = (event) => {
+		this.safely(() => this.lifecycleTelemetry.onRelease(event));
+	};
+	onShutdown = (event) => {
+		this.safely(() => this.shutdownTelemetry.onEvent(event));
+	};
 	/** End any spans whose malformed or missing end event left them pending. */
 	dispose() {
 		if (this.disposed) return;
@@ -301,6 +717,8 @@ var OpenTelemetryRuntimeObserver = class OpenTelemetryRuntimeObserver {
 			if (span === void 0) continue;
 			this.endExecutionSpan(execution, span);
 		}
+		this.lifecycleTelemetry.dispose();
+		this.shutdownTelemetry.dispose();
 	}
 	[Symbol.dispose]() {
 		this.dispose();