AEM Sites Playbook, Chapter 12: Performance, queries and capacity
What is slow, what causes it and does the proposed change help?
November 10, 2026
Define the slow operation precisely
Use this chapter when a customer journey, author task, query or background operation is too slow or unreliable. State the operation, expected result, affected population and measurable symptom. A page load, editor interaction, content query and external API call need different evidence even when users describe them all as slow AEM.
Business owners set the performance requirement for the task and deadline. Engineers capture a reproducible baseline with the deployment, content fixture, identity, route, device/network conditions and workload. Observe more than a single successful request. Distinguish steady behavior, cold/warm caches, errors and relevant concurrency rather than hide them in one average.
Separate frontend work, media payloads, remote dependencies, repository queries, background queues and resource pressure. Trace the slow interval before choosing a remedy. A different image size cannot repair a slow external service; a new index cannot correct a browser script loop.
Inspect queries in their content context
Capture the query, bound parameters, relevant result count, content structure and selected execution plan using the target platform's supported tools. Check whether the application needs a query or can retrieve known content directly. Adobe's query and indexing practices discuss alternatives and query cost; a query in every rendered component deserves explicit review.
For Cloud Service, use the managed indexing process and supported project/package structure. For 6.5/LTS, follow the applicable version's index and operational guidance. Do not generalize a local packaging repair from the index deployment discussion.
The localized full-text discussion exposes conflicting index suggestions and an author-reported support recommendation about index selection. It provides neither a representative cloud performance result nor a universal per-language design. Check the chosen index, scope, query plan and impact on existing functionality before deploying a candidate.
Test a proposed improvement
Keep the workload and content fixture constant while comparing the change. Record response behavior, errors, resource symptoms and customer/author outcomes. If a change improves one query but degrades author search, it has introduced an unacceptable trade-off unless the owner explicitly accepts it.
Use representative payloads and dependencies for capacity trials. Vary concurrency or data volume deliberately and document the tested range. Community anecdotes about imports or image savings are useful questions to investigate, not capacity guarantees. Define how queue backlog and recovery behave after a downstream slowdown, not only under normal operation.
The 6.5.21 traversal exception case reinforces this approach: the author later attributed deletion failure to an extension version and reported a local rollback result. Increasing traversal limits would not have established the extension's compatibility. Test the actual task and dependency matrix before changing protective limits or prescribing a general downgrade.
Select a remedy from the failing operation
Community discussions describe different reported outcomes for extension compatibility and local index packaging. Neither establishes that increasing a query limit or changing a package type will repair an arbitrary performance problem. Record the actual operation, platform and dependencies before selecting a remedy.
Scroll horizontally if needed.
| Observed behavior | First evidence | Candidate workstream |
|---|---|---|
| Slow visual completion with fast content response | Frontend/media/network timing and actual page fixture | Client libraries, rendering and media |
| Slow server response correlated with a query | Query, parameters, plan, data volume and repeat conditions | Retrieval/model/index assessment |
| Slow response correlated with an external service | Service timing, timeout/retry behavior and fallback | Integration contract and resilience |
| Growing background backlog | Input rate, completion rate, failures and retries | Work allocation, bounded processing and downstream behavior |
| Regression after a dependency upgrade | Same task on relevant versions and configuration | Compatibility/regression investigation |
| Local success but target failure | Package/tool/platform evidence | Deployment compatibility before tuning |
Define observation conditions before measurement: fixture revision, identity, device/network where relevant, cache state, background work and workload. Retain distributions or individual observations appropriate to the requirement; a single average can conceal failures that block a customer task.
Worked scenario of a slow product listing
The following workload, timings and results are hypothetical. A product listing becomes slow after content growth. The business owner requires acceptable completion for normal visitors and a usable editor. Engineers suspect a query and propose a new index immediately.
The team first records a representative query and its plan, expected result ordering, content fixture and actual delivered page. It tests the same conditions with the current implementation and proposed change. It also checks whether known-path retrieval or precomputed content would meet the need without repeating a query on every render, consistent with query guidance.
Scroll horizontally if needed.
| Proposed approach | What it may address | Additional obligation |
|---|---|---|
| Correct inefficient retrieval | Avoid unnecessary repeated work | Prove equivalent content/order and update behavior |
| Adjust an appropriate supported index | Improve the demonstrated query plan | Platform-compliant deployment and other-query regression tests |
| Cache/precompute suitable results | Reduce repeated computation | Defined freshness, invalidation and missing-result behavior |
| Change media/frontend behavior | Improve the displayed experience | Preserve quality/accessibility and measure the customer task |
| Increase capacity | Address a demonstrated capacity constraint | Evidence that the bottleneck and operating cost justify it |
Suppose the repeatable comparison finds:
Scroll horizontally if needed.
| Check | Illustrative result | Decision |
|---|---|---|
| Listing response | Improves under the representative workload | Keep investigating the candidate |
| Required ordering | Some tied items change position between pages | Repair correctness before accepting speed |
| Author search | Slower after the candidate index change | Investigate overlap/selection and hold deployment |
| Content update | Precomputed result remains stale beyond the requirement | Freshness contract fails |
| Error rate during downstream failure | Increases despite faster normal responses | Include degraded conditions in the decision |
The team holds the candidate until it satisfies correctness, authoring and failure requirements. It does not accept an index solely because the target query is faster. If one narrower retrieval change works without those regressions, compare that option on the same fixture.
Make query evidence actionable
Capture the query language/shape, actual bound values after removing sensitive data, expected result scope, selected index/plan and observed time under stated conditions. Include relevant content structure and concurrent work. A screenshot saying slow query without those conditions is difficult for another engineer to reproduce.
For Cloud Service, validate the definition and deployment against managed indexing. For 6.5/LTS, use the applicable procedures and operational authority. Local index selection is useful evidence but does not establish managed-cloud behavior. A successful deployment also does not establish relevance, correctness or overall performance.
Estimate capacity from a measured range
Use the workload tested, not a community volume anecdote, to describe what the evidence covers. Record input/output rates, failure conditions, queue recovery and resource behavior for the selected range. Identify when a production change would invalidate that conclusion: more content, different query patterns, another consumer or changed media/dependencies.
Business owners accept the task outcome and limitations. Engineers explain the causal evidence and regression set. Operations owners accept the observability and recovery requirements. Review the measured baseline after material changes instead of retaining a permanent performance-pass label.
Accept a measured result
Complete W12 with baseline, workload, diagnosis, proposed change, repeatable comparison and regression results. Attach query plans/log references where relevant. The business owner judges task usefulness; the platform owner accepts resource and reliability consequences; practitioners retain the method. Schedule another measurement when content, traffic, components or connected services change enough to invalidate the baseline.
W12 Performance comparison
Use with chapter 12. Keep the fixture and measurement method stable for the comparison.
Scroll horizontally if needed.
| Record | Entry |
|---|---|
| Failing task, affected users and required result | [enter] |
| Route, content/data fixture, workload and network/device conditions | [enter] |
| Baseline timings/errors/resource symptoms and observation method | [enter] |
| Query/parameters/plan or other layer-specific diagnostic evidence | [enter] |
| Proposed change and repeatable before/after comparison | [enter] |
| Regressions, tested range, accepted trade-off and retest trigger | [enter] |
