@senad-d/observme 0.1.4 → 0.1.5

package/src/query/trace-link.ts

@@ -0,0 +1,186 @@
+import type { ObservMeConfig } from "../config/schema.ts";
+import { assertNoSensitiveQueryInput } from "../safety/sensitive-input.ts";
+
+interface TraceTemplateReplacement {
+  readonly pattern: RegExp;
+  readonly key: TraceTemplateValueKey;
+}
+
+type TraceTemplateValueKey = "traceId" | "tempoDatasourceUid";
+type TraceTemplateValues = Record<TraceTemplateValueKey, string>;
+
+interface GrafanaExploreDatasourceRef {
+  readonly type: "tempo";
+  readonly uid: string;
+}
+
+interface GrafanaTraceQuery {
+  readonly refId: "A";
+  readonly datasource: GrafanaExploreDatasourceRef;
+  readonly queryType: "traceId";
+  readonly query: string;
+}
+
+interface GrafanaExplorePane {
+  readonly datasource: string;
+  readonly queries: readonly GrafanaTraceQuery[];
+  readonly range: {
+    readonly from: "now-1h";
+    readonly to: "now";
+  };
+}
+
+type GrafanaExplorePanes = Record<string, GrafanaExplorePane>;
+
+export const TRACE_LINK_CONFIGURATION_ERROR =
+  "Grafana trace link configuration is invalid: use an absolute HTTP(S) traceUrlTemplate with {traceId}, {{traceId}}, ${traceId}, or %TRACE_ID%, or use the ellipsis fallback with an absolute query.grafana.url.";
+
+const maximumTraceLinkLength = 4096;
+const traceIdPattern = /^[a-f0-9]{32}$/iu;
+const zeroTraceIdPattern = /^0{32}$/u;
+const traceIdTemplatePattern = /\{\{\s*traceId\s*\}\}|\{traceId\}|\$\{traceId\}|%TRACE_ID%/u;
+const fallbackTraceTemplateMarkerPattern = /\.\.\./u;
+const unresolvedTemplatePlaceholderPatterns: readonly RegExp[] = [
+  /\{\{\s*[A-Za-z]\w*\s*\}\}/u,
+  /\$\{[A-Za-z]\w*\}/u,
+  /\{[A-Za-z]\w*\}/u,
+  /%[A-Z][A-Z0-9_]*%/u,
+  /\$traceId\b/u,
+  /__TRACE_ID__/u,
+];
+const traceTemplateReplacements: readonly TraceTemplateReplacement[] = [
+  { pattern: /\{\{\s*traceId\s*\}\}/gu, key: "traceId" },
+  { pattern: /\$\{traceId\}/gu, key: "traceId" },
+  { pattern: /\{traceId\}/gu, key: "traceId" },
+  { pattern: /%TRACE_ID%/gu, key: "traceId" },
+  { pattern: /\{\{\s*tempoDatasourceUid\s*\}\}/gu, key: "tempoDatasourceUid" },
+  { pattern: /\$\{tempoDatasourceUid\}/gu, key: "tempoDatasourceUid" },
+  { pattern: /\{tempoDatasourceUid\}/gu, key: "tempoDatasourceUid" },
+  { pattern: /%TEMPO_DATASOURCE_UID%/gu, key: "tempoDatasourceUid" },
+];
+
+export function buildGrafanaTraceLink(config: ObservMeConfig, traceId: string): string {
+  const normalizedTraceId = normalizeTraceId(traceId);
+  const template = config.query.links.traceUrlTemplate.trim();
+
+  if (isFallbackTraceTemplate(template)) return buildDefaultGrafanaTraceLink(config, normalizedTraceId);
+  if (!hasTraceIdTemplatePlaceholder(template)) throw new Error(TRACE_LINK_CONFIGURATION_ERROR);
+
+  return renderTraceUrlTemplate(template, config, normalizedTraceId);
+}
+
+function buildDefaultGrafanaTraceLink(config: ObservMeConfig, traceId: string): string {
+  const url = parseTraceLinkUrl(config.query.grafana.url.trim());
+  const basePath = removeTrailingSlashes(url.pathname);
+  url.pathname = `${basePath}/explore`;
+  url.search = "";
+  url.hash = "";
+  url.searchParams.set("schemaVersion", "1");
+  url.searchParams.set("panes", JSON.stringify(createDefaultExplorePanes(config, traceId)));
+  return formatTraceLinkUrl(url);
+}
+
+function removeTrailingSlashes(value: string): string {
+  let end = value.length;
+  while (end > 0 && value[end - 1] === "/") end -= 1;
+  return value.slice(0, end);
+}
+
+function createDefaultExplorePanes(config: ObservMeConfig, traceId: string): GrafanaExplorePanes {
+  const tempoUid = config.query.grafana.datasourceUids.tempo;
+  return {
+    observmeTrace: {
+      datasource: tempoUid,
+      queries: [
+        {
+          refId: "A",
+          datasource: { type: "tempo", uid: tempoUid },
+          queryType: "traceId",
+          query: traceId,
+        },
+      ],
+      range: { from: "now-1h", to: "now" },
+    },
+  };
+}
+
+function renderTraceUrlTemplate(template: string, config: ObservMeConfig, traceId: string): string {
+  const values = createTraceTemplateValues(config, traceId);
+  let rendered = template;
+
+  for (const replacement of traceTemplateReplacements) {
+    rendered = rendered.replace(replacement.pattern, values[replacement.key]);
+  }
+
+  if (hasUnresolvedTemplatePlaceholder(rendered)) throw new Error(TRACE_LINK_CONFIGURATION_ERROR);
+  return formatTraceLinkUrl(parseTraceLinkUrl(rendered));
+}
+
+function hasUnresolvedTemplatePlaceholder(value: string): boolean {
+  for (const pattern of unresolvedTemplatePlaceholderPatterns) {
+    if (pattern.test(value)) return true;
+  }
+  return false;
+}
+
+function createTraceTemplateValues(config: ObservMeConfig, traceId: string): TraceTemplateValues {
+  return {
+    traceId: encodeURIComponent(traceId),
+    tempoDatasourceUid: encodeURIComponent(config.query.grafana.datasourceUids.tempo),
+  };
+}
+
+function normalizeTraceId(traceId: string): string {
+  const trimmed = traceId.trim();
+  assertNoSensitiveQueryInput(trimmed, "Grafana traceId");
+
+  if (!traceIdPattern.test(trimmed) || zeroTraceIdPattern.test(trimmed)) {
+    throw new Error(
+      "Unsafe Grafana traceId: expected a non-zero 32-character hexadecimal OpenTelemetry trace id; raw prompts, commands, paths, and environment values are not query inputs.",
+    );
+  }
+
+  return trimmed.toLowerCase();
+}
+
+function hasTraceIdTemplatePlaceholder(template: string): boolean {
+  return traceIdTemplatePattern.test(template);
+}
+
+function isFallbackTraceTemplate(template: string): boolean {
+  return template === "" || fallbackTraceTemplateMarkerPattern.test(template);
+}
+
+function parseTraceLinkUrl(value: string): URL {
+  if (!value || value.length > maximumTraceLinkLength || hasUnsafeUrlCharacters(value)) {
+    throw new Error(TRACE_LINK_CONFIGURATION_ERROR);
+  }
+
+  try {
+    const url = new URL(value);
+    if (!isSupportedTraceLinkProtocol(url.protocol) || url.username || url.password) {
+      throw new Error(TRACE_LINK_CONFIGURATION_ERROR);
+    }
+    return url;
+  } catch {
+    throw new Error(TRACE_LINK_CONFIGURATION_ERROR);
+  }
+}
+
+function formatTraceLinkUrl(url: URL): string {
+  const link = url.toString();
+  if (link.length > maximumTraceLinkLength) throw new Error(TRACE_LINK_CONFIGURATION_ERROR);
+  return link;
+}
+
+function hasUnsafeUrlCharacters(value: string): boolean {
+  for (const character of value) {
+    const codePoint = character.codePointAt(0);
+    if (codePoint !== undefined && (codePoint <= 31 || codePoint === 127)) return true;
+  }
+  return false;
+}
+
+function isSupportedTraceLinkProtocol(protocol: string): boolean {
+  return protocol === "http:" || protocol === "https:";
+}

