@blogic-cz/agent-tools 0.11.0 → 0.12.0

package/src/{grafana-tool → observability-tool}/shared.ts

@@ -2,17 +2,24 @@ import { Effect, Option } from "effect";
 import { Flag } from "effect/unstable/cli";
 
 import { ConfigService, getToolConfig } from "#config";
-import type { GrafanaConfig } from "#config";
+import type { ObservabilityConfig } from "#config";
 
-import { GrafanaToolError } from "./errors";
-import type { DsQueryOpts, DsQueryResponse, GrafanaEnvConfig } from "./types";
+import { ObservabilityToolError } from "./errors";
+import type {
+  DsQueryOpts,
+  DsQueryResponse,
+  GrafanaDatasource,
+  ObservabilityEnvConfig,
+} from "./types";
 
 const DEFAULT_LOCAL_URL = "http://localhost:40300";
 const DEFAULT_PROMETHEUS_UID = "prometheus";
 const DEFAULT_LOKI_UID = "loki";
-export function formatGrafanaError(error: unknown): string {
-  if (error instanceof GrafanaToolError) {
-    return formatGrafanaError(error.cause);
+const DEFAULT_TEMPO_UID = "tempo";
+
+export function formatObservabilityError(error: unknown): string {
+  if (error instanceof ObservabilityToolError) {
+    return formatObservabilityError(error.cause);
   }
 
   if (error instanceof Error) {
@@ -30,7 +37,7 @@ export const envOption = Flag.string("env").pipe(
 export const profileOption = Flag.optional(
   Flag.string("profile").pipe(
     Flag.withDescription(
-      "Grafana profile name from agent-tools config (default: 'default' key or single entry)",
+      "Observability profile name from agent-tools config (default: 'default' key or single entry)",
     ),
   ),
 );
@@ -48,43 +55,67 @@ function resolveToken(tokenEnvVar?: string): string | undefined {
   return token;
 }
 
-function resolveFromProfile(
-  profile: GrafanaConfig | undefined,
+async function discoverDatasources(url: string, token?: string): Promise<GrafanaDatasource[]> {
+  const headers = buildHeaders(token);
+  const response = await fetch(`${url}/api/datasources`, { headers });
+
+  if (!response.ok) {
+    const body = await response.text().catch(() => "");
+    throw new Error(`Grafana API ${response.status}: /api/datasources — ${body}`);
+  }
+
+  return (await response.json()) as GrafanaDatasource[];
+}
+
+async function resolveFromProfile(
+  profile: ObservabilityConfig | undefined,
   env: string,
-): GrafanaEnvConfig | undefined {
+): Promise<ObservabilityEnvConfig | undefined> {
   const environment = profile?.environments[env];
   if (!environment) {
     return undefined;
   }
 
+  const token = resolveToken(environment.tokenEnvVar);
+  const datasources = await discoverDatasources(environment.url, token);
+
+  const tempoUid =
+    datasources.find((datasource) => datasource.uid === DEFAULT_TEMPO_UID)?.uid ??
+    datasources.find((datasource) => datasource.type === "tempo")?.uid;
+
+  if (!tempoUid) {
+    throw new Error(`No Tempo datasource found in observability.${env} config`);
+  }
+
   return {
     url: environment.url,
-    token: resolveToken(environment.tokenEnvVar),
+    token,
     prometheusUid: environment.prometheusUid ?? DEFAULT_PROMETHEUS_UID,
     lokiUid: environment.lokiUid ?? DEFAULT_LOKI_UID,
+    tempoUid,
   };
 }
 
-function resolveFromEnv(env: string): GrafanaEnvConfig {
+function resolveFromEnv(
+  env: string,
+): Pick<ObservabilityEnvConfig, "url" | "token" | "prometheusUid" | "lokiUid"> {
   if (env === "local") {
     return {
-      url: process.env.GRAFANA_URL_LOCAL ?? DEFAULT_LOCAL_URL,
-      token: process.env.GRAFANA_TOKEN_LOCAL,
+      url: process.env.OBSERVABILITY_URL_LOCAL ?? DEFAULT_LOCAL_URL,
+      token: process.env.OBSERVABILITY_TOKEN_LOCAL,
       prometheusUid: DEFAULT_PROMETHEUS_UID,
       lokiUid: DEFAULT_LOKI_UID,
     };
   }
 
   const upper = env.toUpperCase();
-  const url = process.env[`GRAFANA_URL_${upper}`];
-  const token = process.env[`GRAFANA_TOKEN_${upper}`];
+  const url = process.env[`OBSERVABILITY_URL_${upper}`];
+  const token = process.env[`OBSERVABILITY_TOKEN_${upper}`];
 
   if (!url) {
-    throw new Error(`No grafana.${env} config found and GRAFANA_URL_${upper} is not set`);
-  }
-
-  if (!token) {
-    throw new Error(`No grafana.${env} config found and GRAFANA_TOKEN_${upper} is not set`);
+    throw new Error(
+      `No observability.${env} config found and OBSERVABILITY_URL_${upper} is not set`,
+    );
   }
 
   return {
@@ -99,11 +130,36 @@ export const resolveConfig = (env: string, profile: Option.Option<string>) =>
   Effect.gen(function* () {
     const config = yield* ConfigService;
     const profileName = Option.getOrUndefined(profile);
-    const grafanaConfig = getToolConfig<GrafanaConfig>(config, "grafana", profileName);
-
-    return yield* Effect.try({
-      try: () => resolveFromProfile(grafanaConfig, env) ?? resolveFromEnv(env),
-      catch: (cause) => new GrafanaToolError({ cause }),
+    const observabilityConfig = getToolConfig<ObservabilityConfig>(
+      config,
+      "observability",
+      profileName,
+    );
+
+    return yield* Effect.tryPromise({
+      try: async () => {
+        const profileResolved = await resolveFromProfile(observabilityConfig, env);
+        if (profileResolved) {
+          return profileResolved;
+        }
+
+        const resolved = resolveFromEnv(env);
+
+        const datasources = await discoverDatasources(resolved.url, resolved.token);
+        const tempoUid =
+          datasources.find((datasource) => datasource.uid === DEFAULT_TEMPO_UID)?.uid ??
+          datasources.find((datasource) => datasource.type === "tempo")?.uid;
+
+        if (!tempoUid) {
+          throw new Error(`No Tempo datasource found for environment '${env}'`);
+        }
+
+        return {
+          ...resolved,
+          tempoUid,
+        } satisfies ObservabilityEnvConfig;
+      },
+      catch: (cause) => new ObservabilityToolError({ cause }),
     });
   });
 
@@ -120,11 +176,11 @@ export function buildHeaders(token?: string): Headers {
   return headers;
 }
 
-export function grafanaFetch<T>(
-  config: GrafanaEnvConfig,
+export function observabilityFetch<T>(
+  config: ObservabilityEnvConfig,
   path: string,
   init?: RequestInit,
-): Effect.Effect<T, GrafanaToolError> {
+): Effect.Effect<T, ObservabilityToolError> {
   return Effect.tryPromise({
     try: async () => {
       const headers = buildHeaders(config.token);
@@ -147,17 +203,17 @@ export function grafanaFetch<T>(
 
       return (await response.json()) as T;
     },
-    catch: (cause) => new GrafanaToolError({ cause }),
+    catch: (cause) => new ObservabilityToolError({ cause }),
   });
 }
 
-export function grafanaDsQuery(
-  config: GrafanaEnvConfig,
+export function observabilityDsQuery(
+  config: ObservabilityEnvConfig,
   datasourceUid: string,
   datasourceType: "prometheus" | "loki",
   expr: string,
   options?: DsQueryOpts,
-): Effect.Effect<DsQueryResponse, GrafanaToolError> {
+): Effect.Effect<DsQueryResponse, ObservabilityToolError> {
   const opts = options ?? {};
   const query: Record<string, unknown> = {
     refId: "A",
@@ -183,7 +239,7 @@ export function grafanaDsQuery(
     }
   }
 
-  return grafanaFetch<DsQueryResponse>(config, "/api/ds/query", {
+  return observabilityFetch<DsQueryResponse>(config, "/api/ds/query", {
     method: "POST",
     body: JSON.stringify({
       queries: [query],

package/src/observability-tool/trace.ts

@@ -0,0 +1,379 @@
+import { Console, Effect } from "effect";
+import { Argument, Command, Flag } from "effect/unstable/cli";
+
+import { formatOption, formatOutput } from "#shared";
+
+import { ObservabilityToolError } from "./errors";
+import {
+  envOption,
+  formatObservabilityError,
+  observabilityDsQuery,
+  observabilityFetch,
+  profileOption,
+  resolveConfig,
+} from "./shared";
+import type {
+  FlattenedSpan,
+  OtlpAnyValue,
+  OtlpAttribute,
+  TempoTraceResponse,
+  TraceSummary,
+} from "./types";
+
+function isHexTraceId(value: string): boolean {
+  return /^[\da-f]{32}$/i.test(value);
+}
+
+function getStringAttribute(
+  attributes: ReadonlyArray<OtlpAttribute> | null,
+  key: string,
+): string | undefined {
+  const attribute = attributes?.find((item) => item.key === key);
+  const value = attribute?.value;
+
+  if (value?.stringValue !== undefined) return value.stringValue;
+  if (value?.intValue !== undefined) return String(value.intValue);
+  if (value?.doubleValue !== undefined) return String(value.doubleValue);
+  if (value?.boolValue !== undefined) return String(value.boolValue);
+  return undefined;
+}
+
+function anyValueToUnknown(value?: OtlpAnyValue): unknown {
+  if (value === undefined) return undefined;
+  if (value.stringValue !== undefined) return value.stringValue;
+  if (value.boolValue !== undefined) return value.boolValue;
+  if (value.intValue !== undefined) return value.intValue;
+  if (value.doubleValue !== undefined) return value.doubleValue;
+  if (value.arrayValue?.values !== undefined) {
+    return value.arrayValue.values.map((item) => anyValueToUnknown(item));
+  }
+  if (value.kvlistValue?.values !== undefined) {
+    return Object.fromEntries(
+      value.kvlistValue.values.map((entry) => [entry.key, anyValueToUnknown(entry.value)]),
+    );
+  }
+  return undefined;
+}
+
+function attributesToRecord(
+  attributes: ReadonlyArray<OtlpAttribute> | null,
+): Record<string, unknown> {
+  return Object.fromEntries(
+    (attributes ?? [])
+      .map((attribute) => [attribute.key, anyValueToUnknown(attribute.value)] as const)
+      .filter((entry) => entry[1] !== undefined),
+  );
+}
+
+function decodeIdToHex(value?: string, expectedBytes?: number): string | undefined {
+  if (value === undefined) return undefined;
+  const trimmed = value.trim();
+  if (trimmed.length === 0) return undefined;
+
+  const expectedHexLength = expectedBytes === undefined ? undefined : expectedBytes * 2;
+  if (
+    expectedHexLength !== undefined &&
+    new RegExp(`^[\\da-f]{${expectedHexLength}}$`, "i").test(trimmed)
+  ) {
+    return trimmed.toLowerCase();
+  }
+
+  try {
+    const bytes = Buffer.from(trimmed, "base64");
+    if (expectedBytes !== undefined && bytes.length !== expectedBytes) {
+      return undefined;
+    }
+    return bytes.toString("hex");
+  } catch {
+    return undefined;
+  }
+}
+
+function nanoToBigInt(value?: string): bigint | undefined {
+  if (value === undefined || value.trim().length === 0) {
+    return undefined;
+  }
+  try {
+    return BigInt(value);
+  } catch {
+    return undefined;
+  }
+}
+
+function computeDurationMs(start?: string, end?: string): number | undefined {
+  const startNano = nanoToBigInt(start);
+  const endNano = nanoToBigInt(end);
+
+  if (startNano === undefined || endNano === undefined || endNano < startNano) {
+    return undefined;
+  }
+
+  return Number(endNano - startNano) / 1_000_000;
+}
+
+function isErrorStatus(code?: string | number): boolean {
+  if (code === undefined) return false;
+  if (typeof code === "number") return code === 2;
+  return code.toUpperCase().includes("ERROR") || code === "2";
+}
+
+function flattenTrace(trace: TempoTraceResponse): FlattenedSpan[] {
+  const spans: FlattenedSpan[] = [];
+
+  for (const batch of trace.batches ?? []) {
+    const resourceAttributes = attributesToRecord(batch.resource?.attributes ?? null);
+    const serviceName =
+      getStringAttribute(batch.resource?.attributes ?? null, "service.name") ?? "unknown-service";
+
+    for (const scopeSpan of batch.scopeSpans ?? []) {
+      for (const span of scopeSpan.spans ?? []) {
+        spans.push({
+          serviceName,
+          scopeName: scopeSpan.scope?.name,
+          name: span.name ?? "unknown-span",
+          kind: span.kind,
+          traceId: decodeIdToHex(span.traceId, 16),
+          spanId: decodeIdToHex(span.spanId, 8),
+          parentSpanId: decodeIdToHex(span.parentSpanId, 8),
+          startTimeUnixNano: span.startTimeUnixNano,
+          endTimeUnixNano: span.endTimeUnixNano,
+          durationMs: computeDurationMs(span.startTimeUnixNano, span.endTimeUnixNano),
+          statusCode: span.status?.code,
+          statusMessage: span.status?.message,
+          isError: isErrorStatus(span.status?.code),
+          attributes: attributesToRecord(span.attributes ?? null),
+          resourceAttributes,
+        });
+      }
+    }
+  }
+
+  return spans.toSorted((left, right) => {
+    const leftStart = nanoToBigInt(left.startTimeUnixNano) ?? 0n;
+    const rightStart = nanoToBigInt(right.startTimeUnixNano) ?? 0n;
+    return leftStart < rightStart ? -1 : leftStart > rightStart ? 1 : 0;
+  });
+}
+
+function summarizeTrace(traceId: string, spans: readonly FlattenedSpan[]): TraceSummary {
+  const services = [...new Set(spans.map((span) => span.serviceName))].toSorted();
+  const spanIds = new Set(
+    spans.map((span) => span.spanId).filter((value): value is string => value !== undefined),
+  );
+  const rootSpans = spans.filter(
+    (span) => span.parentSpanId === undefined || !spanIds.has(span.parentSpanId),
+  );
+
+  const startedAt = spans.reduce<bigint | undefined>((current, span) => {
+    const value = nanoToBigInt(span.startTimeUnixNano);
+    if (value === undefined) return current;
+    if (current === undefined || value < current) return value;
+    return current;
+  }, undefined);
+  const endedAt = spans.reduce<bigint | undefined>((current, span) => {
+    const value = nanoToBigInt(span.endTimeUnixNano);
+    if (value === undefined) return current;
+    if (current === undefined || value > current) return value;
+    return current;
+  }, undefined);
+
+  return {
+    traceId,
+    spanCount: spans.length,
+    serviceCount: services.length,
+    services,
+    errorSpanCount: spans.filter((span) => span.isError).length,
+    rootSpans,
+    totalDurationMs:
+      startedAt !== undefined && endedAt !== undefined && endedAt >= startedAt
+        ? Number(endedAt - startedAt) / 1_000_000
+        : undefined,
+    startedAtUnixNano: startedAt?.toString(),
+    endedAtUnixNano: endedAt?.toString(),
+  };
+}
+
+function parseLabel(value: string | Record<string, string>): Record<string, string> {
+  if (typeof value === "object" && value !== null) {
+    return value;
+  }
+
+  try {
+    return JSON.parse(value) as Record<string, string>;
+  } catch {
+    return {};
+  }
+}
+
+const getCommand = Command.make(
+  "get",
+  {
+    traceId: Argument.string("traceId"),
+    format: formatOption,
+    env: envOption,
+    profile: profileOption,
+  },
+  ({ traceId, format, env, profile }) => {
+    const startedAt = Date.now();
+
+    return Effect.gen(function* () {
+      if (!isHexTraceId(traceId)) {
+        return yield* new ObservabilityToolError({
+          cause: new Error("trace get requires a 32-character hex trace ID"),
+        });
+      }
+
+      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);
+
+      if (spans.length === 0) {
+        return yield* new ObservabilityToolError({
+          cause: new Error(`Trace ${traceId} returned zero spans`),
+        });
+      }
+
+      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,
+        },
+        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));
+        }),
+      ),
+    );
+  },
+).pipe(Command.withDescription("Resolve a trace by ID via Grafana/Tempo"));
+
+const logsCommand = Command.make(
+  "logs",
+  {
+    traceId: Argument.string("traceId"),
+    format: formatOption,
+    env: envOption,
+    profile: profileOption,
+    limit: Flag.integer("limit").pipe(
+      Flag.withDescription("Max log lines (default: 100)"),
+      Flag.withDefault(100),
+    ),
+    start: Flag.string("start").pipe(
+      Flag.withDescription("Start time (default: now-1h)"),
+      Flag.withDefault("now-1h"),
+    ),
+    end: Flag.string("end").pipe(
+      Flag.withDescription("End time (default: now)"),
+      Flag.withDefault("now"),
+    ),
+  },
+  ({ traceId, format, env, profile, limit, start, end }) => {
+    const startedAt = Date.now();
+
+    return Effect.gen(function* () {
+      if (!isHexTraceId(traceId)) {
+        return yield* new ObservabilityToolError({
+          cause: new Error("trace logs requires a 32-character hex trace ID"),
+        });
+      }
+
+      const config = yield* resolveConfig(env, profile);
+      const normalizedTraceId = traceId.toLowerCase();
+      const logql = `{job=~".+"} |= "${normalizedTraceId}"`;
+      const response = yield* observabilityDsQuery(config, config.lokiUid, "loki", logql, {
+        from: start,
+        to: end,
+        maxLines: limit,
+      });
+
+      if (response.results.A.error) {
+        return yield* new ObservabilityToolError({
+          cause: new Error(response.results.A.error),
+        });
+      }
+
+      const logs: Array<{ timestamp: string; line: string; labels: Record<string, string> }> = [];
+      for (const frame of response.results.A.frames ?? []) {
+        const fields = frame.schema.fields;
+        const values = frame.data.values;
+        const timeIndex = fields.findIndex(
+          (field) => field.name === "timestamp" || field.type === "time",
+        );
+        const lineIndex = fields.findIndex(
+          (field) => field.name === "body" || field.name === "Line" || field.name === "line",
+        );
+        const labelsIndex = fields.findIndex(
+          (field) => field.name === "labels" || field.name === "labelTypes",
+        );
+
+        const timestamps = (timeIndex >= 0 ? values[timeIndex] : []) as Array<string | number>;
+        const lines = (lineIndex >= 0 ? values[lineIndex] : []) as string[];
+        const labelValues = (labelsIndex >= 0 ? values[labelsIndex] : []) as Array<
+          string | Record<string, string>
+        >;
+
+        for (const [index, line] of lines.entries()) {
+          logs.push({
+            timestamp: String(timestamps[index] ?? ""),
+            line,
+            labels: labelValues[index] ? parseLabel(labelValues[index]) : {},
+          });
+        }
+      }
+
+      const result = {
+        success: true,
+        message: `Found ${logs.length} log line(s) mentioning trace ${normalizedTraceId}`,
+        data: {
+          environment: env,
+          grafanaUrl: config.url,
+          lokiDatasourceUid: config.lokiUid,
+          query: logql,
+          logCount: logs.length,
+          logs: logs.toSorted((left, right) => right.timestamp.localeCompare(left.timestamp)),
+        },
+        executionTimeMs: Date.now() - startedAt,
+      };
+
+      yield* Console.log(formatOutput(result, format));
+    }).pipe(
+      Effect.catch((error) =>
+        Effect.gen(function* () {
+          const result = {
+            success: false,
+            message: "Failed to execute trace log lookup",
+            error: formatObservabilityError(error),
+            hint: "Check trace ID format and Grafana/Loki connectivity",
+            executionTimeMs: Date.now() - startedAt,
+          };
+          yield* Console.log(formatOutput(result, format));
+        }),
+      ),
+    );
+  },
+).pipe(Command.withDescription("Find Loki logs mentioning a trace ID"));
+
+export const traceCommand = Command.make("trace", {}).pipe(
+  Command.withDescription("Tempo trace operations"),
+  Command.withSubcommands([getCommand, logsCommand]),
+);

package/src/observability-tool/types.ts

@@ -0,0 +1,119 @@
+export type ObservabilityEnvConfig = {
+  url: string;
+  token?: string;
+  prometheusUid: string;
+  lokiUid: string;
+  tempoUid: string;
+};
+
+export type GrafanaDatasource = {
+  uid: string;
+  name: string;
+  type: string;
+  url?: string;
+};
+
+export type OtlpAnyValue = {
+  readonly stringValue?: string;
+  readonly boolValue?: boolean;
+  readonly intValue?: number | string;
+  readonly doubleValue?: number;
+  readonly arrayValue?: { readonly values?: readonly OtlpAnyValue[] };
+  readonly kvlistValue?: {
+    readonly values?: ReadonlyArray<{
+      readonly key: string;
+      readonly value?: OtlpAnyValue;
+    }>;
+  };
+};
+
+export type OtlpAttribute = {
+  readonly key: string;
+  readonly value?: OtlpAnyValue;
+};
+
+export type TempoTraceResponse = {
+  readonly batches?: ReadonlyArray<{
+    readonly resource?: {
+      readonly attributes?: ReadonlyArray<OtlpAttribute>;
+    };
+    readonly scopeSpans?: ReadonlyArray<{
+      readonly scope?: {
+        readonly name?: string;
+      };
+      readonly spans?: ReadonlyArray<{
+        readonly attributes?: ReadonlyArray<OtlpAttribute>;
+        readonly endTimeUnixNano?: string;
+        readonly kind?: string | number;
+        readonly name?: string;
+        readonly parentSpanId?: string;
+        readonly spanId?: string;
+        readonly startTimeUnixNano?: string;
+        readonly status?: {
+          readonly code?: string | number;
+          readonly message?: string;
+        };
+        readonly traceId?: string;
+      }>;
+    }>;
+  }>;
+};
+
+export type FlattenedSpan = {
+  readonly serviceName: string;
+  readonly scopeName?: string;
+  readonly name: string;
+  readonly kind?: string | number;
+  readonly traceId?: string;
+  readonly spanId?: string;
+  readonly parentSpanId?: string;
+  readonly startTimeUnixNano?: string;
+  readonly endTimeUnixNano?: string;
+  readonly durationMs?: number;
+  readonly statusCode?: string | number;
+  readonly statusMessage?: string;
+  readonly isError: boolean;
+  readonly attributes: Record<string, unknown>;
+  readonly resourceAttributes: Record<string, unknown>;
+};
+
+export type TraceSummary = {
+  readonly traceId: string;
+  readonly spanCount: number;
+  readonly serviceCount: number;
+  readonly services: string[];
+  readonly errorSpanCount: number;
+  readonly rootSpans: FlattenedSpan[];
+  readonly totalDurationMs?: number;
+  readonly startedAtUnixNano?: string;
+  readonly endedAtUnixNano?: string;
+};
+
+export type DsQueryOpts = {
+  instant?: boolean;
+  from?: string;
+  to?: string;
+  maxLines?: number;
+  intervalMs?: number;
+  maxDataPoints?: number;
+  step?: number;
+};
+
+export type DsQueryResponse = {
+  results: {
+    A: {
+      status?: number;
+      frames?: Array<{
+        schema: {
+          fields: Array<{
+            name: string;
+            type?: string;
+            labels?: Record<string, string>;
+          }>;
+        };
+        data: { values: unknown[][] };
+      }>;
+      error?: string;
+    };
+  };
+};