@smithers-orchestrator/observability 0.16.0

package/src/renderPrometheusMetrics.js

@@ -0,0 +1,205 @@
+import { Effect, Metric, MetricState, Option } from "effect";
+import { smithersMetricCatalog, toPrometheusMetricName, updateProcessMetrics, } from "./metrics/index.js";
+/** @typedef {import("./SmithersMetricDefinition.ts").SmithersMetricDefinition} SmithersMetricDefinition */
+
+/**
+ * @param {string} text
+ * @returns {string}
+ */
+function escapePrometheusText(text) {
+    return text.replace(/\\/g, "\\\\").replace(/\n/g, "\\n");
+}
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+function escapePrometheusLabelValue(value) {
+    return escapePrometheusText(value).replace(/"/g, '\\"');
+}
+/**
+ * @param {number | bigint} value
+ * @returns {string}
+ */
+function formatPrometheusNumber(value) {
+    if (typeof value === "bigint")
+        return value.toString();
+    if (Number.isNaN(value))
+        return "NaN";
+    if (value === Number.POSITIVE_INFINITY)
+        return "+Inf";
+    if (value === Number.NEGATIVE_INFINITY)
+        return "-Inf";
+    return String(value);
+}
+/**
+ * @param {ReadonlyArray<[string, string]>} labels
+ * @returns {string}
+ */
+function formatPrometheusLabels(labels) {
+    if (labels.length === 0)
+        return "";
+    return `{${labels
+        .map(([key, value]) => `${toPrometheusMetricName(key)}="${escapePrometheusLabelValue(value)}"`)
+        .join(",")}}`;
+}
+/**
+ * @param {ReadonlyArray<[string, string]>} base
+ * @param {ReadonlyArray<[string, string]>} extra
+ * @returns {string}
+ */
+function mergePrometheusLabels(base, extra) {
+    const merged = [...base, ...extra].sort(([left], [right]) => left.localeCompare(right));
+    return formatPrometheusLabels(merged);
+}
+/**
+ * @param {any} metricKey
+ * @returns {ReadonlyArray<[string, string]>}
+ */
+function metricLabels(metricKey) {
+    const tags = Array.isArray(metricKey?.tags) ? metricKey.tags : [];
+    return tags
+        .map((tag) => [String(tag.key), String(tag.value)])
+        .sort(([left], [right]) => left.localeCompare(right));
+}
+/**
+ * @param {any} metricKey
+ * @returns {string | undefined}
+ */
+function metricHelp(metricKey) {
+    const description = Option.getOrElse(metricKey?.description, () => "");
+    return description.trim() ? description : undefined;
+}
+/**
+ * @param {any} metricState
+ * @returns {PrometheusBucket[]}
+ */
+function histogramBuckets(metricState) {
+    const buckets = [];
+    if (!metricState?.buckets ||
+        typeof metricState.buckets[Symbol.iterator] !== "function") {
+        return buckets;
+    }
+    for (const [boundary, count] of metricState.buckets) {
+        buckets.push({ boundary, count });
+    }
+    return buckets.sort((left, right) => left.boundary - right.boundary);
+}
+/**
+ * @param {SmithersMetricDefinition} definition
+ * @returns {string | undefined}
+ */
+function defaultMetricHelp(definition) {
+    return definition.description ?? definition.label;
+}
+/**
+ * @param {SmithersMetricDefinition} definition
+ * @returns {string[]}
+ */
+function defaultPrometheusMetricLines(definition) {
+    const labelSets = definition.defaultLabels && definition.defaultLabels.length > 0
+        ? definition.defaultLabels.map((labels) => Object.entries(labels))
+        : [[]];
+    if (definition.type === "histogram") {
+        const boundaries = definition.boundaries ?? [];
+        return labelSets.flatMap((labelSet) => {
+            const baseLabels = labelSet;
+            return [
+                ...boundaries.map((boundary) => `${definition.prometheusName}_bucket${mergePrometheusLabels(baseLabels, [["le", String(boundary)]])} 0`),
+                `${definition.prometheusName}_bucket${mergePrometheusLabels(baseLabels, [["le", "+Inf"]])} 0`,
+                `${definition.prometheusName}_sum${formatPrometheusLabels(baseLabels)} 0`,
+                `${definition.prometheusName}_count${formatPrometheusLabels(baseLabels)} 0`,
+            ];
+        });
+    }
+    return labelSets.map((labelSet) => `${definition.prometheusName}${formatPrometheusLabels(labelSet)} 0`);
+}
+/**
+ * @param {Map<string, PrometheusMetricRecord>} registry
+ * @param {string} name
+ * @param {PrometheusMetricType} type
+ * @param {string | undefined} help
+ */
+function registerPrometheusMetric(registry, name, type, help) {
+    const existing = registry.get(name);
+    if (existing) {
+        if (!existing.help && help) {
+            existing.help = help;
+        }
+        return existing;
+    }
+    const created = { type, help, lines: [] };
+    registry.set(name, created);
+    return created;
+}
+/**
+ * @returns {string}
+ */
+export function renderPrometheusMetrics() {
+    // Snapshot process-level gauges before rendering
+    try {
+        Effect.runSync(updateProcessMetrics());
+    }
+    catch { /* non-critical */ }
+    const registry = new Map();
+    for (const snapshot of Metric.unsafeSnapshot()) {
+        const metricKey = snapshot.metricKey;
+        const metricState = snapshot.metricState;
+        const name = toPrometheusMetricName(String(metricKey.name ?? ""));
+        if (!name)
+            continue;
+        const labels = metricLabels(metricKey);
+        const help = metricHelp(metricKey);
+        if (MetricState.isCounterState(metricState)) {
+            const metric = registerPrometheusMetric(registry, name, "counter", help);
+            metric.lines.push(`${name}${formatPrometheusLabels(labels)} ${formatPrometheusNumber(metricState.count)}`);
+            continue;
+        }
+        if (MetricState.isGaugeState(metricState)) {
+            const metric = registerPrometheusMetric(registry, name, "gauge", help);
+            metric.lines.push(`${name}${formatPrometheusLabels(labels)} ${formatPrometheusNumber(metricState.value)}`);
+            continue;
+        }
+        if (MetricState.isHistogramState(metricState)) {
+            const metric = registerPrometheusMetric(registry, name, "histogram", help);
+            for (const bucket of histogramBuckets(metricState)) {
+                metric.lines.push(`${name}_bucket${mergePrometheusLabels(labels, [["le", String(bucket.boundary)]])} ${formatPrometheusNumber(bucket.count)}`);
+            }
+            metric.lines.push(`${name}_bucket${mergePrometheusLabels(labels, [["le", "+Inf"]])} ${formatPrometheusNumber(metricState.count)}`);
+            metric.lines.push(`${name}_sum${formatPrometheusLabels(labels)} ${formatPrometheusNumber(metricState.sum)}`);
+            metric.lines.push(`${name}_count${formatPrometheusLabels(labels)} ${formatPrometheusNumber(metricState.count)}`);
+            continue;
+        }
+        if (MetricState.isFrequencyState(metricState)) {
+            const metric = registerPrometheusMetric(registry, name, "counter", help);
+            for (const [key, count] of metricState.occurrences) {
+                metric.lines.push(`${name}${mergePrometheusLabels(labels, [["key", key]])} ${formatPrometheusNumber(count)}`);
+            }
+            continue;
+        }
+        if (MetricState.isSummaryState(metricState)) {
+            const metric = registerPrometheusMetric(registry, name, "summary", help);
+            metric.lines.push(`${name}${mergePrometheusLabels(labels, [["quantile", "min"]])} ${formatPrometheusNumber(metricState.min)}`);
+            for (const [quantile, value] of metricState.quantiles) {
+                metric.lines.push(`${name}${mergePrometheusLabels(labels, [["quantile", String(quantile)]])} ${formatPrometheusNumber(Option.getOrElse(value, () => 0))}`);
+            }
+            metric.lines.push(`${name}${mergePrometheusLabels(labels, [["quantile", "max"]])} ${formatPrometheusNumber(metricState.max)}`);
+            metric.lines.push(`${name}_sum${formatPrometheusLabels(labels)} ${formatPrometheusNumber(metricState.sum)}`);
+            metric.lines.push(`${name}_count${formatPrometheusLabels(labels)} ${formatPrometheusNumber(metricState.count)}`);
+        }
+    }
+    for (const definition of smithersMetricCatalog) {
+        const metric = registerPrometheusMetric(registry, definition.prometheusName, definition.type, defaultMetricHelp(definition));
+        if (metric.lines.length === 0) {
+            metric.lines.push(...defaultPrometheusMetricLines(definition));
+        }
+    }
+    const lines = [];
+    for (const [name, metric] of [...registry.entries()].sort(([left], [right]) => left.localeCompare(right))) {
+        if (metric.help) {
+            lines.push(`# HELP ${name} ${escapePrometheusText(metric.help)}`);
+        }
+        lines.push(`# TYPE ${name} ${metric.type}`);
+        lines.push(...metric.lines);
+    }
+    return lines.join("\n") + (lines.length > 0 ? "\n" : "");
+}

package/src/resolveSmithersObservabilityOptions.js

@@ -0,0 +1,79 @@
+import { LogLevel } from "effect";
+/** @typedef {import("./SmithersLogFormat.ts").SmithersLogFormat} SmithersLogFormat */
+
+/** @typedef {import("./ResolvedSmithersObservabilityOptions.ts").ResolvedSmithersObservabilityOptions} ResolvedSmithersObservabilityOptions */
+/** @typedef {import("./SmithersObservabilityOptions.ts").SmithersObservabilityOptions} SmithersObservabilityOptions */
+
+/**
+ * @param {LogLevel.LogLevel | string | undefined} value
+ * @returns {LogLevel.LogLevel}
+ */
+function resolveLogLevel(value) {
+    if (typeof value !== "string") {
+        return value ?? LogLevel.Info;
+    }
+    switch (value.toLowerCase()) {
+        case "none":
+            return LogLevel.None;
+        case "trace":
+            return LogLevel.Trace;
+        case "debug":
+            return LogLevel.Debug;
+        case "warning":
+        case "warn":
+            return LogLevel.Warning;
+        case "error":
+            return LogLevel.Error;
+        case "fatal":
+            return LogLevel.Fatal;
+        case "all":
+            return LogLevel.All;
+        case "info":
+        default:
+            return LogLevel.Info;
+    }
+}
+/**
+ * @param {string | undefined} value
+ * @returns {SmithersLogFormat}
+ */
+function resolveLogFormat(value) {
+    switch ((value ?? "").toLowerCase()) {
+        case "json":
+            return "json";
+        case "pretty":
+            return "pretty";
+        case "string":
+            return "string";
+        case "logfmt":
+        default:
+            return "logfmt";
+    }
+}
+/**
+ * @param {boolean | undefined} value
+ * @returns {boolean}
+ */
+function resolveEnabled(value) {
+    if (typeof value === "boolean")
+        return value;
+    const env = (process.env.SMITHERS_OTEL_ENABLED ?? "").toLowerCase();
+    return env === "1" || env === "true";
+}
+/**
+ * @param {SmithersObservabilityOptions} [options]
+ * @returns {ResolvedSmithersObservabilityOptions}
+ */
+export function resolveSmithersObservabilityOptions(options = {}) {
+    return {
+        enabled: resolveEnabled(options.enabled),
+        endpoint: options.endpoint ??
+            process.env.OTEL_EXPORTER_OTLP_ENDPOINT ??
+            "http://localhost:4318",
+        serviceName: options.serviceName ?? process.env.OTEL_SERVICE_NAME ?? "smithers",
+        logFormat: options.logFormat
+            ? resolveLogFormat(options.logFormat)
+            : resolveLogFormat(process.env.SMITHERS_LOG_FORMAT),
+        logLevel: resolveLogLevel(options.logLevel ?? process.env.SMITHERS_LOG_LEVEL),
+    };
+}

package/src/smithersMetrics.js

@@ -0,0 +1,2 @@
+import { smithersMetricCatalog } from "./metrics/index.js";
+export const smithersMetrics = Object.fromEntries(smithersMetricCatalog.map((metric) => [metric.key, metric.metric]));

package/src/smithersSpanNames.js

@@ -0,0 +1,6 @@
+export const smithersSpanNames = {
+    run: "smithers.run",
+    task: "smithers.task",
+    agent: "smithers.agent",
+    tool: "smithers.tool",
+};

package/src/withSmithersSpan.js

@@ -0,0 +1,15 @@
+import { TracingService, withSmithersSpan as withCoreSmithersSpan, } from "./_coreTracing.js";
+import { Effect } from "effect";
+/**
+ * @template A, E, R
+ * @param {string} name
+ * @param {Effect.Effect<A, E, R>} effect
+ * @param {Readonly<Record<string, unknown>>} [attributes]
+ * @param {Omit<Tracer.SpanOptions, "attributes" | "kind"> & { readonly kind?: Tracer.SpanKind; }} [_options]
+ * @returns {Effect.Effect<A, E, Exclude<R, Tracer.ParentSpan>>}
+ */
+export function withSmithersSpan(name, effect, attributes, _options) {
+    return Effect.flatMap(Effect.serviceOption(TracingService), (service) => service._tag === "Some"
+        ? service.value.withSpan(name, effect, attributes ? { ...attributes } : undefined)
+        : withCoreSmithersSpan(name, effect, attributes));
+}