autotel-cli 0.14.0 → 0.15.0

package/dist/index.js

@@ -13,6 +13,7 @@ import ora from "ora";
 import * as semver from "semver";
 import { Project, SyntaxKind } from "ts-morph";
 import { fileURLToPath } from "node:url";
+import { JsonTraceSerializer, ProtobufTraceSerializer } from "@opentelemetry/otlp-transformer";
 import { buildCollectorGuide, buildInstrumentationGuide, clearSemanticConventionCache, collectUsage, detectAnomalies, discoverLogFields, discoverServices, discoverTraceFields, findRootCause, getCollectorComponentReadme, getCollectorComponentSchema, getModelStats, getSemanticConventionNamespace, listCollectorComponents, listCollectorVersions, listModels, listSemanticConventionNamespaces, listToolUsage, pickErrorMessage, rankExpensiveTraces, rankSlowTraces, refreshCollectorCatalog, resolveCollectorVersion, scoreSpan, suggestCollectorConfig, suggestInstrumentationFixes, toLogSearchQuery, toMetricSearchQuery, toSpanSearchQuery, toTraceSearchQuery, validateCollectorComponentConfig, validateOtlpReceiverConfig } from "autotel-mcp";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { appendFile, mkdir, readFile, unlink, writeFile } from "node:fs/promises";
