gabrielmoreira AEM Debugging & Log Analysis
Purpose
Systematically diagnose and resolve AEM issues using log analysis, debugging tools, error pattern recognition, and structured troubleshooting methodologies.
When to Use (Triggers)
- User mentions "debug," "error," "exception," "log analysis," or "troubleshoot"
- References to error.log, request.log, stack traces, or AEM error pages
- Questions about diagnosing specific exceptions, null pointers, or bundle issues
- Requests involving log configuration, log aggregation, or error patterns
- Discussion of AEM health problems, startup failures, or runtime errors
Core Capabilities
- Analyze AEM log files (error.log, request.log, access.log) for issue diagnosis
- Configure logging levels and custom loggers for targeted debugging
- Interpret common AEM exception patterns and their root causes
- Use debugging tools (remote debug, CRXDE Lite, OSGi console)
- Implement structured troubleshooting for complex multi-component issues
Domain Knowledge Required
Technical Foundation
- Log4j/SLF4J logging framework configuration and MDC context
- Java exception hierarchy and stack trace interpretation
- Remote debugging with JDWP (Java Debug Wire Protocol)
- Log aggregation patterns (ELK stack, Splunk, Azure Monitor)
AEM-Specific Context
- AEM log file locations and their purposes (error.log, request.log, stdout.log)
- Sling Log Support configuration via OSGi
- Common AEM exceptions and their meanings (ResourceNotFoundException, LoginException, etc.)
- OSGi bundle lifecycle states and troubleshooting (Installed, Resolved, Active)
- AEM Developer Tools (browser extension, CRXDE, System Console)
Implementation Approach
Step 1: Issue Classification
Categorize the problem for targeted investigation.
- Determine error type: startup failure, runtime exception, performance, data corruption
- Identify affected layer: OSGi, Sling, JCR, AEM application, dispatcher
- Check if issue is intermittent or consistent
- Establish timeline: when did the issue start, what changed
Step 2: Log Collection
Gather relevant log data for analysis.
- Collect error.log entries around issue timestamp
- Review request.log for associated HTTP requests and timing
- Check stdout.log for JVM-level issues (GC, OOM, native errors)
- Examine bundle startup logs for dependency resolution failures
Step 3: Log Analysis
Interpret log entries to identify root cause.
- Parse stack traces for originating code and nested exceptions
- Identify error patterns (frequency, correlation with user actions)
- Trace request flow through log correlation (request ID, session)
- Check for resource exhaustion (threads, connections, memory)
Step 4: Active Debugging
Use debugging tools for real-time investigation.
- Attach remote debugger to AEM JVM (port 5005 by default)
- Use CRXDE Lite for content inspection and quick fixes
- Check OSGi console for bundle states and service availability
- Inspect Sling Resource Resolution via Sling console
Step 5: Resolution & Prevention
Fix the issue and prevent recurrence.
- Implement fix based on identified root cause
- Add targeted logging for future diagnosis of similar issues
- Create monitoring/alerting for the failure condition
- Document the issue pattern and resolution for knowledge base
Quality Checklist
- Root cause identified with evidence (not just symptom addressed)
- Log entries clearly point to the issue origin
- Custom loggers configured for affected code paths
- Fix validated in test environment before production
- Monitoring added to detect recurrence
- Knowledge base updated with issue pattern
- Log levels restored to production-appropriate settings after debugging
- No sensitive data exposed in log output
Related Skills
- aem-monitoring-alerting (proactive issue detection)
- aem-performance-tuning-profiling (performance-related debugging)
- aem-custom-osgi-services (service-level debugging)
Example Use Cases
- Bundle Resolution Failure: Diagnose an OSGi bundle stuck in "Installed" state by analyzing dependency resolution errors, identifying missing imports, and resolving version conflicts in Maven dependencies.
- Intermittent 500 Errors: Track down sporadic Internal Server Errors on publish using request.log correlation, error.log stack traces, and thread dump analysis revealing connection pool exhaustion.
- Post-Deployment Regression: Investigate functionality broken after deployment by comparing bundle versions, analyzing Sling Model registration errors, and identifying service ranking conflicts.
Notes
- Remote debugging on production is extremely risky — it pauses JVM threads. Use only as last resort.
- AEM Cloud Service logs are accessed via Cloud Manager or Adobe Experience League tools
- Configure custom loggers per package (not per class) to balance detail vs. log volume
- Request.log TIMER entries are AEM's built-in profiler — learn to read them