Diagnoses and fixes Adobe Experience Manager slowness by layer — CDN and dispatcher hit ratio, uncacheable requests, slow JCR queries and missing Oak indexes, heavy Sling Models and HTL, blocking external calls, Sling Dynamic Include, Core Web Vitals, and author-side backlogs.
When agents use itUse this whenever the user says AEM pages or the author UI are slow, TTFB or LCP is high, publish CPU spikes under normal traffic, the cache hit ratio is low, error.log shows "Traversed … nodes" or a query limit exception, a Sling Model or HTL render is slow, workflows, Sling Job queues, replication, asset processing or MSM rollouts back up, or they ask about thread dumps, request.log, rlog, the Developer Console, CDN logs or load testing AEM. For a PageSpeed or Lighthouse problem on an Edge Delivery Services site use `aem-edge-delivery-services` instead. Also apply it when apparent capacity trouble turns out to be a caching or query problem.
Install
Copilot (VS Code, Visual Studio, Copilot CLI and github.com) reads skills from the repository — commit them so the whole team gets them.
npx skills add AGCO-Global/org-skills --skill aem-performance -a github-copilot
# or with the org installer (adds .github/skills/aem-performance):
npx -y github:AGCO-Global/org-skills add skill aem-performance
Uses the open skills CLI. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, OpenCode, Windsurf and 60+ others — it asks which agent to install into.
Installs the aem-architecture-skills plugin, which bundles all AEM / Architecture skills and keeps them updated.
/plugin marketplace add AGCO-Global/org-skills
/plugin install aem-architecture-skills@org-skills
# or just this skill, in this repository:
npx skills add AGCO-Global/org-skills --skill aem-performance -a claude-code
Use Download .zip above, then upload it under Customize → Skills → Upload skill. Team and Enterprise admins can sync this repo as a plugin marketplace instead.
Installs into .agents/skills/, which Codex reads.
npx skills add AGCO-Global/org-skills --skill aem-performance -a codex
Installs into Cursor's skills folder.
npx skills add AGCO-Global/org-skills --skill aem-performance -a cursor
Installs into Gemini CLI's skills folder.
npx skills add AGCO-Global/org-skills --skill aem-performance -a gemini-cli
Nothing to install. Press Download .zip above, unzip it, and drop the aem-performance folder into your tool's skills folder — .claude/skills/, .github/skills/, .cursor/skills/ or .agents/skills/. Step-by-step, per tool: How to use it. For any other tool with rules or custom prompts, Copy SKILL.md and paste it in — it is plain Markdown.
The npx commands need Node.js 20+ and use your normal git sign-in to GitHub, so they work while the repository is private. Without Node.js, see the No Node.js tab — a skill is a folder of Markdown, so copying it in works just as well.
On AEM the fastest request is the one publish never sees. Work down the layers in order — cacheability, then queries, then render code, then the front end — and measure before and after each change with the same tool. Intuition about which layer is slow is wrong often enough that an unmeasured fix is a guess with a deployment attached.
1. Decide first
Question
Default
Change when
Where to look first
Cache hit ratio at the CDN
The URL is already a HIT and still slow → go to the render path
Is this a capacity problem?
No, until the hit ratio is above ~90 % on anonymous HTML
Hit ratio is good, queries are indexed, and publish still saturates
A query is slow
It is missing an index — fix the index
The query itself is unbounded (p.limit=-1, exact totals) → fix the query first
Personalised fragment on a cached page
Client-side fetch
The fragment must be server-rendered → Sling Dynamic Include with SSI (mod_include); ESI is not supported on the Adobe CDN
Good TTFB, bad LCP
A front-end problem — hero image, fonts, tag manager
Never add publish capacity for an LCP number
Author is slow, publish is fine
Workflow, job queue, asset or rollout backlog
Large Content Fragment or DAM folders → folder structure, not capacity
Measurement source
Field data (CrUX/RUM) for CWV, CDN logs for hit ratio
Lighthouse alone is a lab signal and will mislead on mobile
2. Triage table
Symptom
Likely layer
Evidence to collect
Owner
High TTFB on anonymous pages
CDN/dispatcher miss
x-cache, age, CDN log cache field by path
aem-dispatcher
Publish CPU high, traffic normal
Low hit ratio or over-invalidation
Requests reaching publish/s; statfile touches; publish frequency
Cache-rule specifics (/ignoreUrlParams, /statfileslevel, TTLs, purge) belong to aem-dispatcher — collect the evidence here, fix it there.
3. Queries and indexes
Every query in production code must hit an index. Run it through Explain Query (Developer Console → Queries on Cloud Service; Tools → Operations → Diagnosis on 6.5). A plan containing /* traverse */, or a different index than you expected, is the finding.
Traversed N nodes in error.log and Oak read-limit exceptions are failures, not noise. Cloud Service manages the limits and you cannot raise them — that is the point.
Cloud Service supports only type="lucene" definitions, named <prefix>.<name>-<productVersion>-custom-<n> — for example acme.article-1-custom-1. The rule, a complete definition and the packaging settings are in oak-index-naming.md in ../../development/aem-backend-development/references/; do not invent a second convention here.
Constrain queries: node type, ISDESCENDANTNODE, p.limit with p.guessTotal=true. p.facets costs an extra pass over the result set — measure before adding facets to a request path.
Do not query per render. Precompute on activation, cache in a service with a TTL, or traverse a small known subtree.
4. Sling Models and HTL
@Model(adaptables = SlingHttpServletRequest.class, defaultInjectionStrategy = DefaultInjectionStrategy.OPTIONAL) with @ValueMapValue / @ChildResource. Plain @Inject makes the injector try every strategy in turn — measurable in hot components.
Compute once in @PostConstruct; HTL calls a getter every time it appears in the template, including inside loops.
Resolve resources once and pass them down. Re-walking getParent() chains or re-adapting in every child component is the most common self-inflicted render cost.
No JCR queries, no HTTP calls and no getServiceResourceResolver() inside a component render.
Heavy navigation and footers: render as an Experience Fragment or a cached include, not recomputed per page.
5. External calls
One OSGi service per integration, with a pooled client, explicit connect and socket timeouts, a fallback, and a TTL cache keyed by the request parameters (aem-backend-development). Without timeouts, a slow partner turns into exhausted request threads and an outage.
Refresh on a schedule on author where freshness allows; publish reads the cached copy.
Per-user or real-time data is fetched client-side so the page stays cacheable.
6. Front end and dynamic fragments
LCP: Core Image v3 with web-optimized image delivery or Dynamic Media (responsive widths, modern formats). Core Image lazy-loads by default — turn lazy loading off for the hero, set width and height, and preload it if the waterfall shows a late discovery.
Clientlibs: split per template, defer non-critical JS, fingerprinted long-cache URLs. Audit the tag manager payload; it is usually the largest script on the page.
Fonts: self-host, subset, font-display: swap, preload the one or two critical faces.
Sling Dynamic Include lets the page stay cached while one component is dynamic. On Cloud Service use SSI — mod_include is enabled on the dispatcher — or a client-side include. ESI is not available at the Adobe CDN, so an SDI configuration that emits ESI silently serves nothing.
GraphQL-driven front ends: query cost grows with fragment-reference depth; see aem-headless before blaming the network.
7. Author and background work
Workflows: transient where no history is needed; purge completed instances; launchers scoped to a path and a node type, never every change under /content.
Sling Jobs: check queue depth and queue.maxparallel before raising concurrency; a saturated queue looks exactly like a slow author.
Assets: Cloud Service processes through asset microservices driven by folder processing profiles — keep custom post-processing light and check the Bulk Import backlog before blaming the UI. On 6.5, tune DAM Update Asset.
Large folders: keep DAM and Content Fragment folders in the low thousands of children. A flat folder with 100k assets is slow in the UI, in queries and in rollouts.
MSM: roll out in batches off-peak; a rollout config triggered on every modification will back up the queue.
Reindexing, large package installs and bulk activations are off-peak work.
Deliverable format
## Symptom and baseline — metric, value, tool, URL set, time window
## Findings
| Layer | Evidence | Impact | Fix | Effort |
|---|---|---|---|---|
| CDN | 58 % HIT on /content/acme/*.html; utm_* in cache key | ~4x publish load | Ignore `*` in /ignoreUrlParams, deny only `page` | S |
## Changes — diffs: index definitions, dispatcher rules, model refactors
## Verification — same measurement after the change, hit ratio and CWV delta
## Follow-ups — alerts that would catch the regression
Checklist
A baseline number exists, with the tool and the time window that produced it
Hit ratio measured per path and content type before any capacity discussion
Every query in the changed code has an Explain Query plan attached
Index definitions are lucene and correctly named
No query, HTTP call or resolver acquisition inside a component render
Outbound calls have connect and socket timeouts and a fallback
LCP element is not lazy-loaded and has explicit dimensions
Dynamic fragments use SSI or client-side include, never ESI
Author findings name the queue or folder, not "author is slow"
The same measurement is repeated after the fix and reported
Anti-patterns
Adding publish capacity before measuring hit ratio → autoscaling multiplies a bad query, it does not fix it.
Raising a query limit instead of adding an index → on Cloud Service you cannot, and on 6.5 you are hiding a traversal.
Index named mysite-articles-custom-1 or type="property" → acme.articles-1-custom-1, type="lucene".
A query inside a Sling Model getter → precompute in @PostConstruct or cache in a service.
External HTTP on the request thread with default timeouts → explicit timeouts, cache, fallback.
Lazy-loading the hero image → the LCP element loads eagerly, with dimensions.
Configuring SDI with ESI on Cloud Service → SSI via mod_include, or a client-side include.
Clearing a replication or workflow queue to "fix" it → find the failing item; clearing loses the work and the evidence.
Load tests that bypass the CDN → run against stage through the full path, and report the hit ratio the test achieved.
Go deeper
references/diagnostics.md — tool-per-question table, CDN log fields and a hit-ratio-per-path recipe, rlog.jar usage, Oak query limits, how to run a load test that means something.
oak-index-naming.md in ../../development/aem-backend-development/references/ — index naming, lucene-only rule, a complete definition.
Sibling skills: aem-dispatcher for cache and CDN rules, aem-backend-development for query and service code, aem-frontend-development for clientlibs and Core Web Vitals, aem-headless for GraphQL cost, aem-assets for processing and DAM structure.
---
name: aem-performance
description: >
Diagnoses and fixes Adobe Experience Manager slowness by layer — CDN and dispatcher hit ratio, uncacheable requests, slow JCR queries and missing Oak indexes, heavy Sling Models and HTL, blocking external calls, Sling Dynamic Include, Core Web Vitals, and author-side backlogs. Use this whenever the user says AEM pages or the author UI are slow, TTFB or LCP is high, publish CPU spikes under normal traffic, the cache hit ratio is low, error.log shows "Traversed … nodes" or a query limit exception, a Sling Model or HTL render is slow, workflows, Sling Job queues, replication, asset processing or MSM rollouts back up, or they ask about thread dumps, request.log, rlog, the Developer Console, CDN logs or load testing AEM. For a PageSpeed or Lighthouse problem on an Edge Delivery Services site use `aem-edge-delivery-services` instead. Also apply it when apparent capacity trouble turns out to be a caching or query problem.
metadata:
technology: AEM
type: performance
---
# AEM Performance
> **Targets:** AEM as a Cloud Service 2026.x, AEM 6.5 noted where different · **Verified:** 2026-09 against https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/content-delivery/caching
On AEM the fastest request is the one publish never sees. Work down the layers in order — cacheability, then queries, then render code, then the front end — and measure before and after each change with the same tool. Intuition about which layer is slow is wrong often enough that an unmeasured fix is a guess with a deployment attached.
## 1. Decide first
| Question | Default | Change when |
|---|---|---|
| Where to look first | Cache hit ratio at the CDN | The URL is already a `HIT` and still slow → go to the render path |
| Is this a capacity problem? | No, until the hit ratio is above ~90 % on anonymous HTML | Hit ratio is good, queries are indexed, and publish still saturates |
| A query is slow | It is missing an index — fix the index | The query itself is unbounded (`p.limit=-1`, exact totals) → fix the query first |
| Personalised fragment on a cached page | Client-side fetch | The fragment must be server-rendered → Sling Dynamic Include with SSI (`mod_include`); **ESI is not supported on the Adobe CDN** |
| Good TTFB, bad LCP | A front-end problem — hero image, fonts, tag manager | Never add publish capacity for an LCP number |
| Author is slow, publish is fine | Workflow, job queue, asset or rollout backlog | Large Content Fragment or DAM folders → folder structure, not capacity |
| Measurement source | Field data (CrUX/RUM) for CWV, CDN logs for hit ratio | Lighthouse alone is a lab signal and will mislead on mobile |
## 2. Triage table
| Symptom | Likely layer | Evidence to collect | Owner |
|---|---|---|---|
| High TTFB on anonymous pages | CDN/dispatcher miss | `x-cache`, `age`, CDN log `cache` field by path | `aem-dispatcher` |
| Publish CPU high, traffic normal | Low hit ratio or over-invalidation | Requests reaching publish/s; statfile touches; publish frequency | `aem-dispatcher` |
| One page type slow even uncached | Query or render cost | `request.log` + `rlog.jar`, Developer Console → Queries | §3, §4 |
| `Traversed N nodes` / query limit exception | Missing or wrong index | Explain Query plan | §3 |
| Slow only when a partner API is slow | Blocking outbound call | Thread dumps: threads stuck in socket read | §5 |
| Good TTFB, poor LCP/CLS | Front end | Field CWV + waterfall | §6 |
| Periodic slowdowns | Jobs, GC, workflows | GC logs, Sling Job queues, scheduler activity | §7 |
| Author sluggish | Backlogs | Workflow console, job queues, replication queue | §7 |
Cache-rule specifics (`/ignoreUrlParams`, `/statfileslevel`, TTLs, purge) belong to `aem-dispatcher` — collect the evidence here, fix it there.
## 3. Queries and indexes
- Every query in production code must hit an index. Run it through **Explain Query** (Developer Console → Queries on Cloud Service; Tools → Operations → Diagnosis on 6.5). A plan containing `/* traverse */`, or a different index than you expected, is the finding.
- `Traversed N nodes` in `error.log` and Oak read-limit exceptions are failures, not noise. Cloud Service manages the limits and you cannot raise them — that is the point.
- Cloud Service supports only `type="lucene"` definitions, named `<prefix>.<name>-<productVersion>-custom-<n>` — for example `acme.article-1-custom-1`. The rule, a complete definition and the packaging settings are in `oak-index-naming.md` in `../../development/aem-backend-development/references/`; do not invent a second convention here.
- Constrain queries: node type, `ISDESCENDANTNODE`, `p.limit` with `p.guessTotal=true`. `p.facets` costs an extra pass over the result set — measure before adding facets to a request path.
- Do not query per render. Precompute on activation, cache in a service with a TTL, or traverse a small known subtree.
## 4. Sling Models and HTL
- `@Model(adaptables = SlingHttpServletRequest.class, defaultInjectionStrategy = DefaultInjectionStrategy.OPTIONAL)` with `@ValueMapValue` / `@ChildResource`. Plain `@Inject` makes the injector try every strategy in turn — measurable in hot components.
- Compute once in `@PostConstruct`; HTL calls a getter every time it appears in the template, including inside loops.
- Resolve resources once and pass them down. Re-walking `getParent()` chains or re-adapting in every child component is the most common self-inflicted render cost.
- No JCR queries, no HTTP calls and no `getServiceResourceResolver()` inside a component render.
- Heavy navigation and footers: render as an Experience Fragment or a cached include, not recomputed per page.
## 5. External calls
- One OSGi service per integration, with a pooled client, explicit connect and socket timeouts, a fallback, and a TTL cache keyed by the request parameters (`aem-backend-development`). Without timeouts, a slow partner turns into exhausted request threads and an outage.
- Refresh on a schedule on author where freshness allows; publish reads the cached copy.
- Per-user or real-time data is fetched client-side so the page stays cacheable.
## 6. Front end and dynamic fragments
- **LCP**: Core Image v3 with web-optimized image delivery or Dynamic Media (responsive widths, modern formats). Core Image lazy-loads by default — turn lazy loading *off* for the hero, set width and height, and preload it if the waterfall shows a late discovery.
- **Clientlibs**: split per template, `defer` non-critical JS, fingerprinted long-cache URLs. Audit the tag manager payload; it is usually the largest script on the page.
- **Fonts**: self-host, subset, `font-display: swap`, preload the one or two critical faces.
- **Sling Dynamic Include** lets the page stay cached while one component is dynamic. On Cloud Service use SSI — `mod_include` is enabled on the dispatcher — or a client-side include. ESI is not available at the Adobe CDN, so an SDI configuration that emits ESI silently serves nothing.
- GraphQL-driven front ends: query cost grows with fragment-reference depth; see `aem-headless` before blaming the network.
## 7. Author and background work
- **Workflows**: transient where no history is needed; purge completed instances; launchers scoped to a path and a node type, never every change under `/content`.
- **Sling Jobs**: check queue depth and `queue.maxparallel` before raising concurrency; a saturated queue looks exactly like a slow author.
- **Assets**: Cloud Service processes through asset microservices driven by folder **processing profiles** — keep custom post-processing light and check the Bulk Import backlog before blaming the UI. On 6.5, tune DAM Update Asset.
- **Large folders**: keep DAM and Content Fragment folders in the low thousands of children. A flat folder with 100k assets is slow in the UI, in queries and in rollouts.
- **MSM**: roll out in batches off-peak; a rollout config triggered on every modification will back up the queue.
- Reindexing, large package installs and bulk activations are off-peak work.
## Deliverable format
```
## Symptom and baseline — metric, value, tool, URL set, time window
## Findings
| Layer | Evidence | Impact | Fix | Effort |
|---|---|---|---|---|
| CDN | 58 % HIT on /content/acme/*.html; utm_* in cache key | ~4x publish load | Ignore `*` in /ignoreUrlParams, deny only `page` | S |
## Changes — diffs: index definitions, dispatcher rules, model refactors
## Verification — same measurement after the change, hit ratio and CWV delta
## Follow-ups — alerts that would catch the regression
```
## Checklist
- [ ] A baseline number exists, with the tool and the time window that produced it
- [ ] Hit ratio measured per path and content type before any capacity discussion
- [ ] Every query in the changed code has an Explain Query plan attached
- [ ] Index definitions are lucene and correctly named
- [ ] No query, HTTP call or resolver acquisition inside a component render
- [ ] Outbound calls have connect and socket timeouts and a fallback
- [ ] LCP element is not lazy-loaded and has explicit dimensions
- [ ] Dynamic fragments use SSI or client-side include, never ESI
- [ ] Author findings name the queue or folder, not "author is slow"
- [ ] The same measurement is repeated after the fix and reported
## Anti-patterns
- **Adding publish capacity before measuring hit ratio** → autoscaling multiplies a bad query, it does not fix it.
- **Raising a query limit instead of adding an index** → on Cloud Service you cannot, and on 6.5 you are hiding a traversal.
- **Index named `mysite-articles-custom-1` or `type="property"`** → `acme.articles-1-custom-1`, `type="lucene"`.
- **A query inside a Sling Model getter** → precompute in `@PostConstruct` or cache in a service.
- **External HTTP on the request thread with default timeouts** → explicit timeouts, cache, fallback.
- **Lazy-loading the hero image** → the LCP element loads eagerly, with dimensions.
- **Configuring SDI with ESI on Cloud Service** → SSI via `mod_include`, or a client-side include.
- **Clearing a replication or workflow queue to "fix" it** → find the failing item; clearing loses the work and the evidence.
- **Load tests that bypass the CDN** → run against stage through the full path, and report the hit ratio the test achieved.
## Go deeper
- `references/diagnostics.md` — tool-per-question table, CDN log fields and a hit-ratio-per-path recipe, `rlog.jar` usage, Oak query limits, how to run a load test that means something.
- `oak-index-naming.md` in `../../development/aem-backend-development/references/` — index naming, lucene-only rule, a complete definition.
- Sibling skills: `aem-dispatcher` for cache and CDN rules, `aem-backend-development` for query and service code, `aem-frontend-development` for clientlibs and Core Web Vitals, `aem-headless` for GraphQL cost, `aem-assets` for processing and DAM structure.