@vestig/next 0.5.0 → 0.8.0

package/dist/metrics/thresholds.js

@@ -0,0 +1,148 @@
+/**
+ * Core Web Vitals Thresholds
+ *
+ * Official thresholds from Google's Core Web Vitals program.
+ * These determine whether a metric is rated as "good", "needs-improvement", or "poor".
+ *
+ * @see https://web.dev/articles/vitals
+ * @packageDocumentation
+ */
+/**
+ * Official Core Web Vitals thresholds
+ *
+ * Values represent the upper bounds:
+ * - good: value < threshold.good
+ * - needs-improvement: threshold.good <= value < threshold.poor
+ * - poor: value >= threshold.poor
+ */
+export const THRESHOLDS = {
+    /**
+     * Largest Contentful Paint
+     * Measures loading performance - when the largest content element becomes visible
+     */
+    LCP: {
+        good: 2500,
+        poor: 4000,
+        unit: 'ms',
+        description: 'Largest Contentful Paint - Loading performance',
+    },
+    /**
+     * Cumulative Layout Shift
+     * Measures visual stability - how much the page layout shifts unexpectedly
+     */
+    CLS: {
+        good: 0.1,
+        poor: 0.25,
+        unit: 'score',
+        description: 'Cumulative Layout Shift - Visual stability',
+    },
+    /**
+     * Interaction to Next Paint
+     * Measures interactivity - time from user interaction to visual feedback
+     */
+    INP: {
+        good: 200,
+        poor: 500,
+        unit: 'ms',
+        description: 'Interaction to Next Paint - Interactivity',
+    },
+    /**
+     * Time to First Byte
+     * Measures server responsiveness - time until first byte of response
+     */
+    TTFB: {
+        good: 800,
+        poor: 1800,
+        unit: 'ms',
+        description: 'Time to First Byte - Server responsiveness',
+    },
+    /**
+     * First Contentful Paint
+     * Measures perceived load speed - when first content is rendered
+     */
+    FCP: {
+        good: 1800,
+        poor: 3000,
+        unit: 'ms',
+        description: 'First Contentful Paint - Perceived load speed',
+    },
+};
+/**
+ * Calculate rating for a metric value
+ *
+ * @param name - Web Vital metric name
+ * @param value - Metric value
+ * @returns Rating based on thresholds
+ *
+ * @example
+ * ```ts
+ * getRating('LCP', 2000) // 'good'
+ * getRating('LCP', 3000) // 'needs-improvement'
+ * getRating('LCP', 5000) // 'poor'
+ * ```
+ */
+export function getRating(name, value) {
+    const threshold = THRESHOLDS[name];
+    if (!threshold)
+        return 'needs-improvement';
+    if (value < threshold.good)
+        return 'good';
+    if (value < threshold.poor)
+        return 'needs-improvement';
+    return 'poor';
+}
+/**
+ * Get human-readable description for a metric
+ */
+export function getMetricDescription(name) {
+    return THRESHOLDS[name]?.description ?? name;
+}
+/**
+ * Get unit for a metric
+ */
+export function getMetricUnit(name) {
+    return THRESHOLDS[name]?.unit ?? 'ms';
+}
+/**
+ * Format a metric value for display
+ *
+ * @param name - Metric name
+ * @param value - Metric value
+ * @returns Formatted string
+ *
+ * @example
+ * ```ts
+ * formatMetricValue('LCP', 2500) // '2.50s'
+ * formatMetricValue('CLS', 0.15) // '0.15'
+ * formatMetricValue('INP', 150)  // '150ms'
+ * ```
+ */
+export function formatMetricValue(name, value) {
+    const unit = getMetricUnit(name);
+    if (unit === 'score') {
+        return value.toFixed(3);
+    }
+    // For timing metrics
+    if (value < 1) {
+        return `${(value * 1000).toFixed(0)}μs`;
+    }
+    if (value < 1000) {
+        return `${value.toFixed(0)}ms`;
+    }
+    return `${(value / 1000).toFixed(2)}s`;
+}
+/**
+ * Rating colors for UI display
+ */
+export const RATING_COLORS = {
+    good: { bg: '#dcfce7', text: '#166534', border: '#86efac' },
+    'needs-improvement': { bg: '#fef3c7', text: '#92400e', border: '#fcd34d' },
+    poor: { bg: '#fee2e2', text: '#991b1b', border: '#fca5a5' },
+};
+/**
+ * Get color scheme for a rating
+ */
+export function getRatingColors(rating) {
+    return RATING_COLORS[rating];
+}
+//# sourceMappingURL=thresholds.js.map

