perf-skills 1.0.0

package/perf-skills/references/tools/gatling.md

@@ -0,0 +1,286 @@
+# Gatling Reference
+
+> Targets: Gatling 3.10+, Java DSL 3.7+
+
+Gatling is a high-performance, Scala/Java-based load testing tool designed for HTTP-heavy applications. Its simulation DSL is expressive, and its async Netty-based engine handles very high concurrency with low resource overhead.
+
+---
+
+## Core Concepts
+
+| Concept | Description |
+|---|---|
+| **Simulation** | Top-level test class extending `Simulation` |
+| **Protocol** | HTTP, JMS, or gRPC configuration |
+| **Scenario** | Named sequence of actions (chain of steps) |
+| **Feeder** | Data source for parameterization (CSV, JSON, JDBC) |
+| **Check** | Assertion on a response (status, body, header) |
+| **Population** | VU injection strategy (open/closed model) |
+| **Session** | VU-level state store (like JMeter `vars`) |
+
+---
+
+## Simulation Structure
+
+```scala
+import io.gatling.core.Predef._
+import io.gatling.http.Predef._
+import scala.concurrent.duration._
+
+class CheckoutSimulation extends Simulation {
+
+  // 1. Protocol config
+  val httpProtocol = http
+    .baseUrl("https://api.example.com")
+    .acceptHeader("application/json")
+    .contentTypeHeader("application/json")
+    .shareConnections  // Reuse connections across VUs (more realistic)
+
+  // 2. Feeders (data)
+  val userFeeder = csv("data/users.csv").circular
+
+  // 3. Scenario (chain of steps)
+  val loginScenario = scenario("Login and Browse")
+    .feed(userFeeder)
+    .exec(
+      http("POST Login")
+        .post("/auth/login")
+        .body(StringBody("""{"username":"#{username}","password":"#{password}"}""")).asJson
+        .check(status.is(200))
+        .check(jsonPath("$.token").saveAs("authToken"))
+    )
+    .pause(1, 3)  // Think time: 1–3 seconds
+    .exec(
+      http("GET Products")
+        .get("/products")
+        .header("Authorization", "Bearer #{authToken}")
+        .check(status.is(200))
+        .check(jsonPath("$[0].id").saveAs("productId"))
+    )
+    .pause(2)
+
+  // 4. Injection (load profile)
+  setUp(
+    loginScenario.inject(
+      nothingFor(5.seconds),         // Wait before starting
+      atOnceUsers(5),                // Smoke check
+      rampUsers(100).during(2.minutes),
+      constantUsersPerSec(20).during(5.minutes),
+      rampUsersPerSec(20).to(0).during(1.minute)
+    ).protocols(httpProtocol)
+  ).assertions(
+    global.responseTime.percentile(95).lt(500),
+    global.failedRequests.percent.lt(1)
+  )
+}
+```
+
+---
+
+## Injection Profiles
+
+### Closed model (VU-based)
+```scala
+rampUsers(100).during(2.minutes)        // Ramp to 100 VUs over 2 min
+constantConcurrentUsers(100).during(5.minutes)  // Hold at 100 VUs
+```
+
+### Open model (arrival-rate)
+```scala
+constantUsersPerSec(50).during(5.minutes)           // 50 new users/sec
+rampUsersPerSec(10).to(100).during(3.minutes)       // Ramp RPS from 10 to 100
+heavisideUsers(1000).during(20.seconds)             // S-curve injection (realistic burst)
+```
+
+> For closed vs open model guidance and when to use each, see `references/topics/workload-design.md`.
+
+---
+
+## Feeders (Parameterization)
+
+```scala
+// CSV
+val csvFeeder = csv("data/users.csv").circular      // Loop forever
+val csvFeeder = csv("data/users.csv").random        // Pick random row
+val csvFeeder = csv("data/users.csv").shuffle       // Randomize order, no repeat
+val csvFeeder = csv("data/users.csv").queue         // Each VU gets next row; fail if empty
+
+// JSON
+val jsonFeeder = jsonFile("data/products.json").random
+
+// Custom feeder
+val customFeeder = Iterator.continually(Map(
+  "timestamp" -> System.currentTimeMillis(),
+  "uuid"      -> java.util.UUID.randomUUID().toString
+))
+
+// Use in scenario
+scenario("test").feed(csvFeeder).exec(...)
+```
+
+---
+
+## Checks (Assertions)
+
+```scala
+// Status code
+.check(status.is(200))
+.check(status.in(200, 201))
+
+// JSON body
+.check(jsonPath("$.userId").exists)
+.check(jsonPath("$.token").saveAs("token"))
+.check(jsonPath("$.items.length()").is("5"))
+
+// Header
+.check(header("X-Request-Id").exists)
+
+// Response time
+.check(responseTimeInMillis.lte(2000))
+
+// Body string
+.check(bodyString.contains("success"))
+.check(substring("access_granted").count.is(1))
+
+// Multiple checks (all must pass)
+.check(status.is(200), jsonPath("$.status").is("ok"))
+```
+
+---
+
+## Session Variables
+
+```scala
+// Save during check
+.check(jsonPath("$.orderId").saveAs("orderId"))
+
+// Access in body
+.body(StringBody("""{"orderId":"#{orderId}"}"""))
+
+// Access in Exec block
+.exec(session => {
+  val orderId = session("orderId").as[String]
+  println(s"Processing order: $orderId")
+  session
+})
+
+// Conditional logic
+.doIf(session => session("isAdmin").as[Boolean]) {
+  exec(http("Admin Action").get("/admin"))
+}
+```
+
+---
+
+## Assertions (Global SLA)
+
+```scala
+setUp(...).assertions(
+  global.responseTime.percentile(95).lt(500),     // p95 < 500ms
+  global.responseTime.max.lt(2000),               // max < 2s
+  global.failedRequests.percent.lt(1),            // Error rate < 1%
+  global.requestsPerSec.gte(100),                 // Throughput >= 100 RPS
+  forAll.failedRequests.count.is(0),              // No failures on any request
+  details("POST Login").responseTime.percentile(99).lt(1000)  // Named request SLA
+)
+```
+
+---
+
+## Protocol Configuration
+
+### HTTP
+```scala
+val httpProtocol = http
+  .baseUrl("https://api.example.com")
+  .proxy(Proxy("proxy.corp.net", 8080))
+  .acceptHeader("application/json")
+  .acceptEncodingHeader("gzip, deflate")
+  .userAgentHeader("Gatling/Perf-Test")
+  .maxConnectionsPerHost(10)
+  .warmUp("https://api.example.com/health")
+  .disableFollowRedirect           // Disable for accuracy
+  .disableAutoReferer
+```
+
+### WebSocket
+```scala
+import io.gatling.http.Predef._
+
+exec(
+  ws("Connect WS").connect("/ws/chat")
+    .await(5.seconds)(
+      ws.checkTextMessage("message received")
+        .matching(jsonPath("$.type").is("ack"))
+    )
+)
+.exec(ws("Send Message").sendText("""{"msg":"hello"}"""))
+.exec(ws("Close").close())
+```
+
+---
+
+## Running Gatling
+
+```bash
+# Maven (Scala DSL)
+mvn gatling:test -Dgatling.simulationClass=CheckoutSimulation
+
+# Gradle (Java DSL)
+./gradlew gatlingRun
+
+# Bundle (no build tool)
+./bin/gatling.sh -s CheckoutSimulation -rd "Staging load test"
+
+# With overrides
+mvn gatling:test \
+  -Dgatling.simulationClass=CheckoutSimulation \
+  -DbaseUrl=https://staging.example.com \
+  -Dusers=100 \
+  -Dduration=300
+```
+
+---
+
+## Java DSL (Gatling 3.7+)
+
+Gatling now supports Java and Kotlin natively — no Scala required:
+
+```java
+import io.gatling.javaapi.core.*;
+import io.gatling.javaapi.http.*;
+import static io.gatling.javaapi.core.CoreDsl.*;
+import static io.gatling.javaapi.http.HttpDsl.*;
+
+public class LoginSimulation extends Simulation {
+  HttpProtocolBuilder httpProtocol = http.baseUrl("https://api.example.com");
+
+  ScenarioBuilder scenario = scenario("Login")
+    .exec(
+      http("POST Login")
+        .post("/auth/login")
+        .body(StringBody("{\"user\":\"test\"}")).asJson()
+        .check(status().is(200))
+    );
+
+  { setUp(scenario.injectOpen(rampUsers(100).during(60))).protocols(httpProtocol); }
+}
+```
+
+---
+
+## Results
+
+Gatling generates an HTML report in `target/gatling/<simulation-timestamp>/index.html` — commit the link to CI artifacts or use Gatling Enterprise for centralized dashboards.
+
+---
+
+## Gatling-Specific Tips
+
+- **Never use blocking/synchronous calls inside `exec`** — Gatling's engine is async; blocking calls degrade throughput significantly.
+- **Use `.warmUp()` or an initial ramp phase** — JVM JIT compilation distorts early metrics without warm-up.
+- **Use `global` or named `details()` assertions** — asserting on individual requests instead of aggregated transactions is noisy.
+- **Prefer `heavisideUsers` for burst injection** — S-curve injection is more realistic than `atOnceUsers` for spike tests.
+
+> For CI/CD integration (Maven, Gradle, GitHub Actions), see `references/topics/test-execution.md`.
+> For anti-patterns, assertions, think time, and parameterization principles, see **Key Principles** in `SKILL.md`.

