Deco Performance Audit Skill

This skill performs a comprehensive performance analysis of a Deco site using CDN metrics and error logs. It generates actionable reports with specific recommendations.

When to Use This Skill

• Investigating slow page loads

• Analyzing cache effectiveness

• Debugging high error rates

• Understanding traffic patterns

• Before/after deployment comparisons

• Monthly performance reviews

What the Audit Produces

Performance Report

• Overall metrics summary (requests, bandwidth, cache rate)

• Hot paths table - Top 20 paths with requests AND bandwidth columns

• Content type breakdown - Grouped by type (API, HTML, JS, Images, etc.)

• Bandwidth hotspots - Which paths consume the most bandwidth

• Cache status breakdown with drill-down

• HTTP status code distribution

• Time series analysis - Peak hours, traffic patterns

• Lazy section analysis - /deco/render performance

• Error log analysis with grouping

• Geographic traffic distribution

• Period comparison - Week over week (if available)

• Actionable recommendations with priority

Tools Used

CDN Monitoring (MONITOR_* tools)

Tool Purpose

MONITOR_SUMMARY

Overall metrics: requests, pageviews, bandwidth, cache ratio, latency

MONITOR_TOP_PATHS

Top URLs by requests or bandwidth

MONITOR_CACHE_STATUS

Cache hit/miss/expired breakdown

MONITOR_STATUS_CODES

HTTP status code distribution

MONITOR_TOP_COUNTRIES

Geographic traffic distribution

MONITOR_USAGE_TIMELINE

Time series usage data

Error Logs (HyperDX)

Tool Purpose

SEARCH_LOGS

Find error messages by query

GET_LOG_DETAILS

Get detailed log entries with grouping

QUERY_CHART_DATA

Time series error counts

Tool Parameters

All MONITOR tools require:

