@equipe-tech/observability 0.2.0 → 0.3.5

package/dist/profile/LifecycleRegistry.js

@@ -0,0 +1,240 @@
+import { Cause, Clock, Effect, Option, Schema } from "effect";
+import { AdapterFailure, AdapterName, isOfficialAdapterRegistration, isTestingAdapterRegistration, registerOfficialAdapter, } from "./ObservabilityAdapter.js";
+import { InvalidObservabilityConfig } from "./ObservabilityConfigError.js";
+import { profileCapabilityRank, profileCapabilityRequirement, profileStageDeadlineMillis, } from "./ObservabilityProfile.js";
+export class ObservabilityLifecycleError extends Schema.TaggedError()("ObservabilityLifecycleError", {
+    code: Schema.Literals(["OBS_OBSERVABILITY_STARTUP_FAILED", "OBS_OBSERVABILITY_CLOSED"]),
+    message: Schema.String,
+    adapter: Schema.Option(AdapterName),
+    cause: Schema.Defect(),
+}) {
+}
+const expectedStage = (profile, capability) => capability === "metrics"
+    ? "metrics"
+    : capability === "browser-ingest" && profile.runtime === "browser-global"
+        ? "browser"
+        : "server";
+const invalidAdapter = (code, message) => new InvalidObservabilityConfig({
+    code,
+    field: "adapters",
+    message,
+    rule: "one supported registration for each required external capability",
+});
+const reservedAdapterNames = new Set(["core-traces", "core-metrics"]);
+const cleanupReserveMillis = 1_000;
+const forcedCleanupBudgetMillis = 500;
+const runtimeDisposalReserveMillis = 500;
+const deadlineSafetyMillis = 50;
+export const validateAdapterRegistrationKinds = (registrations, options) => {
+    for (const registration of registrations) {
+        const official = isOfficialAdapterRegistration(registration);
+        const testing = isTestingAdapterRegistration(registration);
+        if (!official && !testing) {
+            return Effect.fail(invalidAdapter("OBS_OBSERVABILITY_ADAPTER_UNSUPPORTED", "The adapter registration is not authentic. Use the package registration factories."));
+        }
+        if (testing && !options.allowTesting) {
+            return Effect.fail(invalidAdapter("OBS_OBSERVABILITY_ADAPTER_TESTING", `Testing adapter "${registration.adapter.name}" cannot run through an official factory. Use a factory from @equipe-tech/observability/testing.`));
+        }
+        if (reservedAdapterNames.has(registration.adapter.name)) {
+            return Effect.fail(invalidAdapter("OBS_OBSERVABILITY_ADAPTER_UNSUPPORTED", `Adapter name "${registration.adapter.name}" is reserved for the built-in lifecycle registry. Choose another adapter name.`));
+        }
+    }
+    return Effect.void;
+};
+export const validateAdapterRegistrations = Effect.fn("validateAdapterRegistrations")(function* (profile, environment, registrations, options) {
+    yield* validateAdapterRegistrationKinds(registrations, options);
+    const names = new Set();
+    const capabilities = new Set();
+    for (const registration of registrations) {
+        const adapter = registration.adapter;
+        if (names.has(adapter.name)) {
+            return yield* Effect.fail(invalidAdapter("OBS_OBSERVABILITY_ADAPTER_DUPLICATE", `Adapter "${adapter.name}" is registered more than once. Use one registration per adapter name.`));
+        }
+        names.add(adapter.name);
+        const requirement = profileCapabilityRequirement(profile, adapter.capability);
+        if (requirement === "forbidden" ||
+            adapter.stage !== expectedStage(profile, adapter.capability) ||
+            !profile.stages.includes(adapter.stage) ||
+            adapter.capability === "traces" ||
+            adapter.capability === "metrics") {
+            return yield* Effect.fail(invalidAdapter("OBS_OBSERVABILITY_ADAPTER_UNSUPPORTED", `${registration.kind === "official" ? "Official" : "Testing"} adapter "${adapter.name}" cannot supply ${adapter.capability} for profile "${profile.name}".`));
+        }
+        if (capabilities.has(adapter.capability)) {
+            return yield* Effect.fail(invalidAdapter("OBS_OBSERVABILITY_ADAPTER_DUPLICATE", `Capability "${adapter.capability}" is registered by more than one adapter. Use one registration per capability.`));
+        }
+        capabilities.add(adapter.capability);
+    }
+    const externalCapabilities = [
+        "events",
+        "defects",
+        "browser-ingest",
+    ];
+    for (const capability of externalCapabilities) {
+        const requirement = profileCapabilityRequirement(profile, capability);
+        const required = requirement === "required" ||
+            (requirement === "required-in-production" && environment === "production");
+        if (required && !capabilities.has(capability)) {
+            return yield* Effect.fail(invalidAdapter("OBS_OBSERVABILITY_ADAPTER_MISSING", `Profile "${profile.name}" requires a ${options.allowTesting ? "registered" : "official"} ${capability} adapter in ${environment}.`));
+        }
+    }
+});
+const adapterFailure = (operation, cause) => Option.getOrElse(Cause.findErrorOption(cause), () => new AdapterFailure({
+    code: "OBS_OBSERVABILITY_ADAPTER_FAILED",
+    message: `Observability adapter ${operation} failed without a typed failure. Fix the adapter implementation before retrying.`,
+    cause,
+}));
+const runtimeFailure = (cause) => new AdapterFailure({
+    code: "OBS_OBSERVABILITY_ADAPTER_FAILED",
+    message: "Observability runtime disposal failed. Inspect the defect before retrying.",
+    cause,
+});
+const ordered = (profile, started, stage) => started
+    .filter((entry) => entry.registration.adapter.stage === stage)
+    .toSorted((left, right) => profileCapabilityRank(profile, stage, left.registration.adapter.capability) -
+    profileCapabilityRank(profile, stage, right.registration.adapter.capability));
+const runParticipant = Effect.fn("runObservabilityParticipant")(function* (entry, operation, budgetMillis) {
+    const adapter = entry.registration.adapter;
+    if (budgetMillis <= 0) {
+        return {
+            participant: "adapter",
+            adapter: adapter.name,
+            capability: adapter.capability,
+            stage: adapter.stage,
+            result: { kind: "deadline-exceeded", budgetMillis: 0 },
+        };
+    }
+    const startedAt = yield* Clock.currentTimeMillis;
+    const effect = operation === "flush" ? entry.handle.flush : entry.handle.close;
+    const result = yield* effect.pipe(Effect.exit, Effect.timeoutOption(budgetMillis));
+    const durationMillis = (yield* Clock.currentTimeMillis) - startedAt;
+    if (Option.isNone(result)) {
+        return {
+            participant: "adapter",
+            adapter: adapter.name,
+            capability: adapter.capability,
+            stage: adapter.stage,
+            result: { kind: "deadline-exceeded", budgetMillis },
+        };
+    }
+    if (result.value._tag === "Failure") {
+        return {
+            participant: "adapter",
+            adapter: adapter.name,
+            capability: adapter.capability,
+            stage: adapter.stage,
+            result: { kind: "failed", error: adapterFailure(operation, result.value.cause) },
+        };
+    }
+    return {
+        participant: "adapter",
+        adapter: adapter.name,
+        capability: adapter.capability,
+        stage: adapter.stage,
+        result: { kind: "completed", durationMillis },
+    };
+});
+const runForcedClose = Effect.fn("runForcedObservabilityClose")(function* (entry, budgetMillis) {
+    const startedAt = yield* Clock.currentTimeMillis;
+    const result = yield* entry.handle.close.pipe(Effect.exit, Effect.timeoutOption(Math.max(0, budgetMillis)));
+    const durationMillis = (yield* Clock.currentTimeMillis) - startedAt;
+    if (Option.isNone(result)) {
+        return { kind: "deadline-exceeded", budgetMillis };
+    }
+    if (result.value._tag === "Failure") {
+        return { kind: "failed", error: adapterFailure("close", result.value.cause) };
+    }
+    return { kind: "completed", durationMillis };
+});
+const runRuntimeDisposal = Effect.fn("runRuntimeDisposal")(function* (disposeRuntime, budgetMillis) {
+    const startedAt = yield* Clock.currentTimeMillis;
+    const result = yield* disposeRuntime.pipe(Effect.exit, Effect.timeoutOption(Math.max(0, budgetMillis)));
+    const durationMillis = (yield* Clock.currentTimeMillis) - startedAt;
+    if (Option.isNone(result)) {
+        return { participant: "runtime-disposal", result: { kind: "deadline-exceeded", budgetMillis } };
+    }
+    if (result.value._tag === "Failure") {
+        return {
+            participant: "runtime-disposal",
+            result: { kind: "failed", error: runtimeFailure(result.value.cause) },
+        };
+    }
+    return { participant: "runtime-disposal", result: { kind: "completed", durationMillis } };
+});
+const coreRegistration = (name, capability, stage, effect) => ({
+    registration: registerOfficialAdapter({
+        name: AdapterName.make(name),
+        capability,
+        stage,
+        start: () => Effect.die("Built-in lifecycle participants are already started."),
+    }),
+    handle: {
+        flush: effect,
+        close: effect,
+        eventLayer: Option.none(),
+        auditLayer: Option.none(),
+        degraded: () => false,
+    },
+});
+export const createLifecycleRegistry = (profile, started, flusher, disposeRuntime) => {
+    const traces = coreRegistration("core-traces", "traces", "server", flusher.flush);
+    const metrics = coreRegistration("core-metrics", "metrics", "metrics", flusher.flush);
+    const participants = [...started, traces, metrics];
+    const run = Effect.fn("LifecycleRegistry.run")(function* (operation) {
+        const startedAt = yield* Clock.currentTimeMillis;
+        const operationalDeadlineMillis = Math.max(0, profile.shutdownDeadlineMillis - deadlineSafetyMillis);
+        const deadline = startedAt + operationalDeadlineMillis;
+        const cleanupReserve = operation === "close" ? Math.min(cleanupReserveMillis, operationalDeadlineMillis) : 0;
+        const runtimeReserve = Math.min(runtimeDisposalReserveMillis, cleanupReserve);
+        const gracefulDeadline = deadline - cleanupReserve;
+        const outcomes = [];
+        const forcedCleanup = [];
+        for (const stage of profile.stages) {
+            const now = yield* Clock.currentTimeMillis;
+            const totalRemaining = Math.max(0, gracefulDeadline - now);
+            const stageBudget = profileStageDeadlineMillis(profile, stage) ?? totalRemaining;
+            const stageDeadline = now + Math.min(totalRemaining, stageBudget);
+            for (const participant of ordered(profile, participants, stage)) {
+                const remaining = Math.max(0, stageDeadline - (yield* Clock.currentTimeMillis));
+                const outcome = yield* runParticipant(participant, operation, remaining);
+                const outcomeIndex = outcomes.push(outcome) - 1;
+                if (operation === "close" && outcome.result.kind === "deadline-exceeded") {
+                    forcedCleanup.push({ outcomeIndex, entry: participant });
+                }
+            }
+        }
+        if (operation === "close") {
+            const forcedDeadline = deadline - runtimeReserve;
+            const forcedBudget = Math.min(forcedCleanupBudgetMillis, Math.max(0, forcedDeadline - (yield* Clock.currentTimeMillis)));
+            const cleanupResults = yield* Effect.forEach(forcedCleanup, (candidate) => runForcedClose(candidate.entry, forcedBudget), { concurrency: "unbounded" });
+            for (let index = 0; index < forcedCleanup.length; index += 1) {
+                const candidate = forcedCleanup[index];
+                const cleanupResult = cleanupResults[index];
+                if (candidate === undefined || cleanupResult === undefined)
+                    continue;
+                const outcome = outcomes[candidate.outcomeIndex];
+                if (outcome?.participant === "adapter" && outcome.result.kind === "deadline-exceeded") {
+                    outcomes[candidate.outcomeIndex] = {
+                        ...outcome,
+                        result: { ...outcome.result, forcedCleanup: cleanupResult },
+                    };
+                }
+            }
+            const remaining = Math.max(0, deadline - (yield* Clock.currentTimeMillis));
+            outcomes.push(yield* runRuntimeDisposal(disposeRuntime, remaining));
+        }
+        const durationMillis = (yield* Clock.currentTimeMillis) - startedAt;
+        return {
+            operation,
+            outcomes,
+            durationMillis,
+            degraded: outcomes.some((outcome) => outcome.result.kind !== "completed") ||
+                started.some((entry) => entry.handle.degraded()),
+        };
+    });
+    return { run };
+};
+export const rollbackStartedAdapters = Effect.fn("rollbackStartedAdapters")(function* (started) {
+    for (const entry of started.toReversed()) {
+        yield* entry.handle.close.pipe(Effect.catch(() => Effect.void));
+    }
+});

