CLAUDE.md

1# CLAUDE.md - DotCMS JMeter Performance Testing
2 
3This file provides AI-specific guidance for Claude Code when working with the DotCMS performance testing infrastructure in the `test-jmeter` module.
4 
5**📖 Primary Documentation**: See [README.md](README.md) for comprehensive user documentation, command reference, and configuration details.
6 
7## AI Assistant Quick Reference
8 
9### Module Purpose
10Dual-purpose performance testing infrastructure:
111. **Traditional JMeter Tests**: Maven-based tests for core dotCMS functionality  
122. **Analytics Performance Testing**: Advanced Kubernetes/Helm-based analytics testing
13 
14### Key Architecture Points
15- **Unified Entry Point**: `./dotcms-analytics-test.sh` (1,394 lines) 
16- **Helm-based Deployment**: Production-ready Kubernetes infrastructure
17- **Built-in Analysis**: Comprehensive performance reporting and bottleneck detection
18- **No Infrastructure Knowledge Required**: Abstracts Kubernetes/Helm complexity
19 
20## Key Components
21 
22### Primary Script
23- **`dotcms-analytics-test.sh`** - Main entry point (1162+ lines)
24  - Replaces multiple legacy scripts
25  - Handles setup, testing, analysis, and cleanup
26  - No Kubernetes/Helm knowledge required for developers
27 
28### Infrastructure
29- **`helm-chart/jmeter-performance/`** - Kubernetes deployment configuration
30- **`jmx-tests/`** - JMeter test plans for different endpoints
31 
32### Test Plans (JMX Files)
33**Analytics Tests:**
34- **`analytics-direct-cluster-test.jmx`** - Tests analytics platform directly
35- **`analytics-api-cluster-test.jmx`** - Tests DotCMS API analytics endpoints
36- **`analytics-events.jmx`** - General analytics events testing
37 
38**Traditional dotCMS Tests:**
39- **`core-sessions.jmx`** - Core dotCMS functionality and session testing
40 
41## Essential Commands Reference
42 
43**📖 Complete Command Reference**: See [README.md](README.md#all-available-commands) for full command documentation.
44 
45### Quick Command Examples
46```bash
47# Analytics Testing (NEW)
48./dotcms-analytics-test.sh setup           # One-time setup
49./dotcms-analytics-test.sh quick-test      # Baseline test
50./dotcms-analytics-test.sh compare-endpoints  # KEY: Find bottlenecks
51 
52# Traditional dotCMS Testing  
53./mvnw install -Djmeter.test.skip=false -pl :dotcms-test-jmeter
54just run-jmeter-tests
55```
56 
57## Performance Concepts Summary
58 
59**📊 Detailed Testing Strategy**: See [README.md](README.md#performance-testing-strategy) for comprehensive performance concepts.
60 
61### Key Performance Finding
62**Critical Discovery**: DotCMS API layer adds ~30x response time overhead vs direct analytics
63- Direct Analytics: ~3ms response time, ~300 EPS
64- DotCMS API: ~85ms response time, ~270 EPS  
65- **Recommendation**: Use direct analytics for high-volume scenarios
66 
67### Load Testing Levels
68- **Baseline**: 100-200 EPS → **Standard**: 200-400 EPS → **High**: 400-800 EPS → **Stress**: 800+ EPS
69 
70## File Structure and Organization
71 
72### Scripts (Consolidated)
73- ✅ **`dotcms-analytics-test.sh`** - Main unified script
74- ❌ **`analyze-results.py`** - REMOVED (functionality moved to main script)
75- ❌ **Legacy scaling scripts** - REMOVED (consolidated into main script)
76 
77### Configuration Files
78- **`helm-chart/jmeter-performance/values.yaml`** - Default Helm values
79 
80### Test Results
81- **`test-results/`** - Directory for JMeter output files (.jtl, .csv)
82- **Generated reports** - Markdown files with analysis and recommendations
83 
84## AI Assistant Guidelines
85 
86### When Working with Performance Tests
871. **Always use the unified script** - Don't suggest individual JMeter commands
882. **Start with simple tests** - `quick-test` before complex scenarios
893. **Focus on bottleneck identification** - This is the primary use case
904. **Include analysis step** - Always run `analyze` after tests
91 
92### Authentication Quick Reference
93 
94**DotCMS API Token (JWT)**: 
95- **Purpose**: Authenticates requests to DotCMS API endpoints
96- **Format**: `eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...`
97- **Source**: DotCMS Admin → User Tools → API Tokens OR /api/v1/authentication
98- **Environment**: `DOTCMS_JWT_TOKEN`
99 
100**Analytics Key**:
101- **Purpose**: Identifies analytics tracking in analytics platform  
102- **Format**: `js.cluster1.customer1.vgwy3nli4co84u531c`
103- **Source**: DotCMS → Apps → Analytics → Configuration → Analytics Key
104- **Environment**: `DOTCMS_ANALYTICS_KEY`
105 
106### Common Developer Questions
107 
108**Authentication:**
109- **"Where do I get the JWT token?"** → DotCMS Admin → User Tools → API Tokens
110- **"Where do I find the Analytics Key?"** → DotCMS → Apps → Analytics → Configuration
111- **"Token expired?"** → Run `./dotcms-analytics-test.sh refresh-tokens`
112 
113**Analytics Performance:**
114- **"How do I test analytics performance?"** → Start with `./dotcms-analytics-test.sh quick-test`
115- **"Why is the API slow?"** → Run `./dotcms-analytics-test.sh compare-endpoints`
116- **"What's our maximum capacity?"** → Use `./dotcms-analytics-test.sh find-maximum-rate`
117- **"How do I interpret results?"** → Use `./dotcms-analytics-test.sh analyze`
118 
119**Traditional dotCMS Performance:**
120- **"How do I test general dotCMS performance?"** → Use `./mvnw install -Djmeter.test.skip=false -pl :dotcms-test-jmeter`
121- **"How do I modify test scenarios?"** → Open with `../mvnw jmeter:configure jmeter:gui -DguiTestFile=jmx-tests/core-sessions.jmx`
122- **"How do I test against my instance?"** → Use `-Djmeter.host=myhost -Djmeter.port=443`
123- **"Where are the test results?"** → Check `target/jmeter/reports/` and `target/jmeter/results/`
124 
125### Troubleshooting Common Issues
1261. **Pod not starting**: Check Kubernetes resources and namespace permissions
1272. **Authentication failures**: Verify analytics key and JWT token validity
1283. **High response times**: Likely infrastructure or code bottlenecks
1294. **Connection errors**: Network connectivity or firewall issues
130 
131### Code Modification Guidelines
132- **JMX files**: Apache JMeter XML format for test plans
133- **Helm templates**: Kubernetes YAML with Go templating
134- **Shell scripts**: Bash with set -e (fail on error)
135- **Configuration**: Helm values.yaml structure
136 
137## Performance Expectations
138 
139### Baseline Performance (from testing)
140- **Direct Analytics**: ~300 EPS at 3ms average response time
141- **DotCMS API**: ~270 EPS at 85ms average response time
142- **Error Rate**: <1% for normal loads
143- **Maximum Tested**: Up to 2000 EPS (endpoint dependent)
144 
145### Production Recommendations
146- **Use direct analytics** for high-volume scenarios
147- **Monitor DotCMS API** for >100ms response times
148- **Set capacity planning** at 70-80% of tested maximum
149- **Implement caching** for DotCMS API layer optimization
150 
151## Related Documentation
152 
153- **Main README**: Developer-focused quick start guide
154- **Helm Chart README**: Detailed Kubernetes deployment guide
155 
156This module provides **dual testing approaches**:
1571. **Traditional Maven-based tests** for core dotCMS functionality with simple execution
1582. **Advanced analytics testing** with minimal infrastructure knowledge required but comprehensive performance insights
159 
160Both approaches are designed to be **developer-friendly** while providing different levels of performance analysis for various dotCMS scenarios.