@nwire/studio 0.9.1

package/src/pages/Trace.vue

@@ -0,0 +1,511 @@
+<script setup lang="ts">
+/**
+ * Trace — visualize one correlationId's full causal tree.
+ *
+ *   /trace?correlationId=…
+ *
+ * Pulls events from the running wire's `/_nwire/events/{recent,stream}`
+ * SSE surface, groups them by `correlationId`, and renders the causation
+ * forest as a vertical tree (each `causationId` is an edge from parent
+ * `messageId` → child).
+ *
+ *   - Left:   trace picker — recent correlation ids, with the count of
+ *             events under each. Click → loads.
+ *   - Middle: the causation tree. Each node is an event card with name,
+ *             timestamp, payload (collapsed), source location pill.
+ *   - Right:  context explorer — modules touched, apps participating,
+ *             unique events fired, total span, error count. The "who
+ *             touched this trace?" answer.
+ */
+import { computed, onMounted, onUnmounted, ref, watch } from "vue";
+import { useRoute, useRouter } from "vue-router";
+import {
+  Activity,
+  Boxes,
+  Clock,
+  Globe,
+  Network,
+  RefreshCw,
+  Search,
+  Workflow,
+  Zap,
+} from "lucide-vue-next";
+import { useCache } from "@/lib/cache";
+import { SourceDrawer } from "@/components";
+import TraceNode from "./TraceNode.vue";
+
+interface BufferedEvent {
+  seq: number;
+  eventName?: string;
+  payload: unknown;
+  envelope: {
+    messageId: string;
+    correlationId: string;
+    causationId: string;
+    tenant?: string;
+    userId?: string;
+    timestamp: string;
+    version: number;
+  };
+  source: "in-process" | "external";
+  appName: string;
+  capturedAt: string;
+}
+
+const route = useRoute();
+const router = useRouter();
+const { cache } = useCache();
+
+const events = ref<BufferedEvent[]>([]);
+const status = ref<"connecting" | "open" | "closed" | "error">("connecting");
+const expanded = ref<Record<string, boolean>>({});
+const filter = ref("");
+const sourcePreview = ref<{ file: string; line: number; column?: number } | null>(null);
+
+let es: EventSource | null = null;
+
+const selectedCorrelation = computed<string | undefined>({
+  get: () => (route.query.correlationId as string | undefined) ?? recentCorrelations.value[0],
+  set: (id) => {
+    // Preserve the action filter when the user picks a trace.
+    const q: Record<string, string> = {};
+    if (id) q.correlationId = id;
+    if (typeof route.query.action === "string" && route.query.action) {
+      q.action = route.query.action;
+    }
+    router.replace({ path: "/trace", query: q });
+  },
+});
+
+/**
+ * `?action=<name>` seeds the search filter on first paint so the operator
+ * lands on traces whose events were emitted by (or named after) the action.
+ * It is a non-destructive seed — the user can clear it. The existing
+ * `?correlationId` deep-link path is untouched and still wins selection.
+ */
+function applyActionFilter(): void {
+  const action = route.query.action;
+  if (typeof action === "string" && action.length > 0) {
+    filter.value = action;
+  }
+}
+
+onMounted(() => {
+  applyActionFilter();
+  void start();
+});
+watch(() => route.query.action, applyActionFilter);
+onUnmounted(() => es?.close());
+
+async function start() {
+  await loadRecent();
+  connectStream();
+}
+
+async function loadRecent() {
+  try {
+    const r = await fetch("/_nwire/events/recent?limit=500");
+    if (!r.ok) return;
+    const json = (await r.json()) as BufferedEvent[];
+    events.value = json.slice().reverse(); // oldest first
+  } catch {
+    // Wire not reachable yet — connectStream() will retry.
+  }
+}
+
+function connectStream() {
+  status.value = "connecting";
+  es?.close();
+  es = new EventSource("/_nwire/events/stream");
+  es.onopen = () => {
+    status.value = "open";
+  };
+  es.onerror = () => {
+    status.value = "error";
+  };
+  es.onmessage = (m) => {
+    try {
+      const evt = JSON.parse(m.data) as BufferedEvent;
+      events.value.push(evt);
+      if (events.value.length > 2000) events.value.splice(0, 500);
+    } catch {
+      /* ignore */
+    }
+  };
+}
+
+function reconnect() {
+  connectStream();
+}
+function refresh() {
+  void loadRecent();
+}
+
+// ── Recent correlation ids (newest first), bucketed by activity ──────
+const recentCorrelations = computed<readonly string[]>(() => {
+  const seen = new Map<string, number>(); // id → last seq
+  for (const e of events.value) {
+    seen.set(e.envelope.correlationId, e.seq);
+  }
+  return Array.from(seen.entries())
+    .sort((a, b) => b[1] - a[1])
+    .map(([id]) => id);
+});
+
+const filteredCorrelations = computed<readonly string[]>(() => {
+  const q = filter.value.toLowerCase();
+  if (!q) return recentCorrelations.value;
+  return recentCorrelations.value.filter((id) => {
+    if (id.toLowerCase().includes(q)) return true;
+    // Filter on event names + tenant within the trace too.
+    const traceEvents = events.value.filter((e) => e.envelope.correlationId === id);
+    return traceEvents.some(
+      (e) =>
+        e.eventName?.toLowerCase().includes(q) ||
+        e.envelope.tenant?.toLowerCase().includes(q) ||
+        e.envelope.userId?.toLowerCase().includes(q),
+    );
+  });
+});
+
+function correlationLabel(id: string): string {
+  return id.split("-")[0] ?? id.slice(0, 8);
+}
+function correlationCount(id: string): number {
+  let n = 0;
+  for (const e of events.value) if (e.envelope.correlationId === id) n++;
+  return n;
+}
+
+// ── The causal tree for the selected correlation ─────────────────────
+interface TraceNode {
+  evt: BufferedEvent;
+  children: TraceNode[];
+}
+
+const selectedTraceEvents = computed<readonly BufferedEvent[]>(() => {
+  if (!selectedCorrelation.value) return [];
+  return events.value
+    .filter((e) => e.envelope.correlationId === selectedCorrelation.value)
+    .sort((a, b) => a.seq - b.seq);
+});
+
+const causalForest = computed<TraceNode[]>(() => {
+  const evts = selectedTraceEvents.value;
+  if (evts.length === 0) return [];
+  const byMsg = new Map<string, TraceNode>();
+  for (const evt of evts) byMsg.set(evt.envelope.messageId, { evt, children: [] });
+
+  const roots: TraceNode[] = [];
+  for (const node of byMsg.values()) {
+    const cid = node.evt.envelope.causationId;
+    if (!cid || cid === node.evt.envelope.messageId) {
+      roots.push(node);
+      continue;
+    }
+    const parent = byMsg.get(cid);
+    if (parent) parent.children.push(node);
+    else roots.push(node);
+  }
+  return roots;
+});
+
+// ── Index by name for cross-linking to /actions, /events, etc. ───────
+const eventIndex = computed(() => {
+  const m = new Map<
+    string,
+    { module: string; app: string; source?: { file: string; line: number; column?: number } }
+  >();
+  if (cache.value) {
+    for (const e of cache.value.events) {
+      m.set(e.name, { module: e.module, app: e.app, source: e.source });
+    }
+  }
+  return m;
+});
+
+// ── Context explorer ─────────────────────────────────────────────────
+interface ContextDigest {
+  apps: Set<string>;
+  modules: Set<string>;
+  uniqueEvents: Set<string>;
+  startedAt: string;
+  endedAt: string;
+  spanMs: number;
+  total: number;
+  inProcess: number;
+  external: number;
+  tenants: Set<string>;
+  users: Set<string>;
+}
+
+const context = computed<ContextDigest | undefined>(() => {
+  const evts = selectedTraceEvents.value;
+  if (evts.length === 0) return undefined;
+  const apps = new Set<string>();
+  const modules = new Set<string>();
+  const unique = new Set<string>();
+  const tenants = new Set<string>();
+  const users = new Set<string>();
+  let inProc = 0;
+  let external = 0;
+
+  for (const e of evts) {
+    apps.add(e.appName);
+    if (e.eventName) {
+      unique.add(e.eventName);
+      const meta = eventIndex.value.get(e.eventName);
+      if (meta) modules.add(`${meta.app}/${meta.module}`);
+    }
+    if (e.envelope.tenant) tenants.add(e.envelope.tenant);
+    if (e.envelope.userId) users.add(e.envelope.userId);
+    if (e.source === "external") external++;
+    else inProc++;
+  }
+
+  const startedAt = evts[0]!.capturedAt;
+  const endedAt = evts[evts.length - 1]!.capturedAt;
+  const spanMs = new Date(endedAt).getTime() - new Date(startedAt).getTime();
+
+  return {
+    apps,
+    modules,
+    uniqueEvents: unique,
+    startedAt,
+    endedAt,
+    spanMs,
+    total: evts.length,
+    inProcess: inProc,
+    external,
+    tenants,
+    users,
+  };
+});
+
+function isExpanded(id: string): boolean {
+  return expanded.value[id] !== false; // default expanded
+}
+function toggle(id: string): void {
+  expanded.value[id] = !isExpanded(id);
+}
+function formatTime(iso: string): string {
+  return new Date(iso).toLocaleTimeString(undefined, { hour12: false });
+}
+function payloadPreview(p: unknown): string {
+  if (p === undefined || p === null) return "—";
+  const s = JSON.stringify(p);
+  return s.length > 80 ? s.slice(0, 80) + "…" : s;
+}
+
+watch(
+  () => selectedCorrelation.value,
+  () => {
+    expanded.value = {};
+  },
+);
+</script>
+
+<template>
+  <div class="h-full flex">
+    <!-- ── Left: trace picker ───────────────────────────────────────── -->
+    <aside class="w-72 border-r border-zinc-800 flex flex-col shrink-0">
+      <header class="border-b border-zinc-800 px-4 py-3 flex items-center justify-between gap-2">
+        <div class="flex items-center gap-2 min-w-0">
+          <Workflow class="w-4 h-4 text-orange-400" />
+          <h1 class="text-sm font-medium truncate">Traces</h1>
+          <span
+            class="text-[9px] uppercase tracking-wide px-1.5 py-0.5 rounded bg-zinc-900 text-zinc-400"
+          >
+            {{ status }}
+          </span>
+        </div>
+        <button
+          class="p-1 rounded hover:bg-zinc-800 text-zinc-400"
+          title="Refresh"
+          @click="refresh"
+        >
+          <RefreshCw class="w-3.5 h-3.5" />
+        </button>
+      </header>
+
+      <div class="px-3 py-2 border-b border-zinc-800">
+        <div class="relative">
+          <Search class="absolute left-2 top-1/2 -translate-y-1/2 w-3.5 h-3.5 text-zinc-500" />
+          <input
+            v-model="filter"
+            placeholder="filter…"
+            class="w-full bg-zinc-900 border border-zinc-800 rounded pl-7 pr-2 py-1 text-xs placeholder:text-zinc-600 focus:outline-none focus:border-zinc-600"
+          />
+        </div>
+        <div class="text-[10px] text-zinc-500 mt-1">
+          {{ filteredCorrelations.length }} traces · {{ events.length }} events
+        </div>
+      </div>
+
+      <div class="flex-1 overflow-auto">
+        <div v-if="filteredCorrelations.length === 0" class="p-4 text-xs text-zinc-500">
+          {{ events.length === 0 ? "Waiting for events…" : "No traces match the filter." }}
+          <button
+            v-if="status === 'error' || status === 'closed'"
+            class="block mt-2 text-orange-400 hover:underline"
+            @click="reconnect"
+          >
+            Reconnect
+          </button>
+        </div>
+        <button
+          v-for="id in filteredCorrelations"
+          :key="id"
+          class="w-full text-left px-3 py-2 border-b border-zinc-900 hover:bg-zinc-900/50 transition-colors"
+          :class="{ 'bg-zinc-900/70': id === selectedCorrelation }"
+          @click="selectedCorrelation = id"
+        >
+          <div class="flex items-center justify-between gap-2">
+            <span class="font-mono text-xs text-zinc-200 truncate">
+              {{ correlationLabel(id) }}
+            </span>
+            <span class="text-[10px] text-zinc-500 tabular-nums shrink-0">
+              {{ correlationCount(id) }} ev
+            </span>
+          </div>
+        </button>
+      </div>
+    </aside>
+
+    <!-- ── Middle: causal tree ──────────────────────────────────────── -->
+    <main class="flex-1 flex flex-col min-w-0">
+      <header class="border-b border-zinc-800 px-4 py-3 flex items-center gap-3">
+        <Activity class="w-4 h-4 text-emerald-400" />
+        <h2 class="text-sm font-medium">Causal trace</h2>
+        <span v-if="selectedCorrelation" class="text-xs font-mono text-zinc-500">
+          corr {{ correlationLabel(selectedCorrelation) }}
+        </span>
+        <span v-else class="text-xs text-zinc-500">No trace selected.</span>
+      </header>
+
+      <div class="flex-1 overflow-auto p-4">
+        <div
+          v-if="!selectedCorrelation || causalForest.length === 0"
+          class="text-xs text-zinc-500 italic"
+        >
+          Pick a trace from the left to see its causation tree.
+        </div>
+        <ul v-else class="space-y-3">
+          <li v-for="root in causalForest" :key="root.evt.envelope.messageId">
+            <TraceNode
+              :node="root"
+              :depth="0"
+              :event-index="eventIndex"
+              :is-expanded="isExpanded"
+              :toggle="toggle"
+              :format-time="formatTime"
+              :payload-preview="payloadPreview"
+              @open-source="(s) => (sourcePreview = s)"
+            />
+          </li>
+        </ul>
+      </div>
+    </main>
+
+    <!-- ── Right: context explorer ──────────────────────────────────── -->
+    <aside class="w-80 border-l border-zinc-800 flex flex-col shrink-0">
+      <header class="border-b border-zinc-800 px-4 py-3 flex items-center gap-2">
+        <Boxes class="w-4 h-4 text-violet-400" />
+        <h2 class="text-sm font-medium">Context</h2>
+      </header>
+      <div v-if="!context" class="p-4 text-xs text-zinc-500 italic">
+        Context appears once a trace is selected.
+      </div>
+      <div v-else class="overflow-auto divide-y divide-zinc-800">
+        <section class="px-4 py-3">
+          <h3 class="text-[10px] uppercase tracking-wide text-zinc-500 mb-2">Span</h3>
+          <div class="flex items-center gap-2 text-xs">
+            <Clock class="w-3.5 h-3.5 text-zinc-500" />
+            <span class="font-mono">{{ context.spanMs }} ms</span>
+            <span class="text-zinc-600">·</span>
+            <span class="font-mono text-zinc-400">{{ context.total }} events</span>
+          </div>
+          <div class="text-[10px] text-zinc-500 font-mono mt-1">
+            {{ formatTime(context.startedAt) }} → {{ formatTime(context.endedAt) }}
+          </div>
+        </section>
+
+        <section class="px-4 py-3">
+          <h3 class="text-[10px] uppercase tracking-wide text-zinc-500 mb-2">Apps</h3>
+          <div class="flex flex-wrap gap-1">
+            <span
+              v-for="a in [...context.apps]"
+              :key="a"
+              class="inline-flex items-center gap-1 text-xs font-mono bg-zinc-900 border border-zinc-800 rounded px-1.5 py-0.5"
+            >
+              <Globe class="w-3 h-3 text-emerald-400" />
+              {{ a }}
+            </span>
+          </div>
+        </section>
+
+        <section v-if="context.modules.size" class="px-4 py-3">
+          <h3 class="text-[10px] uppercase tracking-wide text-zinc-500 mb-2">Modules touched</h3>
+          <ul class="space-y-1">
+            <li
+              v-for="m in [...context.modules]"
+              :key="m"
+              class="flex items-center gap-2 text-xs font-mono"
+            >
+              <Boxes class="w-3 h-3 text-violet-400" />
+              {{ m }}
+            </li>
+          </ul>
+        </section>
+
+        <section v-if="context.uniqueEvents.size" class="px-4 py-3">
+          <h3 class="text-[10px] uppercase tracking-wide text-zinc-500 mb-2">Distinct events</h3>
+          <ul class="space-y-1">
+            <li
+              v-for="ev in [...context.uniqueEvents]"
+              :key="ev"
+              class="flex items-center gap-2 text-xs font-mono"
+            >
+              <Zap class="w-3 h-3 text-amber-400" />
+              {{ ev }}
+            </li>
+          </ul>
+        </section>
+
+        <section v-if="context.external > 0" class="px-4 py-3">
+          <h3 class="text-[10px] uppercase tracking-wide text-zinc-500 mb-2">Origin</h3>
+          <div class="text-xs space-y-0.5">
+            <div class="flex items-center gap-2">
+              <Globe class="w-3 h-3 text-emerald-400" />
+              <span class="text-zinc-400">in-process</span>
+              <span class="ml-auto font-mono">{{ context.inProcess }}</span>
+            </div>
+            <div class="flex items-center gap-2">
+              <Network class="w-3 h-3 text-violet-400" />
+              <span class="text-zinc-400">external (bus)</span>
+              <span class="ml-auto font-mono">{{ context.external }}</span>
+            </div>
+          </div>
+        </section>
+
+        <section v-if="context.tenants.size || context.users.size" class="px-4 py-3">
+          <h3 class="text-[10px] uppercase tracking-wide text-zinc-500 mb-2">Actor / scope</h3>
+          <div v-if="context.tenants.size" class="text-xs space-y-0.5">
+            <div class="text-zinc-500">Tenants</div>
+            <div v-for="t in [...context.tenants]" :key="t" class="font-mono">
+              {{ t }}
+            </div>
+          </div>
+          <div v-if="context.users.size" class="text-xs space-y-0.5 mt-2">
+            <div class="text-zinc-500">Users</div>
+            <div v-for="u in [...context.users]" :key="u" class="font-mono truncate">
+              {{ u }}
+            </div>
+          </div>
+        </section>
+      </div>
+    </aside>
+
+    <SourceDrawer :source="sourcePreview" @close="sourcePreview = null" />
+  </div>
+</template>

