@smthrs/observability 0.33.0

package/src/renderPrometheusMetrics.js

@@ -0,0 +1,212 @@
+import { Effect, Metric, Option } from "effect";
+import { smithersMetricCatalog, toPrometheusMetricName, updateProcessMetrics } from "./metrics/index.js";
+/** @typedef {import("./metrics/SmithersMetricDefinition.ts").SmithersMetricDefinition} SmithersMetricDefinition */
+/** @typedef {{ boundary: number; count: number | bigint }} PrometheusBucket */
+/** @typedef {"counter" | "gauge" | "histogram" | "summary"} PrometheusMetricType */
+/** @typedef {{ type: PrometheusMetricType; help: string | undefined; lines: string[] }} PrometheusMetricRecord */
+
+/**
+ * @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 {Record<string, string> | undefined} attributes
+ * @returns {ReadonlyArray<[string, string]>}
+ */
+function metricLabels(attributes) {
+  return Object.entries(attributes ?? {}).sort(([left], [right]) => left.localeCompare(right));
+}
+/**
+ * @param {string | undefined} description
+ * @returns {string | undefined}
+ */
+function metricHelp(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) {
+    // Effect appends a +Inf boundary to every histogram; the explicit +Inf line below emits it.
+    if (!Number.isFinite(boundary)) continue;
+    buckets.push({ boundary, count });
+  }
+  return buckets.sort((left, right) => left.boundary - right.boundary);
+}
+/**
+ * @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 ?? []).filter(Number.isFinite);
+    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 Effect.runSync(Metric.snapshot)) {
+    const metricState = snapshot.state;
+    const name = toPrometheusMetricName(snapshot.id);
+    if (!name) continue;
+    const labels = metricLabels(snapshot.attributes);
+    const help = metricHelp(snapshot.description);
+    if (snapshot.type === "Counter") {
+      const metric = registerPrometheusMetric(registry, name, "counter", help);
+      metric.lines.push(`${name}${formatPrometheusLabels(labels)} ${formatPrometheusNumber(metricState.count)}`);
+      continue;
+    }
+    if (snapshot.type === "Gauge") {
+      const metric = registerPrometheusMetric(registry, name, "gauge", help);
+      metric.lines.push(`${name}${formatPrometheusLabels(labels)} ${formatPrometheusNumber(metricState.value)}`);
+      continue;
+    }
+    if (snapshot.type === "Histogram") {
+      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 (snapshot.type === "Frequency") {
+      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 (snapshot.type === "Summary") {
+      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) {
+    // description is the long-form HELP text; label is the required short human name.
+    const metric = registerPrometheusMetric(
+      registry,
+      definition.prometheusName,
+      definition.type,
+      definition.description ?? definition.label,
+    );
+    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/resolveAgentTraceCapabilities.js

@@ -0,0 +1,59 @@
+import { agentTraceCapabilities } from "./agentTraceCapabilities.js";
+/**
+ * @typedef {import('./agentTrace.ts').AgentFamily} AgentFamily
+ * @typedef {import('./agentTrace.ts').AgentCaptureMode} AgentCaptureMode
+ * @typedef {import('./agentTrace.ts').AgentTraceCapabilityProfile} AgentTraceCapabilityProfile
+ */
+
+/**
+ * @param {AgentFamily} agentFamily
+ * @param {AgentCaptureMode} captureMode
+ * @returns {AgentTraceCapabilityProfile}
+ */
+export function resolveAgentTraceCapabilities(agentFamily, captureMode) {
+  const base = {
+    ...agentTraceCapabilities[agentFamily],
+    // Smithers persists a canonical NDJSON trace artifact for every successful
+    // flush regardless of the upstream agent family.
+    persistedSessionArtifact: true,
+  };
+  if (captureMode === "sdk-events" || captureMode === "cli-text") {
+    return base;
+  }
+  if (agentFamily === "codex") {
+    return {
+      ...base,
+      assistantTextDeltas: captureMode === "cli-json-stream",
+      toolExecutionStart: captureMode === "cli-json-stream",
+      toolExecutionUpdate: captureMode === "cli-json-stream",
+      toolExecutionEnd: captureMode === "cli-json-stream",
+    };
+  }
+  if (agentFamily === "claude-code") {
+    return {
+      ...base,
+      toolExecutionStart: captureMode === "cli-json-stream",
+      toolExecutionUpdate: captureMode === "cli-json-stream",
+      toolExecutionEnd: captureMode === "cli-json-stream",
+    };
+  }
+  if (agentFamily === "gemini" || agentFamily === "antigravity") {
+    return {
+      ...base,
+      assistantTextDeltas: captureMode === "cli-json-stream",
+      toolExecutionStart: captureMode === "cli-json-stream",
+      toolExecutionUpdate: captureMode === "cli-json-stream",
+      toolExecutionEnd: captureMode === "cli-json-stream",
+    };
+  }
+  if (agentFamily === "kimi") {
+    return {
+      ...base,
+      assistantTextDeltas: captureMode === "cli-json-stream",
+      toolExecutionStart: captureMode === "cli-json-stream",
+      toolExecutionUpdate: captureMode === "cli-json-stream",
+      toolExecutionEnd: captureMode === "cli-json-stream",
+    };
+  }
+  return base;
+}

package/src/resolveSmithersObservabilityOptions.js