{ "sitename": "mystore", // Deco site name "hostname": "www.mystore.com", // Production hostname "startDate": "2026-01-17", // YYYY-MM-DD "endDate": "2026-01-18", // YYYY-MM-DD "granularity": "daily" // "hourly" or "daily" }

Optional filters:

{ "filters": [ { "type": "path", "operator": "contains", "value": "/p" }, { "type": "cache_status", "operator": "equals", "value": "miss" }, { "type": "status_code", "operator": "equals", "value": "500" } ] }

Filter types: cache_status , status_code , path , country

Operators: equals , not_equals , contains , not_contains

Workflow

1. Get MONITOR_SUMMARY → Overall health
2. Get MONITOR_TOP_PATHS → Hot pages
3. Get MONITOR_CACHE_STATUS → Cache effectiveness
4. Get MONITOR_STATUS_CODES → Error rates
5. SEARCH_LOGS → Find error patterns
6. GET_LOG_DETAILS → Dig into specific errors
7. Correlate with code → Find root causes
8. Generate report → Actionable recommendations

Metrics to Analyze

1. Cache Performance

Goal: Cache hit ratio > 80%

MONITOR_CACHE_STATUS response:

• hit: Served from cache (good)
• miss: Origin fetch required (optimize)
• expired: Cache expired, refetched
• revalidated: Cache validated with origin
• unknown: No cache header

Red Flags:

• Cache hit ratio < 50%

• High "unknown" cache status (missing headers)

• High "miss" on static assets

Recommendations:

• Add cache-control headers to loaders

• Use stale-while-revalidate for dynamic content

• Cache static assets aggressively

2. Error Rates

Goal: 5xx errors < 0.1%, 4xx < 5%

MONITOR_STATUS_CODES response:

• 200: Success
• 301/302/307: Redirects (expected but minimize)
• 304: Not Modified (good - client cache)
• 400: Bad Request (client issue)
• 404: Not Found (check for broken links)
• 429: Too Many Requests (rate limiting)
• 500: Server Error (investigate immediately)
• 502/504: Gateway errors (origin issues)

Red Flags:

• 5xx > 0.5%

• 429 > 5% (hitting rate limits)

• 404 > 10% (broken links/SEO issue)

3. Hot Paths & Traffic Analysis

Goal: Understand traffic patterns with full visibility

MUST Include: Complete Hot Paths Table

Always generate a table showing the actual data:

Hot Paths by Requests

Hot Paths by Bandwidth

Content Type Grouping

Group paths by type for clearer analysis:

Content Type Pattern Requests Bandwidth Cache Rate

API Calls /live/invoke/*

2.1M 89GB 0.05%

Lazy Sections /deco/render

450K 12GB 15%

JavaScript /_frsh/js/*

1.8M 45GB 94%

Static Images /image/* , *.png/jpg

890K 120GB 88%

HTML Pages / , /s , /:slug/p

320K 8GB 5%

Fonts *.woff2

210K 3.2GB 99%

Icons /sprites.svg

180K 540MB 99%

This grouping reveals:

• API calls often consume most bandwidth but have low cache

• Lazy sections (/deco/render ) need cache optimization

• Static assets should have >90% cache rate

4. Lazy Section Analysis

Goal: Understand /deco/render performance

MONITOR_TOP_PATHS with filter: filters: [{ type: "path", operator: "contains", value: "/deco/render" }]

Analyze:

Section (from query params) Requests Avg Latency Cache Hit

ProductShelf 120K 180ms 12%

Reviews 85K 220ms 5%

SimilarProducts 65K 350ms 0%

Red Flags:

• Lazy sections with 0% cache = every scroll triggers origin fetch

• High latency on popular sections = poor UX

5. Time Series Analysis

Goal: Identify traffic patterns and correlations

MONITOR_USAGE_TIMELINE with granularity: "hourly"

Generate:

Hour Requests Errors Cache Hit % Notes

00:00 85K 12 52% Low traffic

10:00 320K 45 48% Morning peak

14:00 410K 120 45% Afternoon peak

20:00 380K 200 44% Evening peak, error spike

Look for:

• Peak hours (when to avoid deployments)

• Error spikes correlated with traffic spikes

• Cache hit rate degradation under load

6. Bandwidth Hotspots

Goal: Find paths consuming disproportionate bandwidth

Sort by bandwidth descending and highlight:

• Uncached large payloads (JSON API responses)

• Large images not going through optimization

• JS bundles that could be smaller

🔴 Bandwidth Concerns:

4. Error Log Analysis

Common Error Patterns:

Error Meaning Action

"Too Many Requests" VTEX rate limiting Reduce API calls, add caching

"TypeError: Cannot read" JS runtime error Fix the code

"Failed to fetch" Network/API issue Add retries, timeout handling

"Oops! dangling reference" Missing block Fix block config

Searching Logs:

SEARCH_LOGS({ query: "level:error site:mystore", limit: 50 })

Getting Details:

GET_LOG_DETAILS({ query: "level:error site:mystore", groupBy: ["body", "service", "site"] })

Report Template

Performance Audit Report - [Site Name]

Period: 2026-01-17 to 2026-01-18 Generated: 2026-01-18T15:00:00Z

Executive Summary

Key Findings

1. Finding 1 with impact and recommendation
2. Finding 2 with impact and recommendation
3. Finding 3 with impact and recommendation

Traffic Analysis

Hot Paths by Requests (Top 15)

Bandwidth Hotspots (Top 10 by GB)

Content Type Summary

Lazy Section Performance

/deco/render Analysis

Issues:

• SimilarProducts has 0% cache hit - every scroll fetches from origin
• High latency on Reviews section affects perceived performance

Time Series (24h Pattern)

Pattern Analysis:

• Peak: 10:00-14:00 and 18:00-22:00
• 429 errors correlate with evening peak
• Cache hit degrades under high load

Cache Analysis

Status Breakdown

Uncached Hot Paths (Cache MISS filter)

Error Analysis

HTTP Status Distribution

500 Error Breakdown

Error Log Patterns

Geographic Distribution

Recommendations

🔴 High Priority

🟡 Medium Priority

🟢 Low Priority

Targets

Example Queries

Find pages with high miss rate

MONITOR_TOP_PATHS with filter: filters: [{ type: "cache_status", operator: "equals", value: "miss" }]

Find 5xx errors by path

MONITOR_TOP_PATHS with filter: filters: [{ type: "status_code", operator: "contains", value: "5" }]

Error trend over time

QUERY_CHART_DATA({ series: [{ dataSource: "events", aggFn: "count", where: "level:error site:mystore", groupBy: ["service"] }], granularity: "1 hour" })

Integration with deco-full-analysis

Use this skill after running deco-full-analysis to:

• Correlate performance issues with specific loaders/sections

• Identify which custom code paths are problematic

• Validate that lazy loading is working correctly

• Verify cache headers on custom loaders

Best Practices

Cache Headers for Loaders

// loaders/myLoader.ts export const cache = "stale-while-revalidate"; export const cacheKey = (props: Props) => ${props.id};

Reducing API Calls

// Use loader deduplication // Same loader called multiple times = single fetch export const cache = "stale-while-revalidate";

Error Handling

// Graceful degradation try { const data = await fetch(url); return data; } catch (e) { console.error("Fetch failed:", e); return fallbackData; }