---
title: "Observability"
description: "Monitor microfrontends routing with debug headers, Vercel Observability, and session tracing."
canonical_url: "https://vercel.com/academy/microfrontends-on-vercel/observability"
md_url: "https://vercel.com/academy/microfrontends-on-vercel/observability.md"
docset_id: "vercel-academy"
doc_version: "1.0"
last_updated: "2026-04-11T13:35:15.129Z"
content_type: "lesson"
course: "microfrontends-on-vercel"
course_title: "Microfrontends on Vercel"
prerequisites:  []
---

<agent-instructions>
Vercel Academy — structured learning, not reference docs.
Lessons are sequenced.
Adapt commands to the human's actual environment (OS, package manager, shell, editor) — detect from project context or ask, don't assume.
The lesson shows one path; if the human's project diverges, adapt concepts to their setup.
Preserve the learning goal over literal steps.
Quizzes are pedagogical — engage, don't spoil.
Quiz answers are included for your reference.
</agent-instructions>

# Observability

# 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:

| Header                                   | Description                              |
| ---------------------------------------- | ---------------------------------------- |
| `x-vercel-mfe-app`                       | Which app handled the request            |
| `x-vercel-mfe-matched-path`              | Which routing pattern matched            |
| `x-vercel-mfe-target-deployment-id`      | Deployment that served the request       |
| `x-vercel-mfe-default-app-deployment-id` | Default app's deployment ID              |
| `x-vercel-mfe-zone-from-middleware`      | App chosen by middleware (flagged paths) |
| `x-vercel-mfe-response-reason`           | Internal routing reason                  |

## 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:

```javascript
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:

| Attribute                              | Description                      |
| -------------------------------------- | -------------------------------- |
| `vercel.mfe.app`                       | Project that handled the request |
| `vercel.mfe.target_deployment_id`      | Deployment ID                    |
| `vercel.mfe.default_app_deployment_id` | Default app deployment           |
| `vercel.mfe.matched_path`              | Matched routing pattern          |
| `vercel.mfe.app_from_middleware`       | Middleware decision (if flagged) |

## 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`:

```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`:

```typescript title="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

```bash
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.


---

[Full course index](/academy/llms.txt) · [Sitemap](/academy/sitemap.md)