package/dist/metrics/thresholds.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"thresholds.js","sourceRoot":"","sources":["../../src/metrics/thresholds.ts"],"names":[],"mappings":"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"}

package/dist/metrics/types.d.ts

@@ -0,0 +1,211 @@
+/**
+ * Core Web Vitals and Route Metrics Types
+ *
+ * These types define the structure for capturing and reporting
+ * performance metrics in Next.js applications.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Web Vital metric names
+ * - LCP: Largest Contentful Paint (loading performance)
+ * - CLS: Cumulative Layout Shift (visual stability)
+ * - INP: Interaction to Next Paint (interactivity)
+ * - TTFB: Time to First Byte (server responsiveness)
+ * - FCP: First Contentful Paint (perceived load speed)
+ */
+export type WebVitalName = 'LCP' | 'CLS' | 'INP' | 'TTFB' | 'FCP';
+/**
+ * Rating for a metric based on Core Web Vitals thresholds
+ */
+export type MetricRating = 'good' | 'needs-improvement' | 'poor';
+/**
+ * Navigation type from Performance API
+ */
+export type NavigationType = 'navigate' | 'reload' | 'back-forward' | 'back-forward-cache' | 'prerender' | 'restore';
+/**
+ * Web Vital metric captured from the browser
+ */
+export interface WebVitalMetric {
+    /** Metric name (LCP, CLS, INP, TTFB, FCP) */
+    name: WebVitalName;
+    /** Metric value (ms for timing metrics, score for CLS) */
+    value: number;
+    /** Rating based on Core Web Vitals thresholds */
+    rating: MetricRating;
+    /** Change since last measurement */
+    delta: number;
+    /** Unique identifier for this metric instance */
+    id: string;
+    /** How the page was navigated to */
+    navigationType: NavigationType;
+    /** Entries that contributed to this metric */
+    entries: PerformanceEntry[];
+}
+/**
+ * Route-specific performance metric
+ */
+export interface RouteMetric {
+    /** Route pathname (e.g., /dashboard, /users/[id]) */
+    pathname: string;
+    /** Time to render the route in ms */
+    renderTime: number;
+    /** Time to hydrate the route in ms */
+    hydrationTime: number;
+    /** Time to fetch route data (if applicable) */
+    dataFetchTime?: number;
+    /** ISO timestamp when metric was captured */
+    timestamp: string;
+    /** Request ID for correlation with server logs */
+    requestId?: string;
+}
+/**
+ * Stored metric entry for Dev Overlay and reporting
+ */
+export interface MetricEntry {
+    /** Unique identifier */
+    id: string;
+    /** ISO timestamp */
+    timestamp: string;
+    /** Type of metric */
+    type: 'web-vital' | 'route' | 'custom';
+    /** Metric name */
+    name: string;
+    /** Metric value */
+    value: number;
+    /** Rating (for web vitals) */
+    rating?: MetricRating;
+    /** Additional metadata */
+    metadata: {
+        pathname?: string;
+        requestId?: string;
+        traceId?: string;
+        userAgent?: string;
+        navigationType?: NavigationType;
+        delta?: number;
+    };
+}
+/**
+ * Histogram bucket for metric visualization
+ */
+export interface HistogramBucket {
+    /** Lower bound of bucket (inclusive) */
+    min: number;
+    /** Upper bound of bucket (exclusive) */
+    max: number;
+    /** Count of values in this bucket */
+    count: number;
+    /** Percentage of total */
+    percentage: number;
+}
+/**
+ * Summary statistics for a metric
+ */
+export interface MetricSummary {
+    /** Metric name */
+    name: string;
+    /** Number of samples */
+    count: number;
+    /** Average value */
+    avg: number;
+    /** Minimum value */
+    min: number;
+    /** Maximum value */
+    max: number;
+    /** 50th percentile (median) */
+    p50: number;
+    /** 75th percentile */
+    p75: number;
+    /** 95th percentile */
+    p95: number;
+    /** 99th percentile */
+    p99: number;
+    /** Overall rating based on p75 */
+    rating: MetricRating;
+}
+/**
+ * Configuration for VestigMetrics component
+ */
+export interface VestigMetricsConfig {
+    /**
+     * Sampling rate for metrics collection (0.0 - 1.0)
+     * @default 1.0 in development, 0.1 in production
+     */
+    sampleRate?: number;
+    /**
+     * Endpoint to report metrics to
+     * @default '/api/vestig/metrics'
+     */
+    reportEndpoint?: string;
+    /**
+     * Enable/disable metrics collection
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Batch interval for reporting in milliseconds
+     * @default 5000
+     */
+    batchInterval?: number;
+    /**
+     * Report immediately when a metric has poor rating
+     * @default true
+     */
+    reportPoorImmediately?: boolean;
+    /**
+     * Capture route metrics (render time, hydration)
+     * @default true
+     */
+    captureRouteMetrics?: boolean;
+    /**
+     * Debug mode - logs metrics to console
+     * @default false
+     */
+    debug?: boolean;
+}
+/**
+ * Metrics store state
+ */
+export interface MetricsState {
+    /** All captured metrics */
+    metrics: MetricEntry[];
+    /** Maximum number of metrics to keep in memory */
+    maxMetrics: number;
+    /** Latest value for each web vital */
+    latestVitals: Partial<Record<WebVitalName, MetricEntry>>;
+}
+/**
+ * Metrics store interface
+ */
+export interface MetricsStore {
+    /** Subscribe to store changes */
+    subscribe: (listener: () => void) => () => void;
+    /** Get current snapshot of state */
+    getSnapshot: () => MetricsState;
+    /** Add a new metric */
+    addMetric: (entry: Omit<MetricEntry, 'id' | 'timestamp'>) => void;
+    /** Get histogram for a specific metric */
+    getHistogram: (name: string, bucketCount?: number) => HistogramBucket[];
+    /** Get summary statistics for a metric */
+    getSummary: (name: string) => MetricSummary | null;
+    /** Get all summaries for web vitals */
+    getVitalsSummary: () => Partial<Record<WebVitalName, MetricSummary>>;
+    /** Get the latest metric for a given name */
+    getLatest: (name: string) => MetricEntry | null;
+    /** Clear all metrics */
+    clear: () => void;
+}
+/**
+ * Payload for metrics reporting
+ */
+export interface MetricsReportPayload {
+    /** Metrics to report */
+    metrics: MetricEntry[];
+    /** Client metadata */
+    client: {
+        userAgent: string;
+        pathname: string;
+        timestamp: string;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/metrics/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/metrics/types.ts"],"names":[],"mappings":"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"}

package/dist/metrics/types.js

@@ -0,0 +1,10 @@
+/**
+ * Core Web Vitals and Route Metrics Types
+ *
+ * These types define the structure for capturing and reporting
+ * performance metrics in Next.js applications.
+ *
+ * @packageDocumentation
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/metrics/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/metrics/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/metrics/web-vitals.d.ts

@@ -0,0 +1,72 @@
+/**
+ * VestigMetrics Component
+ *
+ * Drop-in component for capturing Core Web Vitals and route metrics.
+ * Add this to your root layout for automatic performance monitoring.
+ *
+ * @example
+ * ```tsx
+ * // app/layout.tsx
+ * import { VestigMetrics } from '@vestig/next/metrics'
+ *
+ * export default function RootLayout({ children }) {
+ *   return (
+ *     <html>
+ *       <body>
+ *         {children}
+ *         <VestigMetrics
+ *           sampleRate={0.1}  // 10% sampling in production
+ *           reportEndpoint="/api/vestig/metrics"
+ *         />
+ *       </body>
+ *     </html>
+ *   )
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+import type { VestigMetricsConfig } from './types';
+/**
+ * Props for VestigMetrics component
+ */
+export interface VestigMetricsProps extends VestigMetricsConfig {
+}
+/**
+ * VestigMetrics - Core Web Vitals and Route Metrics Component
+ *
+ * This component automatically captures:
+ * - **LCP** (Largest Contentful Paint) - Loading performance
+ * - **CLS** (Cumulative Layout Shift) - Visual stability
+ * - **INP** (Interaction to Next Paint) - Interactivity
+ * - **TTFB** (Time to First Byte) - Server responsiveness
+ * - **FCP** (First Contentful Paint) - Perceived load speed
+ * - **Route metrics** - Navigation and hydration times
+ *
+ * @example Basic usage
+ * ```tsx
+ * <VestigMetrics />
+ * ```
+ *
+ * @example With configuration
+ * ```tsx
+ * <VestigMetrics
+ *   sampleRate={0.1}           // 10% of users
+ *   reportEndpoint="/api/metrics"
+ *   reportPoorImmediately      // Alert on poor metrics
+ *   captureRouteMetrics        // Track route changes
+ *   debug={process.env.NODE_ENV === 'development'}
+ * />
+ * ```
+ *
+ * @example Production setup
+ * ```tsx
+ * <VestigMetrics
+ *   enabled={process.env.NODE_ENV === 'production'}
+ *   sampleRate={0.1}
+ *   reportPoorImmediately
+ * />
+ * ```
+ */
+export declare function VestigMetrics({ enabled, sampleRate, reportEndpoint, reportPoorImmediately, captureRouteMetrics, debug, }: VestigMetricsProps): null;
+//# sourceMappingURL=web-vitals.d.ts.map

package/dist/metrics/web-vitals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-vitals.d.ts","sourceRoot":"","sources":["../../src/metrics/web-vitals.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAIH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAA;AAIlD;;GAEG;AACH,MAAM,WAAW,kBAAmB,SAAQ,mBAAmB;CAAG;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,aAAa,CAAC,EAC7B,OAAc,EACd,UAAU,EACV,cAAsC,EACtC,qBAA4B,EAC5B,mBAA0B,EAC1B,KAAa,GACb,EAAE,kBAAkB,GAAG,IAAI,CAwB3B"}

package/dist/metrics/web-vitals.js

@@ -0,0 +1,89 @@
+/**
+ * VestigMetrics Component
+ *
+ * Drop-in component for capturing Core Web Vitals and route metrics.
+ * Add this to your root layout for automatic performance monitoring.
+ *
+ * @example
+ * ```tsx
+ * // app/layout.tsx
+ * import { VestigMetrics } from '@vestig/next/metrics'
+ *
+ * export default function RootLayout({ children }) {
+ *   return (
+ *     <html>
+ *       <body>
+ *         {children}
+ *         <VestigMetrics
+ *           sampleRate={0.1}  // 10% sampling in production
+ *           reportEndpoint="/api/vestig/metrics"
+ *         />
+ *       </body>
+ *     </html>
+ *   )
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+'use client';
+import { useWebVitals } from './hooks/use-web-vitals';
+import { useRouteMetrics } from './hooks/use-route-metrics';
+/**
+ * VestigMetrics - Core Web Vitals and Route Metrics Component
+ *
+ * This component automatically captures:
+ * - **LCP** (Largest Contentful Paint) - Loading performance
+ * - **CLS** (Cumulative Layout Shift) - Visual stability
+ * - **INP** (Interaction to Next Paint) - Interactivity
+ * - **TTFB** (Time to First Byte) - Server responsiveness
+ * - **FCP** (First Contentful Paint) - Perceived load speed
+ * - **Route metrics** - Navigation and hydration times
+ *
+ * @example Basic usage
+ * ```tsx
+ * <VestigMetrics />
+ * ```
+ *
+ * @example With configuration
+ * ```tsx
+ * <VestigMetrics
+ *   sampleRate={0.1}           // 10% of users
+ *   reportEndpoint="/api/metrics"
+ *   reportPoorImmediately      // Alert on poor metrics
+ *   captureRouteMetrics        // Track route changes
+ *   debug={process.env.NODE_ENV === 'development'}
+ * />
+ * ```
+ *
+ * @example Production setup
+ * ```tsx
+ * <VestigMetrics
+ *   enabled={process.env.NODE_ENV === 'production'}
+ *   sampleRate={0.1}
+ *   reportPoorImmediately
+ * />
+ * ```
+ */
+export function VestigMetrics({ enabled = true, sampleRate, reportEndpoint = '/api/vestig/metrics', reportPoorImmediately = true, captureRouteMetrics = true, debug = false, }) {
+    // Determine sample rate based on environment if not specified
+    const effectiveSampleRate = sampleRate ??
+        (typeof window !== 'undefined' && process.env.NODE_ENV === 'production' ? 0.1 : 1.0);
+    // Capture Core Web Vitals
+    useWebVitals({
+        enabled,
+        sampleRate: effectiveSampleRate,
+        reportEndpoint,
+        reportPoorImmediately,
+        debug,
+    });
+    // Capture route metrics
+    useRouteMetrics({
+        enabled: enabled && captureRouteMetrics,
+        reportEndpoint,
+        debug,
+    });
+    // This component doesn't render anything
+    return null;
+}
+//# sourceMappingURL=web-vitals.js.map

package/dist/metrics/web-vitals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-vitals.js","sourceRoot":"","sources":["../../src/metrics/web-vitals.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,YAAY,CAAA;AAGZ,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAA;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAA;AAO3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,UAAU,aAAa,CAAC,EAC7B,OAAO,GAAG,IAAI,EACd,UAAU,EACV,cAAc,GAAG,qBAAqB,EACtC,qBAAqB,GAAG,IAAI,EAC5B,mBAAmB,GAAG,IAAI,EAC1B,KAAK,GAAG,KAAK,GACO;IACpB,8DAA8D;IAC9D,MAAM,mBAAmB,GACxB,UAAU;QACV,CAAC,OAAO,MAAM,KAAK,WAAW,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;IAErF,0BAA0B;IAC1B,YAAY,CAAC;QACZ,OAAO;QACP,UAAU,EAAE,mBAAmB;QAC/B,cAAc;QACd,qBAAqB;QACrB,KAAK;KACL,CAAC,CAAA;IAEF,wBAAwB;IACxB,eAAe,CAAC;QACf,OAAO,EAAE,OAAO,IAAI,mBAAmB;QACvC,cAAc;QACd,KAAK;KACL,CAAC,CAAA;IAEF,yCAAyC;IACzC,OAAO,IAAI,CAAA;AACZ,CAAC"}

package/dist/server/middleware.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../src/server/middleware.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC1C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAC9C,OAAO,EACN,KAAK,QAAQ,EAEb,KAAK,cAAc,EAKnB,MAAM,QAAQ,CAAA;AAIf,MAAM,WAAW,iBAAiB;IACjC,0CAA0C;IAC1C,KAAK,CAAC,EAAE,QAAQ,CAAA;IAChB,6BAA6B;IAC7B,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,8BAA8B;IAC9B,QAAQ,CAAC,EAAE,cAAc,CAAA;IACzB,oCAAoC;IACpC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,sCAAsC;IACtC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;IACpB,wCAAwC;IACxC,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,0CAA0C;IAC1C,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,sCAAsC;IACtC,eAAe,CAAC,EAAE,QAAQ,CAAA;IAC1B,uCAAuC;IACvC,gBAAgB,CAAC,EAAE,QAAQ,CAAA;IAC3B,iCAAiC;IACjC,UAAU,CAAC,EAAE,OAAO,CAAA;CACpB;AAmCD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,GAAE,iBAAsB,IAGpC,SAAS,WAAW,2BA2ErD;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,gBAAgB,YA3Fc,WAAW,0BA2FE,CAAA;AAGxD,YAAY,EAAE,iBAAiB,IAAI,YAAY,EAAE,CAAA;AAEjD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,iBAAsB,aApHtB,WAAW,2BAwHrD;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,WAAW,YAvImB,WAAW,0BAuIR,CAAA;AAE9C;;GAEG;AACH,wBAAgB,kBAAkB,CACjC,OAAO,GAAE;IACR,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;CACb;;EAMN;AAED;;GAEG;AACH,eAAO,MAAM,uBAAuB,2BAAqB,CAAA"}
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../src/server/middleware.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC1C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAC9C,OAAO,EACN,KAAK,QAAQ,EAEb,KAAK,cAAc,EAMnB,MAAM,QAAQ,CAAA;AAIf,MAAM,WAAW,iBAAiB;IACjC,0CAA0C;IAC1C,KAAK,CAAC,EAAE,QAAQ,CAAA;IAChB,6BAA6B;IAC7B,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,8BAA8B;IAC9B,QAAQ,CAAC,EAAE,cAAc,CAAA;IACzB,oCAAoC;IACpC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,sCAAsC;IACtC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;IACpB,wCAAwC;IACxC,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,0CAA0C;IAC1C,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,sCAAsC;IACtC,eAAe,CAAC,EAAE,QAAQ,CAAA;IAC1B,uCAAuC;IACvC,gBAAgB,CAAC,EAAE,QAAQ,CAAA;IAC3B,iCAAiC;IACjC,UAAU,CAAC,EAAE,OAAO,CAAA;CACpB;AAmCD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,GAAE,iBAAsB,IAGpC,SAAS,WAAW,2BA4FrD;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,gBAAgB,YA5Gc,WAAW,0BA4GE,CAAA;AAGxD,YAAY,EAAE,iBAAiB,IAAI,YAAY,EAAE,CAAA;AAEjD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,iBAAsB,aArItB,WAAW,2BAyIrD;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,WAAW,YAxJmB,WAAW,0BAwJR,CAAA;AAE9C;;GAEG;AACH,wBAAgB,kBAAkB,CACjC,OAAO,GAAE;IACR,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;CACb;;EAMN;AAED;;GAEG;AACH,eAAO,MAAM,uBAAuB,2BAAqB,CAAA"}

package/dist/server/middleware.js

@@ -1,5 +1,5 @@
 import { NextResponse } from 'next/server';
-import { createCorrelationContext, createLogger, createTraceparent, parseTraceparent, } from 'vestig';
+import { createCorrelationContext, createLogger, createTraceparent, parseTraceparent, spanSync, } from 'vestig';
 import { CORRELATION_HEADERS } from '../utils/headers';
 import { createRequestTiming, formatDuration } from '../utils/timing';
 // Default options
@@ -70,46 +70,60 @@ export function createVestigMiddleware(options = {}) {
             traceId: parsed?.traceId,
             spanId: parsed?.spanId,
         });
-        // Log incoming request
-        const requestLogLevel = mergedOptions.requestLogLevel;
-        log[requestLogLevel]('Request received', {
-            method: request.method,
-            path: pathname,
-            search: request.nextUrl.search || undefined,
-            userAgent: request.headers.get('user-agent')?.slice(0, 100),
-            ip: request.headers.get('x-forwarded-for')?.split(',')[0]?.trim() ??
-                request.headers.get('x-real-ip'),
-            requestId: ctx.requestId,
-            traceId: ctx.traceId,
-        });
-        // Create new headers with correlation IDs
-        const requestHeaders = new Headers(request.headers);
-        requestHeaders.set(CORRELATION_HEADERS.REQUEST_ID, ctx.requestId);
-        requestHeaders.set(CORRELATION_HEADERS.TRACE_ID, ctx.traceId);
-        requestHeaders.set(CORRELATION_HEADERS.SPAN_ID, ctx.spanId);
-        requestHeaders.set(CORRELATION_HEADERS.TRACEPARENT, createTraceparent(ctx.traceId, ctx.spanId));
-        // Create response with updated headers
-        const response = NextResponse.next({
-            request: {
-                headers: requestHeaders,
-            },
-        });
-        // Add correlation headers to response
-        response.headers.set(CORRELATION_HEADERS.REQUEST_ID, ctx.requestId);
-        response.headers.set(CORRELATION_HEADERS.TRACE_ID, ctx.traceId);
-        // Log response with timing if enabled
-        if (mergedOptions.timing) {
-            const duration = timing.complete();
-            const responseLogLevel = mergedOptions.responseLogLevel;
-            log[responseLogLevel]('Response sent', {
+        // Wrap middleware processing in a span
+        return spanSync(`middleware:${mergedOptions.namespace}`, (s) => {
+            // Set HTTP attributes on span
+            s.setAttributes({
+                'http.method': request.method,
+                'http.path': pathname,
+                'http.request_id': ctx.requestId,
+                'http.trace_id': ctx.traceId,
+            });
+            // Log incoming request
+            const requestLogLevel = mergedOptions.requestLogLevel;
+            log[requestLogLevel]('Request received', {
                 method: request.method,
                 path: pathname,
-                duration: formatDuration(duration),
-                durationMs: duration,
+                search: request.nextUrl.search || undefined,
+                userAgent: request.headers.get('user-agent')?.slice(0, 100),
+                ip: request.headers.get('x-forwarded-for')?.split(',')[0]?.trim() ??
+                    request.headers.get('x-real-ip'),
                 requestId: ctx.requestId,
+                traceId: ctx.traceId,
             });
-        }
-        return response;
+            s.addEvent('request-received');
+            // Create new headers with correlation IDs
+            const requestHeaders = new Headers(request.headers);
+            requestHeaders.set(CORRELATION_HEADERS.REQUEST_ID, ctx.requestId);
+            requestHeaders.set(CORRELATION_HEADERS.TRACE_ID, ctx.traceId);
+            requestHeaders.set(CORRELATION_HEADERS.SPAN_ID, ctx.spanId);
+            requestHeaders.set(CORRELATION_HEADERS.TRACEPARENT, createTraceparent(ctx.traceId, ctx.spanId));
+            // Create response with updated headers
+            const response = NextResponse.next({
+                request: {
+                    headers: requestHeaders,
+                },
+            });
+            // Add correlation headers to response
+            response.headers.set(CORRELATION_HEADERS.REQUEST_ID, ctx.requestId);
+            response.headers.set(CORRELATION_HEADERS.TRACE_ID, ctx.traceId);
+            // Log response with timing if enabled
+            if (mergedOptions.timing) {
+                const duration = timing.complete();
+                s.setAttribute('http.duration_ms', duration);
+                s.addEvent('response-sent');
+                const responseLogLevel = mergedOptions.responseLogLevel;
+                log[responseLogLevel]('Response sent', {
+                    method: request.method,
+                    path: pathname,
+                    duration: formatDuration(duration),
+                    durationMs: duration,
+                    requestId: ctx.requestId,
+                });
+            }
+            s.setStatus('ok');
+            return response;
+        });
     };
 }
 /**