Performance Tuning

Dispatcher Performance Tuning (Cloud)

Improve cache efficiency, latency, and throughput for cloud deployments that use the Adobe Dispatcher Apache HTTP Server module and related HTTPD configuration.

Variant Scope

• This skill is cloud-service-only.
• Scope is fixed by this skill directory; do not ask the user to choose deployment variant.

MCP Tool Contract

Use only these Dispatcher MCP tools:

• validate
• lint
• sdk
• trace_request
• inspect_cache
• monitor_metrics
• tail_logs

Workflow

1. Capture baseline metrics and cache evidence. 2. Apply cloud guardrails (immutable/default includes, reserved probe paths, and CDN-vs-Dispatcher ownership) before proposing changes. 3. Prioritize low-risk/high-impact changes. 4. Apply minimal edits. 5. Verify with validate, lint, and sdk. 6. Compare before/after runtime evidence.

Verification Scope Selection

Use shared references to select optimization evidence depth:

• mode-specific-verification-matrix.md
• test-case-catalog.md

Output Contract

Always return:

• baseline metrics snapshot
• prioritized optimization list with impact/risk
• changed files and intent
• executed checks + before/after evidence
• selected test IDs and outcomes
• rollback plan and open risks

Guardrails

• Do not claim improvement without measurable comparison.
• Keep high-risk tuning opt-in unless user explicitly requests it.
• Keep cloud assumptions explicit for each recommendation batch.
• Route edge/WAF/CDN-only concerns to CDN layer guidance instead of Dispatcher config changes.

References

• optimization-patterns.md
• performance-scenario-playbooks.md – scenario-driven tuning flows adapted from broader MCP prompt surfaces
• load-testing-guidance.md
• performance-monitoring-setup.md
• quick-start-execution-path.md – fast entry path for optimization requests
• repo-layout-workflows.md – map performance findings to cache, farm, vhost, and rewrite file families
• playbook-command-linkage.md – exact MCP command chains for tuning playbooks
• mode-specific-verification-matrix.md
• cloud-service-aemaacs-guardrails.md – cloud-service-only immutable/include/runtime boundary checks from AEMaaCS patterns
• test-case-catalog.md
• change-risk-and-rollback-template.md
• public-docs-index.md
• public-doc-citation-rules.md
• core-7-tools-reference.md

Change Risk And Rollback Template

Use this template for any dispatcher recommendation that changes behavior.

1) Change Summary

• Change scope:
• Target mode: cloud
• Files impacted:
• User-visible impact expected:

2) Risk Assessment

3) Blast Radius

• Hostnames/farms affected:
• URL classes affected:
• Dependency assumptions:

4) Rollback Plan

• Rollback trigger criteria:
• Immediate rollback action:
• Validation after rollback:
• Owner/escalation path:

5) Verification Gate

The change is production-ready only when:

1. Required checks in mode-specific-verification-matrix.md are complete. 2. Evidence is attached for each executed check. 3. Open risks are explicitly accepted or remediated.

AEMaaCS Cloud Guardrails (Core-7)

Use this checklist before proposing or applying Dispatcher/HTTPD changes in AEMaaCS.

This guardrail is grounded in current cloud dispatcher configuration layouts, validator behavior, managed runtime defaults, and dispatcher/httpd semantics.

1) Source-Of-Truth Layout And Ownership

Treat dispatcher/src as the deployable config root (must contain conf.d and conf.dispatcher.d).

Do not edit cloud-managed defaults directly. Put customer intent in mutable wrappers:

