@blogic-cz/agent-tools 0.12.1 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blogic-cz/agent-tools",
-  "version": "0.12.1",
+  "version": "0.13.0",
   "description": "CLI tools for AI coding agent workflows — GitHub, database, Kubernetes, Azure DevOps, logs, sessions, and audit",
   "keywords": [
     "agent",

package/src/observability-tool/trace.ts

@@ -1,7 +1,8 @@
-import { Console, Effect } from "effect";
+import { Console, Effect, type Option } from "effect";
 import { Argument, Command, Flag } from "effect/unstable/cli";
 
 import { formatOption, formatOutput } from "#shared";
+import type { OutputFormat } from "#shared";
 
 import { ObservabilityToolError } from "./errors";
 import {
@@ -14,14 +15,31 @@ import {
 } from "./shared";
 import type {
   FlattenedSpan,
+  ObservabilityEnvConfig,
   OtlpAnyValue,
   OtlpAttribute,
+  ParsedId,
+  SearchWindow,
+  SpanResolution,
+  TempoSearchResponse,
   TempoTraceResponse,
   TraceSummary,
 } from "./types";
 
-function isHexTraceId(value: string): boolean {
-  return /^[\da-f]{32}$/i.test(value);
+const SPAN_SEARCH_WINDOWS: SearchWindow[] = [
+  { start: "now-1h", end: "now" },
+  { start: "now-24h", end: "now" },
+];
+
+function parseId(value: string): ParsedId | undefined {
+  const trimmed = value.trim().toLowerCase();
+  if (/^[\da-f]{32}$/.test(trimmed)) {
+    return { rawId: value, normalizedId: trimmed, kind: "trace_id" };
+  }
+  if (/^[\da-f]{16}$/.test(trimmed)) {
+    return { rawId: value, normalizedId: trimmed, kind: "span_id" };
+  }
+  return undefined;
 }
 
 function getStringAttribute(
@@ -111,6 +129,16 @@ function computeDurationMs(start?: string, end?: string): number | undefined {
   return Number(endNano - startNano) / 1_000_000;
 }
 
+function relativeToEpoch(value: string, nowEpoch: number): number {
+  const match = /^now-(\d+)([smhd])$/.exec(value.trim());
+  if (!match) return nowEpoch;
+
+  const amount = Number(match[1]);
+  const unit = match[2];
+  const multipliers: Record<string, number> = { s: 1, m: 60, h: 3600, d: 86400 };
+  return nowEpoch - amount * (multipliers[unit] ?? 1);
+}
+
 function isErrorStatus(code?: string | number): boolean {
   if (code === undefined) return false;
   if (typeof code === "number") return code === 2;
@@ -205,72 +233,207 @@ function parseLabel(value: string | Record<string, string>): Record<string, stri
   }
 }
 
-const getCommand = Command.make(
-  "get",
-  {
-    traceId: Argument.string("traceId"),
-    format: formatOption,
-    env: envOption,
-    profile: profileOption,
-  },
-  ({ traceId, format, env, profile }) => {
-    const startedAt = Date.now();
+type ResolvedTrace = {
+  readonly resolution: SpanResolution;
+  readonly spans: FlattenedSpan[];
+};
+
+function searchTempoBySpanId(
+  config: ObservabilityEnvConfig,
+  spanId: string,
+  window: SearchWindow,
+): Effect.Effect<TempoSearchResponse, ObservabilityToolError> {
+  const now = Math.floor(Date.now() / 1000);
+  const startEpoch = relativeToEpoch(window.start, now);
+  const endEpoch = relativeToEpoch(window.end, now);
+  const traceql = encodeURIComponent(`{ span:id = "${spanId}" }`);
+  const searchUrl =
+    `/api/datasources/proxy/uid/${config.tempoUid}/api/search` +
+    `?q=${traceql}&start=${startEpoch}&end=${endEpoch}&limit=5`;
+
+  return observabilityFetch<TempoSearchResponse>(config, searchUrl);
+}
 
-    return Effect.gen(function* () {
-      if (!isHexTraceId(traceId)) {
+function fetchFullTrace(
+  config: ObservabilityEnvConfig,
+  traceId: string,
+): Effect.Effect<FlattenedSpan[], ObservabilityToolError> {
+  return Effect.gen(function* () {
+    const raw = yield* observabilityFetch<TempoTraceResponse>(
+      config,
+      `/api/datasources/proxy/uid/${config.tempoUid}/api/traces/${traceId}`,
+    );
+    return flattenTrace(raw);
+  });
+}
+
+function resolveTraceFromId(
+  config: ObservabilityEnvConfig,
+  parsed: ParsedId,
+  explicitWindows?: { start: string; end: string },
+): Effect.Effect<ResolvedTrace, ObservabilityToolError> {
+  return Effect.gen(function* () {
+    if (parsed.kind === "trace_id") {
+      const spans = yield* fetchFullTrace(config, parsed.normalizedId);
+      if (spans.length === 0) {
         return yield* new ObservabilityToolError({
-          cause: new Error("trace get requires a 32-character hex trace ID"),
+          cause: new Error(`Trace ${parsed.normalizedId} returned zero spans`),
         });
       }
+      return {
+        resolution: {
+          via: "direct_trace_id" as const,
+          resolvedTraceId: parsed.normalizedId,
+        },
+        spans,
+      };
+    }
 
-      const config = yield* resolveConfig(env, profile);
-      const raw = yield* observabilityFetch<TempoTraceResponse>(
-        config,
-        `/api/datasources/proxy/uid/${config.tempoUid}/api/traces/${traceId.toLowerCase()}`,
-      );
-      const spans = flattenTrace(raw);
+    const windows = explicitWindows
+      ? [{ start: explicitWindows.start, end: explicitWindows.end }]
+      : SPAN_SEARCH_WINDOWS;
 
-      if (spans.length === 0) {
+    const attemptedWindows: SearchWindow[] = [];
+    let usedWindow: SearchWindow | undefined;
+    let uniqueTraceIds: string[] = [];
+
+    for (const window of windows) {
+      attemptedWindows.push(window);
+      const searchResult = yield* searchTempoBySpanId(config, parsed.normalizedId, window);
+      const traces = searchResult.traces ?? [];
+
+      if (traces.length === 0) continue;
+
+      const candidateTraceIds = traces
+        .map((trace) => trace.traceID?.toLowerCase())
+        .filter((id): id is string => id !== undefined);
+
+      uniqueTraceIds = [...new Set(candidateTraceIds)];
+
+      if (uniqueTraceIds.length > 1) {
         return yield* new ObservabilityToolError({
-          cause: new Error(`Trace ${traceId} returned zero spans`),
+          cause: {
+            message: `Ambiguous span ID ${parsed.normalizedId} — found in ${uniqueTraceIds.length} traces`,
+            code: "AMBIGUOUS_SPAN_ID",
+            retryable: true,
+            details: { candidateTraceIds: uniqueTraceIds },
+          },
         });
       }
 
-      const result = {
-        success: true,
-        message: `Resolved trace ${traceId.toLowerCase()} with ${spans.length} span(s)`,
-        data: {
-          environment: env,
-          grafanaUrl: config.url,
-          tempoDatasourceUid: config.tempoUid,
-          summary: summarizeTrace(traceId.toLowerCase(), spans),
-          spans,
+      usedWindow = window;
+      break;
+    }
+
+    if (uniqueTraceIds.length === 0 || !usedWindow) {
+      const windowDesc = attemptedWindows
+        .map((window) => `${window.start} → ${window.end}`)
+        .join(", ");
+      return yield* new ObservabilityToolError({
+        cause: new Error(
+          `No trace found containing span ${parsed.normalizedId} (searched windows: ${windowDesc})`,
+        ),
+      });
+    }
+
+    const traceId = uniqueTraceIds[0];
+    const spans = yield* fetchFullTrace(config, traceId);
+
+    if (spans.length === 0) {
+      return yield* new ObservabilityToolError({
+        cause: new Error(`Trace ${traceId} returned zero spans`),
+      });
+    }
+
+    const focusSpan = spans.find((span) => span.spanId === parsed.normalizedId);
+
+    return {
+      resolution: {
+        via: "span_search" as const,
+        resolvedTraceId: traceId,
+        searchedSpanId: parsed.normalizedId,
+        focusSpan,
+        attemptedWindows,
+        usedWindow,
+      },
+      spans,
+    };
+  });
+}
+
+function handleTraceGet(
+  id: string,
+  format: OutputFormat,
+  env: string,
+  profile: Option.Option<string>,
+) {
+  const startedAt = Date.now();
+
+  return Effect.gen(function* () {
+    const parsed = parseId(id);
+    if (!parsed) {
+      return yield* new ObservabilityToolError({
+        cause: {
+          message: `Invalid ID format: expected 32-char trace ID or 16-char span ID, got ${id.length} characters`,
+          code: "INVALID_ID_FORMAT",
+          retryable: false,
         },
-        executionTimeMs: Date.now() - startedAt,
-      };
+      });
+    }
 
-      yield* Console.log(formatOutput(result, format));
-    }).pipe(
-      Effect.catch((error) =>
-        Effect.gen(function* () {
-          const result = {
-            success: false,
-            message: "Failed to resolve trace from Tempo",
-            error: formatObservabilityError(error),
-            hint: "Check trace ID format and Grafana/Tempo connectivity",
-            executionTimeMs: Date.now() - startedAt,
-          };
-          yield* Console.log(formatOutput(result, format));
-        }),
-      ),
-    );
+    const config = yield* resolveConfig(env, profile);
+    const { resolution, spans } = yield* resolveTraceFromId(config, parsed);
+
+    const result = {
+      success: true,
+      message:
+        parsed.kind === "span_id"
+          ? `Found trace ${resolution.resolvedTraceId} via span ${parsed.normalizedId} with ${spans.length} span(s)`
+          : `Resolved trace ${resolution.resolvedTraceId} with ${spans.length} span(s)`,
+      data: {
+        environment: env,
+        grafanaUrl: config.url,
+        tempoDatasourceUid: config.tempoUid,
+        input: parsed,
+        resolution,
+        summary: summarizeTrace(resolution.resolvedTraceId, spans),
+        spans,
+      },
+      executionTimeMs: Date.now() - startedAt,
+    };
+
+    yield* Console.log(formatOutput(result, format));
+  }).pipe(
+    Effect.catch((error) =>
+      Effect.gen(function* () {
+        const result = {
+          success: false,
+          message: "Failed to resolve trace from Tempo",
+          error: formatObservabilityError(error),
+          hint: "Accepts 32-char trace ID or 16-char span ID. Check format and Grafana/Tempo connectivity",
+          executionTimeMs: Date.now() - startedAt,
+        };
+        yield* Console.log(formatOutput(result, format));
+      }),
+    ),
+  );
+}
+
+const getCommand = Command.make(
+  "get",
+  {
+    id: Argument.string("id"),
+    format: formatOption,
+    env: envOption,
+    profile: profileOption,
   },
-).pipe(Command.withDescription("Resolve a trace by ID via Grafana/Tempo"));
+  ({ id, format, env, profile }) => handleTraceGet(id, format, env, profile),
+).pipe(Command.withDescription("Resolve a trace by trace ID or span ID via Grafana/Tempo"));
 
 const logsCommand = Command.make(
   "logs",
   {
-    traceId: Argument.string("traceId"),
+    id: Argument.string("id"),
     format: formatOption,
     env: envOption,
     profile: profileOption,
@@ -287,19 +450,26 @@ const logsCommand = Command.make(
       Flag.withDefault("now"),
     ),
   },
-  ({ traceId, format, env, profile, limit, start, end }) => {
+  ({ id, format, env, profile, limit, start, end }) => {
     const startedAt = Date.now();
 
     return Effect.gen(function* () {
-      if (!isHexTraceId(traceId)) {
+      const parsed = parseId(id);
+      if (!parsed) {
         return yield* new ObservabilityToolError({
-          cause: new Error("trace logs requires a 32-character hex trace ID"),
+          cause: {
+            message: `Invalid ID format: expected 32-char trace ID or 16-char span ID, got ${id.length} characters`,
+            code: "INVALID_ID_FORMAT",
+            retryable: false,
+          },
         });
       }
 
       const config = yield* resolveConfig(env, profile);
-      const normalizedTraceId = traceId.toLowerCase();
-      const logql = `{job=~".+"} |= "${normalizedTraceId}"`;
+      const { resolution } = yield* resolveTraceFromId(config, parsed, { start, end });
+      const resolvedTraceId = resolution.resolvedTraceId;
+
+      const logql = `{job=~".+"} |= "${resolvedTraceId}"`;
       const response = yield* observabilityDsQuery(config, config.lokiUid, "loki", logql, {
         from: start,
         to: end,
@@ -343,11 +513,16 @@ const logsCommand = Command.make(
 
       const result = {
         success: true,
-        message: `Found ${logs.length} log line(s) mentioning trace ${normalizedTraceId}`,
+        message:
+          parsed.kind === "span_id"
+            ? `Found ${logs.length} log line(s) for trace ${resolvedTraceId} (resolved from span ${parsed.normalizedId})`
+            : `Found ${logs.length} log line(s) mentioning trace ${resolvedTraceId}`,
         data: {
           environment: env,
           grafanaUrl: config.url,
           lokiDatasourceUid: config.lokiUid,
+          input: parsed,
+          resolution,
           query: logql,
           logCount: logs.length,
           logs: logs.toSorted((left, right) => right.timestamp.localeCompare(left.timestamp)),
@@ -363,7 +538,7 @@ const logsCommand = Command.make(
             success: false,
             message: "Failed to execute trace log lookup",
             error: formatObservabilityError(error),
-            hint: "Check trace ID format and Grafana/Loki connectivity",
+            hint: "Accepts 32-char trace ID or 16-char span ID. Check format and Grafana/Loki connectivity",
             executionTimeMs: Date.now() - startedAt,
           };
           yield* Console.log(formatOutput(result, format));
@@ -371,9 +546,20 @@ const logsCommand = Command.make(
       ),
     );
   },
-).pipe(Command.withDescription("Find Loki logs mentioning a trace ID"));
+).pipe(Command.withDescription("Find Loki logs mentioning a trace (accepts trace ID or span ID)"));
+
+const findCommand = Command.make(
+  "find",
+  {
+    id: Argument.string("id"),
+    format: formatOption,
+    env: envOption,
+    profile: profileOption,
+  },
+  ({ id, format, env, profile }) => handleTraceGet(id, format, env, profile),
+).pipe(Command.withDescription("Alias for 'trace get' — resolve a trace by trace ID or span ID"));
 
 export const traceCommand = Command.make("trace", {}).pipe(
   Command.withDescription("Tempo trace operations"),
-  Command.withSubcommands([getCommand, logsCommand]),
+  Command.withSubcommands([getCommand, logsCommand, findCommand]),
 );

package/src/observability-tool/types.ts

@@ -1,3 +1,5 @@
+import { Schema } from "effect";
+
 export type ObservabilityEnvConfig = {
   url: string;
   token?: string;
@@ -89,6 +91,52 @@ export type TraceSummary = {
   readonly endedAtUnixNano?: string;
 };
 
+export type TempoSearchResponse = {
+  readonly traces?: ReadonlyArray<{
+    readonly traceID?: string;
+    readonly rootServiceName?: string;
+    readonly rootTraceName?: string;
+    readonly startTimeUnixNano?: string;
+    readonly durationMs?: number;
+    readonly spanSets?: ReadonlyArray<{
+      readonly spans?: ReadonlyArray<{
+        readonly spanID?: string;
+        readonly startTimeUnixNano?: string;
+        readonly durationNanos?: string;
+        readonly attributes?: ReadonlyArray<OtlpAttribute>;
+      }>;
+      readonly matched?: number;
+    }>;
+  }>;
+  readonly metrics?: Record<string, unknown>;
+};
+
+export const IdKind = Schema.Literals(["trace_id", "span_id"]);
+export type IdKind = typeof IdKind.Type;
+
+export const ResolutionVia = Schema.Literals(["direct_trace_id", "span_search"]);
+export type ResolutionVia = typeof ResolutionVia.Type;
+
+export type ParsedId = {
+  readonly rawId: string;
+  readonly normalizedId: string;
+  readonly kind: IdKind;
+};
+
+export type SearchWindow = {
+  readonly start: string;
+  readonly end: string;
+};
+
+export type SpanResolution = {
+  readonly via: ResolutionVia;
+  readonly resolvedTraceId: string;
+  readonly searchedSpanId?: string;
+  readonly focusSpan?: FlattenedSpan;
+  readonly attemptedWindows?: ReadonlyArray<SearchWindow>;
+  readonly usedWindow?: SearchWindow;
+};
+
 export type DsQueryOpts = {
   instant?: boolean;
   from?: string;