nuxt-devtools-observatory 0.1.30 → 0.1.32

package/dist/runtime/nitro/ssr-trace-store.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Per-request SSR trace collector.
+ *
+ * Each incoming SSR page request gets its own record keyed by a unique
+ * requestId (stored on H3 `event.context`). Spans are accumulated during the
+ * request lifecycle and drained once the HTML is rendered (via the
+ * `render:html` Nitro hook), so they can be injected into the page as inline
+ * JSON for the client plugin to pick up.
+ */
+export interface SsrSpan {
+    id: string;
+    name: string;
+    type: string;
+    /** Milliseconds relative to request start (0 = request began). */
+    startTime: number;
+    endTime?: number;
+    durationMs?: number;
+    status: 'ok' | 'error' | 'active';
+    metadata?: Record<string, unknown>;
+}
+export interface SsrTraceRecord {
+    traceId: string;
+    name: string;
+    spans: SsrSpan[];
+}
+/**
+ * Open a new per-request SSR record. A `navigation` span covering the full
+ * request is pre-populated; its end time is filled in when `drainSsrRecord`
+ * is called.
+ * @param {string} requestId - Unique identifier for the HTTP request, stored in `event.context`.
+ * @param {string} route - Request pathname (e.g. `/dashboard`).
+ * @param {string} method - HTTP method in upper-case (e.g. `GET`).
+ * @returns {SsrTraceRecord} The newly created `SsrTraceRecord` keyed by `requestId`.
+ */
+export declare function createSsrRecord(requestId: string, route: string, method: string): SsrTraceRecord;
+/**
+ * Append an SSR-side fetch span. `startMs` / `endMs` are milliseconds
+ * relative to request start (same origin as `createSsrRecord`).
+ * @param {string} requestId - The request identifier returned by `createSsrRecord`.
+ * @param {object} opts - Span options.
+ * @param {string} opts.url - The request URL or path that was fetched.
+ * @param {string} opts.method - HTTP method in upper-case (e.g. `GET`).
+ * @param {number} opts.startMs - Span start, in ms relative to the request start time.
+ * @param {number} opts.endMs - Span end, in ms relative to the request start time.
+ * @param {number} [opts.statusCode] - Optional HTTP response status code.
+ * @param {boolean} [opts.error] - Set to `true` to mark the span status as `error`.
+ */
+export declare function addSsrFetchSpan(requestId: string, opts: {
+    url: string;
+    method: string;
+    startMs: number;
+    endMs: number;
+    statusCode?: number;
+    error?: boolean;
+}): void;
+/**
+ * Append a generic SSR phase span (e.g. `render:html`, `afterResponse`) to
+ * an existing request record.
+ * @param {string} requestId - The request identifier returned by `createSsrRecord`.
+ * @param {object} opts - Span options.
+ * @param {string} opts.name - Human-readable span name.
+ * @param {string} [opts.type] - Span type. Defaults to `server`.
+ * @param {number} opts.startMs - Span start, in ms relative to request start.
+ * @param {number} opts.endMs - Span end, in ms relative to request start.
+ * @param {boolean} [opts.error] - Set to `true` to mark the span status as `error`.
+ * @param {Record<string, unknown>} [opts.metadata] - Additional metadata fields.
+ */
+export declare function addSsrPhaseSpan(requestId: string, opts: {
+    name: string;
+    type?: string;
+    startMs: number;
+    endMs: number;
+    error?: boolean;
+    metadata?: Record<string, unknown>;
+}): void;
+/**
+ * Finalize and remove the record for `requestId`. The pre-populated
+ * navigation span is closed with `durationMs`. Returns `undefined` if the
+ * requestId is unknown (e.g. non-page requests that never called
+ * `createSsrRecord`).
+ * @param {string} requestId - The request identifier returned by `createSsrRecord`.
+ * @param {number} durationMs - Total SSR request duration in milliseconds, used to close the navigation span.
+ * @returns {SsrTraceRecord | undefined} The completed `SsrTraceRecord`, or `undefined` if no record exists for `requestId`.
+ */
+export declare function drainSsrRecord(requestId: string, durationMs: number): SsrTraceRecord | undefined;

