Observability

When something routes wrong, you need to know why. Debug headers, observability dashboards, and session traces show exactly what happened to each request.

Outcome

Enable and use debug headers to inspect routing decisions, and view microfrontends data in Vercel Observability.

Debug Headers

When debug mode is enabled, responses include headers showing routing decisions:

Fast Track

1. Enable debug mode via cookie or Vercel Toolbar
2. Inspect response headers in DevTools
3. View routing data in Observability dashboard

Hands-on Exercise 3.3

Enable debug mode and trace a request through the microfrontends layer.

Part 1: Enable Debug Mode

Option A: Set a cookie

In your browser's DevTools console:

document.cookie = "VERCEL_MFE_DEBUG=1; path=/";

Refresh the page. Now all responses include debug headers.

Option B: Use Vercel Toolbar

If you have the Vercel Toolbar installed:

1. Click the Vercel icon in the toolbar
2. Open the "Microfrontends" panel
3. Toggle "Enable Debug Mode"

Part 2: Inspect Response Headers

1. Open DevTools → Network tab
2. Visit your deployed Vercel URL (e.g., acme-platform.vercel.app/docs)
3. Click on the document request
4. Look at Response Headers:

x-vercel-mfe-app: docs
x-vercel-mfe-matched-path: /docs/:path*
x-vercel-mfe-target-deployment-id: dpl_abc123xyz
x-vercel-mfe-default-app-deployment-id: dpl_def456uvw

This tells you:

• The docs app handled this request
• It matched the /docs/:path* pattern
• The specific deployment IDs involved

Part 3: View Observability Dashboard

1. Go to your Vercel dashboard
2. Click the Observability tab
3. In the left sidebar, find CDN → Microfrontends

The dashboard shows:

• Requests by app - Which apps are handling traffic
• Matched paths - Which routing patterns are being used
• Response times - Performance by app

Part 4: Capture a Session Trace

Session tracing shows the full lifecycle of a request:

1. In Vercel Observability, click Sessions
2. Start a new session or find a recent one
3. Make a request to your microfrontends URL
4. Find the request in the session
5. Expand the Microfrontends span

The span includes attributes:

Debugging Common Issues

"Wrong app is serving this path"

Check the headers:

Request: /docs/api
Expected: docs app
Actual header: x-vercel-mfe-app: marketing

Diagnosis: The path pattern isn't matching. Check microfrontends.json:

"@acme/docs": {
  "routing": [
    { "paths": ["/docs", "/docs/:path*"] }
  ]
}

"Redirect isn't working"

Remember the execution order:

Microfrontends → Headers → Redirects → Middleware → Rewrites

If your redirect is in the marketing app but the path routes to docs, the redirect never runs.

Check: Which app does the path route to?

x-vercel-mfe-app: docs  // Redirect needs to be in docs app!

"Middleware isn't running"

Middleware only runs for paths routed to that app.

Request: /app/dashboard
x-vercel-mfe-app: dashboard

If middleware isn't running, check:

1. Is middleware in the correct app (dashboard)?
2. Does the middleware matcher include this path?

Creating a Debug Helper

Add a debug endpoint to quickly check routing:

Create apps/marketing/app/api/debug/route.ts:

import { headers } from "next/headers";
 
export async function GET() {
  const headersList = await headers();
 
  const debugInfo = {
    app: "marketing",
    timestamp: new Date().toISOString(),
    headers: {
      "x-vercel-mfe-app": headersList.get("x-vercel-mfe-app"),
      "x-vercel-mfe-matched-path": headersList.get("x-vercel-mfe-matched-path"),
      "x-vercel-deployment-id": headersList.get("x-vercel-deployment-id"),
    },
  };
 
  return Response.json(debugInfo);
}

Visit /api/debug to see routing info as JSON.

Commit

git add -A
git commit -m "feat: add debug API endpoint for routing inspection"

Done-When

• Debug mode enabled (cookie or toolbar)
• Can see x-vercel-mfe-app header in DevTools
• Viewed microfrontends data in Observability dashboard
• Understand how to trace routing decisions

Observability Checklist

When debugging microfrontends issues:

1. Enable debug headers - See which app handled the request
2. Check matched path - Verify the pattern is correct
3. Compare deployment IDs - Ensure the right deployment is serving
4. View session trace - See the full request lifecycle
5. Check middleware - Confirm it ran (or didn't, and why)

What's Next

Configure deployment protection and firewall rules that work across microfrontends.