package/perf-skills/references/tools/jmeter.md

@@ -0,0 +1,251 @@
+# JMeter Reference
+
+> Targets: JMeter 5.6+, Plugins Manager 1.10+
+
+Apache JMeter is the most widely used open-source performance testing tool. It supports a broad range of protocols and is extended through a rich plugin ecosystem.
+
+---
+
+## Core Concepts
+
+| Concept | Description |
+|---|---|
+| **Test Plan** | Root container — the `.jmx` file |
+| **Thread Group** | Defines VU count, ramp-up, and loop count |
+| **Sampler** | Makes a request (HTTP, JDBC, JMS, TCP, etc.) |
+| **Controller** | Logic: Loop, If, While, Throughput |
+| **Config Element** | HTTP Defaults, CSV Data Set, Cache Manager |
+| **Pre/Post Processor** | Run before/after a sampler (BeanShell, JSR223) |
+| **Assertion** | Validates the response (Response Code, Duration, JSON) |
+| **Listener** | Collects and displays results (View Results Tree, Summary) |
+| **Timer** | Adds think time (Constant, Gaussian, Synchronizing) |
+
+---
+
+## Thread Group Configuration Patterns
+
+### Standard load ramp
+```
+Thread Group:
+  Number of Threads (users): 100
+  Ramp-Up Period (seconds):   120   ← 1 VU every 1.2s, avoids thundering herd
+  Loop Count:                 -1    ← run forever until duration
+  Duration:                   600   ← 10 minutes
+  Startup Delay:              0
+```
+
+### Stepping Thread Group (requires JMeter Plugins)
+Use `jp@gc - Stepping Thread Group` for staged load:
+- Start 10 VUs, hold 60s → add 10 every 30s → max 100 VUs → hold 300s → ramp down
+
+### Concurrency Thread Group (preferred for modern tests)
+Use `jp@gc - Concurrency Thread Group` for target-concurrency model:
+- Maintains a target concurrency level dynamically, compensates for slow VUs
+
+---
+
+## HTTP Sampler Best Practices
+
+- Always use **HTTP Request Defaults** config element for base URL/port/protocol — never hardcode in individual samplers.
+- Set **Content-Type** header in an HTTP Header Manager at Thread Group level, not per sampler.
+- Use **KeepAlive** (default on) for realistic connection reuse.
+- Use **Follow Redirects** only when your app requires it; disable otherwise for accuracy.
+- Avoid using **View Results Tree** listener in load tests — it's memory-intensive; use it only during script development.
+
+---
+
+## Correlation: Extracting Dynamic Values
+
+Correlation is the #1 cause of script failures in session-heavy apps.
+
+### Regular Expression Extractor
+```
+Reference Name:    csrf_token
+Regular Expression: name="_token" value="(.+?)"
+Template:          $1$
+Match No.:         1
+Default Value:     NOT_FOUND
+```
+
+### JSON Extractor (REST APIs)
+```
+Reference Name:    access_token
+JSON Path:         $.data.token
+Match No.:         1
+Default Value:     NOT_FOUND
+```
+
+### Boundary Extractor (fastest, no regex overhead)
+```
+Reference Name:    session_id
+Left Boundary:     "sessionId":"
+Right Boundary:    "
+```
+
+### Using Extracted Values
+Reference with `${variable_name}` in subsequent requests.
+
+Always add an assertion on the extracted value:
+```
+Response Assertion → Variable: ${csrf_token} → Pattern: NOT_FOUND → Negate
+```
+
+---
+
+## CSV Data Set Config
+
+```
+Filename:           ${__P(data.dir,./data)}/users.csv
+Variable Names:     username,password,account_id
+Delimiter:          ,
+Allow Quoted Data:  true
+Recycle on EOF:     true
+Stop Thread on EOF: false
+Sharing Mode:       All Threads  ← or "Current Thread Group" if isolated data needed
+```
+
+**Tips:**
+- Use `${__P(data.dir,...)}` property for portable paths across environments.
+- For high VU counts, ensure the CSV has at least as many rows as peak VU count to avoid data collisions.
+- In distributed tests, the CSV file must exist on **each injector node**, not just the controller.
+
+---
+
+## JSR223 Scripting (Groovy)
+
+Always use **JSR223** over BeanShell — Groovy is compiled and cached, BeanShell is not.
+
+### Pre-processor: Generate a dynamic timestamp
+```groovy
+import java.time.Instant
+vars.put("timestamp", Instant.now().toEpochMilli().toString())
+```
+
+### Post-processor: Parse JSON response
+```groovy
+import groovy.json.JsonSlurper
+def json = new JsonSlurper().parseText(prev.getResponseDataAsString())
+vars.put("userId", json.data.id.toString())
+```
+
+### Pre-processor: Compute HMAC signature
+```groovy
+import javax.crypto.Mac
+import javax.crypto.spec.SecretKeySpec
+def key   = vars.get("api_secret")
+def data  = vars.get("request_body")
+def mac   = Mac.getInstance("HmacSHA256")
+mac.init(new SecretKeySpec(key.bytes, "HmacSHA256"))
+vars.put("signature", mac.doFinal(data.bytes).encodeHex().toString())
+```
+
+---
+
+## Assertions
+
+### Response Code Assertion
+```
+Field to Test:  Response Code
+Pattern:        200
+```
+
+### JSON Assertion
+```
+JSON Path:      $.status
+Expected Value: success
+```
+
+### Duration Assertion
+```
+Duration to assert: 2000   ← flag any response > 2000ms
+```
+
+### Response Size Assertion
+Use to detect incomplete responses — flag if body < 100 bytes unexpectedly.
+
+**Important:** Add assertions to the **transaction controller level** where possible, not individual samplers, to get meaningful business-transaction-level validation.
+
+---
+
+## Transaction Controllers
+
+Wrap related HTTP samplers in Transaction Controllers to measure end-to-end business transaction time:
+
+```
+Transaction Controller: Login Flow
+  ├── HTTP Sampler: GET /login
+  ├── HTTP Sampler: POST /authenticate
+  └── HTTP Sampler: GET /dashboard
+```
+
+Set **Generate Parent Sample = true** to log only the aggregate transaction (not individual child requests) in results.
+
+---
+
+## Timers (Think Time)
+
+| Timer | Use Case |
+|---|---|
+| Constant Timer | Simple fixed think time |
+| Uniform Random Timer | Range between min–max |
+| Gaussian Random Timer | Bell-curve distribution — most realistic |
+| Throughput Shaping Timer | Target a specific RPS regardless of VU count |
+
+Gaussian formula: `delay = Constant + Gaussian(deviation)`
+Realistic web-app think time: Gaussian with constant=3000ms, deviation=1500ms.
+
+---
+
+## Running JMeter Non-GUI (Command Line)
+
+> For distributed testing architecture and setup, see `references/topics/test-execution.md`.
+
+Always run load tests in non-GUI mode:
+```bash
+jmeter -n \
+  -t test.jmx \
+  -l results/results.jtl \
+  -e -o results/dashboard \
+  -Jenv=staging \
+  -Jthreads=100 \
+  -Jduration=600
+```
+
+| Flag | Purpose |
+|---|---|
+| `-n` | Non-GUI mode |
+| `-t` | Test plan path |
+| `-l` | JTL results file |
+| `-e -o` | Generate HTML dashboard after run |
+| `-J` | Set JMeter property (use `${__P(env,dev)}` in plan) |
+| `-G` | Set global property (available to remote engines) |
+
+---
+
+## Key Plugins (JMeter Plugins Manager)
+
+| Plugin | Purpose |
+|---|---|
+| `Concurrency Thread Group` | Maintain target concurrency |
+| `Stepping Thread Group` | Step-ramp load profile |
+| `Throughput Shaping Timer` | Control RPS exactly |
+| `PerfMon` | Collect server-side CPU/memory via agent |
+| `3 Basic Graphs` | Lightweight real-time charting |
+| `JDBC Connection Configuration` | Database load testing |
+| `WebSocket Sampler` | WS protocol support |
+| `gRPC Sampler` | gRPC protocol support |
+
+Install plugins via: **Options → Plugins Manager → Available Plugins**
+
+---
+
+## JMeter-Specific Tips
+
+- **Always run in non-GUI mode** for load tests — GUI mode consumes JMeter's own resources and distorts results.
+- **Use HTTP Request Defaults** — hardcoded hosts make environment switching painful.
+- **Never put listeners inside loops** — View Results Tree in a loop will OOM the JVM.
+- **Use JSR223 (Groovy) over BeanShell** — Groovy is compiled and cached; BeanShell is interpreted per invocation.
+- **Set JVM heap** for large tests: `JVM_ARGS="-Xms2g -Xmx4g" jmeter -n -t test.jmx`
+
+> For CI/CD integration (Maven, GitHub Actions, GitLab, Jenkins), see `references/topics/test-execution.md`.
+> For anti-patterns, assertions, think time, and parameterization principles, see **Key Principles** in `SKILL.md`.