@@ -2250,6 +2251,7 @@ const AutotelErrorCodes = {
 	E_INSTALL_FAILED: "AUTOTEL_E_INSTALL_FAILED",
 	E_WRITE_FAILED: "AUTOTEL_E_WRITE_FAILED",
 	E_READ_FAILED: "AUTOTEL_E_READ_FAILED",
+	E_RATE_LIMITED: "AUTOTEL_E_RATE_LIMITED",
 	E_UNKNOWN: "AUTOTEL_E_UNKNOWN"
 };
 /**
@@ -7211,6 +7213,11 @@ const ERROR_CATALOGUE = [
 		type: "io",
 		description: "Failed to read a file"
 	},
+	{
+		code: AutotelErrorCodes.E_RATE_LIMITED,
+		type: "runtime",
+		description: "Backend rate limit outlasted the retry budget — wait and retry"
+	},
 	{
 		code: AutotelErrorCodes.E_UNKNOWN,
 		type: "runtime",
@@ -7377,6 +7384,9 @@ function applyFlagsToEnv(flags) {
 	if (flags.lokiBaseUrl !== void 0) process.env.LOKI_BASE_URL = flags.lokiBaseUrl;
 	if (flags.collectorPort !== void 0) process.env.AUTOTEL_COLLECTOR_PORT = String(flags.collectorPort);
 	if (flags.fixturePath !== void 0) process.env.AUTOTEL_FIXTURE_PATH = flags.fixturePath;
+	if (flags.logfireBaseUrl !== void 0) process.env.LOGFIRE_BASE_URL = flags.logfireBaseUrl;
+	if (flags.datadogSite !== void 0) process.env.DD_SITE = flags.datadogSite;
+	if (flags.signozBaseUrl !== void 0) process.env.SIGNOZ_BASE_URL = flags.signozBaseUrl;
 }
 /**
 * Build a backend from CLI flags/env. Caller is responsible for calling
@@ -7451,10 +7461,17 @@ function toInvestigateError(command, error) {
 			expected: { issues }
 		});
 	}
+	const message = error instanceof Error ? error.message : String(error);
+	if (/\bHTTP 429\b/.test(message)) return new AutotelError({
+		type: "runtime",
+		code: AutotelErrorCodes.E_RATE_LIMITED,
+		message: `autotel ${command} failed: ${message} — the backend rate limit outlasted the retry budget. Wait for the limit window to reset and run the command again.`,
+		retryable: true
+	});
 	return new AutotelError({
 		type: "runtime",
 		code: "AUTOTEL_E_UNKNOWN",
-		message: `autotel ${command} failed: ${error instanceof Error ? error.message : String(error)}`,
+		message: `autotel ${command} failed: ${message}`,
 		retryable: false
 	});
 }
@@ -7472,7 +7489,7 @@ const floatArg = (v) => Number.parseFloat(v);
 * investigate command. Applied to a Command in place (mutates + returns).
 */
 function addBackendFlags(cmd) {
-	return cmd.option("--backend <kind>", "Backend: collector|jaeger|tempo|prometheus|loki|stack|auto|fixture (env: AUTOTEL_BACKEND)").option("--jaeger-base-url <url>", "Jaeger base URL (env: JAEGER_BASE_URL)").option("--tempo-base-url <url>", "Tempo base URL (env: TEMPO_BASE_URL)").option("--prometheus-base-url <url>", "Prometheus base URL (env: PROMETHEUS_BASE_URL)").option("--loki-base-url <url>", "Loki base URL (env: LOKI_BASE_URL)").option("--collector-port <n>", "OTLP receiver port for the collector backend", intArg).option("--fixture-path <path>", "Fixture JSON for the fixture backend").option("--output-file <path>", "Persist JSON output to this file").option("--no-secrets-in-output", "Redact secret-shaped values");
+	return cmd.option("--backend <kind>", "Backend: collector|jaeger|tempo|prometheus|loki|stack|auto|fixture|logfire|datadog|signoz (env: AUTOTEL_BACKEND)").option("--jaeger-base-url <url>", "Jaeger base URL (env: JAEGER_BASE_URL)").option("--tempo-base-url <url>", "Tempo base URL (env: TEMPO_BASE_URL)").option("--prometheus-base-url <url>", "Prometheus base URL (env: PROMETHEUS_BASE_URL)").option("--loki-base-url <url>", "Loki base URL (env: LOKI_BASE_URL)").option("--collector-port <n>", "OTLP receiver port for the collector backend", intArg).option("--fixture-path <path>", "Fixture JSON for the fixture backend").option("--logfire-base-url <url>", "Logfire region URL (env: LOGFIRE_BASE_URL; token via LOGFIRE_READ_TOKEN)").option("--datadog-site <site>", "Datadog site, e.g. datadoghq.eu, or a full API URL (env: DD_SITE; keys via DD_API_KEY + DD_APP_KEY)").option("--signoz-base-url <url>", "SigNoz base URL (env: SIGNOZ_BASE_URL; key via SIGNOZ_API_KEY)").option("--output-file <path>", "Persist JSON output to this file").option("--no-secrets-in-output", "Redact secret-shaped values");
 }
 /**
 * Smaller flag set for commands that don't need a backend (semconv,
@@ -7490,6 +7507,9 @@ function backendFlagsFromOpts(opts) {
 		lokiBaseUrl: opts.lokiBaseUrl,
 		collectorPort: opts.collectorPort,
 		fixturePath: opts.fixturePath,
+		logfireBaseUrl: opts.logfireBaseUrl,
+		datadogSite: opts.datadogSite,
+		signozBaseUrl: opts.signozBaseUrl,
 		outputFile: opts.outputFile,
 		noSecrets: opts.secretsInOutput === false
 	};
@@ -7517,22 +7537,200 @@ function windowFlagsFromOpts(opts) {
 	};
 }
 //#endregion
+//#region src/commands/investigate/freshness.ts
+const PROBE_SPAN_NAME = "autotel.freshness.probe";
+const PROBE_SCOPE = "autotel-cli/freshness";
+/** Nominal probe span duration; a zero-length span reads oddly in a UI. */
+const PROBE_DURATION_MS = 1;
+function randomHex(bytes) {
+	const out = [];
+	for (let index = 0; index < bytes; index++) out.push(Math.floor(Math.random() * 256).toString(16).padStart(2, "0"));
+	return out.join("");
+}
+/** Epoch ms → OTel's `[seconds, nanoseconds]` pair. */
+function toHrTime(ms) {
+	const seconds = Math.floor(ms / 1e3);
+	return [seconds, Math.round((ms - seconds * 1e3) * 1e6)];
+}
+/** One finished span, ready for either serializer. */
+function buildProbeSpan(service, startMs) {
+	const traceId = randomHex(16);
+	const spanId = randomHex(8);
+	return {
+		name: PROBE_SPAN_NAME,
+		kind: 0,
+		spanContext: () => ({
+			traceId,
+			spanId,
+			traceFlags: 1
+		}),
+		parentSpanContext: void 0,
+		startTime: toHrTime(startMs),
+		endTime: toHrTime(startMs + PROBE_DURATION_MS),
+		duration: toHrTime(PROBE_DURATION_MS),
+		status: { code: 0 },
+		attributes: {},
+		links: [],
+		events: [],
+		ended: true,
+		resource: { attributes: { "service.name": service } },
+		instrumentationScope: { name: PROBE_SCOPE },
+		droppedAttributesCount: 0,
+		droppedEventsCount: 0,
+		droppedLinksCount: 0
+	};
+}
+/** Serialize a probe span into an OTLP request body plus its content type. */
+function encodeProbe(span, encoding) {
+	const spans = [span];
+	return encoding === "json" ? {
+		body: JsonTraceSerializer.serializeRequest(spans) ?? /* @__PURE__ */ new Uint8Array(),
+		contentType: "application/json"
+	} : {
+		body: ProtobufTraceSerializer.serializeRequest(spans) ?? /* @__PURE__ */ new Uint8Array(),
+		contentType: "application/x-protobuf"
+	};
+}
+/**
+* Parse the standard `OTEL_EXPORTER_OTLP_HEADERS` format (`k=v,k2=v2`).
+*
+* Hosted OTLP endpoints all require an auth header, and this is the variable
+* users already set for their exporters — so the probe reads the same one
+* rather than inventing a flag that would put a token in argv.
+*/
+function otlpHeadersFromEnv(raw) {
+	const headers = {};
+	for (const pair of (raw ?? "").split(",")) {
+		const separator = pair.indexOf("=");
+		if (separator <= 0) continue;
+		const key = pair.slice(0, separator).trim();
+		const value = pair.slice(separator + 1).trim();
+		if (key === "") continue;
+		headers[key] = value;
+	}
+	return headers;
+}
+/** POST an OTLP/HTTP trace. Kept separate so tests never touch the network. */
+async function sendOtlpTrace(endpoint, span, headers = {}, encoding = "protobuf") {
+	const url = resolveOtlpTraceUrl(endpoint);
+	const { body, contentType } = encodeProbe(span, encoding);
+	const response = await fetch(url, {
+		method: "POST",
+		headers: {
+			"Content-Type": contentType,
+			...headers
+		},
+		body
+	});
+	if (!response.ok) {
+		const otherEncoding = encoding === "json" ? "protobuf" : "json";
+		throw new Error(`OTLP endpoint ${url} rejected the probe span: ${response.status} ${response.statusText}. Sent ${encoding}; if the receiver wants the other encoding, pass --otlp-encoding ${otherEncoding}.`);
+	}
+}
+/** Resolve an OTLP base endpoint without discarding vendor-specific paths. */
+function resolveOtlpTraceUrl(endpoint) {
+	const url = new URL(endpoint);
+	const basePath = url.pathname.replace(/\/+$/, "");
+	if (!basePath.endsWith("/v1/traces")) url.pathname = `${basePath}/v1/traces`;
+	return url.toString();
+}
+const DEFAULT_TIMEOUT_MS = 12e4;
+const DEFAULT_POLL_INTERVAL_MS = 2e3;
+function defaultSleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+const DEADLINE_REACHED = Symbol("freshness-deadline-reached");
+async function beforeDeadline(promise, remainingMs) {
+	if (remainingMs <= 0) return DEADLINE_REACHED;
+	let timer;
+	try {
+		return await Promise.race([promise, new Promise((resolve) => {
+			timer = setTimeout(() => resolve(DEADLINE_REACHED), remainingMs);
+		})]);
+	} finally {
+		if (timer !== void 0) clearTimeout(timer);
+	}
+}
+/**
+* Write one probe span and time how long the backend takes to serve it back.
+*
+* An empty successful read means "not yet". Read failures are surfaced because
+* authentication and configuration errors cannot become fresh by polling.
+*/
+async function measureFreshness(options) {
+	const { backend, otlpEndpoint, encoding = "protobuf", timeoutMs = DEFAULT_TIMEOUT_MS, pollIntervalMs = DEFAULT_POLL_INTERVAL_MS, headers = otlpHeadersFromEnv(process.env.OTEL_EXPORTER_OTLP_HEADERS), now = Date.now, sleep = defaultSleep, send = sendOtlpTrace } = options;
+	const probeService = `autotel-freshness-probe-${randomHex(6)}`;
+	const startedAt = now();
+	const timedOutResult = (attempts) => ({
+		probeService,
+		otlpEndpoint,
+		encoding,
+		timeToQueryableSeconds: null,
+		timedOut: true,
+		attempts,
+		timeoutMs
+	});
+	if (await beforeDeadline(send(otlpEndpoint, buildProbeSpan(probeService, startedAt), headers, encoding), timeoutMs) === DEADLINE_REACHED) return timedOutResult(0);
+	let attempts = 0;
+	for (;;) {
+		attempts++;
+		const remainingMs = timeoutMs - (now() - startedAt);
+		const result = await beforeDeadline(backend.searchTraces({
+			service: probeService,
+			limit: 1
+		}), remainingMs);
+		if (result === DEADLINE_REACHED) return timedOutResult(attempts);
+		if ((result.items?.length ?? 0) > 0) return {
+			probeService,
+			otlpEndpoint,
+			encoding,
+			timeToQueryableSeconds: (now() - startedAt) / 1e3,
+			timedOut: false,
+			attempts,
+			timeoutMs
+		};
+		if (now() - startedAt >= timeoutMs) return timedOutResult(attempts);
+		await sleep(Math.min(pollIntervalMs, timeoutMs - (now() - startedAt)));
+	}
+}
+//#endregion
 //#region src/commands/investigate/health.ts