package/dist/runtime/nitro/ssr-trace-store.js

@@ -0,0 +1,84 @@
+const pending = /* @__PURE__ */ new Map();
+let _counter = 0;
+function newId(prefix) {
+  _counter = (_counter + 1) % 999999;
+  return `${prefix}_ssr_${Date.now()}_${_counter}`;
+}
+export function createSsrRecord(requestId, route, method) {
+  const record = {
+    traceId: newId("trace"),
+    name: `ssr:${route}`,
+    spans: [
+      {
+        id: newId("span"),
+        name: "ssr:navigation",
+        type: "navigation",
+        startTime: 0,
+        status: "active",
+        metadata: {
+          origin: "ssr",
+          route,
+          method
+        }
+      }
+    ]
+  };
+  pending.set(requestId, record);
+  return record;
+}
+export function addSsrFetchSpan(requestId, opts) {
+  const record = pending.get(requestId);
+  if (!record) {
+    return;
+  }
+  const durationMs = Math.max(opts.endMs - opts.startMs, 0);
+  record.spans.push({
+    id: newId("span"),
+    name: opts.url,
+    type: "fetch",
+    startTime: opts.startMs,
+    endTime: opts.endMs,
+    durationMs,
+    status: opts.error ? "error" : "ok",
+    metadata: {
+      origin: "ssr",
+      url: opts.url,
+      method: opts.method,
+      statusCode: opts.statusCode
+    }
+  });
+}
+export function addSsrPhaseSpan(requestId, opts) {
+  const record = pending.get(requestId);
+  if (!record) {
+    return;
+  }
+  const durationMs = Math.max(opts.endMs - opts.startMs, 0);
+  record.spans.push({
+    id: newId("span"),
+    name: opts.name,
+    type: opts.type ?? "server",
+    startTime: opts.startMs,
+    endTime: opts.endMs,
+    durationMs,
+    status: opts.error ? "error" : "ok",
+    metadata: {
+      origin: "ssr",
+      ...opts.metadata ?? {}
+    }
+  });
+}
+export function drainSsrRecord(requestId, durationMs) {
+  const record = pending.get(requestId);
+  pending.delete(requestId);
+  if (!record) {
+    return void 0;
+  }
+  const navSpan = record.spans[0];
+  if (navSpan) {
+    navSpan.endTime = durationMs;
+    navSpan.durationMs = durationMs;
+    navSpan.status = "ok";
+  }
+  return record;
+}

package/dist/runtime/plugin.js

@@ -5,6 +5,10 @@ import { setupFetchRegistry } from "./composables/fetch-registry.js";
 import { setupProvideInjectRegistry } from "./composables/provide-inject-registry.js";
 import { setupRenderRegistry } from "./composables/render-registry.js";
 import { setupTransitionRegistry } from "./composables/transition-registry.js";
