@smithers-orchestrator/observability 0.16.0

package/src/SmithersMetricUnit.ts

@@ -0,0 +1,8 @@
+export type SmithersMetricUnit =
+  | "count"
+  | "milliseconds"
+  | "seconds"
+  | "bytes"
+  | "tokens"
+  | "ratio"
+  | "depth";

package/src/SmithersObservability.js

@@ -0,0 +1,6 @@
+import { Context } from "effect";
+/** @typedef {import("./SmithersObservabilityService.ts").SmithersObservabilityService} SmithersObservabilityService */
+
+const _SmithersObservabilityBase = /** @type {Context.TagClass<SmithersObservability, "SmithersObservability", SmithersObservabilityService>} */ (/** @type {unknown} */ (Context.Tag("SmithersObservability")()));
+export class SmithersObservability extends _SmithersObservabilityBase {
+}

package/src/SmithersObservabilityOptions.ts

@@ -0,0 +1,10 @@
+import type { LogLevel } from "effect";
+import type { SmithersLogFormat } from "./SmithersLogFormat";
+
+export type SmithersObservabilityOptions = {
+  readonly enabled?: boolean;
+  readonly endpoint?: string;
+  readonly serviceName?: string;
+  readonly logFormat?: SmithersLogFormat;
+  readonly logLevel?: LogLevel.LogLevel | string;
+};

package/src/SmithersObservabilityService.ts

@@ -0,0 +1,15 @@
+import type { Effect } from "effect";
+import type * as Tracer from "effect/Tracer";
+import type { ResolvedSmithersObservabilityOptions } from "./ResolvedSmithersObservabilityOptions";
+
+export type SmithersObservabilityService = {
+  readonly options: ResolvedSmithersObservabilityOptions;
+  readonly annotate: (
+    attributes: Readonly<Record<string, unknown>>,
+  ) => Effect.Effect<void>;
+  readonly withSpan: <A, E, R>(
+    name: string,
+    effect: Effect.Effect<A, E, R>,
+    attributes?: Readonly<Record<string, unknown>>,
+  ) => Effect.Effect<A, E, Exclude<R, Tracer.ParentSpan>>;
+};

package/src/_coreCorrelation/CorrelationContext.ts

@@ -0,0 +1,10 @@
+export type CorrelationContext = {
+  runId: string;
+  nodeId?: string;
+  iteration?: number;
+  attempt?: number;
+  workflowName?: string;
+  parentRunId?: string;
+  traceId?: string;
+  spanId?: string;
+};

package/src/_coreCorrelation/CorrelationContextLive.js

@@ -0,0 +1,11 @@
+import { Layer } from "effect";
+import { CorrelationContextService } from "./CorrelationContextService.js";
+import { correlationContextToLogAnnotations } from "./correlationContextToLogAnnotations.js";
+import { getCurrentCorrelationContextEffect } from "./getCurrentCorrelationContextEffect.js";
+import { withCorrelationContext } from "./withCorrelationContext.js";
+/** @type {Layer.Layer<CorrelationContextService, never, never>} */
+export const CorrelationContextLive = Layer.succeed(CorrelationContextService, {
+    current: () => getCurrentCorrelationContextEffect(),
+    withCorrelation: (patch, effect) => withCorrelationContext(effect, patch),
+    toLogAnnotations: correlationContextToLogAnnotations,
+});

package/src/_coreCorrelation/CorrelationContextService.js

@@ -0,0 +1,6 @@
+import { Context } from "effect";
+/** @typedef {import("./CorrelationContextServiceShape.ts").CorrelationContextServiceShape} CorrelationContextServiceShape */
+
+const _CorrelationContextServiceBase = /** @type {Context.TagClass<CorrelationContextService, "CorrelationContextService", CorrelationContextServiceShape>} */ (/** @type {unknown} */ (Context.Tag("CorrelationContextService")()));
+export class CorrelationContextService extends _CorrelationContextServiceBase {
+}

package/src/_coreCorrelation/CorrelationContextServiceShape.ts

@@ -0,0 +1,14 @@
+import type { Effect } from "effect";
+import type { CorrelationContext } from "./CorrelationContext.ts";
+import type { CorrelationPatch } from "./CorrelationPatch.ts";
+
+export type CorrelationContextServiceShape = {
+  readonly current: () => Effect.Effect<CorrelationContext | undefined>;
+  readonly withCorrelation: <A, E, R>(
+    patch: CorrelationPatch,
+    effect: Effect.Effect<A, E, R>,
+  ) => Effect.Effect<A, E, R>;
+  readonly toLogAnnotations: (
+    context?: CorrelationContext | null,
+  ) => Record<string, unknown> | undefined;
+};

package/src/_coreCorrelation/CorrelationPatch.ts