+function resolvedFreshnessEncoding(requested, backend) {
+	return requested ?? (backend.kind === "collector" ? "json" : "protobuf");
+}
 async function runHealth(flags) {
 	await runInvestigate("health", flags, async (backend) => {
 		const [health, capabilities] = await Promise.all([backend.healthCheck(), Promise.resolve(backend.capabilities())]);
-		return {
+		const base = {
 			...health,
 			signals: capabilities
 		};
+		if (!flags.otlpEndpoint) return base;
+		const encoding = resolvedFreshnessEncoding(flags.otlpEncoding, backend);
+		const freshness = await measureFreshness({
+			backend,
+			otlpEndpoint: flags.otlpEndpoint,
+			timeoutMs: flags.freshnessTimeoutMs,
+			encoding
+		});
+		return {
+			...base,
+			freshness
+		};
 	});
 }
 async function runCapabilities(flags) {
 	await runInvestigate("capabilities", flags, async (backend) => backend.capabilities());
 }
 function registerHealthCommands(program) {
-	const healthCmd = new Command("health").description("Backend health check + signal coverage (JSON)").action(async function() {
-		await runHealth(backendFlagsFromOpts(this.opts()));
+	const healthCmd = new Command("health").description("Backend health check + signal coverage (JSON)").option("--otlp-endpoint <url>", "Also measure ingest-to-queryable lag: write a probe span to this OTLP/HTTP endpoint and poll until it reads back").option("--freshness-timeout-ms <ms>", "Give up waiting for the probe span after this long (default 120000)", (value) => Number.parseInt(value, 10)).option("--otlp-encoding <encoding>", "Probe payload encoding: protobuf (default, and the only one some vendors accept) or json (the built-in collector)").action(async function() {
+		const opts = this.opts();
+		await runHealth({
+			...backendFlagsFromOpts(opts),
+			otlpEndpoint: opts.otlpEndpoint,
+			freshnessTimeoutMs: opts.freshnessTimeoutMs,
+			otlpEncoding: opts.otlpEncoding
+		});
 	});
 	addBackendFlags(healthCmd);
 	program.addCommand(healthCmd);
@@ -9246,5 +9444,3 @@ run().catch((error) => {
 });
 //#endregion
 export {};
-
-//# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autotel-cli",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "CLI for autotel - setup wizard, diagnostics, and incremental features",
   "type": "module",
   "bin": {
@@ -17,6 +17,7 @@
   ],
   "dependencies": {
     "@inquirer/prompts": "^8.5.2",
+    "@opentelemetry/otlp-transformer": "^0.221.0",
     "chalk": "^5.6.2",
     "commander": "^15.0.0",
     "glob": "^13.0.6",
@@ -24,22 +25,22 @@
     "semver": "^7.8.5",
     "ts-morph": "^28.0.0",
     "yaml": "^2.9.0",
-    "autotel-mcp": "0.1.19"
+    "autotel-mcp": "0.2.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@types/eslint-config-prettier": "^6.11.3",
-    "@types/node": "^26.1.1",
+    "@types/node": "^26.1.2",
     "@types/semver": "^7.7.1",
     "eslint": "^10.7.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-unicorn": "^64.0.0",
-    "tsdown": "^0.22.12",
+    "tsdown": "^0.22.14",
     "tsx": "^4.23.1",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.65.0",
     "vitest": "^4.1.10",
-    "autotel-telemetry": "0.1.1"
+    "autotel-telemetry": "0.1.2"
   },
   "engines": {
     "node": ">=22.0.0"