@smthrs/observability 0.35.0 → 1.0.0-rc.4

package/src/renderPrometheusMetrics.js

@@ -1,212 +0,0 @@
-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

@@ -1,59 +0,0 @@
-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

@@ -1,109 +0,0 @@
-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

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

package/src/smithersSpanNames.js

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

package/src/unsupportedKindsForCapabilities.js

@@ -1,32 +0,0 @@
-/**
- * @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

@@ -1,17 +0,0 @@
-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

@@ -1,17 +0,0 @@
-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