@@ -0,0 +1,109 @@
+import { LogLevel } from "effect";
+/** @typedef {import("./SmithersLogFormat.ts").SmithersLogFormat} SmithersLogFormat */
+
+/** @typedef {import("./ResolvedSmithersObservabilityOptions.ts").ResolvedSmithersObservabilityOptions} ResolvedSmithersObservabilityOptions */
+/** @typedef {import("./SmithersObservabilityOptions.ts").SmithersObservabilityOptions} SmithersObservabilityOptions */
+
+// 4318 is the OTLP/HTTP receiver port of the local collector started by
+// `smithers observability` (docker-compose.otel.yml).
+const DEFAULT_OTLP_HTTP_ENDPOINT = "http://localhost:4318";
+
+/**
+ * @param {LogLevel.LogLevel | string | undefined} value
+ * @returns {LogLevel.LogLevel}
+ */
+function resolveLogLevel(value) {
+  if (typeof value !== "string") {
+    return value ?? "Info";
+  }
+  switch (value.toLowerCase()) {
+    case "none":
+      return "None";
+    case "trace":
+      return "Trace";
+    case "debug":
+      return "Debug";
+    case "warning":
+    case "warn":
+      return "Warn";
+    case "error":
+      return "Error";
+    case "fatal":
+      return "Fatal";
+    case "all":
+      return "All";
+    case "info":
+    default:
+      return "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 {string | undefined} value
+ * @returns {Record<string, string> | undefined}
+ */
+export function parseOtlpHeaders(value) {
+  if (!value) {
+    return undefined;
+  }
+  /** @type {Record<string, string>} */
+  const headers = {};
+  for (const entry of value.split(",")) {
+    const separator = entry.indexOf("=");
+    if (separator === -1) {
+      continue;
+    }
+    const key = entry.slice(0, separator).trim();
+    if (!key) {
+      continue;
+    }
+    try {
+      headers[key] = decodeURIComponent(entry.slice(separator + 1).trim());
+    } catch {
+      continue;
+    }
+  }
+  return Object.keys(headers).length > 0 ? headers : undefined;
+}
+/**
+ * @param {SmithersObservabilityOptions} [options]
+ * @returns {ResolvedSmithersObservabilityOptions}
+ */
+export function resolveSmithersObservabilityOptions(options = {}) {
+  return {
+    enabled: resolveEnabled(options.enabled),
+    endpoint: options.endpoint ?? process.env.OTEL_EXPORTER_OTLP_ENDPOINT ?? DEFAULT_OTLP_HTTP_ENDPOINT,
+    headers: options.headers ?? parseOtlpHeaders(process.env.OTEL_EXPORTER_OTLP_HEADERS),
+    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),
+    installLogger: options.installLogger !== false,
+  };
+}

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/unsupportedKindsForCapabilities.js

@@ -0,0 +1,32 @@
+/**
+ * @typedef {import('./agentTrace.ts').AgentTraceCapabilityProfile} AgentTraceCapabilityProfile
+ * @typedef {import('./agentTrace.ts').CanonicalAgentTraceEventKind} CanonicalAgentTraceEventKind
+ */
+
+/** @type {Array<[keyof AgentTraceCapabilityProfile, CanonicalAgentTraceEventKind[]]>} */
+const capabilityKindMap = [
+  ["sessionMetadata", ["session.start", "session.end"]],
+  ["assistantTextDeltas", ["assistant.text.delta"]],
+  ["visibleThinkingDeltas", ["assistant.thinking.delta"]],
+  ["finalAssistantMessage", ["assistant.message.final"]],
+  ["toolExecutionStart", ["tool.execution.start"]],
+  ["toolExecutionUpdate", ["tool.execution.update"]],
+  ["toolExecutionEnd", ["tool.execution.end", "tool.result"]],
+  ["retryEvents", ["retry.start", "retry.end"]],
+  ["compactionEvents", ["compaction.start", "compaction.end"]],
+  ["rawStderrDiagnostics", ["stderr"]],
+  ["persistedSessionArtifact", ["artifact.created"]],
+];
+
+/**
+ * @param {AgentTraceCapabilityProfile} profile
+ * @returns {CanonicalAgentTraceEventKind[]}
+ */
+export function unsupportedKindsForCapabilities(profile) {
+  /** @type {CanonicalAgentTraceEventKind[]} */
+  const kinds = [];
+  for (const [field, mappedKinds] of capabilityKindMap) {
+    if (!profile[field]) kinds.push(...mappedKinds);
+  }
+  return kinds;
+}

package/src/withSmithersSpan.js

@@ -0,0 +1,17 @@
+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<import("effect/Tracer").SpanOptions, "attributes" | "kind"> & { readonly kind?: import("effect/Tracer").SpanKind; }} [_options]
+ * @returns {Effect.Effect<A, E, Exclude<R, import("effect/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),
+  );
+}

package/tempo/tempo.yml

@@ -0,0 +1,17 @@
+server:
+  http_listen_port: 3200
+
+distributor:
+  receivers:
+    otlp:
+      protocols:
+        grpc:
+          endpoint: "0.0.0.0:4317"
+
+storage:
+  trace:
+    backend: local
+    local:
+      path: /tmp/tempo/blocks
+    wal:
+      path: /tmp/tempo/wal