@@ -0,0 +1,3 @@
+import type { CorrelationContext } from "./CorrelationContext.ts";
+
+export type CorrelationPatch = Partial<CorrelationContext> | undefined | null;

package/src/_coreCorrelation/_correlationStorage.js

@@ -0,0 +1,4 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+/** @typedef {import("./CorrelationContext.ts").CorrelationContext} CorrelationContext */
+/** @type {AsyncLocalStorage<CorrelationContext>} */
+export const correlationStorage = new AsyncLocalStorage();

package/src/_coreCorrelation/correlationContextFiberRef.js

@@ -0,0 +1,2 @@
+import { FiberRef } from "effect";
+export const correlationContextFiberRef = FiberRef.unsafeMake(undefined);

package/src/_coreCorrelation/correlationContextToLogAnnotations.js

@@ -0,0 +1,28 @@
+
+/** @typedef {import("./CorrelationContext.ts").CorrelationContext} CorrelationContext */
+/**
+ * @param {CorrelationContext | null} [context]
+ * @returns {Record<string, unknown> | undefined}
+ */
+export function correlationContextToLogAnnotations(context) {
+    if (!context)
+        return undefined;
+    const annotations = {};
+    if (context.runId)
+        annotations.runId = context.runId;
+    if (context.nodeId)
+        annotations.nodeId = context.nodeId;
+    if (context.workflowName)
+        annotations.workflowName = context.workflowName;
+    if (context.parentRunId)
+        annotations.parentRunId = context.parentRunId;
+    if (context.traceId)
+        annotations.traceId = context.traceId;
+    if (context.spanId)
+        annotations.spanId = context.spanId;
+    if (typeof context.iteration === "number")
+        annotations.iteration = context.iteration;
+    if (typeof context.attempt === "number")
+        annotations.attempt = context.attempt;
+    return Object.keys(annotations).length > 0 ? annotations : undefined;
+}

package/src/_coreCorrelation/getCurrentCorrelationContext.js

@@ -0,0 +1,9 @@
+import { correlationStorage } from "./_correlationStorage.js";
+/** @typedef {import("./CorrelationContext.ts").CorrelationContext} CorrelationContext */
+
+/**
+ * @returns {CorrelationContext | undefined}
+ */
+export function getCurrentCorrelationContext() {
+    return correlationStorage.getStore();
+}

package/src/_coreCorrelation/getCurrentCorrelationContextEffect.js

@@ -0,0 +1,11 @@
+import { Effect, FiberRef } from "effect";
+import { correlationContextFiberRef } from "./correlationContextFiberRef.js";
+import { correlationStorage } from "./_correlationStorage.js";
+/** @typedef {import("./CorrelationContext.ts").CorrelationContext} CorrelationContext */
+
+/**
+ * @returns {Effect.Effect< CorrelationContext | undefined >}
+ */
+export function getCurrentCorrelationContextEffect() {
+    return FiberRef.get(correlationContextFiberRef).pipe(Effect.map((fiberContext) => fiberContext ?? correlationStorage.getStore()));
+}

package/src/_coreCorrelation/index.js

@@ -0,0 +1,14 @@
+/** @typedef {import("./CorrelationContext.ts").CorrelationContext} CorrelationContext */
+/** @typedef {import("./CorrelationPatch.ts").CorrelationPatch} CorrelationPatch */
+
+export { correlationContextFiberRef } from "./correlationContextFiberRef.js";
+export { CorrelationContextService } from "./CorrelationContextService.js";
+export { CorrelationContextLive } from "./CorrelationContextLive.js";
+export { mergeCorrelationContext } from "./mergeCorrelationContext.js";
+export { getCurrentCorrelationContext } from "./getCurrentCorrelationContext.js";
+export { getCurrentCorrelationContextEffect } from "./getCurrentCorrelationContextEffect.js";
+export { updateCurrentCorrelationContext } from "./updateCurrentCorrelationContext.js";
+export { runWithCorrelationContext } from "./runWithCorrelationContext.js";
+export { withCorrelationContext } from "./withCorrelationContext.js";
+export { withCurrentCorrelationContext } from "./withCurrentCorrelationContext.js";
+export { correlationContextToLogAnnotations } from "./correlationContextToLogAnnotations.js";

package/src/_coreCorrelation/mergeCorrelationContext.js