package/src/safety/display-bounds.ts

@@ -0,0 +1,84 @@
+export const OBS_BACKEND_LABEL_MAX_CHARS = 96;
+export const OBS_COMMAND_OUTPUT_MAX_CHARS = 8192;
+export const OBS_COMMAND_OUTPUT_MAX_ROWS = 64;
+export const OBS_COMMAND_RENDER_ROW_LIMIT = 20;
+
+const truncationMarker = "…";
+const outputTruncationSuffix = "\n… output truncated";
+const unsafeDisplayControlPattern = /[\p{Cc}\p{Zl}\p{Zp}]+/gu;
+const displayWhitespacePattern = /\s+/gu;
+
+export interface BoundedObsCommandRows<T> {
+  readonly rows: readonly T[];
+  readonly omittedCount: number;
+}
+
+export function normalizeObsBackendLabel(value: string | undefined): string | undefined {
+  const normalized = value?.replace(unsafeDisplayControlPattern, " ").replace(displayWhitespacePattern, " ").trim();
+  if (!normalized) return undefined;
+  return truncateUnicodeText(normalized, OBS_BACKEND_LABEL_MAX_CHARS, truncationMarker);
+}
+
+export function normalizeObsBackendLabelRecord(labels: Readonly<Record<string, string>>): Record<string, string> {
+  const normalizedLabels: Record<string, string> = {};
+
+  for (const [key, value] of Object.entries(labels)) {
+    const normalizedKey = normalizeObsBackendLabel(key);
+    const normalizedValue = normalizeObsBackendLabel(value);
+    if (normalizedKey && normalizedValue !== undefined) normalizedLabels[normalizedKey] = normalizedValue;
+  }
+
+  return normalizedLabels;
+}
+
+export function selectObsCommandRows<T>(rows: readonly T[]): BoundedObsCommandRows<T> {
+  if (rows.length <= OBS_COMMAND_RENDER_ROW_LIMIT) return { rows, omittedCount: 0 };
+
+  return {
+    rows: rows.slice(0, OBS_COMMAND_RENDER_ROW_LIMIT),
+    omittedCount: rows.length - OBS_COMMAND_RENDER_ROW_LIMIT,
+  };
+}
+
+export function boundObsCommandOutput(output: string): string {
+  const normalized = normalizeObsCommandOutput(output);
+  const rows = normalized.split("\n");
+  const rowsTruncated = rows.length > OBS_COMMAND_OUTPUT_MAX_ROWS;
+  const content = rowsTruncated ? rows.slice(0, OBS_COMMAND_OUTPUT_MAX_ROWS - 1).join("\n") : normalized;
+
+  if (!rowsTruncated && content.length <= OBS_COMMAND_OUTPUT_MAX_CHARS) return content;
+
+  const prefixLimit = OBS_COMMAND_OUTPUT_MAX_CHARS - outputTruncationSuffix.length;
+  const characterBounded = truncateUnicodeText(content, prefixLimit, "");
+  const rowBounded = selectOutputRows(characterBounded, OBS_COMMAND_OUTPUT_MAX_ROWS - 1);
+  return `${rowBounded}${outputTruncationSuffix}`;
+}
+
+function normalizeObsCommandOutput(output: string): string {
+  return output.replace(unsafeDisplayControlPattern, normalizeObsCommandControlSequence);
+}
+
+function normalizeObsCommandControlSequence(sequence: string): string {
+  let normalized = "";
+  for (const character of sequence) normalized += character === "\n" ? "\n" : " ";
+  return normalized;
+}
+
+function selectOutputRows(output: string, maximumRows: number): string {
+  const rows = output.split("\n");
+  if (rows.length <= maximumRows) return output;
+  return rows.slice(0, maximumRows).join("\n");
+}
+
+function truncateUnicodeText(value: string, maximumChars: number, suffix: string): string {
+  if (value.length <= maximumChars) return value;
+
+  const prefixLimit = Math.max(0, maximumChars - suffix.length);
+  let prefix = "";
+  for (const codePoint of value) {
+    if (prefix.length + codePoint.length > prefixLimit) break;
+    prefix += codePoint;
+  }
+
+  return `${prefix}${suffix}`;
+}

package/src/semconv/metrics.ts

@@ -95,6 +95,7 @@ export const LOG_EVENT_NAMES = {
   AGENT_SPAWN_STARTED: "agent.spawn.started",
   AGENT_SPAWN_COMPLETED: "agent.spawn.completed",
   AGENT_SPAWN_FAILED: "agent.spawn.failed",
+  AGENT_SPAWN_CANCELLED: "agent.spawn.cancelled",
   AGENT_WAIT_STARTED: "agent.wait.started",
   AGENT_WAIT_COMPLETED: "agent.wait.completed",
   AGENT_JOIN_STARTED: "agent.join.started",

package/src/semconv/values.ts

@@ -1,3 +1,5 @@
+export const OBSERVME_CORRELATION_ENTRY_TYPE = "observme.correlation";
+
 export const SUBAGENT_SPAWN_REASON_VALUES = [
   "delegated_task",
   "parallel_search",