• conf.d/rewrites/rewrite.rules (includes default rewrite rules)
• conf.dispatcher.d/filters/filters.any (includes default filters)
• conf.dispatcher.d/cache/rules.any (includes default cache rules)
• conf.dispatcher.d/clientheaders/clientheaders.any (includes default clientheaders)
• conf.dispatcher.d/virtualhosts/virtualhosts.any (includes default virtualhosts)
• custom conf.d/available_vhosts/*.vhost and conf.dispatcher.d/available_farms/*.farm

Treat these wrapper files as extension points, not replacement excuses. Preserve the include of the managed default unless there is a deliberate, evidence-backed reason to override the baseline:

• conf.d/rewrites/rewrite.rules should keep default_rewrite.rules
• conf.dispatcher.d/filters/filters.any should keep default_filters.any
• conf.dispatcher.d/cache/rules.any should keep default_rules.any
• conf.dispatcher.d/clientheaders/clientheaders.any should keep default_clientheaders.any
• conf.dispatcher.d/virtualhosts/virtualhosts.any should keep default_virtualhosts.any

Treat these as cloud-managed defaults whose semantics should be preserved unless platform documentation explicitly says otherwise:

• conf.d/dispatcher_vhost.conf
• conf.dispatcher.d/dispatcher.any
• conf.d/available_vhosts/default.vhost
• conf.dispatcher.d/available_farms/default.farm
• cloud-managed safety vhosts and unmatched-host catch-all behavior in conf.d/dispatcher_vhost.conf

2) Required Cloud Topology Invariants

Keep these invariants intact for validator compatibility:

• conf.dispatcher.d/dispatcher.any includes enabled_farms/*.farm
• conf.d/dispatcher_vhost.conf includes conf.d/enabled_vhosts/*.vhost
• conf.d/enabled_vhosts/*.vhost and conf.dispatcher.d/enabled_farms/*.farm are symlinks
• farm includes remain in known locations:
• /clientheaders -> ../clientheaders/clientheaders.any
• /virtualhosts -> ../virtualhosts/virtualhosts.any
• /renders -> ../renders/default_renders.any
• /filter -> ../filters/filters.any
• /cache/rules -> ../cache/rules.any
• /cache/allowedClients -> ../cache/default_invalidate.any
• /cache/ignoreUrlParams -> ../cache/marketing_query_parameters.any or a wrapper file at the validator-supported customer include location

If include topology changes, require explicit validator proof.

3) Validator-Enforced Contracts

For cloud readiness, assume these checks are mandatory:

• must find at least one enabled farm (conf.dispatcher.d/enabled_farms/*.farm)
• must find at least one enabled vhost (conf.d/enabled_vhosts/*.vhost)
• include targets must match known include locations (unknown include paths fail)
• ServerName "*" is invalid and fails validation
• filename/symlink/file-size checks are part of full
• ServerAlias "*.adobeaemcloud.net" and ServerAlias "*.adobeaemcloud.com" are expected; currently warnings but treat as release blockers

Typical failure signatures seen in validator testdata:

• missing farm: unable to find any farm in 'conf.dispatcher.d/enabled_farms'
• missing vhost: no file found for matching pattern: conf.d/enabled_vhosts/*.vhost
• bad include location: included file (...) does not match any known file
• bad ServerName: ServerName directive is set to '*'
• invalid statfileslevel: Statfileslevel set to -1... misconfiguration

Important cloud warning to treat as action item:

• if /ignoreUrlParams is not configured, validator warns about marketing parameter strategy

4) Reserved Runtime Paths And Rewrite Safety

Do not repurpose or rewrite over cloud-managed health and probe paths:

• /system/probes/live
• /system/probes/start
• /system/probes/ready
• /system/probes/health
• /systemready

dispatcher_vhost.conf wires these paths for liveness, startup, readiness, and managed rewrite-map rollout behavior. Any vhost or rewrite customization must preserve their pass-through behavior and must not introduce redirects, auth gates, or filter denials on those endpoints.

When managed rewrite maps are enabled, readiness behavior depends on the rewrite-map readiness state. Do not assume redirect maps are active before readiness conditions are met.

Preserve cloud-managed vhost safety behavior as well:

• customer vhosts are included explicitly via conf.d/enabled_vhosts/*.vhost
• cloud-managed safety vhosts may exist ahead of customer vhosts
• an unmatched-host catch-all exists to avoid leaking customer site behavior to arbitrary hostnames

Do not remove or bypass these guards unless the user is intentionally working on those specific cloud-runtime behaviors and the change is validated end to end.

5) Runtime And Variable Assumptions

• prefer cloud variables (for example ${DOCROOT}, ${AEM_IP}) over hardcoded absolute paths
• avoid local-host assumptions in deployable files
• separate local-only SDK execution paths from final cloud config content

Preserve these cloud defaults unless the change explicitly requires otherwise and the impact is proven:

• AllowEncodedSlashes NoDecode
• ModMimeUsePathInfo On
• DirectorySlash Off
• DispatcherUseProcessedURL On
• DispatcherPassError 0
• DispatcherUseForwardedHost may be controlled by platform-provided configuration; treat host-forwarding behavior as a trust-boundary setting
• DispatcherRestrictUncacheableContent On

Preserve managed defaults in these extension surfaces unless the user is intentionally changing the feature:

• default_clientheaders.any forwards critical headers such as Authorization, Cookie, Host, X-Forwarded-Proto, and x-request-id
• default_filters.any carries supported allow rules for CSRF token fetches, GraphQL, persisted queries, Forms, Screens, clientlibs, and selected commerce-related routes
• default_rules.any keeps known deny cache rules such as CSRF token responses and Screens channel JSON
• default_rewrite.rules includes protections such as X-Forwarded-For spoof blocking, common abusive path blocking (xmlrpc.php, wp-login), and the persisted-query ;.json pass-through rewrite used for cache file extension compatibility

Managed runtime behavior to respect:

• CACHE_GRAPHQL_PERSISTED_QUERIES requires matching CORS and endpoint verification when enabled
• default.farm enables serveStaleOnError, gracePeriod, and enableTTL by default; tune them deliberately, not accidentally

Cloud-managed environment-sensitive routes also exist:

• development-only and product-feature routes may be enabled by environment
• Commerce GraphQL endpoints, frontend-static passthrough, and Dynamic Media delivery paths may have dedicated proxy or no-rewrite handling in the cloud baseline

Do not classify these as unconditional vulnerabilities. Evaluate them by environment and by whether the behavior is intentional for the documented cloud baseline.

Design implication: do not depend on trace-level logging for production diagnostics.

6) CDN vs Dispatcher Decision Boundary

Use Dispatcher/HTTPD for:

• filter rules, cache rules, vhost/rewrite routing near AEM
• request handling that depends on farm/filter/cache semantics

Use CDN configuration for:

• edge traffic filtering, WAF, rate limiting
• CDN-native redirect/error-page and edge cache policy concerns

When both are possible, document why one layer is chosen.

7) Cloud Preflight Verification (Core-7)

Minimum static evidence before sign-off:

1. validate({"config":"<changed dispatcher content>","type":"cloud"}) 2. lint({"mode":"directory","target":"<dispatcher src path>","strict_mode":true}) 3. sdk({"action":"check-files","config_path":"<dispatcher src path>"}) 4. sdk({"action":"diff-baseline","config_path":"<dispatcher src path>"}) for drift-sensitive changes

When a local dispatcher validator is available, corroborate with:

• validator full <dispatcher-src>
• validator httpd <dispatcher-src>
• validator dispatcher <dispatcher-src>

When local SDK runtime verification is required, use local-sdk-execution.md to record the launcher mode and any non-default environment variables that affect local behavior.

Runtime evidence when behavior changed:

• trace_request({"url":"<representative url>","config_path":"<dispatcher src path>"})
• inspect_cache({"url":"<representative cacheable url>","config_path":"<dispatcher src path>"})

Also verify these cloud-specific invariants when relevant:

• reserved probe paths still bypass custom rewrites/redirects
• platform-managed safety vhosts and unmatched-host behavior remain intact
• custom vhosts still provide the required adobeaemcloud.net and adobeaemcloud.com alias coverage
• query-parameter cache strategy is explicit if cache behavior changed
• GraphQL persisted-query caching changes include matching CORS verification
• default client header forwarding is still sufficient for the feature set in use
• default rewrite protections and supported product endpoint rewrites remain intact unless intentionally replaced

8) Output Expectations For Cloud Recommendations

Always include:

• explicit cloud assumption (AEMaaCS)
• whether immutable/default include contracts were impacted
• whether concern belongs to Dispatcher layer or CDN layer
• which validator/lint/runtime checks were executed vs skipped
• residual risk if runtime proof was not available

Reference docs:

• Cloud Dispatcher overview: https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/content-delivery/disp-overview
• Validation/debugging and file rules: https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/content-delivery/validation-debug
• Traffic filter rules / WAF: https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/security/traffic-filter-rules-including-waf
• CDN overview: https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/content-delivery/cdn

Core-7 Tools Reference

This document defines the shared MCP tool contract used by the dispatcher skills.

Overview

The core-7-tools contract is the baseline tool set for dispatcher work across both AEMaaCS and AMS variants.

The contract exists to keep dispatcher skills:

• deterministic
• auditable
• variant-aware
• constrained to a stable, reviewable execution surface

Tool Catalog

validate

Purpose:

• syntax and structure validation for dispatcher and HTTPD config fragments

Use when:

• authoring or reviewing .any, vhost, rewrite, cache, or filter changes
• checking config before runtime verification

Common patterns:

• dispatcher section validation
• HTTPD/vhost block validation
• variant-specific validation modes such as ams or cloud

lint

Purpose:

• best-practice analysis across security, performance, ordering, and maintainability concerns

Use when:

• filter order matters
• release gates or security gates are required
• config quality matters beyond raw syntax validity

Common patterns:

• lint(strict) for release or security gates
• lint(deep) for filter, cache, and ordering-heavy changes

sdk

Purpose:

• file-level integrity checks, baseline drift analysis, and SDK-backed validation helpers

Use when:

• include topology matters
• immutable/default drift matters
• local project or validator-backed evidence is needed

Common patterns:

• sdk(check-files)
• sdk(diff-baseline)
• optional deeper validation helpers when the environment supports them

trace_request

Purpose:

• trace effective routing and decision flow for a representative request

Use when:

• debugging 403, 5xx, redirect loops, host routing, or rewrite behavior
• proving expected allow or deny outcomes

Common patterns:

• failing URL versus healthy URL comparison
• canonical redirect checks
• host and method-sensitive routing checks

inspect_cache

Purpose:

• inspect cacheability, cache state, and metadata for representative URLs

Use when:

• tuning cache rules
• debugging cache misses, stale content, or invalidation scope
• checking auth-sensitive cache behavior

monitor_metrics

Purpose:

• capture operational signals such as status-code mix, latency shifts, or hit-ratio changes

Use when:

• triaging incidents
• comparing before/after tuning evidence
• quantifying impact windows

tail_logs

Purpose:

• collect concrete runtime evidence from dispatcher or HTTPD logs

Use when:

• an incident needs real examples instead of only static reasoning
• cache or redirect behavior needs corroboration
• a request trace needs supporting log evidence

Contract Rules

All dispatcher skills that declare mcp-tool-contract: core-7-tools should follow these rules:

1. Prefer the smallest sufficient command chain. 2. Do not claim a tool was run unless evidence exists. 3. Distinguish observation from inference. 4. Use static checks first unless the task is runtime-first by nature. 5. Keep variant assumptions explicit (ams vs cloud). 6. Report skipped checks and why they were skipped.

Selection Guidance

Use this progression unless a specialist playbook says otherwise:

1. validate 2. lint 3. sdk 4. trace_request 5. inspect_cache 6. tail_logs 7. monitor_metrics

Not every task needs all seven tools. The contract defines the allowed baseline, not a mandatory full run.

Failure And Troubleshooting Patterns

When a tool fails or cannot be used:

• validate failure:
• report the exact failing block and error text
• do not continue as if the config is structurally sound
• lint failure or warning set:
• separate hard blockers from advisory findings
• keep ordering and security warnings explicit
• sdk(check-files) failure:
• treat include topology, immutable-file drift, or missing-file issues as high-signal structural problems
• trace_request unavailable:
• fall back to static rule analysis and state the confidence limit clearly
• inspect_cache unavailable:
• use static cache reasoning plus any available log or metric signals
• tail_logs unavailable:
• avoid claiming runtime confirmation
• monitor_metrics unavailable:
• avoid quantifying impact improvements or regressions

Variant Notes

• The tool contract is shared across variants.
• The meaning of success differs by variant because guardrails differ.
• Always pair the tool outputs with the relevant variant guardrails and verification matrix.

Local Dispatcher SDK Execution (Cloud)

Use this reference when cloud dispatcher work requires a local SDK-backed runtime, not just static validation.

This file documents the launcher contract exposed by the shipped Dispatcher SDK scripts. It aligns with Set up Dispatcher Tools (Adobe Experience League): Dispatcher is run locally using Docker against the src Dispatcher and Apache Web server configuration files. Treat the help output from the installed SDK package as the final authority for your exact SDK version.

When To Use This

Use local SDK execution when you need one of these:

• container-backed runtime verification for rewrites, filters, vhosts, cache behavior, or probe-path handling
• local test mode to confirm the processed config and basic HTTPD/dispatcher validity
• hot-reload feedback while iterating on dispatcher config changes

Do not confuse this with deployable cloud config content. These commands are local runtime helpers.

Positional Contract

The shipped launcher usage is:

./bin/docker_run.sh <dispatcher-src> <aem-host>:<aem-port> <local-port>
./bin/docker_run.sh <dispatcher-src> <aem-host>:<aem-port> test

Common examples (first argument is the path to the Dispatcher configuration src folder):

./bin/docker_run.sh ./src <aem-host>:4503 8080
DISP_RUN_MODE=stage ./bin/docker_run.sh ./src <aem-host>:4503 8080
DISP_LOG_LEVEL=trace1 ./bin/docker_run.sh ./src <aem-host>:4503 8080
REWRITE_LOG_LEVEL=trace2 ./bin/docker_run.sh ./src <aem-host>:4503 8080
./bin/docker_run.sh ./src <aem-host>:4503 test

For an AEM project, point to the project's dispatcher/src folder (e.g. ~/code/my-project/dispatcher/src).

Meaning of the positional arguments:

• <dispatcher-src>: path to the Dispatcher configuration src folder (e.g. SDK's ./src or project's dispatcher/src). The launcher runs against these config files; there is no separate "out" deployment folder.
• <aem-host>:<aem-port>: backend AEM endpoint the local Dispatcher runtime should talk to
• <local-port>: host port that exposes the local Dispatcher runtime
• test: run config test mode instead of exposing a live local port

Hot reload

Hot reload lets the container pick up changes to Dispatcher and Apache config files without restarting the container—useful when iterating on rewrites, filters, vhosts, or other config under <dispatcher-src>.

Preferred: hot-reload launcher

Many SDK packages include a dedicated launcher:

./bin/docker_run_hot_reload.sh <dispatcher-src> <aem-host>:<aem-port> <local-port>

It uses the same positional contract as docker_run.sh but watches the config src folder and reloads when files change. Prefer this when available; if your SDK prints different usage, follow its help output.

Fallback: HOT_RELOAD with standard launcher

If docker_run_hot_reload.sh is not present, some SDK versions support hot reload via the standard launcher and the HOT_RELOAD environment variable:

HOT_RELOAD=true ./bin/docker_run.sh ./src <aem-host>:<aem-port> 8080

Check your SDK version; when supported, config changes under the src folder are picked up without restarting. See Runtime Environment Variables for the HOT_RELOAD variable details.

Runtime Environment Variables

The shipped launcher help exposes these environment variables:

DISP_RUN_MODE

Defines the simulated environment type for the local run.

Valid values:

• dev
• stage
• prod

Default is dev.

DISP_LOG_LEVEL

Sets dispatcher log verbosity.

Valid values:

• trace1
• debug
• info
• warn
• error

Default is warn.

Use trace1 when you need backend request flow or dispatcher decision detail.

REWRITE_LOG_LEVEL

Sets rewrite-engine log verbosity.

Valid values:

• trace1 through trace8
• debug
• info
• warn
• error

Default is warn.

Use this when debugging RewriteRule and RewriteCond behavior.

ENV_FILE

Imports variables from a file before startup.

Use this when local SDK execution depends on variables that would otherwise be exported manually.

HOT_RELOAD

Enables config reload when watched files in the config src folder change (no container restart).

Valid values:

• true
• false

Default is false.

Use this for local iteration loops on rewrites, filters, and vhosts. When your SDK does not provide docker_run_hot_reload.sh, try HOT_RELOAD=true with docker_run.sh if the package supports it. See Hot reload for usage.

ALLOW_CACHE_INVALIDATION_GLOBALLY

Overwrites the default invalidation behavior to allow all connections for cache invalidation.

Valid values:

• true
• false

Default is false.

Treat this as a local test convenience only. Do not carry this posture into production guidance.

HTTPD_DUMP_VHOSTS

Enables vhost dump output for debugging.

Valid values:

• true
• false

Default is false.

ENABLE_MANAGED_REWRITE_MAPS_FLAG

Enables managed rewrite maps.

Valid values:

• true
• false

Default is true.

This matters when local behavior depends on rewrite-map-backed redirects or readiness gating.

MANAGED_REWRITE_MAPS_PROBE_CHECK_SKIP

Skips probe checks for managed rewrite maps.

Valid values:

• true
• false

Default is false.

Only use this when intentionally isolating local rewrite-map behavior and call out that the check was skipped.

Host-Side Compatibility Variable

You may also see:

export DOCKER_API_VERSION=1.43

This is a host Docker-client compatibility override, not a dispatcher runtime setting. Use it only when the installed SDK scripts or local Docker environment require it.

Recommended Execution Patterns

1. Static Config Test

Use this first when the goal is syntax or processed-config validation:

./bin/docker_run.sh ./src <aem-host>:<aem-port> test

Use this before claiming runtime behavior is verified.

2. Live Local Dispatcher Port

Use this when you need request/response verification:

./bin/docker_run.sh ./src <aem-host>:<aem-port> 8080

Then verify behavior with representative requests against the local port.

3. Hot Reload Iteration

Use this when tuning rewrites, filters, or vhosts repeatedly so config changes apply without restarting the container. See Hot reload for the launcher and HOT_RELOAD fallback.

./bin/docker_run_hot_reload.sh ./src <aem-host>:<aem-port> 8080

If your SDK does not include docker_run_hot_reload.sh, use HOT_RELOAD=true ./bin/docker_run.sh ./src <aem-host>:<aem-port> 8080 when supported.

Skill Usage Guidance

When using local SDK execution in cloud dispatcher skills:

• state whether evidence came from static validation, local SDK runtime, or MCP runtime tools
• record the exact launcher mode used: live port, hot reload, or test
• record any non-default env vars that materially changed behavior
• call out when managed rewrite map checks, invalidation safety, or run-mode simulation could affect the conclusion
• do not treat local SDK behavior as stronger evidence than executed MCP/runtime evidence against the actual target environment

Cloud Verification Matrix

Use this matrix to select the minimum acceptable verification set for cloud mode.

How To Use

1. Pick the change or incident type. 2. Execute required static checks. 3. Execute runtime checks when behavior is runtime-sensitive. 4. Record evidence in the skill output contract.

Verification Matrix (cloud)

Skip Rules

You may skip runtime checks only when runtime prerequisites are unavailable. If skipped, state:

• exactly which checks were skipped
• why they were skipped
• what remains unverified
• what environment is required to complete verification

Examples

Example 1: Filter Rule Change

Scenario: Add allow rule for /content/site/api/* with GET method only.

# Static checks
lint({"mode":"directory","target":"/path/to/dispatcher/src","strict_mode":true})
sdk({"action":"check-files","config_path":"/path/to/dispatcher/src"})
validate({"config":"<dispatcher.any content>","type":"cloud"})

# Runtime verification
trace_request({
  "url": "/content/site/api/products.json",
  "method": "GET",
  "config_path": "/path/to/dispatcher/src"
})

Example 2: Cache Behavior Investigation

Scenario: Investigate why /content/site/en.html is not caching as expected.

inspect_cache({"url":"/content/site/en.html","config_path":"/path/to/dispatcher/src"})
monitor_metrics({"window_minutes":10,"breakdown_by":"status_code"})
tail_logs({"lines":100,"filter_cache_status":"MISS"})

Example 3: Cloud Readiness Validation

Scenario: Validate config works in cloud mode.

validate({"config":"<dispatcher.any content>","type":"cloud"})
lint({"mode":"directory","target":"/path/to/dispatcher/src","strict_mode":true})
sdk({"action":"check-files","config_path":"/path/to/dispatcher/src"})
sdk({"action":"diff-baseline","config_path":"/path/to/dispatcher/src"})

Common Issues Found:

• hardcoded container paths
• Docker-specific directive mistakes
• include graph and filter logic regressions
• missing ServerAlias "*.adobeaemcloud.net" / "*.adobeaemcloud.com" coverage
• missing /ignoreUrlParams strategy for marketing/query parameter cache control
• custom rewrites intercepting /systemready or /system/probes/*
• dropped managed default includes or header forwarding causing feature regressions

Playbook To MCP Command Linkage (Cloud Dispatcher)

Use this file after selecting a playbook. It turns the playbook choice into a deterministic MCP command chain with expected evidence.

Config Authoring Playbooks

Incident Response Playbooks

Security Playbooks

Performance Playbooks

Command Usage Notes

• Use validate(dispatcher) as shorthand for a dispatcher-targeted validate(...) call with the relevant merged config section.
• Use validate(httpd) as shorthand for an Apache/vhost-targeted validate(...) call with the relevant vhost or rewrite block.
• Use lint(strict) for release-gate or security-gate reviews; use lint(deep) when rule ordering or cache policy nuance matters.
• If runtime prerequisites are missing, run the available static commands, report the gap, and leave the runtime tests open.

Public Doc Citation Rules

Use these rules for all Cloud dispatcher advisory responses.

Allowed Sources

• Use links listed in public-docs-index.md.
• Use only Experience League references (cloud mode docs + common Dispatcher docs).
• Do not cite sources unavailable to external readers in public skill guidance.

Citation Requirements

For non-trivial recommendations, include:

1. at least one common Dispatcher source 2. at least one cloud-specific source when behavior differs by mode

Topic-To-Citation Minimums

Use these minimum citation sets for precision and consistency:

• Filter ordering / allow-deny conflicts:
• Dispatcher content filter docs
• Dispatcher security checklist
• statfileslevel / invalidation scope:
• Dispatcher invalidation by folder level docs
• Dispatcher cache flush/invalidation docs
• URL decomposition / selector-suffix logic:
• Dispatcher content filter docs
• Cloud validation/debug docs when recommendation depends on include/file layout constraints
• Rewrite behavior / redirects:
• Dispatcher configuration docs
• Cloud Dispatcher overview or pipeline-free redirect docs (pick claim-aligned source)
• Cache headers / TTL strategy:
• Dispatcher caching docs
• AEMaaCS caching docs
• Cloud immutable/include/validator compatibility:
• AEMaaCS validation/debug docs
• Cloud Dispatcher overview docs
• CDN vs Dispatcher ownership decisions:
• AEMaaCS CDN docs
• Cloud Dispatcher overview docs

Citation Format

Use a compact list:

• Title - URL - one-line relevance note

Claim Discipline

• Distinguish observed MCP evidence from documentation guidance.
• If docs and runtime evidence conflict, state the conflict and prioritize executed evidence for environment-specific conclusions.
• For version-sensitive claims, include release-notes citation when available.

Prohibited Patterns

• Unsupported claims without citations.
• Ambiguous mixed-mode guidance without mode labels.
• Copying large verbatim excerpts from external docs.

Public Docs Index (Dispatcher Source Of Truth)

Use this file as the curated public reference set for Cloud Dispatcher guidance.

Dispatcher Core (Common Experience League)

• Dispatcher overview: https://experienceleague.adobe.com/en/docs/experience-manager-dispatcher/using/dispatcher
• Dispatcher FAQ: https://experienceleague.adobe.com/en/docs/experience-manager-dispatcher/using/troubleshooting/dispatcher-faq
• Dispatcher install: https://experienceleague.adobe.com/en/docs/experience-manager-dispatcher/using/getting-started/dispatcher-install
• Dispatcher configuration: https://experienceleague.adobe.com/en/docs/experience-manager-dispatcher/using/configuring/dispatcher-configuration
• Content filter config: https://experienceleague.adobe.com/en/docs/experience-manager-dispatcher/using/configuring/dispatcher-configuration#configuring-access-to-content-filter
• Caching docs: https://experienceleague.adobe.com/en/docs/experience-manager-dispatcher/using/configuring/dispatcher-configuration#caching-documents
• Cache invalidation: https://experienceleague.adobe.com/en/docs/experience-manager-dispatcher/using/configuring/dispatcher-configuration#invalidating-files-by-folder-level
• Flush from AEM: https://experienceleague.adobe.com/en/docs/experience-manager-dispatcher/using/configuring/dispatcher-configuration#invalidating-dispatcher-cache-from-aem
• Dispatcher domains: https://experienceleague.adobe.com/en/docs/experience-manager-dispatcher/using/configuring/dispatcher-domains
• Dispatcher SSL: https://experienceleague.adobe.com/en/docs/experience-manager-dispatcher/using/configuring/dispatcher-ssl
• Permissions cache: https://experienceleague.adobe.com/en/docs/experience-manager-dispatcher/using/configuring/permissions-cache
• Page invalidate patterns: https://experienceleague.adobe.com/en/docs/experience-manager-dispatcher/using/configuring/page-invalidate
• Dispatcher troubleshooting: https://experienceleague.adobe.com/en/docs/experience-manager-dispatcher/using/troubleshooting/dispatcher-troubleshooting
• Security checklist: https://experienceleague.adobe.com/en/docs/experience-manager-dispatcher/using/getting-started/security-checklist
• Dispatcher release notes: https://experienceleague.adobe.com/en/docs/experience-manager-dispatcher/using/getting-started/release-notes
• Dispatcher CSRF hardening: https://experienceleague.adobe.com/en/docs/experience-manager-dispatcher/using/configuring/configuring-dispatcher-to-prevent-csrf

AEMaaCS Dispatcher (Cloud)

• Cloud Dispatcher overview: https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/content-delivery/disp-overview
• Content delivery overview: https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/content-delivery/overview
• Cloud Dispatcher migration notes: https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/content-delivery/disp-overview#migrating
• Validation and debugging: https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/content-delivery/validation-debug
• Validation and debugging (legacy): https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/content-delivery/validation-debug-legacy
• Local Dispatcher Tools setup: https://experienceleague.adobe.com/en/docs/experience-manager-learn/cloud-service/local-development-environment-set-up/dispatcher-tools
• Caching in AEMaaCS: https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/content-delivery/caching
• Edge Side Includes (ESI): https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/content-delivery/edge-side-includes
• CDN overview: https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/content-delivery/cdn
• CDN traffic configuration: https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/content-delivery/cdn-configuring-traffic
• CDN credentials/authentication: https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/content-delivery/cdn-credentials-authentication
• Pipeline-free redirects: https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/content-delivery/pipeline-free-url-redirects
• CDN cache purge: https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/content-delivery/cdn-cache-purge
• CDN error pages: https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/content-delivery/cdn-error-pages
• Traffic filter rules / WAF: https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/security/traffic-filter-rules-including-waf
• Advanced networking: https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/security/configuring-advanced-networking
• IMS support: https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/security/ims-support
• Cloud release notes: https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/release-notes/home
• AMS hosted on AEMaaCS architecture: https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/content-delivery/ams-aem

Cloud Caching Tutorials (Experience League Learn)

• Caching overview: https://experienceleague.adobe.com/en/docs/experience-manager-learn/cloud-service/caching/overview
• Author-tier caching: https://experienceleague.adobe.com/en/docs/experience-manager-learn/cloud-service/caching/author
• Publish-tier caching: https://experienceleague.adobe.com/en/docs/experience-manager-learn/cloud-service/caching/publish
• CDN cache hit ratio analysis: https://experienceleague.adobe.com/en/docs/experience-manager-learn/cloud-service/caching/cdn-cache-hit-ratio-analysis
• Enable caching (how-to): https://experienceleague.adobe.com/en/docs/experience-manager-learn/cloud-service/caching/how-to/enable-caching
• Disable caching (how-to): https://experienceleague.adobe.com/en/docs/experience-manager-learn/cloud-service/caching/how-to/disable-caching
• Purge cache (how-to): https://experienceleague.adobe.com/en/docs/experience-manager-learn/cloud-service/caching/how-to/purge-cache

Key Concepts

• Filter evaluation: last applied rule wins (see content filter docs).
• URL decomposition for all URL-based rules (filters, cache rules): use path/selectors/extension/suffix; in filters use (/path, /selectors, /extension, /suffix) from Dispatcher configuration docs.

Question-To-Doc Mapping

• Filter conflict/order questions:
• Content filter config
• Security checklist
• CSRF mitigation questions:
• Dispatcher CSRF hardening
• Content filter config
• statfileslevel / invalidation blast-radius questions:
• Cache invalidation by folder level
• Flush from AEM
• URL decomposition / selector-suffix questions (filters, cache rules):
• Content filter config
• Caching docs
• Validation and debugging
• Rewrite/redirect behavior questions:
• Dispatcher configuration
• pipeline-free redirects
• Cache headers / TTL / CDN behavior questions:
• Caching in AEMaaCS
• Dispatcher caching docs
• Cache operations questions (enable/disable/purge):
• Enable caching (how-to)
• Disable caching (how-to)
• Purge cache (how-to)
• Cloud WAF or traffic filtering questions:
• Traffic filter rules / WAF
• CDN overview
• Cloud immutable/include/validator-compatibility questions:
• Validation and debugging
• Validation and debugging (legacy)
• Cloud Dispatcher overview
• ESI and fragment composition questions:
• Edge Side Includes (ESI)
• Content delivery overview
• CDN vs Dispatcher ownership questions:
• CDN overview
• Cloud Dispatcher overview

Usage Policy

1. Use only Experience League links listed in this file. 2. Keep recommendations scoped to cloud mode. 3. If docs and MCP runtime evidence conflict, state the conflict and prioritize executed evidence for environment-specific conclusions.

Quick Start Execution Path (Cloud Dispatcher)

Use this file when the user is new to the dispatcher skills, asks for "start to finish" help, or provides a broad request such as "set up dispatcher for this feature" or "audit and fix the config."

In this skill set, "Dispatcher" means the Adobe Dispatcher Apache HTTP Server module plus its HTTPD/dispatcher configuration, not an AEM OSGi bundle.

Fast Entry Checklist

1. Normalize the config root to the dispatcher src directory. 2. Confirm the target hostnames, paths, methods, and cache/auth expectations. 3. Classify the change as one of:

• config implementation
• security review
• performance tuning
• incident investigation
• full lifecycle / mixed work

4. Apply cloud guardrails before proposing changes. 5. Select the matching playbook and exact MCP command chain. 6. If local SDK-backed runtime checks are needed, use local-sdk-execution.md to choose live-port, hot-reload, or test mode. 7. Return evidence, risk, rollback, and any missing runtime prerequisites.

Normalize The Repo Layout

Use a dispatcher source root shaped like one of these public layouts:

Layout A: Standalone Dispatcher Package

<repo>/
  src/
    conf.d/
    conf.dispatcher.d/

Use config_path="<repo>/src" for sdk(...) actions.

Layout B: Dispatcher Subproject Inside A Larger Repo

<repo>/
  dispatcher/
    src/
      conf.d/
      conf.dispatcher.d/

Use config_path="<repo>/dispatcher/src" for sdk(...) actions.

If the user gives a broader repo root, resolve it to the dispatcher src directory before running validation or SDK checks.

Default Skill Routing

Default Command Chain

Use this minimum chain unless the selected playbook says otherwise:

1. Static structure:

• validate(...)
• lint(...)

2. Config integrity:

• sdk({"action":"check-files","config_path":"<dispatcher src path>"})
• sdk({"action":"diff-baseline","config_path":"<dispatcher src path>"}) when wrapper/include drift matters

3. Runtime evidence for behavior changes:

• trace_request(...)
• inspect_cache(...) when cache behavior changed
• tail_logs(...) and monitor_metrics(...) for incidents or performance analysis

Minimum Output

Always return:

• normalized dispatcher source root
• selected skill and playbook
• files or file families affected
• executed MCP commands and evidence
• selected test IDs from test-case-catalog.md
• rollback trigger and rollback action
• explicit note for any skipped runtime checks

Dispatcher Foundation References

This directory contains cross-cutting references shared by multiple dispatcher skills.

It is named dispatcher-foundation because these files support config authoring, incident response, performance tuning, security hardening, and technical advisory work. They are not advisory-only materials.

The specialist skills may also contain lightweight wrapper files that point back to this directory so local links remain predictable from each skill.

Repo Layout Workflows (Cloud Dispatcher)

Use this file to map a user request to the actual dispatcher repo layout before editing files or running MCP commands.

Here, "Dispatcher" refers to the Adobe Dispatcher Apache HTTP Server module and its HTTPD/dispatcher configuration files, not an AEM bundle.

Supported Public Layouts

Layout A: Standalone Dispatcher Package

<repo>/
  src/
    conf.d/
      available_vhosts/
      enabled_vhosts/
      rewrites/
    conf.dispatcher.d/
      available_farms/
      enabled_farms/
      filters/
      cache/
      clientheaders/
      renders/
      virtualhosts/

Dispatcher source root:

• <repo>/src

Layout B: Dispatcher Subproject Inside A Larger Repo

<repo>/
  dispatcher/
    src/
      conf.d/
      conf.dispatcher.d/

Dispatcher source root:

• <repo>/dispatcher/src

Workflow Maps

1) New Site Or New Public Domain

Primary playbook:

• config-authoring -> config-scenario-playbooks.md Playbook A or C

Usually touch:

• <src>/conf.d/available_vhosts/<site>.vhost
• <src>/conf.d/enabled_vhosts/<site>.vhost
• <src>/conf.d/rewrites/<site>_rewrites.rules
• <src>/conf.dispatcher.d/available_farms/<site>_farm.any
• <src>/conf.dispatcher.d/enabled_farms/<site>_farm.any
• <src>/conf.dispatcher.d/filters/<site>_filters.any
• <src>/conf.dispatcher.d/cache/<site>_cache.any

Runtime proof:

• canonical host redirect
• one allowed content URL
• one denied sensitive URL

2) Headless API, CORS, Or Persisted GraphQL

Primary playbook:

• config-authoring -> Playbook B, H, or I

Usually touch:

• <src>/conf.d/available_vhosts/<site>.vhost
• <src>/conf.d/rewrites/<site>_rewrites.rules
• <src>/conf.dispatcher.d/filters/<site>_filters.any
• <src>/conf.dispatcher.d/cache/<site>_cache.any
• <src>/conf.dispatcher.d/clientheaders/<site>_clientheaders.any

Runtime proof:

• preflight or API request trace
• persisted-query trace where applicable
• cache proof for one cacheable and one non-cacheable request

3) Security Hardening Or Release Gate

Primary playbook:

• security-hardening -> Playbook 1 or 3

Usually inspect first:

• <src>/conf.dispatcher.d/filters/*.any
• <src>/conf.dispatcher.d/cache/*.any
• <src>/conf.dispatcher.d/clientheaders/*.any
• <src>/conf.d/available_vhosts/*.vhost
• <src>/conf.d/rewrites/*.rules

Change only after evidence shows a gap.

4) Cache Or Invalidation Tuning

Primary playbook:

• performance-tuning -> Playbook 1, 2, 5, or 7

Usually touch:

• <src>/conf.dispatcher.d/cache/*.any
• <src>/conf.dispatcher.d/available_farms/*.any
• <src>/conf.d/available_vhosts/*.vhost

Runtime proof:

• cache object state
• hit/miss comparison
• invalidation scope rationale

5) Runtime Incident Triage

Primary playbook:

• incident-response -> Playbook 1, 2, 3, 4, 5, or 10

Inspect before editing:

• changed vhost, farm, filter, cache, and rewrite files under the dispatcher source root

Runtime proof:

• metrics window
• log evidence
• healthy vs failing request trace

6) Full Lifecycle Change

Primary playbook:

• workflow-orchestrator

Order: 1. normalize repo layout 2. pick the authoring playbook 3. run security and performance review for the touched surfaces 4. finish with release-gate validation and rollback notes

File-Family Heuristics

• Host and redirect changes usually start in conf.d/available_vhosts/ and conf.d/rewrites/.
• Farm behavior usually starts in conf.dispatcher.d/available_farms/.
• URL exposure rules usually start in conf.dispatcher.d/filters/.
• Cache policy usually starts in conf.dispatcher.d/cache/.
• Header forwarding usually starts in conf.dispatcher.d/clientheaders/.

Normalize to these file families before producing a change plan.

Dispatcher Test Case Catalog

Use these IDs when proposing or reporting verification scenarios.

Filter Coverage

Cache Coverage

Rewrite/Redirect Coverage

Header / Contract Coverage

Runtime Incident Coverage

Mode Compatibility Coverage

Minimum Selection Rule

For configuration changes, include at least:

• one filter test
• one cache test
• one rewrite/redirect test if rewrite logic changed
• one mode test for selected cloud mode

Load Testing Guidance

Purpose

Provide executable load testing strategies for dispatcher performance validation.

Load Testing Modes

Cloud Mode (AEMaaCS Local SDK)

Prerequisites:

• Running dispatcher container
• Local AEM author/publish instance
• Load testing tool (Apache JMeter, Gatling, or k6)

Approach:

# 1. Establish baseline with current config
# Run load test: 100 users, 5 min ramp, 30 min sustained

# 2. Monitor during load test
monitor_metrics({"window_minutes":30,"breakdown_by":"status_code"})

# 3. Analyze results
inspect_cache({"url":"/content/site/en.html","show_metadata":true})
tail_logs({"lines":500})

Key Metrics:

• Throughput (requests/sec)
• Response time (p50, p95, p99)
• Error rate (%)
• Cache hit ratio during load
• Container CPU/memory utilization

Load Test Scenarios

Scenario 1: Cache Warming

Goal: Validate cache efficiency after initial population.

1. Clear cache
2. Run synthetic traffic across key URLs
3. Measure cache hit ratio progression
4. Validate steady-state performance

Scenario 2: Traffic Spike Simulation

Goal: Verify behavior under sudden load increase.

1. Start with baseline load (e.g., 10 users)
2. Ramp to 10x load over 2 minutes
3. Sustain peak for 10 minutes
4. Measure response time degradation
5. Check error rate increase

Scenario 3: Cache Invalidation Under Load

Goal: Validate invalidation behavior doesn't cause cascade failures.

1. Establish steady-state load
2. Trigger cache invalidation (via flush)
3. Measure cache miss spike
4. Measure backend request surge
5. Validate recovery time

Scenario 4: Mixed Content Type Load

Goal: Validate performance across HTML, JSON, assets.

1. Generate mixed traffic: 60% HTML, 30% images, 10% JSON
2. Measure cache hit ratio per content type
3. Identify content type bottlenecks
4. Validate content-type-specific optimizations

Load Testing Tools

Apache JMeter

<!-- Example thread group for dispatcher load test -->
<ThreadGroup guiclass="ThreadGroupGui" testclass="ThreadGroup" testname="Dispatcher Load">
  <intProp name="ThreadGroup.num_threads">100</intProp>
  <intProp name="ThreadGroup.ramp_time">300</intProp>
  <longProp name="ThreadGroup.duration">1800</longProp>
</ThreadGroup>

k6 (Recommended for CI/CD)

import http from 'k6/http';
import { check } from 'k6';

export let options = {
  stages: [
    { duration: '5m', target: 100 },  // Ramp-up
    { duration: '30m', target: 100 }, // Sustained
    { duration: '2m', target: 0 },    // Ramp-down
  ],
  thresholds: {
    'http_req_duration': ['p(95)<500'],  // 95% under 500ms
    'http_req_failed': ['rate<0.01'],    // <1% errors
  },
};

export default function () {
  let res = http.get('http://dispatcher:8080/content/site/en.html');
  check(res, { 'status 200': (r) => r.status === 200 });
}

Gatling (for complex scenarios)

val scn = scenario("Dispatcher Load Test")
  .exec(http("Homepage").get("/content/site/en.html"))
  .pause(1)
  .exec(http("Product Page").get("/content/site/en/products.html"))
  .pause(2)

setUp(scn.inject(rampUsers(100) during (5 minutes)))
  .protocols(http.baseUrl("http://dispatcher:8080"))

Capacity Planning Calculations

Formula: Max Concurrent Users

Max Users = (Throughput @ Target Latency) / (Requests per User Session)

Example:
- Dispatcher handles 1000 req/sec at p95 < 300ms
- Average user session: 10 requests
- Max Users = 1000 / 10 = 100 concurrent users/sec turnover

Formula: Cache Hit Ratio Impact

Backend Load = Total Requests x (1 - Cache Hit Ratio)

Example:
- 1000 req/sec to dispatcher
- Cache hit ratio: 80%
- Backend load: 1000 x (1 - 0.80) = 200 req/sec to AEM

Bottleneck Identification

Pre-Production Load Test Checklist

• [ ] Load test environment mirrors production topology
• [ ] Dispatcher config is production-identical
• [ ] Cache is warmed before sustained load phase
• [ ] Backend (AEM) can handle expected cache miss load
• [ ] Monitoring is active (metrics, logs)
• [ ] Success criteria defined (latency, error rate, throughput)
• [ ] Rollback plan ready if performance degrades
• [ ] Load ramp is gradual (avoid thundering herd)
• [ ] Multiple content types represented in load mix
• [ ] Peak load sustained for meaningful duration (>15 min)

References

• Dispatcher caching docs: https://experienceleague.adobe.com/en/docs/experience-manager-dispatcher/using/configuring/dispatcher-configuration#caching-documents
• Caching in AEMaaCS: https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/content-delivery/caching
• Validation and debugging: https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/content-delivery/validation-debug

Dispatcher Performance Tuning Patterns

Cache Optimization Patterns

Pattern 1: Extend TTL for Stable Content

Use Case: Content that rarely changes (legal pages, terms, static content).

Before:

/cache {
    /enableTTL "1"
    /rules {
        /0000 { /glob "*" /type "allow" }
    }
    # Default TTL: short or not set
}

After:

/cache {
    /enableTTL "1"
    /rules {
        /0000 { /glob "*" /type "allow" }
        /0001 { /glob "/content/site/en/legal/*" /type "allow" }
        /0002 { /glob "/content/site/en/about/*" /type "allow" }
    }
}

# Apply TTL through response headers (respected by /enableTTL)
<LocationMatch "^/content/site/en/(legal|about)/">
    Header set Cache-Control "public, s-maxage=86400, max-age=43200"
</LocationMatch>

Expected Impact: +5-10% cache hit ratio, -20-30% backend requests for stable paths.

---

Pattern 2: Add Cache-Control Headers for Static Assets

Use Case: Images, CSS, JS, fonts should be cached aggressively.

Before:

<LocationMatch "\.(js|css|gif|jpg|jpeg|png|svg|woff|woff2)$">
    # No caching headers
</LocationMatch>

After:

<LocationMatch "\.(js|css|gif|jpg|jpeg|png|svg|woff|woff2)$">
    Header set Cache-Control "public, max-age=31536000, immutable"
    Header set Expires "1 year"
</LocationMatch>

Expected Impact: CDN/browser cache offload, -15-25% dispatcher requests for assets.

---

Pattern 3: Optimize Cache Invalidation (Reduce Over-Flushing)

Use Case: Selective invalidation instead of full cache flush.

Before:

/invalidate {
    /0000 { /glob "*" /type "deny" }
    /0001 { /glob "*.html" /type "allow" }  # Invalidates all HTML
}

After:

/invalidate {
    /0000 { /glob "*" /type "deny" }
    /0001 { /glob "/content/site/${specific-path}/*" /type "allow" }  # Targeted
}

/cache {
    /statfileslevel "2"  # Folder-level stat files
}

Expected Impact: +10-15% cache persistence, faster cache recovery after publish.

---

Pattern 4: Implement Query String Caching (Selectively)

Use Case: API endpoints with cacheable query parameters.

Before:

/ignoreUrlParams {
    /0001 { /glob "*" /type "deny" }  # Ignore all query params by default
}

After:

/ignoreUrlParams {
    /0001 { /glob "*" /type "deny" }
    /0002 { /glob "page" /type "allow" }  # Allow caching with 'page' param
    /0003 { /glob "lang" /type "allow" }  # Allow caching with 'lang' param
}

Expected Impact: +20-30% cache hit ratio for API endpoints with common query patterns.

---

Static Asset Optimization Patterns

Pattern 5: Enable Compression

Before:

# No compression

After:

<IfModule mod_deflate.c>
    AddOutputFilterByType DEFLATE text/html text/plain text/xml text/css text/javascript application/javascript application/json
    DeflateCompressionLevel 6
</IfModule>

Expected Impact: -60-80% response size for compressible content, faster transfer times.

---

Pattern 6: Asset Versioning for Cache Busting

Before:

<link rel="stylesheet" href="/etc.clientlibs/site/clientlib.css">

After:

<link rel="stylesheet" href="/etc.clientlibs/site/clientlib.v20260303.css">
<!-- Or use query string: /etc.clientlibs/site/clientlib.css?v=20260303 -->

# Rewrite versioned URLs to actual file
RewriteRule ^(.*)\.(v[0-9]+)\.(css|js)$ $1.$3 [L]

Expected Impact: Safe long-term caching, no manual cache purging needed for assets.

---

Request Processing Optimization Patterns

Pattern 7: Simplify Filter Rules (Order & Specificity)

Before:

/filter {
    /0000 { /glob "*" /type "allow" }  # Overly broad
    /0001 { /glob "/content/*" /type "allow" }
    /0002 { /glob "/content/site/*" /type "allow" }  # Redundant
    # ... 50 more rules ...
}

After:

/filter {
    /0000 { /glob "*" /type "deny" }  # Deny by default
    /0001 { /glob "/content/site/*/en/*" /type "allow" /method "GET" }  # Specific allow
    /0002 { /glob "/etc.clientlibs/site/*" /type "allow" /method "GET" }
    # Fewer, more specific rules
}

Expected Impact: -10-20% filter evaluation time, clearer security posture.

---

Pattern 8: Optimize Rewrite Rules (Minimize Redirects)

Before:

RewriteRule ^/old-path1/(.*)$ /new-path1/$1 [R=301,L]
RewriteRule ^/old-path2/(.*)$ /new-path2/$1 [R=301,L]
# ... many redirect chains ...
RewriteRule ^/new-path1/(.*)$ /final-path/$1 [R=301,L]  # Redirect chain!

After:

# Eliminate redirect chains - go directly to final destination
RewriteRule ^/old-path1/(.*)$ /final-path/$1 [R=301,L]
RewriteRule ^/old-path2/(.*)$ /new-path2/$1 [R=301,L]

# Use RewriteMap for many redirects
RewriteMap redirects txt:/etc/httpd/conf.d/redirects.txt
RewriteCond ${redirects:$1} !=""
RewriteRule ^/(.*)$ ${redirects:$1} [R=301,L]

Expected Impact: -100-300ms latency per eliminated redirect, better UX.

---

Pattern 9: Reduce Header Processing Overhead

Before:

# Setting many headers on every request
Header always set X-Custom-Header-1 "value1"
Header always set X-Custom-Header-2 "value2"
Header always set X-Custom-Header-3 "value3"
# ... 10 more headers ...

After:

# Only set necessary headers, conditionally
<LocationMatch "^/content/site/">
    Header set X-Frame-Options "SAMEORIGIN"
    Header set X-Content-Type-Options "nosniff"
    # Only essential security headers
</LocationMatch>

Expected Impact: -5-10ms per request, reduced processing overhead.

---

Cloud-Specific Patterns (AEMaaCS)

Pattern 10: Dispatcher/CDN-Friendly Static Asset Headers

Before: All static assets served through dispatcher.

After:

# Keep assets cacheable with headers that downstream CDN/browser layers can honor
<LocationMatch "\.(jpg|jpeg|png|gif|svg|css|js|woff|woff2)$">
    Header set Cache-Control "public, max-age=31536000, immutable"
</LocationMatch>

Expected Impact: Better edge/browser offload without moving CDN policy into custom rewrite logic.

---

Pattern 11: Edge Caching Configuration

Use Case: Leverage AEMaaCS CDN for additional caching layer.

# Set CDN-friendly cache headers
<LocationMatch "^/content/site/en/products/">
    Header set Cache-Control "public, s-maxage=600, max-age=300"
    # CDN caches for 10min, browser for 5min
</LocationMatch>

Expected Impact: +20-30% cache offload to CDN, reduced dispatcher requests.

---

Verification Pattern

For every optimization applied:

# 1. Measure baseline BEFORE
baseline_metrics = monitor_metrics({
  "window_minutes": 10,
  "breakdown_by": "url_pattern"
})

# 2. Apply optimization
# (edit config files)

# 3. Validate config
lint({"mode":"directory","target":"/path/to/dispatcher/src","strict_mode":true})
sdk({"action":"check-files","config_path":"/path/to/dispatcher/src"})
validate({"config":"<updated dispatcher.any content>","type":"cloud"})

# 4. Reload dispatcher (environment-specific)

# 5. Measure impact AFTER
post_metrics = monitor_metrics({
  "window_minutes": 10,
  "breakdown_by": "url_pattern"
})

# 6. Verify specific improvements
inspect_cache({"url":"/sample/page.html","config_path":"/path/to/dispatcher/src"})
trace_request({"url":"/sample/page.html","method":"GET","config_path":"/path/to/dispatcher/src"})

Anti-Patterns (Avoid These)

Anti-Pattern 1: Overly Aggressive Caching

# BAD: Apply 1-year TTL headers to all HTML pages
<LocationMatch "^/content/.*\\.html$">
    Header set Cache-Control "public, s-maxage=31536000, max-age=31536000"
</LocationMatch>

Problem: Personalized/dynamic content cached incorrectly, stale content issues.

---

Anti-Pattern 2: No Cache Invalidation Strategy

# BAD: No invalidation rules
/invalidate {
    /0000 { /glob "*" /type "deny" }
}

Problem: Manual cache clearing required, stale content persists indefinitely.

---

Anti-Pattern 3: Allowing All Query Parameters

# BAD: Cache with all query params
/ignoreUrlParams {
    /0001 { /glob "*" /type "allow" }
}

Problem: Cache fragmentation, low hit ratio, potential cache pollution attacks.

---

Anti-Pattern 4: Excessive Redirect Chains

# BAD: Multiple redirects
RewriteRule ^/a$ /b [R=301,L]
RewriteRule ^/b$ /c [R=301,L]
RewriteRule ^/c$ /d [R=301,L]

Problem: 300-900ms added latency, poor user experience.

---

Pattern Selection Guide

References

• Dispatcher Configuration: https://experienceleague.adobe.com/en/docs/experience-manager-dispatcher/using/configuring/dispatcher-configuration
• Caching in AEMaaCS: https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/content-delivery/caching

Performance Monitoring Setup

Purpose

Guide proactive performance monitoring configuration (not incident-driven alerting).

Key Performance Indicators (KPIs)

Tier 1 - Critical Metrics

Tier 2 - Optimization Metrics

Tier 3 - Capacity Metrics

Cloud Mode Monitoring (AEMaaCS)

Container Metrics

# Docker-based host metrics collection (outside MCP)
docker stats <dispatcher-container-name> --no-stream

# Dispatcher-specific MCP metrics
monitor_metrics({"window_minutes":60,"breakdown_by":"status_code"})
tail_logs({"lines":200})

Example External Metrics Pipeline

# Example scrape config for an external metrics system
scrape_configs:
  - job_name: 'aem-dispatcher'
    static_configs:
      - targets: ['dispatcher:9113']
    metrics_path: '/metrics'
    scrape_interval: 30s

    # Key metrics to track
    metric_relabel_configs:
      - source_labels: [__name__]
        regex: '(dispatcher_cache_hit_ratio|dispatcher_requests_total|dispatcher_request_duration_seconds)'
        action: keep

Alert Configuration (Cloud)

# Example alert rules
groups:
  - name: dispatcher_performance
    interval: 1m
    rules:
      - alert: DispatcherCacheHitRatioLow
        expr: dispatcher_cache_hit_ratio < 0.70
        for: 5m
        annotations:
          summary: "Cache hit ratio below 70% for 5 minutes"

      - alert: DispatcherP95LatencyHigh
        expr: histogram_quantile(0.95, dispatcher_request_duration_seconds) > 0.5
        for: 5m
        annotations:
          summary: "P95 latency above 500ms for 5 minutes"

Dashboard Design

Essential Dashboard Widgets

1. Cache Efficiency Panel

• Cache hit ratio (line chart, 24h)
• Cache miss rate by URL pattern (bar chart)
• Cache size trend (line chart, 7d)

2. Latency Panel

• P50, P95, P99 response time (multi-line chart, 24h)
• Response time by content type (heatmap)
• Slow request top 10 (table)

3. Throughput Panel

• Requests/second (line chart, 24h)
• Status code distribution (stacked area chart)
• Error rate (line chart with threshold markers)

4. Capacity Panel

• Resource utilization (CPU, memory, disk)
• Worker/thread saturation (gauge)
• Traffic forecast vs capacity (dual-axis line chart)

Example Dashboard Definition

{
  "dashboard": {
    "title": "Dispatcher Performance",
    "panels": [
      {
        "title": "Cache Hit Ratio",
        "targets": [
          {
            "expr": "rate(dispatcher_cache_hits_total[5m]) / rate(dispatcher_requests_total[5m])"
          }
        ],
        "thresholds": [
          { "value": 0.6, "color": "red" },
          { "value": 0.7, "color": "yellow" },
          { "value": 0.8, "color": "green" }
        ]
      },
      {
        "title": "P95 Response Time",
        "targets": [
          {
            "expr": "histogram_quantile(0.95, rate(dispatcher_request_duration_seconds_bucket[5m]))"
          }
        ]
      }
    ]
  }
}

Trend Analysis & Reporting

Daily Performance Report

Dispatcher Performance Summary - [Date]

1. Cache Efficiency
   - Hit Ratio: 78.5% (target: >80%, [WARN] below target)
   - Miss Rate: 21.5%
   - Top 10 Missed URLs: /api/*, /content/dynamic/*

2. Latency
   - P50: 125ms ([OK] within target)
   - P95: 480ms ([OK] within target)
   - P99: 1,200ms ([WARN] investigate)

3. Availability
   - Uptime: 99.95% ([OK] within target)
   - Error Rate: 0.08% ([OK] within target)

4. Capacity
   - Peak Throughput: 1,250 req/sec (85% of capacity)
   - Headroom: 15% ([WARN] plan for scaling)

5. Recommendations
   - Optimize caching for /api/* paths (potential +8% hit ratio)
   - Investigate P99 latency spikes during 14:00-16:00 UTC
   - Plan capacity increase within 30 days

Weekly Trend Analysis

Week of [Date Range]

1. Performance Trends (vs. previous week)
   - Cache Hit Ratio: 78.5% -> 82.1% ([OK] +3.6pp improvement)
   - P95 Latency: 480ms -> 420ms ([OK] -60ms improvement)
   - Throughput: +12% (traffic growth)

2. Optimization Impact
   - Static asset caching: +5% hit ratio
   - Cache TTL increase: -40ms latency

3. Capacity Forecast
   - Current growth rate: +2.5% weekly
   - Capacity exhaustion: ~12 weeks
   - Recommended action: Plan scaling for week of [Date]

Monitoring Setup Checklist

Initial Setup

• [ ] Identify a monitoring platform or metrics sink that fits the environment
• [ ] Configure metric collection (MCP tools, log parsing, or custom exporters)
• [ ] Define KPI targets and alert thresholds
• [ ] Create performance dashboard with essential widgets
• [ ] Set up alert routing (for example: email, chat, or incident-management tooling)
• [ ] Document escalation procedures

Cloud Mode Specific

• [ ] Configure Docker stats collection
• [ ] Set up container resource limits
• [ ] Integrate with your cloud-native monitoring stack
• [ ] Configure CDN performance metrics (if applicable)

Ongoing Maintenance

• [ ] Review dashboard weekly for trends
• [ ] Update alert thresholds based on baseline shifts
• [ ] Archive old metrics data per retention policy
• [ ] Quarterly capacity planning review
• [ ] Monthly performance optimization review

MCP Tool Integration

Automated Metrics Collection Pattern

# Poll every N seconds from your scheduler/automation runner:
metrics = monitor_metrics({"window_minutes":1,"breakdown_by":"status_code"})
logs = tail_logs({"lines":100})

# Persist serialized results to your metrics sink/log store.
# Compare current summary.cache_hit_ratio and latency percentiles
# against your alert thresholds.

Daily Performance Check Pattern

daily = monitor_metrics({"window_minutes":1440,"breakdown_by":"status_code"})

# Evaluate thresholds:
# - daily.metrics.summary.cache_hit_ratio
# - daily.metrics.summary.error_rate
# - daily.metrics.latency.p95_ms / p99_ms

References

• Dispatcher caching docs: https://experienceleague.adobe.com/en/docs/experience-manager-dispatcher/using/configuring/dispatcher-configuration#caching-documents
• Caching docs: https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/content-delivery/caching
• Cloud Dispatcher overview: https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/content-delivery/disp-overview

Performance Scenario Playbooks (Cloud, Core-7)

Playbook 1: Improve Cache Hit Ratio

1. Capture baseline via monitor_metrics. 2. Identify top MISS/PASS URLs using tail_logs and trace_request. 3. Validate candidate cache-rule changes with validate + lint. 4. Verify affected URLs using inspect_cache. 5. Compare post-change metrics.

Playbook 2: Invalidation Blast-Radius Reduction

1. Document current invalidation behavior and statfileslevel. 2. Validate proposed changes with static checks. 3. Verify one invalidated path and one sibling unaffected path. 4. Confirm no stale-content regression indicators.

Playbook 3: Rewrite/Redirect Latency Cleanup

1. Trace redirect-heavy URLs. 2. Remove redundant chains and re-validate. 3. Confirm deterministic final destination in one hop where possible. 4. Compare latency trends before/after.

Playbook 4: Static Asset Delivery Optimization

1. Audit compression and cache-header posture for CSS/JS/fonts/images. 2. Validate Apache header/expires/deflate changes with validate({"config":"<httpd header/expires/deflate block>","type":"httpd"}). 3. Verify cacheability and response behavior on representative static assets. 4. Compare post-change cache-hit and latency metrics.

Playbook 5: Query-Parameter Cache Fragmentation Cleanup

1. Sample high-traffic URLs with marketing/query params from logs. 2. Review and tighten /ignoreUrlParams allow-list policy (include marketing parameter strategy where applicable). 3. Validate/lint updated cache config and run sdk({"action":"check-files","config_path":"<dispatcher src path>"}). 4. Reuse or mirror the existing marketing_query_parameters.any pattern for common tracking params when business-safe. 5. Ensure the common cloud validator warning about missing /ignoreUrlParams strategy is addressed. 6. Verify equivalent content resolves to consistent cache behavior.

Playbook 6: Tail-Latency Hotspot Mitigation

1. Use monitor_metrics to isolate p95/p99 hotspots. 2. trace_request top offenders and identify filter/rewrite/backend causes. 3. Apply minimal changes with highest expected impact. 4. Re-measure p95/p99 and keep rollback thresholds explicit.

Playbook 7: Persisted Query Cache Enablement

1. Confirm persisted-query traffic is a real latency or backend-load hotspot. 2. Check whether CACHE_GRAPHQL_PERSISTED_QUERIES is currently disabled by default and document the current bypass behavior. 3. If enabling cache, align CORS and preflight handling first so cached GraphQL responses do not break browser clients. 4. Validate httpd/vhost changes and verify one persisted-query path plus one non-cacheable GraphQL control path. 5. Compare cache behavior and latency after the change, with a rollback path that reverts only the persisted-query toggle and related headers.

Playbook 8: Cloud Cache Operations Runbook (Enable/Disable/Purge)

1. Identify whether the need is targeted purge, temporary cache disable, or selective cache enablement. 2. Apply the smallest scope change first (single path/pattern before global behavior changes). 3. Validate config changes with validate + lint, then verify behavior with inspect_cache and trace_request. 4. If purge is used, confirm origin freshness and downstream CDN/dispatcher alignment to avoid stale rehydration loops. 5. Capture rollback steps and cite the cloud caching how-to guidance (enable, disable, purge).