@@ -0,0 +1,61 @@
+
+/** @typedef {import("./CorrelationContext.ts").CorrelationContext} CorrelationContext */
+/** @typedef {import("./CorrelationPatch.ts").CorrelationPatch} CorrelationPatch */
+/**
+ * @param {unknown} value
+ * @returns {string | undefined}
+ */
+function cleanString(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+/**
+ * @param {unknown} value
+ * @returns {number | undefined}
+ */
+function cleanNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+/**
+ * @param {CorrelationPatch} patch
+ * @returns {Partial<CorrelationContext> | undefined}
+ */
+function normalizePatch(patch) {
+    if (!patch)
+        return undefined;
+    const normalized = {};
+    const runId = cleanString(patch.runId);
+    const nodeId = cleanString(patch.nodeId);
+    const workflowName = cleanString(patch.workflowName);
+    const parentRunId = cleanString(patch.parentRunId);
+    const traceId = cleanString(patch.traceId);
+    const spanId = cleanString(patch.spanId);
+    const iteration = cleanNumber(patch.iteration);
+    const attempt = cleanNumber(patch.attempt);
+    if (runId)
+        normalized.runId = runId;
+    if (nodeId)
+        normalized.nodeId = nodeId;
+    if (workflowName)
+        normalized.workflowName = workflowName;
+    if (parentRunId)
+        normalized.parentRunId = parentRunId;
+    if (traceId)
+        normalized.traceId = traceId;
+    if (spanId)
+        normalized.spanId = spanId;
+    if (iteration !== undefined)
+        normalized.iteration = iteration;
+    if (attempt !== undefined)
+        normalized.attempt = attempt;
+    return Object.keys(normalized).length > 0 ? normalized : undefined;
+}
+/**
+ * @param {CorrelationContext | null} [base]
+ * @param {CorrelationPatch} [patch]
+ * @returns {CorrelationContext | undefined}
+ */
+export function mergeCorrelationContext(base, patch) {
+    const normalizedPatch = normalizePatch(patch);
+    const merged = { ...base, ...normalizedPatch };
+    return merged.runId ? merged : undefined;
+}

package/src/_coreCorrelation/runWithCorrelationContext.js

@@ -0,0 +1,14 @@
+import { correlationStorage } from "./_correlationStorage.js";
+import { mergeCorrelationContext } from "./mergeCorrelationContext.js";
+/** @typedef {import("./CorrelationPatch.ts").CorrelationPatch} CorrelationPatch */
+
+/**
+ * @template T
+ * @param {CorrelationPatch} patch
+ * @param {() => T} fn
+ * @returns {T}
+ */
+export function runWithCorrelationContext(patch, fn) {
+    const next = mergeCorrelationContext(correlationStorage.getStore(), patch);
+    return next ? correlationStorage.run(next, fn) : fn();
+}

package/src/_coreCorrelation/updateCurrentCorrelationContext.js

@@ -0,0 +1,19 @@
+import { Effect, FiberRef } from "effect";
+import { correlationContextFiberRef } from "./correlationContextFiberRef.js";
+import { getCurrentCorrelationContextEffect } from "./getCurrentCorrelationContextEffect.js";
+import { mergeCorrelationContext } from "./mergeCorrelationContext.js";
+/** @typedef {import("./CorrelationContext.ts").CorrelationContext} CorrelationContext */
+/** @typedef {import("./CorrelationPatch.ts").CorrelationPatch} CorrelationPatch */
+
+/**
+ * @param {CorrelationPatch} patch
+ * @returns {Effect.Effect<CorrelationContext | undefined>}
+ */
+export function updateCurrentCorrelationContext(patch) {
+    return Effect.gen(function* () {
+        const current = yield* getCurrentCorrelationContextEffect();
+        const next = mergeCorrelationContext(current, patch);
+        yield* FiberRef.set(correlationContextFiberRef, next);
+        return next;
+    });
+}

package/src/_coreCorrelation/withCorrelationContext.js

@@ -0,0 +1,15 @@
+import { Effect } from "effect";
+import { correlationContextFiberRef } from "./correlationContextFiberRef.js";
+import { correlationStorage } from "./_correlationStorage.js";
+import { mergeCorrelationContext } from "./mergeCorrelationContext.js";
+/** @typedef {import("./CorrelationPatch.ts").CorrelationPatch} CorrelationPatch */
+
+/**
+ * @template A, E, R
+ * @param {Effect.Effect<A, E, R>} effect
+ * @param {CorrelationPatch} patch
+ */
+export function withCorrelationContext(effect, patch) {
+    const next = mergeCorrelationContext(correlationStorage.getStore(), patch);
+    return next ? effect.pipe(Effect.locally(correlationContextFiberRef, next)) : effect;
+}

package/src/_coreCorrelation/withCurrentCorrelationContext.js

@@ -0,0 +1,13 @@
+import { Effect } from "effect";
+import { correlationContextFiberRef } from "./correlationContextFiberRef.js";
+import { correlationStorage } from "./_correlationStorage.js";
+/**
+ * @template A, E, R
+ * @param {Effect.Effect<A, E, R>} effect
+ */
+export function withCurrentCorrelationContext(effect) {
+    const current = correlationStorage.getStore();
+    return current
+        ? effect.pipe(Effect.locally(correlationContextFiberRef, current))
+        : effect;
+}