package/dist/profile/ObservabilityAdapter.d.ts

@@ -0,0 +1,115 @@
+import { Effect, Layer, ManagedRuntime, Option, Schema } from "effect";
+import type { OtlpExporter } from "effect/unstable/observability";
+import type { CompiledAuditActionDefinition, CompiledEventDefinition } from "../contract/TelemetryContract.js";
+import type { CompiledMetricDefinition } from "../contract/MetricDefinition.js";
+import type { EventName } from "../contract/EventName.js";
+import type { AuditPublisher } from "../audit/AuditPublisher.js";
+import type { TelemetryEventSink } from "../contract/EventProducer.js";
+import type { ResourceIdentity } from "../ResourceIdentity.js";
+import type { TelemetryConfig } from "../TelemetryConfig.js";
+import type { DataPolicy } from "./DataPolicy.js";
+import type { SentryConfig } from "./ObservabilityConfig.js";
+import { InvalidObservabilityConfig } from "./ObservabilityConfigError.js";
+import type { AdapterCapability, LifecycleStage, ObservabilityProfile } from "./ObservabilityProfile.js";
+export declare const AdapterName: Schema.brand<Schema.String, "AdapterName">;
+export type AdapterName = typeof AdapterName.Type;
+declare const AdapterFailure_base: Schema.Class<AdapterFailure, Schema.TaggedStruct<"AdapterFailure", {
+    readonly code: Schema.Literal<"OBS_OBSERVABILITY_ADAPTER_FAILED">;
+    readonly message: Schema.String;
+    readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+export declare class AdapterFailure extends AdapterFailure_base {
+}
+export type ContractRegistry = {
+    readonly version: number;
+    readonly eventNames: ReadonlyArray<EventName>;
+    readonly eventByAlias: ReadonlyMap<string, CompiledEventDefinition>;
+    readonly eventByName: ReadonlyMap<EventName, CompiledEventDefinition>;
+    readonly auditActionByAlias: ReadonlyMap<string, CompiledAuditActionDefinition>;
+    readonly auditActionByName: ReadonlyMap<string, CompiledAuditActionDefinition>;
+    readonly metricByAlias: ReadonlyMap<string, CompiledMetricDefinition>;
+    readonly metricByName: ReadonlyMap<string, CompiledMetricDefinition>;
+};
+export type ObservabilityAdapterContext = {
+    readonly profile: ObservabilityProfile;
+    readonly identity: ResourceIdentity;
+    readonly telemetryConfig: TelemetryConfig;
+    readonly contract: ContractRegistry;
+    readonly policy: DataPolicy;
+    readonly sentry: SentryConfig;
+    readonly runtime: ManagedRuntime.ManagedRuntime<OtlpExporter.Flusher, InvalidObservabilityConfig>;
+};
+export type ObservabilityAdapterHandle = {
+    readonly flush: Effect.Effect<void, AdapterFailure>;
+    readonly close: Effect.Effect<void, AdapterFailure>;
+    readonly eventLayer: Option.Option<Layer.Layer<TelemetryEventSink>>;
+    readonly auditLayer: Option.Option<Layer.Layer<AuditPublisher>>;
+    readonly degraded: () => boolean;
+};
+export type ObservabilityAdapter = {
+    readonly name: AdapterName;
+    readonly capability: AdapterCapability;
+    readonly stage: LifecycleStage;
+    readonly start: (context: ObservabilityAdapterContext) => Effect.Effect<ObservabilityAdapterHandle, AdapterFailure>;
+};
+declare const officialRegistrationBrand: unique symbol;
+declare const testingRegistrationBrand: unique symbol;
+export type OfficialAdapterRegistration = {
+    readonly kind: "official";
+    readonly adapter: ObservabilityAdapter;
+    readonly [officialRegistrationBrand]: true;
+};
+export type TestingAdapterRegistration = {
+    readonly kind: "testing";
+    readonly adapter: ObservabilityAdapter;
+    readonly [testingRegistrationBrand]: true;
+};
+export type AdapterRegistration = OfficialAdapterRegistration | TestingAdapterRegistration;
+export declare const registerOfficialAdapter: (adapter: ObservabilityAdapter) => OfficialAdapterRegistration;
+export declare const registerTestingAdapter: (adapter: ObservabilityAdapter) => TestingAdapterRegistration;
+export declare const isOfficialAdapterRegistration: (registration: AdapterRegistration) => registration is OfficialAdapterRegistration;
+export declare const isTestingAdapterRegistration: (registration: AdapterRegistration) => registration is TestingAdapterRegistration;
+export type LifecycleCleanupResult = {
+    readonly kind: "completed";
+    readonly durationMillis: number;
+} | {
+    readonly kind: "failed";
+    readonly error: AdapterFailure;
+} | {
+    readonly kind: "deadline-exceeded";
+    readonly budgetMillis: number;
+};
+export type LifecycleOutcomeResult = {
+    readonly kind: "completed";
+    readonly durationMillis: number;
+} | {
+    readonly kind: "failed";
+    readonly error: AdapterFailure;
+} | {
+    readonly kind: "deadline-exceeded";
+    readonly budgetMillis: number;
+    readonly forcedCleanup?: LifecycleCleanupResult;
+};
+export type AdapterOutcome = {
+    readonly participant: "adapter";
+    readonly adapter: AdapterName;
+    readonly capability: AdapterCapability;
+    readonly stage: LifecycleStage;
+    readonly result: LifecycleOutcomeResult;
+};
+export type RuntimeDisposalOutcome = {
+    readonly participant: "runtime-disposal";
+    readonly result: LifecycleOutcomeResult;
+};
+export type LifecycleOutcome = AdapterOutcome | RuntimeDisposalOutcome;
+export type LifecycleReport = {
+    readonly operation: "flush" | "close";
+    readonly outcomes: ReadonlyArray<LifecycleOutcome>;
+    readonly durationMillis: number;
+    readonly degraded: boolean;
+};
+export type StartedAdapter = {
+    readonly registration: AdapterRegistration;
+    readonly handle: ObservabilityAdapterHandle;
+};
+export {};

package/dist/profile/ObservabilityAdapter.js

@@ -0,0 +1,50 @@
+import { Option, Predicate, Schema } from "effect";
+import { InvalidObservabilityConfig } from "./ObservabilityConfigError.js";
+export const AdapterName = Schema.String.check(Schema.isPattern(/^[a-z0-9]+(?:-[a-z0-9]+)*$/), Schema.isMaxLength(64)).pipe(Schema.brand("AdapterName"));
+export class AdapterFailure extends Schema.TaggedError()("AdapterFailure", {
+    code: Schema.Literal("OBS_OBSERVABILITY_ADAPTER_FAILED"),
+    message: Schema.String,
+    cause: Schema.Defect(),
+}) {
+}
+const officialRegistrationBrand = Symbol("OfficialAdapterRegistration");
+const testingRegistrationBrand = Symbol("TestingAdapterRegistration");
+const officialRegistrations = new WeakSet();
+const testingRegistrations = new WeakSet();
+const AdapterRegistrationPayload = Schema.Struct({
+    name: AdapterName,
+    capability: Schema.Literals(["events", "traces", "metrics", "defects", "browser-ingest"]),
+    stage: Schema.Literals(["server", "metrics", "browser"]),
+});
+const parseAdapterRegistrationPayload = (adapter) => {
+    const decoded = Schema.decodeUnknownOption(AdapterRegistrationPayload)(adapter);
+    if (Option.isNone(decoded) || !Predicate.isFunction(adapter.start)) {
+        throw new InvalidObservabilityConfig({
+            code: "OBS_OBSERVABILITY_ADAPTER_UNSUPPORTED",
+            field: "adapters",
+            message: "The adapter payload is invalid. Use a valid adapter name, capability, lifecycle stage, and callable start.",
+            rule: "a schema-valid adapter payload with a callable start",
+        });
+    }
+    return Object.freeze(adapter);
+};
+export const registerOfficialAdapter = (adapter) => {
+    const registration = {
+        kind: "official",
+        adapter: parseAdapterRegistrationPayload(adapter),
+        [officialRegistrationBrand]: true,
+    };
+    officialRegistrations.add(registration);
+    return Object.freeze(registration);
+};
+export const registerTestingAdapter = (adapter) => {
+    const registration = {
+        kind: "testing",
+        adapter: parseAdapterRegistrationPayload(adapter),
+        [testingRegistrationBrand]: true,
+    };
+    testingRegistrations.add(registration);
+    return Object.freeze(registration);
+};
+export const isOfficialAdapterRegistration = (registration) => registration.kind === "official" && officialRegistrations.has(registration);
+export const isTestingAdapterRegistration = (registration) => registration.kind === "testing" && testingRegistrations.has(registration);

package/dist/profile/ObservabilityConfig.d.ts

@@ -0,0 +1,68 @@
+import { Effect } from "effect";
+import type { EnvironmentVariables } from "../TelemetryConfig.js";
+import { TelemetryConfig } from "../TelemetryConfig.js";
+import { EnvironmentAliasPolicy, type ResourceIdentity } from "../ResourceIdentity.js";
+import type { ContractRegistry } from "./ObservabilityAdapter.js";
+import { type DataPolicy, type DataPolicyInput } from "./DataPolicy.js";
+import { DuplicateReleaseVariable, InvalidObservabilityConfig } from "./ObservabilityConfigError.js";
+import { type DeploymentScope } from "./EnvironmentPolicy.js";
+import { type NodeObservabilityProfile, type ProfileName } from "./ObservabilityProfile.js";
+export type { DeploymentScope } from "./EnvironmentPolicy.js";
+export type SentryConfig = {
+    readonly enabled: false;
+} | {
+    readonly enabled: true;
+    readonly dsn: URL;
+};
+export type NodeObservabilityConfigDisabled = {
+    readonly enabled: false;
+};
+export type NodeObservabilityConfigEnabled = {
+    readonly enabled: true;
+    readonly profile: NodeObservabilityProfile;
+    readonly deployment: DeploymentScope;
+    readonly identity: ResourceIdentity;
+    readonly telemetry: TelemetryConfig;
+    readonly evlog: {
+        readonly contract: ContractRegistry;
+        readonly policy: DataPolicy;
+    };
+    readonly sentry: SentryConfig;
+};
+export type NodeObservabilityConfig = NodeObservabilityConfigDisabled | NodeObservabilityConfigEnabled;
+export type NodeObservabilityConfigInput = {
+    readonly enabled: false;
+} | {
+    readonly enabled: true;
+    readonly profile: ProfileName;
+    readonly service: {
+        readonly name: string;
+        readonly version: string;
+        readonly environment: string;
+        readonly instance?: string | undefined;
+    };
+    readonly telemetry: {
+        readonly endpoint: URL;
+        readonly environmentAlias?: typeof EnvironmentAliasPolicy.Type | undefined;
+    };
+    readonly evlog: {
+        readonly contract: ContractRegistry;
+        readonly policy: DataPolicyInput;
+    };
+    readonly sentry: {
+        readonly enabled: false;
+    } | {
+        readonly enabled: true;
+        readonly dsn: URL;
+    };
+};
+export type EnvBootstrapInput = {
+    readonly enabled?: boolean | undefined;
+    readonly profile: ProfileName;
+    readonly env: EnvironmentVariables;
+    readonly contract: ContractRegistry;
+    readonly policy: DataPolicyInput;
+    readonly environmentAlias?: typeof EnvironmentAliasPolicy.Type | undefined;
+};
+export declare const parseNodeObservabilityConfig: (input: NodeObservabilityConfigInput) => Effect.Effect<NodeObservabilityConfig, InvalidObservabilityConfig, never>;
+export declare const nodeObservabilityConfigFromEnv: (input: EnvBootstrapInput) => Effect.Effect<NodeObservabilityConfig, DuplicateReleaseVariable | InvalidObservabilityConfig, never>;

package/dist/profile/ObservabilityConfig.js

@@ -0,0 +1,125 @@
+import { Effect, Option, Schema } from "effect";
+import { OtlpEndpoint, TelemetryConfig } from "../TelemetryConfig.js";
+import { parseResourceIdentity, } from "../ResourceIdentity.js";
+import { parseDataPolicy } from "./DataPolicy.js";
+import { InvalidObservabilityConfig, } from "./ObservabilityConfigError.js";
+import { deploymentScopeFromEndpoint, rejectSecondReleaseVariables, resolveEnvironmentPolicy, } from "./EnvironmentPolicy.js";
+import { observabilityProfiles, } from "./ObservabilityProfile.js";
+const decodeServiceName = Schema.decodeUnknownEffect(Schema.NonEmptyString);
+const decodeServiceVersion = Schema.decodeUnknownEffect(Schema.Union([Schema.NonEmptyString, Schema.Undefined]));
+const decodeDeploymentEnvironment = Schema.decodeUnknownEffect(Schema.Union([Schema.NonEmptyString, Schema.Undefined]));
+const decodeServiceInstanceId = Schema.decodeUnknownEffect(Schema.Union([Schema.String, Schema.Undefined]));
+const decodeOtlpEndpoint = Schema.decodeUnknownEffect(Schema.Union([OtlpEndpoint, Schema.Undefined]));
+const decodeSentryDsn = Schema.decodeUnknownEffect(Schema.Union([Schema.URLFromString, Schema.Undefined]));
+const decodeTelemetryConfig = Schema.decodeUnknownEffect(TelemetryConfig);
+const invalid = (field, message, rule, cause) => new InvalidObservabilityConfig({
+    code: field === "profile"
+        ? "OBS_OBSERVABILITY_PROFILE_UNSUPPORTED_RUNTIME"
+        : "OBS_OBSERVABILITY_CONFIG_INVALID",
+    field,
+    message,
+    rule,
+    cause,
+});
+const nodeProfile = (name) => {
+    const selected = observabilityProfiles[name];
+    if (selected.runtime !== "node-global") {
+        return Effect.fail(invalid("profile", `Profile "${name}" does not own a Node global runtime. Use nestjs-api, worker, or cli.`, "a profile that owns a Node global runtime"));
+    }
+    return Effect.succeed(selected);
+};
+const sentryFor = (profile, environment, dsn) => {
+    if (profile.defects === "required-in-production" &&
+        environment === "production" &&
+        dsn === undefined) {
+        return Effect.fail(invalid("SENTRY_DSN", `Profile "${profile.name}" requires SENTRY_DSN in production. Set SENTRY_DSN or use a non-production environment.`, "a Sentry DSN URL for production"));
+    }
+    return Effect.succeed(dsn === undefined ? { enabled: false } : { enabled: true, dsn });
+};
+export const parseNodeObservabilityConfig = Effect.fn("parseNodeObservabilityConfig")(function* (input) {
+    if (!input.enabled) {
+        return { enabled: false };
+    }
+    const profile = yield* nodeProfile(input.profile);
+    const identity = yield* parseResourceIdentity({
+        serviceName: input.service.name,
+        serviceVersion: input.service.version,
+        environment: input.service.environment,
+        instance: Option.fromNullishOr(input.service.instance),
+    }).pipe(Effect.mapError((cause) => invalid(cause.field === "service.name"
+        ? "OTEL_SERVICE_NAME"
+        : cause.field === "service.version"
+            ? "OTEL_SERVICE_VERSION"
+            : cause.field === "service.instance.id"
+                ? "OTEL_SERVICE_INSTANCE_ID"
+                : "OTEL_DEPLOYMENT_ENVIRONMENT", cause.message, cause.rule, cause)));
+    const telemetry = yield* decodeTelemetryConfig({
+        identity,
+        environmentAlias: input.telemetry.environmentAlias ?? "omitted",
+        otlpEndpoint: input.telemetry.endpoint.href,
+    }).pipe(Effect.mapError((cause) => invalid("OTEL_EXPORTER_OTLP_ENDPOINT", "The OTLP endpoint is invalid. Use an HTTP or HTTPS URL without credentials.", "an HTTP or HTTPS URL without credentials", cause)));
+    const deployment = deploymentScopeFromEndpoint(telemetry.otlpEndpoint);
+    const policy = yield* parseDataPolicy(input.evlog.policy).pipe(Effect.mapError((cause) => invalid("policy", "The data policy is invalid. Fix every reported policy issue before starting observability.", "a compiled additive data policy", cause)));
+    const sentry = yield* sentryFor(profile, input.service.environment, input.sentry.enabled ? input.sentry.dsn : undefined);
+    return {
+        enabled: true,
+        profile,
+        deployment,
+        identity,
+        telemetry,
+        evlog: { contract: input.evlog.contract, policy },
+        sentry,
+    };
+});
+export const nodeObservabilityConfigFromEnv = Effect.fn("nodeObservabilityConfigFromEnv")(function* (input) {
+    if (input.enabled === false) {
+        return { enabled: false };
+    }
+    yield* rejectSecondReleaseVariables(input.env);
+    const profile = yield* nodeProfile(input.profile);
+    const serviceName = yield* decodeServiceName(input.env.OTEL_SERVICE_NAME).pipe(Effect.mapError((cause) => invalid("OTEL_SERVICE_NAME", "OTEL_SERVICE_NAME is invalid. Set a non-empty service name.", "a non-empty service name", cause)));
+    const serviceVersion = yield* decodeServiceVersion(input.env.OTEL_SERVICE_VERSION).pipe(Effect.mapError((cause) => invalid("OTEL_SERVICE_VERSION", "OTEL_SERVICE_VERSION is invalid. Set a non-empty release identity.", "a non-empty release identity", cause)));
+    const environment = yield* decodeDeploymentEnvironment(input.env.OTEL_DEPLOYMENT_ENVIRONMENT).pipe(Effect.mapError((cause) => invalid("OTEL_DEPLOYMENT_ENVIRONMENT", "OTEL_DEPLOYMENT_ENVIRONMENT is invalid. Set a non-empty environment name.", "a non-empty environment name", cause)));
+    const serviceInstanceId = yield* decodeServiceInstanceId(input.env.OTEL_SERVICE_INSTANCE_ID).pipe(Effect.mapError((cause) => invalid("OTEL_SERVICE_INSTANCE_ID", "OTEL_SERVICE_INSTANCE_ID is invalid. Set a string instance identifier.", "a string instance identifier", cause)));
+    const endpoint = yield* decodeOtlpEndpoint(input.env.OTEL_EXPORTER_OTLP_ENDPOINT).pipe(Effect.mapError((cause) => invalid("OTEL_EXPORTER_OTLP_ENDPOINT", "OTEL_EXPORTER_OTLP_ENDPOINT is invalid. Use an HTTP or HTTPS URL without credentials.", "an HTTP or HTTPS URL without credentials", cause)));
+    const dsn = yield* decodeSentryDsn(input.env.SENTRY_DSN).pipe(Effect.mapError((cause) => invalid("SENTRY_DSN", "SENTRY_DSN is invalid. Set a valid URL.", "a valid URL", cause)));
+    const resolution = resolveEnvironmentPolicy({
+        endpoint,
+        serviceVersion,
+        environment,
+    });
+    if (resolution.kind === "missing-remote-identity") {
+        if (resolution.missing === "service-version" ||
+            resolution.missing === "service-version-and-environment") {
+            return yield* invalid("OTEL_SERVICE_VERSION", "A remote OTLP endpoint requires OTEL_SERVICE_VERSION. Set it to the deployed release.", "an explicit release identity for a remote endpoint");
+        }
+        return yield* invalid("OTEL_DEPLOYMENT_ENVIRONMENT", "A remote OTLP endpoint requires OTEL_DEPLOYMENT_ENVIRONMENT. Set it to the deployed environment.", "an explicit environment for a remote endpoint");
+    }
+    const identity = yield* parseResourceIdentity({
+        serviceName,
+        serviceVersion: resolution.serviceVersion,
+        environment: resolution.environment,
+        instance: serviceInstanceId === "" ? Option.none() : Option.fromNullishOr(serviceInstanceId),
+    }).pipe(Effect.mapError((cause) => invalid(cause.field === "service.name"
+        ? "OTEL_SERVICE_NAME"
+        : cause.field === "service.version"
+            ? "OTEL_SERVICE_VERSION"
+            : cause.field === "service.instance.id"
+                ? "OTEL_SERVICE_INSTANCE_ID"
+                : "OTEL_DEPLOYMENT_ENVIRONMENT", cause.message, cause.rule, cause)));
+    const policy = yield* parseDataPolicy(input.policy).pipe(Effect.mapError((cause) => invalid("policy", "The data policy is invalid. Fix every reported policy issue before starting observability.", "a compiled additive data policy", cause)));
+    const sentry = yield* sentryFor(profile, resolution.environment, dsn);
+    return {
+        enabled: true,
+        profile,
+        deployment: resolution.deployment,
+        identity,
+        telemetry: new TelemetryConfig({
+            identity,
+            environmentAlias: input.environmentAlias,
+            otlpEndpoint: resolution.endpoint,
+        }),
+        evlog: { contract: input.contract, policy },
+        sentry,
+    };
+});

package/dist/profile/ObservabilityConfigError.d.ts

@@ -0,0 +1,23 @@
+import { Schema } from "effect";
+export declare const ObservabilityConfigField: Schema.Literals<readonly ["profile", "adapters", "policy", "policy.blockedValuePatterns", "OTEL_SERVICE_NAME", "OTEL_SERVICE_VERSION", "OTEL_SERVICE_INSTANCE_ID", "OTEL_DEPLOYMENT_ENVIRONMENT", "OTEL_EXPORTER_OTLP_ENDPOINT", "SENTRY_DSN"]>;
+export type ObservabilityConfigField = typeof ObservabilityConfigField.Type;
+declare const InvalidObservabilityConfig_base: Schema.Class<InvalidObservabilityConfig, Schema.TaggedStruct<"InvalidObservabilityConfig", {
+    readonly code: Schema.Literals<readonly ["OBS_OBSERVABILITY_CONFIG_INVALID", "OBS_OBSERVABILITY_PROFILE_UNSUPPORTED_RUNTIME", "OBS_OBSERVABILITY_ADAPTER_UNSUPPORTED", "OBS_OBSERVABILITY_ADAPTER_MISSING", "OBS_OBSERVABILITY_ADAPTER_DUPLICATE", "OBS_OBSERVABILITY_ADAPTER_TESTING"]>;
+    readonly message: Schema.String;
+    readonly field: Schema.Literals<readonly ["profile", "adapters", "policy", "policy.blockedValuePatterns", "OTEL_SERVICE_NAME", "OTEL_SERVICE_VERSION", "OTEL_SERVICE_INSTANCE_ID", "OTEL_DEPLOYMENT_ENVIRONMENT", "OTEL_EXPORTER_OTLP_ENDPOINT", "SENTRY_DSN"]>;
+    readonly rule: Schema.String;
+    readonly cause: Schema.optionalKey<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+export declare class InvalidObservabilityConfig extends InvalidObservabilityConfig_base {
+}
+export declare const SecondReleaseVariable: Schema.Literals<readonly ["SENTRY_RELEASE", "OTEL_SERVICE_RELEASE"]>;
+export type SecondReleaseVariable = typeof SecondReleaseVariable.Type;
+export declare const secondReleaseVariables: ReadonlyArray<SecondReleaseVariable>;
+declare const DuplicateReleaseVariable_base: Schema.Class<DuplicateReleaseVariable, Schema.TaggedStruct<"DuplicateReleaseVariable", {
+    readonly code: Schema.Literal<"OBS_TELEMETRY_DUPLICATE_RELEASE_VARIABLE">;
+    readonly message: Schema.String;
+    readonly variable: Schema.Literals<readonly ["SENTRY_RELEASE", "OTEL_SERVICE_RELEASE"]>;
+}>, import("effect/Cause").YieldableError>;
+export declare class DuplicateReleaseVariable extends DuplicateReleaseVariable_base {
+}
+export {};

package/dist/profile/ObservabilityConfigError.js

@@ -0,0 +1,39 @@
+import { Schema } from "effect";
+export const ObservabilityConfigField = Schema.Literals([
+    "profile",
+    "adapters",
+    "policy",
+    "policy.blockedValuePatterns",
+    "OTEL_SERVICE_NAME",
+    "OTEL_SERVICE_VERSION",
+    "OTEL_SERVICE_INSTANCE_ID",
+    "OTEL_DEPLOYMENT_ENVIRONMENT",
+    "OTEL_EXPORTER_OTLP_ENDPOINT",
+    "SENTRY_DSN",
+]);
+export class InvalidObservabilityConfig extends Schema.TaggedError()("InvalidObservabilityConfig", {
+    code: Schema.Literals([
+        "OBS_OBSERVABILITY_CONFIG_INVALID",
+        "OBS_OBSERVABILITY_PROFILE_UNSUPPORTED_RUNTIME",
+        "OBS_OBSERVABILITY_ADAPTER_UNSUPPORTED",
+        "OBS_OBSERVABILITY_ADAPTER_MISSING",
+        "OBS_OBSERVABILITY_ADAPTER_DUPLICATE",
+        "OBS_OBSERVABILITY_ADAPTER_TESTING",
+    ]),
+    message: Schema.String,
+    field: ObservabilityConfigField,
+    rule: Schema.String,
+    cause: Schema.Defect().pipe(Schema.optionalKey),
+}) {
+}
+export const SecondReleaseVariable = Schema.Literals(["SENTRY_RELEASE", "OTEL_SERVICE_RELEASE"]);
+export const secondReleaseVariables = [
+    "SENTRY_RELEASE",
+    "OTEL_SERVICE_RELEASE",
+];
+export class DuplicateReleaseVariable extends Schema.TaggedError()("DuplicateReleaseVariable", {
+    code: Schema.Literal("OBS_TELEMETRY_DUPLICATE_RELEASE_VARIABLE"),
+    message: Schema.String,
+    variable: SecondReleaseVariable,
+}) {
+}