+import { setupComponentInstrumentation } from "./instrumentation/component.js";
+import { setupFetchInstrumentation } from "./instrumentation/fetch.js";
+import { setupRouteInstrumentation } from "./instrumentation/route.js";
+import { traceStore } from "./tracing/traceStore.js";
 export default defineNuxtPlugin(() => {
   if (!import.meta.dev) {
     return;
@@ -41,7 +45,55 @@ export default defineNuxtPlugin(() => {
   if (config.transitionTracker) {
     registries.transition = setupTransitionRegistry();
   }
+  function mergeSsrSpans() {
+    if (!import.meta.client) {
+      return;
+    }
+    const el = document.getElementById("__observatory_ssr_spans__");
+    if (!el) {
+      return;
+    }
+    let record;
+    try {
+      record = JSON.parse(el.textContent ?? "");
+    } catch {
+      return;
+    }
+    if (!record?.traceId || !Array.isArray(record.spans)) {
+      return;
+    }
+    const navDurationMs = record.spans[0]?.durationMs ?? 0;
+    const traceStartTime = performance.now() - navDurationMs;
+    traceStore.createTrace({
+      id: record.traceId,
+      name: record.name,
+      startTime: traceStartTime,
+      metadata: { origin: "ssr" }
+    });
+    for (const span of record.spans) {
+      traceStore.addSpan({
+        id: span.id,
+        traceId: record.traceId,
+        name: span.name,
+        type: span.type,
+        startTime: traceStartTime + span.startTime,
+        endTime: span.endTime !== void 0 ? traceStartTime + span.endTime : void 0,
+        status: span.status,
+        metadata: { ...span.metadata ?? {}, origin: "ssr" }
+      });
+    }
+    traceStore.endTrace(record.traceId, {
+      endTime: traceStartTime + navDurationMs,
+      status: "ok",
+      metadata: { origin: "ssr" }
+    });
+  }
   if (import.meta.client) {
+    if (config.traceViewer) {
+      setupComponentInstrumentation(nuxtApp);
+      setupFetchInstrumentation(nuxtApp);
+      mergeSsrSpans();
+    }
     delete window.__observatory__;
     window.__observatory__ = registries;
     const composableRegistry = registries.composable;
@@ -121,6 +173,11 @@ export default defineNuxtPlugin(() => {
   });
   if (import.meta.client) {
     const router = useRouter();
+    if (config.traceViewer) {
+      setupRouteInstrumentation(nuxtApp, {
+        getCurrentPath: () => router.currentRoute.value.path ?? "/"
+      });
+    }
     router.beforeEach(
       (_to, from) => {
         if (!from || from.name === void 0) {
@@ -175,7 +232,8 @@ export default defineNuxtPlugin(() => {
       fetch: Array.isArray(snapshot.fetch) ? snapshot.fetch.length : 0,
       composables: Array.isArray(snapshot.composables) ? snapshot.composables.length : 0,
       renders: Array.isArray(snapshot.renders) ? snapshot.renders.length : 0,
-      transitions: Array.isArray(snapshot.transitions) ? snapshot.transitions.length : 0
+      transitions: Array.isArray(snapshot.transitions) ? snapshot.transitions.length : 0,
+      traces: Array.isArray(snapshot.traces) ? snapshot.traces.length : 0
     });
     lastSnapshotSignature = JSON.stringify(snapshot);
     import.meta.hot.send("observatory:snapshot", snapshot);
@@ -207,13 +265,35 @@ export default defineNuxtPlugin(() => {
       const hasGetSnapshot = reg && typeof reg.getSnapshot === "function";
       snapshot[key === "composable" ? "composables" : key === "render" ? "renders" : key === "transition" ? "transitions" : key] = hasGetSnapshot ? safeParse(reg.getSnapshot(), fallback) : fallback;
     }
+    snapshot.traces = config.traceViewer ? traceStore.getAllTraces().map((trace) => ({
+      id: trace.id,
+      name: trace.name,
+      startTime: trace.startTime,
+      endTime: trace.endTime,
+      durationMs: trace.durationMs,
+      status: trace.status,
+      metadata: trace.metadata,
+      spans: trace.spans.map((span) => ({
+        id: span.id,
+        traceId: span.traceId,
+        parentSpanId: span.parentSpanId,
+        name: span.name,
+        type: span.type,
+        startTime: span.startTime,
+        endTime: span.endTime,
+        durationMs: span.durationMs,
+        status: span.status,
+        metadata: span.metadata
+      }))
+    })) : [];
     snapshot.features = {
       fetchDashboard: !!registries.fetch,
       provideInjectGraph: !!registries.provideInject,
       composableTracker: !!registries.composable,
       composableNavigationMode,
       renderHeatmap: !!registries.render,
-      transitionTracker: !!registries.transition
+      transitionTracker: !!registries.transition,
+      traceViewer: !!config.traceViewer
     };
     return snapshot;
   }

package/dist/runtime/tracing/context.d.ts

@@ -0,0 +1,9 @@
+declare const TRACE_CONTEXT_KEY = "__observatory_trace_context__";
+type TraceContextCarrier = {
+    [TRACE_CONTEXT_KEY]?: {
+        currentTraceId?: string;
+    };
+};
+export declare function setCurrentTraceId(traceId: string | undefined, carrier?: TraceContextCarrier): void;
+export declare function getCurrentTraceId(carrier?: TraceContextCarrier): string | undefined;
+export {};

package/dist/runtime/tracing/context.js

@@ -0,0 +1,15 @@
+const TRACE_CONTEXT_KEY = "__observatory_trace_context__";
+function getGlobalCarrier() {
+  return globalThis;
+}
+export function setCurrentTraceId(traceId, carrier) {
+  const target = carrier ?? getGlobalCarrier();
+  if (!target[TRACE_CONTEXT_KEY]) {
+    target[TRACE_CONTEXT_KEY] = {};
+  }
+  target[TRACE_CONTEXT_KEY].currentTraceId = traceId;
+}
+export function getCurrentTraceId(carrier) {
+  const target = carrier ?? getGlobalCarrier();
+  return target[TRACE_CONTEXT_KEY]?.currentTraceId;
+}

package/dist/runtime/tracing/trace.d.ts

@@ -0,0 +1,25 @@
+export type SpanType = 'render' | 'component' | 'transition' | 'fetch' | 'composable' | 'navigation' | 'custom' | (string & {});
+export type SpanStatus = 'active' | 'ok' | 'error' | 'cancelled';
+export interface Span {
+    id: string;
+    traceId: string;
+    parentSpanId?: string;
+    name: string;
+    type: SpanType;
+    startTime: number;
+    endTime?: number;
+    durationMs?: number;
+    status: SpanStatus;
+    metadata?: Record<string, unknown>;
+}
+export type TraceStatus = 'active' | 'ok' | 'error' | 'cancelled';
+export interface Trace {
+    id: string;
+    name: string;
+    startTime: number;
+    endTime?: number;
+    durationMs?: number;
+    status: TraceStatus;
+    metadata?: Record<string, unknown>;
+    spans: Span[];
+}

package/dist/runtime/tracing/traceStore.d.ts

@@ -0,0 +1,39 @@
+import type { Span, SpanStatus, Trace, TraceStatus } from './trace.js';
+export interface CreateTraceInput {
+    id?: string;
+    name?: string;
+    startTime?: number;
+    metadata?: Record<string, unknown>;
+}
+export interface AddSpanInput {
+    id?: string;
+    traceId: string;
+    parentSpanId?: string;
+    name: string;
+    type: Span['type'];
+    startTime?: number;
+    endTime?: number;
+    status?: SpanStatus;
+    metadata?: Record<string, unknown>;
+}
+export interface EndTraceInput {
+    endTime?: number;
+    status?: TraceStatus;
+    metadata?: Record<string, unknown>;
+}
+export declare class TraceStore {
+    private readonly traces;
+    createTrace(input?: CreateTraceInput): Trace;
+    addSpan(input: AddSpanInput): Span;
+    endTrace(traceId: string, input?: EndTraceInput): Trace | null;
+    endSpan(spanId: string, traceId: string, input?: {
+        endTime?: number;
+        status?: SpanStatus;
+        metadata?: Record<string, unknown>;
+    }): Span | null;
+    getTrace(traceId: string): Trace | undefined;
+    getAllTraces(): Trace[];
+    clear(): void;
+    private ensureTrace;
+}
+export declare const traceStore: TraceStore;

package/dist/runtime/tracing/traceStore.js

@@ -0,0 +1,101 @@
+function createId(prefix) {
+  const random = Math.random().toString(36).slice(2, 10);
+  return `${prefix}_${Date.now()}_${random}`;
+}
+function computeDuration(startTime, endTime) {
+  return Math.max(endTime - startTime, 0);
+}
+export class TraceStore {
+  traces = /* @__PURE__ */ new Map();
+  createTrace(input = {}) {
+    const startTime = input.startTime ?? performance.now();
+    const trace = {
+      id: input.id ?? createId("trace"),
+      name: input.name ?? "trace",
+      startTime,
+      status: "active",
+      metadata: input.metadata,
+      spans: []
+    };
+    this.traces.set(trace.id, trace);
+    return trace;
+  }
+  addSpan(input) {
+    const trace = this.ensureTrace(input.traceId, input.startTime);
+    const startTime = input.startTime ?? performance.now();
+    const endTime = input.endTime;
+    const span = {
+      id: input.id ?? createId("span"),
+      traceId: trace.id,
+      parentSpanId: input.parentSpanId,
+      name: input.name,
+      type: input.type,
+      startTime,
+      endTime,
+      durationMs: endTime !== void 0 ? computeDuration(startTime, endTime) : void 0,
+      status: input.status ?? (endTime !== void 0 ? "ok" : "active"),
+      metadata: input.metadata
+    };
+    trace.spans.push(span);
+    if (trace.endTime !== void 0) {
+      trace.durationMs = computeDuration(trace.startTime, trace.endTime);
+    }
+    return span;
+  }
+  endTrace(traceId, input = {}) {
+    const trace = this.traces.get(traceId);
+    if (!trace) {
+      return null;
+    }
+    const endTime = input.endTime ?? performance.now();
+    trace.endTime = endTime;
+    trace.durationMs = computeDuration(trace.startTime, endTime);
+    trace.status = input.status ?? "ok";
+    if (input.metadata) {
+      trace.metadata = {
+        ...trace.metadata ?? {},
+        ...input.metadata
+      };
+    }
+    return trace;
+  }
+  endSpan(spanId, traceId, input = {}) {
+    const trace = this.traces.get(traceId);
+    if (!trace) {
+      return null;
+    }
+    const span = trace.spans.find((item) => item.id === spanId);
+    if (!span) {
+      return null;
+    }
+    const endTime = input.endTime ?? performance.now();
+    span.endTime = endTime;
+    span.durationMs = computeDuration(span.startTime, endTime);
+    span.status = input.status ?? "ok";
+    if (input.metadata) {
+      span.metadata = {
+        ...span.metadata ?? {},
+        ...input.metadata
+      };
+    }
+    return span;
+  }
+  getTrace(traceId) {
+    return this.traces.get(traceId);
+  }
+  getAllTraces() {
+    return [...this.traces.values()];
+  }
+  clear() {
+    this.traces.clear();
+  }
+  ensureTrace(traceId, startTime) {
+    const existing = this.traces.get(traceId);
+    if (existing) {
+      return existing;
+    }
+    const trace = this.createTrace({ id: traceId, startTime });
+    return trace;
+  }
+}
+export const traceStore = new TraceStore();

package/dist/runtime/tracing/tracing.d.ts

@@ -0,0 +1,27 @@
+import { type TraceStore } from './traceStore.js';
+import type { Span, SpanStatus, SpanType, Trace } from './trace.js';
+export interface StartSpanInput {
+    name: string;
+    type: SpanType;
+    traceId?: string;
+    parentSpanId?: string;
+    metadata?: Record<string, unknown>;
+    startTime?: number;
+}
+export interface EndSpanInput {
+    endTime?: number;
+    status?: SpanStatus;
+    metadata?: Record<string, unknown>;
+}
+export interface SpanHandle {
+    trace: Trace;
+    span: Span;
+    end: (input?: EndSpanInput) => Span;
+}
+export interface StartSpanOptions {
+    store?: TraceStore;
+    carrier?: object;
+    traceName?: string;
+    traceMetadata?: Record<string, unknown>;
+}
+export declare function startSpan(input: StartSpanInput, options?: StartSpanOptions): SpanHandle;

package/dist/runtime/tracing/tracing.js

@@ -0,0 +1,48 @@
+import { getCurrentTraceId, setCurrentTraceId } from "./context.js";
+import { traceStore } from "./traceStore.js";
+export function startSpan(input, options = {}) {
+  const store = options.store ?? traceStore;
+  const activeTraceId = input.traceId ?? getCurrentTraceId(options.carrier);
+  let trace = activeTraceId ? store.getTrace(activeTraceId) : void 0;
+  if (!trace) {
+    trace = store.createTrace({
+      id: activeTraceId,
+      name: options.traceName ?? input.name,
+      metadata: options.traceMetadata,
+      startTime: input.startTime
+    });
+  }
+  setCurrentTraceId(trace.id, options.carrier);
+  const span = store.addSpan({
+    traceId: trace.id,
+    parentSpanId: input.parentSpanId,
+    name: input.name,
+    type: input.type,
+    metadata: input.metadata,
+    startTime: input.startTime
+  });
+  let ended = false;
+  const end = (endInput = {}) => {
+    if (ended) {
+      return span;
+    }
+    const endedSpan = store.endSpan(span.id, trace.id, {
+      endTime: endInput.endTime,
+      status: endInput.status,
+      metadata: endInput.metadata
+    });
+    ended = true;
+    if (endedSpan) {
+      span.endTime = endedSpan.endTime;
+      span.durationMs = endedSpan.durationMs;
+      span.status = endedSpan.status;
+      span.metadata = endedSpan.metadata;
+    }
+    return span;
+  };
+  return {
+    trace,
+    span,
+    end
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "nuxt-devtools-observatory",
-    "version": "0.1.30",
+    "version": "0.1.32",
     "description": "Nuxt DevTools: useFetch Dashboard, provide/inject Graph, Composable Tracker, Render Heatmap",
     "license": "MIT",
     "repository": {
@@ -27,6 +27,10 @@
         "./runtime/fetch-registry": {
             "types": "./dist/runtime/composables/fetch-registry.d.ts",
             "import": "./dist/runtime/composables/fetch-registry.js"
+        },
+        "./runtime/async-data-instrumentation": {
+            "types": "./dist/runtime/instrumentation/asyncData.d.ts",
+            "import": "./dist/runtime/instrumentation/asyncData.js"
         }
     },
     "files": [

package/client/.env

@@ -1,16 +0,0 @@
-# Observatory registry/configurable limits
-VITE_OBSERVATORY_FETCH_DASHBOARD=true
-VITE_OBSERVATORY_PROVIDE_INJECT_GRAPH=true
-VITE_OBSERVATORY_COMPOSABLE_TRACKER=true
-VITE_OBSERVATORY_RENDER_HEATMAP=true
-VITE_OBSERVATORY_TRANSITION_TRACKER=true
-VITE_OBSERVATORY_MAX_FETCH_ENTRIES=200
-VITE_OBSERVATORY_MAX_PAYLOAD_BYTES=10000
-VITE_OBSERVATORY_MAX_TRANSITIONS=500
-VITE_OBSERVATORY_MAX_COMPOSABLE_HISTORY=50
-VITE_OBSERVATORY_MAX_COMPOSABLE_ENTRIES=300
-VITE_OBSERVATORY_MAX_RENDER_TIMELINE=100
-VITE_OBSERVATORY_HEATMAP_THRESHOLD_COUNT=3
-VITE_OBSERVATORY_HEATMAP_THRESHOLD_TIME=1600
-VITE_OBSERVATORY_HEATMAP_HIDE_INTERNALS=true
-VITE_OBSERVATORY_INSTRUMENT_SERVER=true