@smithers-orchestrator/observability 0.16.0

package/src/_corePrometheus.js

@@ -0,0 +1,93 @@
+
+/** @typedef {import("./_corePrometheusShape.ts").MetricLabels} MetricLabels */
+/** @typedef {import("./_corePrometheusShape.ts").PrometheusSample} PrometheusSample */
+export {};
+/**
+ * @param {string} name
+ * @returns {string}
+ */
+export function toPrometheusMetricName(name) {
+    const next = name.replace(/[^a-zA-Z0-9_:]/g, "_");
+    return /^[a-zA-Z_:]/.test(next) ? next : `_${next}`;
+}
+/**
+ * @param {string} text
+ * @returns {string}
+ */
+function escapeText(text) {
+    return text.replace(/\\/g, "\\\\").replace(/\n/g, "\\n");
+}
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+function escapeLabelValue(value) {
+    return escapeText(value).replace(/"/g, '\\"');
+}
+/**
+ * @param {number} value
+ * @returns {string}
+ */
+function formatNumber(value) {
+    if (Number.isNaN(value))
+        return "NaN";
+    if (value === Number.POSITIVE_INFINITY)
+        return "+Inf";
+    if (value === Number.NEGATIVE_INFINITY)
+        return "-Inf";
+    return String(value);
+}
+/**
+ * @param {MetricLabels} labels
+ * @returns {string}
+ */
+function formatLabels(labels) {
+    const entries = Object.entries(labels).sort(([left], [right]) => left.localeCompare(right));
+    if (entries.length === 0)
+        return "";
+    return `{${entries
+        .map(([key, value]) => `${toPrometheusMetricName(key)}="${escapeLabelValue(String(value))}"`)
+        .join(",")}}`;
+}
+/**
+ * @param {MetricLabels} labels
+ * @param {MetricLabels} extra
+ * @returns {MetricLabels}
+ */
+function mergeLabels(labels, extra) {
+    return { ...labels, ...extra };
+}
+/**
+ * @param {readonly PrometheusSample[]} samples
+ * @returns {string}
+ */
+export function renderPrometheusSamples(samples) {
+    const grouped = new Map();
+    for (const sample of samples) {
+        const name = toPrometheusMetricName(sample.name);
+        const group = grouped.get(name) ??
+            (() => {
+                const created = { type: sample.type, lines: [] };
+                grouped.set(name, created);
+                return created;
+            })();
+        if (sample.type === "histogram") {
+            const buckets = [...(sample.buckets ?? new Map()).entries()].sort(([left], [right]) => left - right);
+            for (const [boundary, count] of buckets) {
+                group.lines.push(`${name}_bucket${formatLabels(mergeLabels(sample.labels, { le: boundary }))} ${formatNumber(count)}`);
+            }
+            group.lines.push(`${name}_bucket${formatLabels(mergeLabels(sample.labels, { le: "+Inf" }))} ${formatNumber(sample.count ?? 0)}`);
+            group.lines.push(`${name}_sum${formatLabels(sample.labels)} ${formatNumber(sample.sum ?? 0)}`);
+            group.lines.push(`${name}_count${formatLabels(sample.labels)} ${formatNumber(sample.count ?? 0)}`);
+        }
+        else {
+            group.lines.push(`${name}${formatLabels(sample.labels)} ${formatNumber(sample.value ?? 0)}`);
+        }
+    }
+    const lines = [];
+    for (const [name, group] of [...grouped.entries()].sort(([left], [right]) => left.localeCompare(right))) {
+        lines.push(`# TYPE ${name} ${group.type}`);
+        lines.push(...group.lines.sort());
+    }
+    return lines.join("\n") + (lines.length > 0 ? "\n" : "");
+}

package/src/_corePrometheusShape.ts

@@ -0,0 +1,11 @@
+export type MetricLabels = Readonly<Record<string, string | number | boolean>>;
+
+export type PrometheusSample = {
+  readonly name: string;
+  readonly type: "counter" | "gauge" | "histogram";
+  readonly labels: MetricLabels;
+  readonly value?: number;
+  readonly buckets?: ReadonlyMap<number, number>;
+  readonly sum?: number;
+  readonly count?: number;
+};

package/src/_coreTracing.js

@@ -0,0 +1,142 @@
+import { Context, Effect, Layer } from "effect";
+import { correlationContextToLogAnnotations, getCurrentCorrelationContext, withCorrelationContext, } from "./_coreCorrelation/index.js";
+/** @typedef {import("./SmithersLogFormat.ts").SmithersLogFormat} SmithersLogFormat */
+/** @typedef {import("./_coreTracingShape.ts").SmithersSpanAttributesInput} SmithersSpanAttributesInput */
+/** @typedef {import("./_coreTracingShape.ts").TracingServiceShape} TracingServiceShape */
+
+/** @type {"text/plain; version=0.0.4; charset=utf-8"} */
+export const prometheusContentType = "text/plain; version=0.0.4; charset=utf-8";
+/** @type {{ readonly run: "smithers.run"; readonly task: "smithers.task"; readonly agent: "smithers.agent"; readonly tool: "smithers.tool" }} */
+export const smithersSpanNames = {
+    run: "smithers.run",
+    task: "smithers.task",
+    agent: "smithers.agent",
+    tool: "smithers.tool",
+};
+const _TracingServiceBase = /** @type {Context.TagClass<TracingService, "TracingService", TracingServiceShape>} */ (/** @type {unknown} */ (Context.Tag("TracingService")()));
+export class TracingService extends _TracingServiceBase {
+}
+/**
+ * @returns {| Readonly<Record<string, string>> | undefined}
+ */
+export function getCurrentSmithersTraceAnnotations() {
+    const context = getCurrentCorrelationContext();
+    if (!context?.traceId || !context.spanId)
+        return undefined;
+    return { traceId: context.traceId, spanId: context.spanId };
+}
+/**
+ * @param {SmithersSpanAttributesInput} [attributes]
+ * @returns {Record<string, unknown>}
+ */
+export function makeSmithersSpanAttributes(attributes = {}) {
+    const aliases = {
+        runId: "smithers.run_id",
+        run_id: "smithers.run_id",
+        workflowName: "smithers.workflow_name",
+        workflow_name: "smithers.workflow_name",
+        nodeId: "smithers.node_id",
+        node_id: "smithers.node_id",
+        iteration: "smithers.iteration",
+        attempt: "smithers.attempt",
+        nodeLabel: "smithers.node_label",
+        node_label: "smithers.node_label",
+        toolName: "smithers.tool_name",
+        tool_name: "smithers.tool_name",
+        agent: "smithers.agent",
+        model: "smithers.model",
+        status: "smithers.status",
+        waitReason: "smithers.wait_reason",
+        wait_reason: "smithers.wait_reason",
+    };
+    const result = {};
+    for (const [key, value] of Object.entries(attributes)) {
+        if (value !== undefined) {
+            result[key.startsWith("smithers.") ? key : (aliases[key] ?? key)] = value;
+        }
+    }
+    return result;
+}
+/**
+ * @param {SmithersSpanAttributesInput} [attributes]
+ * @returns {attributes is SmithersSpanAttributesInput}
+ */
+function hasAttributes(attributes) {
+    return Boolean(attributes && Object.keys(attributes).length > 0);
+}
+/**
+ * @param {string} name
+ * @param {SmithersSpanAttributesInput} [attributes]
+ * @returns {string}
+ */
+function inferSmithersSpanName(name, attributes) {
+    if (name.startsWith("smithers."))
+        return name;
+    if (name.startsWith("tool:") ||
+        "toolName" in (attributes ?? {}) ||
+        "tool_name" in (attributes ?? {})) {
+        return smithersSpanNames.tool;
+    }
+    if (name.startsWith("agent:") ||
+        name.startsWith("agent.") ||
+        "agent" in (attributes ?? {})) {
+        return smithersSpanNames.agent;
+    }
+    if ("nodeId" in (attributes ?? {}) || "node_id" in (attributes ?? {})) {
+        return smithersSpanNames.task;
+    }
+    if ("runId" in (attributes ?? {}) || "run_id" in (attributes ?? {})) {
+        return smithersSpanNames.run;
+    }
+    return name;
+}
+/**
+ * @param {SmithersSpanAttributesInput} [attributes]
+ * @returns {Effect.Effect<void>}
+ */
+export function annotateSmithersTrace(attributes = {}) {
+    const spanAttributes = makeSmithersSpanAttributes(attributes);
+    let program = Effect.void;
+    if (Object.keys(spanAttributes).length > 0) {
+        program = program.pipe(Effect.tap(() => Effect.annotateCurrentSpan(spanAttributes).pipe(Effect.catchAll(() => Effect.void))));
+    }
+    if (hasAttributes(attributes)) {
+        program = program.pipe(Effect.annotateLogs(attributes));
+    }
+    return program;
+}
+/**
+ * @template A, E, R
+ * @param {string} name
+ * @param {Effect.Effect<A, E, R>} effect
+ * @param {SmithersSpanAttributesInput} [attributes]
+ * @returns {Effect.Effect<A, E, R>}
+ */
+export function withSmithersSpan(name, effect, attributes) {
+    const spanAttributes = makeSmithersSpanAttributes(attributes);
+    const annotations = correlationContextToLogAnnotations(getCurrentCorrelationContext());
+    let program = effect;
+    if (Object.keys(spanAttributes).length > 0) {
+        program = program.pipe(Effect.annotateSpans(spanAttributes));
+    }
+    if (hasAttributes(attributes)) {
+        program = program.pipe(Effect.annotateLogs(attributes));
+    }
+    if (annotations) {
+        program = program.pipe(Effect.annotateLogs(annotations));
+    }
+    return program.pipe(Effect.withLogSpan(name), Effect.withSpan(inferSmithersSpanName(name, attributes)));
+}
+/** @type {Layer.Layer<TracingService, never, never>} */
+export const TracingServiceLive = Layer.succeed(TracingService, {
+    withSpan: (name, effect, attributes) => {
+        return withSmithersSpan(name, effect, attributes);
+    },
+    annotate: (attributes) => {
+        const spanAttributes = makeSmithersSpanAttributes(attributes);
+        return Object.keys(spanAttributes).length > 0
+            ? Effect.annotateCurrentSpan(spanAttributes).pipe(Effect.catchAll(() => Effect.void))
+            : Effect.void;
+    },
+    withCorrelation: (context, effect) => withCorrelationContext(effect, context),
+});

package/src/_coreTracingShape.ts

@@ -0,0 +1,17 @@
+import type { Effect } from "effect";
+import type { CorrelationPatch } from "./_coreCorrelation/CorrelationPatch.ts";
+
+export type SmithersSpanAttributesInput = Readonly<Record<string, unknown>>;
+
+export type TracingServiceShape = {
+  readonly withSpan: <A, E, R>(
+    name: string,
+    effect: Effect.Effect<A, E, R>,
+    attributes?: Record<string, unknown>,
+  ) => Effect.Effect<A, E, R>;
+  readonly annotate: (attributes: Record<string, unknown>) => Effect.Effect<void>;
+  readonly withCorrelation: <A, E, R>(
+    context: CorrelationPatch,
+    effect: Effect.Effect<A, E, R>,
+  ) => Effect.Effect<A, E, R>;
+};

package/src/_smithersSpanAttributeAliases.js

@@ -0,0 +1,19 @@
+export const smithersSpanAttributeAliases = {
+    runId: "smithers.run_id",
+    run_id: "smithers.run_id",
+    workflowName: "smithers.workflow_name",
+    workflow_name: "smithers.workflow_name",
+    nodeId: "smithers.node_id",
+    node_id: "smithers.node_id",
+    iteration: "smithers.iteration",
+    attempt: "smithers.attempt",
+    nodeLabel: "smithers.node_label",
+    node_label: "smithers.node_label",
+    toolName: "smithers.tool_name",
+    tool_name: "smithers.tool_name",
+    agent: "smithers.agent",
+    model: "smithers.model",
+    status: "smithers.status",
+    waitReason: "smithers.wait_reason",
+    wait_reason: "smithers.wait_reason",
+};

package/src/_smithersTraceSpanStorage.js

@@ -0,0 +1,3 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+/** @type {AsyncLocalStorage<import("effect/Tracer").AnySpan>} */
+export const smithersTraceSpanStorage = new AsyncLocalStorage();

package/src/annotateSmithersTrace.js

@@ -0,0 +1,11 @@
+import { TracingService, annotateSmithersTrace as annotateCoreSmithersTrace, } from "./_coreTracing.js";
+import { Effect } from "effect";
+/**
+ * @param {Readonly<Record<string, unknown>>} [attributes]
+ * @returns {Effect.Effect<void>}
+ */
+export function annotateSmithersTrace(attributes = {}) {
+    return Effect.flatMap(Effect.serviceOption(TracingService), (service) => service._tag === "Some"
+        ? service.value.annotate({ ...attributes })
+        : annotateCoreSmithersTrace(attributes));
+}

package/src/correlation.js

@@ -0,0 +1,20 @@
+import { getCurrentCorrelationContext as getCoreCurrentCorrelationContext, mergeCorrelationContext as mergeCoreCorrelationContext, } from "./_coreCorrelation/index.js";
+/** @typedef {import("./_coreCorrelation/CorrelationContext.ts").CorrelationContext} CorrelationContext */
+/** @typedef {import("./_coreCorrelation/CorrelationPatch.ts").CorrelationPatch} CorrelationPatch */
+/** @typedef {CorrelationPatch} CorrelationContextPatch */
+
+export { correlationContextFiberRef, correlationContextToLogAnnotations, CorrelationContextLive, CorrelationContextService, getCurrentCorrelationContext, getCurrentCorrelationContextEffect, mergeCorrelationContext, runWithCorrelationContext, withCorrelationContext, withCurrentCorrelationContext, } from "./_coreCorrelation/index.js";
+/**
+ * @param {CorrelationPatch} patch
+ */
+export function updateCurrentCorrelationContext(patch) {
+    const current = getCoreCurrentCorrelationContext();
+    if (!current)
+        return;
+    // TODO: replace this compatibility shim once legacy callers adopt the
+    // Effect-returning updateCurrentCorrelationContext from @smithers-orchestrator/observability.
+    const next = mergeCoreCorrelationContext(current, patch);
+    if (!next)
+        return;
+    Object.assign(current, next);
+}

package/src/createSmithersObservabilityLayer.js

@@ -0,0 +1,49 @@
+import * as BunContext from "@effect/platform-bun/BunContext";
+import { TracingServiceLive } from "./_coreTracing.js";
+import { Effect, Layer, Logger } from "effect";
+import { SmithersObservability } from "./SmithersObservability.js";
+import { resolveSmithersObservabilityOptions } from "./resolveSmithersObservabilityOptions.js";
+import { createSmithersOtelLayer } from "./createSmithersOtelLayer.js";
+import { MetricsServiceLive } from "./MetricsServiceLive.js";
+import { annotateSmithersTrace } from "./annotateSmithersTrace.js";
+import { withSmithersSpan } from "./withSmithersSpan.js";
+/** @typedef {import("./ResolvedSmithersObservabilityOptions.ts").ResolvedSmithersObservabilityOptions} ResolvedSmithersObservabilityOptions */
+/** @typedef {import("./SmithersLogFormat.ts").SmithersLogFormat} SmithersLogFormat */
+/** @typedef {import("./SmithersObservabilityService.ts").SmithersObservabilityService} SmithersObservabilityService */
+
+/** @typedef {import("./SmithersObservabilityOptions.ts").SmithersObservabilityOptions} SmithersObservabilityOptions */
+
+/**
+ * @param {SmithersLogFormat} format
+ */
+function resolveLogger(format) {
+    switch (format) {
+        case "json":
+            return Logger.withLeveledConsole(Logger.jsonLogger);
+        case "pretty":
+            return Logger.prettyLogger();
+        case "string":
+            return Logger.withLeveledConsole(Logger.stringLogger);
+        case "logfmt":
+        default:
+            return Logger.withLeveledConsole(Logger.logfmtLogger);
+    }
+}
+/**
+ * @param {ResolvedSmithersObservabilityOptions} options
+ * @returns {SmithersObservabilityService}
+ */
+function makeService(options) {
+    return {
+        options,
+        annotate: (attributes) => annotateSmithersTrace(attributes),
+        withSpan: (name, effect, attributes) => withSmithersSpan(name, effect, attributes),
+    };
+}
+/**
+ * @param {SmithersObservabilityOptions} [options]
+ */
+export function createSmithersObservabilityLayer(options = {}) {
+    const resolved = resolveSmithersObservabilityOptions(options);
+    return Layer.mergeAll(BunContext.layer, Logger.replace(Logger.defaultLogger, resolveLogger(resolved.logFormat)), Logger.minimumLogLevel(resolved.logLevel), createSmithersOtelLayer(resolved), MetricsServiceLive, TracingServiceLive, Layer.succeed(SmithersObservability, makeService(resolved)));
+}

package/src/createSmithersOtelLayer.js

@@ -0,0 +1,21 @@
+import * as FetchHttpClient from "@effect/platform/FetchHttpClient";
+import * as Otlp from "@effect/opentelemetry/Otlp";
+import { Layer } from "effect";
+import { smithersTraceSpanStorage } from "./_smithersTraceSpanStorage.js";
+import { resolveSmithersObservabilityOptions } from "./resolveSmithersObservabilityOptions.js";
+/** @typedef {import("./SmithersObservabilityOptions.ts").SmithersObservabilityOptions} SmithersObservabilityOptions */
+
+/**
+ * @param {SmithersObservabilityOptions} [options]
+ */
+export function createSmithersOtelLayer(options = {}) {
+    const resolved = resolveSmithersObservabilityOptions(options);
+    if (!resolved.enabled) {
+        return Layer.empty;
+    }
+    return Otlp.layerJson({
+        baseUrl: resolved.endpoint,
+        resource: { serviceName: resolved.serviceName },
+        tracerContext: (execute, span) => smithersTraceSpanStorage.run(span, execute),
+    }).pipe(Layer.provide(FetchHttpClient.layer));
+}

package/src/createSmithersRuntimeLayer.js

@@ -0,0 +1,2 @@
+import { createSmithersObservabilityLayer } from "./createSmithersObservabilityLayer.js";
+export const createSmithersRuntimeLayer = createSmithersObservabilityLayer;

package/src/getCurrentSmithersTraceAnnotations.js

@@ -0,0 +1,14 @@
+import { getCurrentSmithersTraceSpan } from "./getCurrentSmithersTraceSpan.js";
+/**
+ * @returns {| Readonly<Record<string, string>> | undefined}
+ */
+export function getCurrentSmithersTraceAnnotations() {
+    const span = getCurrentSmithersTraceSpan();
+    if (!span) {
+        return undefined;
+    }
+    return {
+        traceId: span.traceId,
+        spanId: span.spanId,
+    };
+}

package/src/getCurrentSmithersTraceSpan.js

@@ -0,0 +1,7 @@
+import { smithersTraceSpanStorage } from "./_smithersTraceSpanStorage.js";
+/**
+ * @returns {Tracer.AnySpan | undefined}
+ */
+export function getCurrentSmithersTraceSpan() {
+    return smithersTraceSpanStorage.getStore();
+}