package/src/pages/TraceNode.vue

@@ -0,0 +1,166 @@
+<script setup lang="ts">
+/**
+ * One node in the trace tree. Renders the event card and (when expanded)
+ * recursively renders its causation children.
+ *
+ * Indentation comes from `depth`. The collapsed/expanded state lives in
+ * the parent page (`expanded` ref keyed by messageId) so it survives
+ * re-renders.
+ */
+import { computed } from "vue";
+import { useRouter } from "vue-router";
+import { ChevronDown, ChevronRight, Globe, Network, Zap } from "lucide-vue-next";
+import { useCache } from "@/lib/cache";
+import SourcePill from "@/components/SourcePill.vue";
+
+interface BufferedEvent {
+  seq: number;
+  eventName?: string;
+  payload: unknown;
+  envelope: {
+    messageId: string;
+    correlationId: string;
+    causationId: string;
+    tenant?: string;
+    userId?: string;
+    timestamp: string;
+    version: number;
+  };
+  source: "in-process" | "external";
+  appName: string;
+  capturedAt: string;
+}
+
+interface TraceNode {
+  evt: BufferedEvent;
+  children: TraceNode[];
+}
+
+interface SourceLoc {
+  file: string;
+  line: number;
+  column?: number;
+}
+
+const props = defineProps<{
+  node: TraceNode;
+  depth: number;
+  eventIndex: Map<string, { module: string; app: string; source?: SourceLoc }>;
+  isExpanded: (id: string) => boolean;
+  toggle: (id: string) => void;
+  formatTime: (iso: string) => string;
+  payloadPreview: (p: unknown) => string;
+}>();
+
+const emit = defineEmits<{ (e: "openSource", source: SourceLoc): void }>();
+
+const router = useRouter();
+const { cache } = useCache();
+
+const displayName = props.node.evt.eventName ?? "(framework lifecycle)";
+const meta = props.node.evt.eventName ? props.eventIndex.get(props.node.evt.eventName) : undefined;
+const source = meta?.source;
+
+/**
+ * The action whose handler emitted this event, if any. We look it up by
+ * scanning cache.actions for one whose `emits` list contains this event
+ * name. First match wins. Used to render the "Action: <name>" deep link
+ * back to /actions?name=<name>.
+ */
+const dispatchingAction = computed<string | null>(() => {
+  const evtName = props.node.evt.eventName;
+  if (!evtName || !cache.value) return null;
+  const found = cache.value.actions.find((a) => a.emits.includes(evtName));
+  return found?.name ?? null;
+});
+
+function openAction(name: string): void {
+  void router.push({ path: "/actions", query: { name } });
+}
+
+function open(s: SourceLoc | undefined) {
+  if (s) emit("openSource", s);
+}
+</script>
+
+<template>
+  <div :style="{ paddingLeft: `${depth * 16}px` }">
+    <div class="flex items-start gap-2">
+      <button
+        type="button"
+        class="mt-1.5 text-zinc-500 hover:text-zinc-300 shrink-0"
+        :class="{ invisible: node.children.length === 0 }"
+        @click="toggle(node.evt.envelope.messageId)"
+      >
+        <ChevronDown v-if="isExpanded(node.evt.envelope.messageId)" class="w-3.5 h-3.5" />
+        <ChevronRight v-else class="w-3.5 h-3.5" />
+      </button>
+
+      <div class="flex-1 min-w-0">
+        <div
+          class="rounded border border-zinc-800 bg-zinc-900/30 hover:bg-zinc-900/60 transition-colors p-3"
+        >
+          <div class="flex items-center gap-2 flex-wrap">
+            <component
+              :is="node.evt.source === 'external' ? Network : Globe"
+              class="w-3.5 h-3.5"
+              :class="node.evt.source === 'external' ? 'text-violet-400' : 'text-emerald-400'"
+            />
+            <span
+              class="font-mono text-sm truncate"
+              :class="node.evt.eventName ? 'text-zinc-100' : 'text-zinc-500 italic'"
+            >
+              {{ displayName }}
+            </span>
+            <span class="text-[10px] text-zinc-500 tabular-nums">
+              {{ formatTime(node.evt.capturedAt) }}
+            </span>
+            <span v-if="meta" class="text-[10px] text-zinc-500 font-mono">
+              · {{ meta.app }}/{{ meta.module }}
+            </span>
+            <button v-if="source" type="button" class="ml-auto" @click="open(source)">
+              <SourcePill :source="source" compact />
+            </button>
+          </div>
+          <div class="text-[10px] text-zinc-500 font-mono mt-1 truncate">
+            msg {{ node.evt.envelope.messageId.split("-")[0] }} ← caused by
+            {{ node.evt.envelope.causationId.split("-")[0] }}
+          </div>
+          <div v-if="dispatchingAction" class="text-[10px] mt-1">
+            <button
+              type="button"
+              class="inline-flex items-center gap-1 font-mono text-amber-300 hover:underline"
+              :data-testid="`action-link-${dispatchingAction}`"
+              @click="openAction(dispatchingAction)"
+            >
+              <Zap class="w-3 h-3 text-amber-400" />
+              Action: {{ dispatchingAction }}
+            </button>
+          </div>
+          <div v-if="node.evt.payload" class="text-[11px] font-mono text-zinc-400 mt-1.5 truncate">
+            <Zap class="inline w-3 h-3 text-amber-400 mr-1" />
+            {{ payloadPreview(node.evt.payload) }}
+          </div>
+        </div>
+
+        <div
+          v-if="isExpanded(node.evt.envelope.messageId) && node.children.length"
+          class="mt-2 space-y-2"
+        >
+          <TraceNode
+            v-for="child in node.children"
+            :key="child.evt.envelope.messageId"
+            :node="child"
+            :depth="depth + 1"
+            :event-index="eventIndex"
+            :is-expanded="isExpanded"
+            :toggle="toggle"
+            :format-time="formatTime"
+            :payload-preview="payloadPreview"
+            @open-source="emit('openSource', $event)"
+          />
+        </div>
+      </div>
+    </div>
+  </div>
+</template>