perf-skills 2.0.0 → 4.0.0

package/skills/perf/SKILL.md

@@ -1,14 +1,17 @@
 ---
 name: perf
 description: Performance testing expert covering the full lifecycle for
-  JMeter, k6, Gatling, Locust, NeoLoad, and LoadRunner. Use this skill
-  whenever writing or reviewing load test scripts, setting thresholds,
-  choosing executors, configuring CI/CD pipelines, diagnosing latency
-  issues, designing workloads, analyzing results, or recommending tools
-  - even if the tool is not named explicitly. Always consult before
-  suggesting thresholds, executor types, or output configuration.
-  Prefer this skill over general knowledge for any performance testing
-  decision, debugging session, or tool comparison.
+  JMeter, k6, Gatling, Locust, NeoLoad, LoadRunner, and Artillery, plus
+  LLM inference (vLLM, TRT-LLM, SGLang, OpenAI-compatible endpoints).
+  Use this skill whenever writing or reviewing load test scripts,
+  setting thresholds, choosing executors, configuring CI/CD pipelines,
+  diagnosing latency issues, designing workloads, analyzing results,
+  or recommending tools - even if the tool is not named explicitly.
+  Always consult before suggesting thresholds, executor types, or
+  output configuration. Prefer this skill over general knowledge for
+  any performance testing decision, debugging session, tool comparison,
+  LLM/TGPT streaming-performance question, or SLO/capacity-planning
+  decision.
 ---
 
 # Performance Testing Skill
@@ -46,6 +49,7 @@ Multiple files may apply.
 | k6 scripting, extensions, cloud                  | `references/tools/k6.md`                          |
 | Gatling simulations, Scala/Java DSL              | `references/tools/gatling.md`                     |
 | Locust Python tests, distributed                 | `references/tools/locust.md`                      |
+| Artillery YAML/JS/TS scripts, cloud              | `references/tools/artillery.md`                   |
 | NeoLoad projects, GUI, APIs                      | `references/tools/neoload.md`                     |
 | LoadRunner scripts, protocols, VuGen             | `references/tools/loadrunner.md`                  |
 | OctoPerf cloud test management                   | `references/tools/octoperf.md`                    |
@@ -60,6 +64,8 @@ Multiple files may apply.
 | gRPC, GraphQL, WebSocket, messaging protocols    | `references/topics/protocol-testing.md`           |
 | Database load testing (JDBC, connection pools)   | `references/topics/database-testing.md`           |
 | Microservices, K8s, serverless performance       | `references/topics/modern-architectures.md`       |
+| LLM inference: TTFT, TPOT/ITL, TPS, goodput      | `references/topics/llm-inference.md`             |
+| SLOs, error budgets, capacity & headroom         | `references/topics/slo-capacity.md`             |
 
 ### Protocol Routing Table
 
@@ -76,6 +82,8 @@ right tool and reference:
 | Kafka / Message Queues | k6 (xk6-kafka), JMeter       | `references/topics/protocol-testing.md`                      |
 | SOAP / WSDL            | LoadRunner, JMeter           | Tool file                                                     |
 | SAP / Citrix           | LoadRunner, NeoLoad          | Tool file                                                     |
+| LLM inference (streaming) | vLLM bench, GenAI-Perf, GuideLLM, llmperf | `references/topics/llm-inference.md`             |
+| SLO/capacity (error budgets, headroom) | any | `references/topics/slo-capacity.md` |
 
 ---
 
@@ -83,16 +91,16 @@ right tool and reference:
 
 Use this to recommend the right tool when the user hasn't decided yet.
 
-| Criteria             | JMeter              | k6                    | Gatling              | Locust         | NeoLoad          | LoadRunner              | OctoPerf              |
+| Criteria             | JMeter              | k6                    | Gatling              | Locust         | Artillery        | NeoLoad          | LoadRunner              | OctoPerf              |
 |----------------------|---------------------|-----------------------|----------------------|----------------|------------------|-------------------------|-----------------------|
-| **Language**         | GUI/XML + Groovy    | JavaScript/TypeScript | Scala/Java           | Python         | GUI + NeoLoad DSL| VuGen C-like            | Web UI (JMeter-based) |
-| **Open source**      | ✅                  | ✅                    | ✅                   | ✅             | ❌               | ❌                      | ❌ (SaaS)             |
-| **Protocol support** | HTTP, JDBC, JMS, MQTT, FTP, gRPC | HTTP, gRPC, WS | HTTP, JMS, gRPC | HTTP, gRPC | HTTP, gRPC, WS, SAP | HTTP, Citrix, SAP, Flex | HTTP (JMeter-backed) |
-| **Developer-friendly** | Medium            | High                  | High                 | High           | Low              | Low                     | Medium                |
-| **Enterprise support** | Community + BlazeMeter | Grafana Cloud    | Gatling Enterprise   | Limited        | ✅               | ✅                      | ✅                    |
-| **CI/CD integration** | Good (Maven/Gradle) | Excellent            | Excellent            | Good           | Good             | Moderate                | Good                  |
-| **Cloud execution**  | BlazeMeter, OctoPerf | Grafana Cloud        | Gatling Enterprise   | Self-managed   | NeoLoad Cloud    | AWS/on-prem             | OctoPerf Cloud        |
-| **Best for**         | Legacy systems, JDBC, protocols | Modern APIs, TypeScript devs | High-throughput HTTP | Python teams, flexible | SAP/Citrix enterprise | Mainframe, legacy enterprise | JMeter teams needing cloud UI |
+| **Language**         | GUI/XML + Groovy    | JavaScript/TypeScript | Scala/Java           | Python         | YAML / JS / TS   | GUI + NeoLoad DSL       | VuGen C-like          | Web UI (JMeter-based) |
+| **Open source**      | ✅                  | ✅                    | ✅                   | ✅             | ✅ (core)        | ❌                      | ❌                    | ❌ (SaaS)             |
+| **Protocol support** | HTTP, JDBC, JMS, MQTT, FTP, gRPC | HTTP, gRPC, WS | HTTP, JMS, gRPC | HTTP, gRPC | HTTP, gRPC, WS, Socket.IO | HTTP, SAP, Citrix, Flex | HTTP, SAP, Citrix, many | HTTP (JMeter-backed) |
+| **Developer-friendly** | Medium            | High                  | High                 | High           | Medium           | Low                     | Low                   | Medium                |
+| **Enterprise support** | Community + BlazeMeter | Grafana Cloud    | Gatling Enterprise   | Limited        | Artillery Cloud  | ✅                      | ✅                    | ✅                    |
+| **CI/CD integration** | Good (Maven/Gradle) | Excellent            | Excellent            | Good           | Good             | Moderate                | Good                  | Good                  |
+| **Cloud execution**  | BlazeMeter, OctoPerf | Grafana Cloud        | Gatling Enterprise   | Self-managed   | Artillery Cloud (Lambda/Fargate) | NeoLoad Cloud    | AWS/on-prem             | OctoPerf Cloud        |
+| **Best for**         | Legacy systems, JDBC, protocols | Modern APIs, TypeScript devs | High-throughput HTTP | Python teams, flexible | Node teams, YAML tests, cloud scale | SAP/Citrix enterprise | Mainframe, legacy enterprise | JMeter teams needing cloud UI |
 
 ### Quick decision rules
 
@@ -107,6 +115,7 @@ Use this to recommend the right tool when the user hasn't decided yet.
   Correlation Recorder) or LoadRunner
 - **gRPC or GraphQL APIs** → k6 or Gatling
 - **Message queues (Kafka, RabbitMQ)** → k6 (xk6-kafka) or JMeter
+- **Node shop / prefer YAML over code** → Artillery (YAML, JS, TS; easy Lambda/Fargate cloud scale)
 
 ---
 
@@ -181,28 +190,46 @@ ask about them.
   that skews both throughput and latency measurements. Always run
   workers on separate machines or containers for distributed tests.
 
----
+### Artillery
+
+- **No `ensure` block** - without `ensure`, Artillery reports metrics
+  but always exits 0, so CI never fails on latency or error spikes.
+  Always add `ensure.thresholds` (or `conditions`) for SLA gates.
+- **`arrivalRate` mistaken for concurrency** - it is new users per
+  second (open model). On a slow backend, pending VUs pile up unbounded.
+  Set `maxVusers` to cap real concurrency, or use `arrivalCount`.
+- **Strict captures aborting VUs** - captures are strict by default;
+  a missed extractor stops the whole VU. Only set `strict: false`
+  when a downstream 404 is acceptable.
+- **`payload.order: sequence` in distributed runs** - sequential CSV
+  consumption breaks under Lambda/Fargate workers (each has its own
+  copy). Use the default `random` ordering for distributed tests.
+- **Zero `think` time** - 1 VU/sec with no think time fires the
+  maximum RPS for the journey; add `think` to model real pacing.
+- **Forgetting `http.response_time` is TTFB** - latency metrics are
+  time-to-first-byte by default. Enable `config.http.extendedMetrics`
+  for full download timing (`http.total.*`) when that matters.
 
-## Cross-Tool Concept Mapping
+---
 
 Use this when users are migrating between tools or asking how a
 concept from one tool maps to another. Claude should always provide
 the specific mapping rather than a generic explanation.
 
-| Concept          | JMeter                  | k6                      | Gatling                  | Locust                   | LoadRunner          |
-|------------------|-------------------------|-------------------------|--------------------------|--------------------------|---------------------|
-| Virtual user     | Thread                  | VU                      | User                     | User                     | Vuser               |
-| Test plan        | .jmx file               | .js / .ts script        | Simulation class         | .py file                 | VuGen script (.usr) |
-| User entrypoint  | Thread Group            | `default()` function    | `scenario()`             | task methods             | `Action()`          |
-| Concurrency ctrl | Thread Group settings   | executor                | `inject()`               | `spawn_rate`             | Vuser Group         |
-| Think time       | Constant/Uniform Timer  | `sleep()`               | `pause()`                | `time.sleep()`           | `lr_think_time()`   |
-| Inline assertion | Response Assertion      | `check()`               | `.check()`               | `catch_response`         | `lr_eval_string()`  |
-| SLA enforcement  | Duration Assertion      | `thresholds`            | Assertions (Enterprise)  | custom + exit code       | SLA definition      |
-| Correlation      | Regex / CSS Extractor   | `res.json()` / regex    | `.check()` + `saveAs()`  | `response.text` + regex  | `web_reg_save_param`|
-| Data feed        | CSV Data Set Config     | `SharedArray`           | `feeder`                 | CSV reader               | `lr_paramarr()`     |
-| Grouping         | Transaction Controller  | `group()`               | `group()`                | task sets                | Transaction         |
-| Distributed      | Controller + Agents     | k6 cloud / k6 operator  | Gatling Enterprise       | master + workers         | Load Generator      |
-| Results output   | .jtl (CSV/XML)          | JSON / InfluxDB / cloud | simulation.log           | CSV / Locust web UI      | .lrr file           |
+| Concept          | JMeter                  | k6                      | Gatling                  | Locust                   | Artillery                | LoadRunner          |
+|------------------|-------------------------|-------------------------|--------------------------|--------------------------|--------------------------|---------------------|
+| Virtual user     | Thread                  | VU                      | User                     | User                     | VU (arrival per sec)     | Vuser               |
+| Test plan        | .jmx file               | .js / .ts script        | Simulation class         | .py file                 | .yml / .js / .ts script  | VuGen script (.usr) |
+| User entrypoint  | Thread Group            | `default()` function    | `scenario()`             | task methods             | `flow` in scenario       | `Action()`          |
+| Concurrency ctrl | Thread Group settings   | executor                | `inject()`               | `spawn_rate`             | `maxVusers` / `arrivalRate` | Vuser Group         |
+| Think time       | Constant/Uniform Timer  | `sleep()`               | `pause()`                | `time.sleep()`           | `think`                  | `lr_think_time()`   |
+| Inline assertion | Response Assertion      | `check()`               | `.check()`               | `catch_response`         | `afterResponse` hooks    | `lr_eval_string()`  |
+| SLA enforcement  | Duration Assertion      | `thresholds`            | Assertions (Enterprise)  | custom + exit code       | `ensure` plugin          | SLA definition      |
+| Correlation      | Regex / CSS Extractor   | `res.json()` / regex    | `.check()` + `saveAs()`  | `response.text` + regex  | `capture` (json/xpath/regexp/header) | `web_reg_save_param`|
+| Data feed        | CSV Data Set Config     | `SharedArray`           | `feeder`                 | CSV reader               | `payload` / `variables`  | `lr_paramarr()`     |
+| Grouping         | Transaction Controller  | `group()`               | `group()`                | task sets                | `name` on scenario       | Transaction         |
+| Distributed      | Controller + Agents     | k6 cloud / k6 operator  | Gatling Enterprise       | master + workers         | Lambda / Fargate workers | Load Generator      |
+| Results output   | .jtl (CSV/XML)          | JSON / InfluxDB / cloud | simulation.log           | CSV / Locust web UI      | JSON / HTML report       | .lrr file           |
 
 ---
 

package/skills/perf/evals/evals.json

@@ -144,6 +144,86 @@
           "text": "Notes that values are baselines and should be adjusted to actual SLA requirements"
         }
       ]
+    },
+    {
+      "id": 8,
+      "prompt": "My Artillery test reports great metrics but my CI pipeline always passes even when p95 latency is 5 seconds. How do I make the test fail in CI?",
+      "expected_output": "Identifies missing ensure block as the cause. Without ensure, Artillery always exits 0. Provides an ensure.thresholds example with p95 and error rate conditions.",
+      "files": [],
+      "assertions": [
+        {
+          "id": "ensure-block-cause",
+          "text": "Identifies that without an ensure block, Artillery always exits 0 regardless of metrics"
+        },
+        {
+          "id": "ensure-example",
+          "text": "Provides a concrete ensure.thresholds or ensure.conditions YAML example"
+        },
+        {
+          "id": "exit-code",
+          "text": "Explains that ensure causes a non-zero exit code when thresholds are breached, enabling CI gating"
+        }
+      ]
+    },
+    {
+      "id": 9,
+      "prompt": "I set arrivalRate to 100 in Artillery expecting 100 concurrent users, but my backend is getting overwhelmed with way more than 100 simultaneous requests. What's happening?",
+      "expected_output": "Explains that arrivalRate is new users per second (open model), not concurrency. On a slow backend, VUs pile up unbounded. Recommends maxVusers to cap concurrency or arrivalCount for a fixed total.",
+      "files": [],
+      "assertions": [
+        {
+          "id": "open-model-explanation",
+          "text": "Explains that arrivalRate means new users per second (open model), not concurrent users"
+        },
+        {
+          "id": "pileup-risk",
+          "text": "Explains that on a slow backend, pending VUs accumulate unboundedly"
+        },
+        {
+          "id": "maxvusers-fix",
+          "text": "Recommends maxVusers to cap real concurrency, or arrivalCount for a fixed total number of users"
+        }
+      ]
+    },
+    {
+      "id": 10,
+      "prompt": "We're benchmarking our vLLM endpoint for a chat application. What metrics should we measure and what tools should we use?",
+      "expected_output": "Recommends TTFT, TPOT/ITL, tokens per second, and goodput as key metrics. Suggests vLLM bench, GenAI-Perf, GuideLLM, or llmperf as benchmarking tools. Distinguishes streaming vs non-streaming measurement.",
+      "files": [],
+      "assertions": [
+        {
+          "id": "ttft-tpot-metrics",
+          "text": "Names TTFT (time to first token) and TPOT or ITL (inter-token latency) as key streaming metrics"
+        },
+        {
+          "id": "benchmarking-tools",
+          "text": "Recommends at least one specific LLM benchmarking tool such as vLLM bench, GenAI-Perf, GuideLLM, or llmperf"
+        },
+        {
+          "id": "goodput-or-throughput",
+          "text": "Mentions goodput or tokens per second as a throughput metric distinct from raw request latency"
+        }
+      ]
+    },
+    {
+      "id": 11,
+      "prompt": "How do I set up SLO-based CI gating for my k6 load tests? I want the build to fail if we burn more than 2% of our error budget.",
+      "expected_output": "Explains error budget concept (100% - SLO target). Shows how to translate an error budget into k6 thresholds. Recommends tracking burn rate over the test window.",
+      "files": [],
+      "assertions": [
+        {
+          "id": "error-budget-concept",
+          "text": "Explains error budget as 100% minus the SLO target (e.g., 99.9% SLO = 0.1% budget)"
+        },
+        {
+          "id": "k6-threshold-mapping",
+          "text": "Shows how to express the error budget as concrete k6 thresholds"
+        },
+        {
+          "id": "burn-rate",
+          "text": "Mentions burn rate or multi-window alerting as a way to avoid false positives from short test runs"
+        }
+      ]
     }
   ]
 }

package/skills/perf/evals/trigger-eval.json

@@ -0,0 +1,38 @@
+{
+  "skill_name": "perf",
+  "description": "Queries that SHOULD trigger the perf skill",
+  "trigger": [
+    "Help me write a k6 load test for our REST API",
+    "My JMeter test crashes with OutOfMemoryError in CI",
+    "What tool should I use for load testing a gRPC service?",
+    "How do I correlate JSESSIONID in JMeter?",
+    "Set up a distributed Locust run in GitLab CI",
+    "Our p95 latency spikes during database writes",
+    "What TTFT can our vLLM endpoint sustain at 200 concurrent users?",
+    "How many replicas do we need for our SLO?",
+    "Write an Artillery test with ensure thresholds for our checkout API",
+    "Compare k6 vs Gatling for high-throughput HTTP testing",
+    "My Locust test shows zero failures but the server logs have 500 errors",
+    "How do I parameterize test data in Gatling?",
+    "Set up k6 thresholds for CI gating in GitHub Actions",
+    "What is a good p95 target for a payment endpoint?",
+    "Help me design a soak test to find memory leaks",
+    "How do I benchmark tokens per second on our LLM inference server?",
+    "My Artillery arrivalRate is overwhelming the backend",
+    "Explain Little's Law and how it applies to load testing",
+    "How do I test WebSocket performance?",
+    "Set up error budget alerts for our 99.9% SLO"
+  ],
+  "no_trigger": [
+    "Help me write a unit test for my Python function",
+    "What is the difference between SQL and NoSQL databases?",
+    "How do I set up a React component?",
+    "Explain how Docker containers work",
+    "Write a REST API endpoint in Express.js",
+    "How do I configure ESLint for my project?",
+    "What is the best way to learn machine learning?",
+    "Help me debug a CSS layout issue",
+    "How do I set up a Kubernetes cluster?",
+    "Write a GitHub Actions workflow for deploying my app"
+  ]
+}

package/skills/perf/references/tools/artillery.md

@@ -0,0 +1,331 @@
+# Artillery Reference
+
+> Targets: Artillery v2.x (YAML, JS, and TS test definitions; `http`, `playwright`, `socketio`, `ws` engines)
+
+Artillery is a developer-centric, open-source load testing tool that runs on Node.js. Tests can be written in YAML, JavaScript, or TypeScript, and it scales from a single laptop to distributed AWS Lambda / Fargate runs (Artillery Cloud). It is the closest JS/TS-native alternative to k6 and is a strong fit for teams already in the Node ecosystem.
+
+---
+
+## Core Concepts
+
+| Concept | Description |
+|---|---|
+| **Virtual User (VU)** | A single simulated user executing a `flow` |
+| **Arrival (open model)** | New VUs generated per second - the default load model |
+| **Phase** | A timed load segment (`arrivalRate`, `rampTo`, `arrivalCount`, `pause`) |
+| **Scenario** | Named user journey; a `flow` of requests/actions |
+| **Flow** | Ordered list of actions (request, `think`, `capture`, `loop`, `function`) |
+| **Capture** | Extract a dynamic value from a response for later reuse (correlation) |
+| **Processor** | Custom JS/TS module supplying hooks and metric logic |
+| **`ensure`** | SLO/assertion plugin - FAILS the run (non-zero exit) if breached |
+| **Environment** | Named config profile switched with `-e` |
+
+> Artillery uses an **open (arrival-rate) load model by default**. `arrivalRate` is *new users per second*, NOT concurrent users. Use `maxVusers` to cap real concurrency. For closed/concurrency modeling, see `../topics/workload-design.md`.
+
+---
+
+## Script Structure (YAML)
+
+```yaml
+config:
+  target: 'https://staging.example.com'
+  phases:
+    - duration: '2m'
+      arrivalRate: 10
+      rampTo: 50
+      name: ramp-up
+    - duration: '5m'
+      arrivalRate: 50
+      maxVusers: 200
+      name: sustain
+  ensure:
+    thresholds:
+      - 'http.response_time.p95': 500
+      - 'http.response_time.p99': 1000
+    conditions:
+      - expression: 'http.codes.5xx < http.codes.2xx * 0.01'  # <1% 5xx
+  processor: './helpers.js'
+
+scenarios:
+  - name: 'Browse + Checkout'
+    weight: 1
+    flow:
+      - post:
+          url: '/auth'
+          json:
+            username: '{{ username }}'
+            password: '{{ password }}'
+          capture:
+            - json: '$.id_token'
+              as: token
+      - think: 2
+      - get:
+          url: '/products'
+          headers:
+            authorization: 'Bearer {{ token }}'
+      - post:
+          url: '/checkout'
+          json:
+            itemId: '{{ $uuid }}'
+          capture:
+            - json: '$.orderId'
+              as: orderId
+      - get:
+          url: '/orders/{{ orderId }}'
+          headers:
+            authorization: 'Bearer {{ token }}'
+```
+
+---
+
+## Script Structure (JS / TS)
+
+```javascript
+export const config = {
+  target: 'https://staging.example.com',
+  phases: [
+    { duration: '2m', arrivalRate: 10, rampTo: 50, name: 'ramp-up' },
+    { duration: '5m', arrivalRate: 50, maxVusers: 200, name: 'sustain' },
+  ],
+  ensure: {
+    thresholds: [
+      'http.response_time.p95: 500',
+      'http.response_time.p99: 1000',
+    ],
+  },
+  processor: './helpers.js',
+};
+
+export const scenarios = [
+  {
+    name: 'Browse + Checkout',
+    flow: [
+      {
+        post: {
+          url: '/auth',
+          json: { username: '{{ username }}', password: '{{ password }}' },
+          capture: [{ json: '$.id_token', as: 'token' }],
+        },
+      },
+      { think: 2 },
+      {
+        get: {
+          url: '/products',
+          headers: { authorization: 'Bearer {{ token }}' },
+        },
+      },
+    ],
+  },
+];
+```
+
+---
+
+## Load Phases
+
+`config.phases` is an array executed sequentially. Four phase kinds:
+
+| Phase kind | Key options | Use case |
+|---|---|---|
+| **Constant arrival** | `arrivalRate` | Steady RPS-style load (open model) |
+| **Ramp** | `arrivalRate` + `rampTo` (both over `duration`) | Warm-up / ramp-up |
+| **Fixed count** | `arrivalCount` | Exact N total users spread over `duration` |
+| **Pause** | `pause` | Idle gap (soak cool-down, between spikes) |
+
+```yaml
+phases:
+  - duration: '30m'
+    arrivalRate: 1
+    rampTo: 100
+    name: ramp-up
+  - duration: '3h'
+    arrivalRate: 100
+    name: sustain          # soak/endurance
+  - duration: '1m'
+    arrivalRate: 500
+    name: spike            # spike test
+  - pause: 60
+```
+
+- `duration` / `pause` accept human-readable units (`'5m'`, `'3h'`) as well as seconds.
+- `maxVusers` caps in-flight VUs for any phase - essential to bound concurrency on slow servers (open-model load otherwise queues unbounded pending VUs).
+- `name` makes phases identifiable in CLI output and Artillery Cloud.
+
+---
+
+## Correlation (Capture / Dynamic Values)
+
+Use `capture` on a request to extract a value for later steps. Requires `as` and one extractor:
+
+| Extractor | Syntax | Example |
+|---|---|---|
+| JSONPath | `json: '$.path'` | `json: '$.id_token'` |
+| XPath | `xpath: '//node/text()'` | SOAP / XML bodies |
+| Regex | `regexp: 'pattern'`, optional `group`, `flags` | `regexp: 'sid=([^&]+)'` |
+| Header | `header: 'X-Custom'` | `header: 'Set-Cookie'` |
+| Selector | `selector: 'a.product'`, `attr`, `index` | HTML scraping |
+
+```yaml
+- get:
+    url: '/login'
+    capture:
+      - json: '$.csrf'
+        as: csrf
+      - header: 'set-cookie'
+        as: cookie
+- post:
+    url: '/submit'
+    headers:
+      x-csrf-token: '{{ csrf }}'
+    cookie:
+      session: '{{ cookie }}'
+```
+
+- **Captures are strict by default**: a failed capture stops that VU. Set `strict: false` only when a later request can safely 404.
+- For multi-step journeys, capture once near the top and reuse via `{{ var }}` in every later request.
+- Capture multiple values from one response with an array of capture specs.
+
+> For framework-specific extraction rules (ASP.NET ViewState, JSF, JWT, SAP `sap-contextid`), see `../topics/correlation.md`.
+
+---
+
+## Parameterization
+
+### CSV payload (`config.payload`)
+```yaml
+config:
+  payload:
+    path: 'users.csv'
+    fields: ['username', 'password']
+    skipHeader: true
+    order: sequence        # 'random' (default) | 'sequence'
+scenarios:
+  - flow:
+      - post:
+          url: '/auth'
+          json:
+            username: '{{ username }}'
+            password: '{{ password }}'
+```
+- `order: sequence` is deterministic but **breaks under distributed runs** (each worker has its own copy). Use `random` (default) for distributed tests.
+- `loadAll: true` + `name` exposes the whole dataset to each VU for `loop`.
+- `cast: false` keeps values as strings; `delimiter` overrides the comma.
+
+### Inline variables (`config.variables`)
+```yaml
+config:
+  variables:
+    postcode: ['SE1', 'EC1', 'E8']
+    id: ['8731', '9965', '2806']
+```
+One value is picked at random per VU. Cannot template `config` values.
+
+### Environment variables (`$env`)
+```yaml
+headers:
+  x-api-key: '{{ $env.API_KEY }}'
+```
+Run with `API_KEY=xxx artillery run script.yml` or `--env-file .env`. Keeps secrets out of source.
+
+### Environments (`-e`)
+Reuse one script across dev/staging/prod by defining `config.environments` with per-env `target` and `phases`:
+```bash
+artillery run -e production script.yml
+```
+Access the active name via `{{ $environment }}` (e.g. to pick a CSV: `path: '{{ $environment }}-logins.csv'`).
+
+---
+
+## SLO Checks with `ensure` (Assertions)
+
+`ensure` is Artillery's SLA gate - **without it, the run reports metrics but always exits 0**, so CI never fails on latency. Always add it for CI.
+
+```yaml
+config:
+  plugins:
+    ensure:
+      thresholds:                 # value must be LESS than this
+        - 'http.response_time.p95': 500
+        - 'http.response_time.p99': 1000
+      conditions:                 # advanced boolean/numeric expressions
+        - expression: 'http.response_time.p95 < 500 and http.request_rate > 1000'
+        - expression: 'http.codes.5xx <= http.codes.2xx * 0.01'
+          strict: false           # optional check; failure won't fail the run
+```
+
+- `thresholds` check a metric's aggregate is **below** the integer.
+- `conditions` combine metrics with `+ - * / % ^`, comparisons, `and`/`or`/`not`, and `ceil/floor/round`.
+- `strict: true` (default) fails the run on breach; `strict: false` reports only.
+- Using a non-existent metric name makes that check fail.
+
+### Key metrics for `ensure`
+| Metric | Meaning |
+|---|---|
+| `http.response_time.p95` / `.p99` | Latency percentile (ms) |
+| `http.request_rate` | Requests/sec |
+| `http.codes.2xx` / `.4xx` / `.5xx` | Status-code counters |
+| `http.downloaded_bytes` | Total payload bytes |
+| `vusers.completed` / `vusers.failed` | VU outcomes |
+
+> `http.response_time.*` is **TTFB** by default. Enable `config.http.extendedMetrics: true` for full `http.total.*` (download-complete) timing. For SLA baseline tables, see SKILL.md "Threshold Starting Points" and `../topics/results-analysis.md`.
+
+---
+
+## Custom Logic (Processor Hooks)
+
+Load JS/TS via `config.processor`:
+
+```javascript
+// helpers.js
+module.exports = {
+  setApiKey(context, events, done) {
+    context.vars.apiKey = process.env.API_KEY;
+    return done();
+  },
+  assertOrder(context, events, done) {
+    const status = context.vars.orderStatus;
+    if (status !== 'confirmed') {
+      events.emit('counter', 'order_failures', 1);
+    }
+    return done();
+  },
+};
+```
+
+Hook points:
+- **`beforeRequest` / `afterResponse`** - set on a request; customize/inspect URL, headers, body.
+- **`beforeScenario` / `afterScenario`** - set on a scenario.
+- **`function`** step - run arbitrary code mid-flow.
+
+Async hooks are supported (v2.0.7+). Use `events.emit('counter'|'histogram'|'rate', name, value)` for custom metrics.
+
+---
+
+## Output and Observability
+
+| Output | How |
+|---|---|
+| Terminal summary | Default (`artillery run script.yml`) |
+| JSON report | `artillery run -o json=report.json script.yml` |
+| Artillery Cloud | `artillery run --record script.yml` (dashboards, historical trends) |
+| CSV | `artillery run -o csv=results.csv script.yml` |
+| Distributed | AWS Lambda / Fargate workers via `artillery run-fargate` |
+
+Enable `config.http.distributedTracing: true` to attach a W3C `traceparent` header to every request - correlates load with backend spans in your APM.
+
+---
+
+## Artillery-Specific Tips
+
+- **`arrivalRate` is new-users-per-second, not concurrency.** A slow backend makes pending VUs pile up. Always set `maxVusers` to bound real concurrency, or switch to `arrivalCount`/closed-model thinking via `workload-design.md`.
+- **Always add `ensure` for CI.** A test with no `ensure` exits 0 regardless of latency or error spikes - it generates traffic but enforces nothing.
+- **Captures are strict by default.** A missed extractor aborts the whole VU. Only set `strict: false` when a downstream 404 is acceptable.
+- **Add `think` between steps.** Zero think time maximizes RPS unrealistically; use `think` (seconds or `ms` units) to model real pacing.
+- **Default `payload.order` is `random`** - deterministic `sequence` ordering does not work correctly in distributed runs.
+- **`http.response_time` is TTFB.** Turn on `extendedMetrics` if you need full download time (`http.total.*`).
+- **Secrets via `$env` / `--env-file`**, never inline. Use `config.environments` + `-e` to promote the same script dev → staging → prod.
+- **Avoid heavy `log` actions under load** - they add overhead; prefer `ensure`/custom counters for visibility.
+- **Browser load?** Use the `playwright` engine (`engines: { playwright: {} }`) to drive real pages; note it is far heavier per VU than HTTP.
+
+> For CI/CD integration (GitHub Actions, GitLab CI, distributed execution), see `../topics/test-execution.md`.
+> For anti-patterns, assertions, think time, and parameterization principles, see **Key Principles** in `SKILL.md`.

package/skills/perf/references/tools/loadrunner.md

@@ -112,5 +112,29 @@ web_add_header("Authorization", "Bearer {AuthToken}");
 - Use **Correlation graphs** to overlay server metrics (CPU, memory) from SiteScope/Diagnostics.
 - Export to Excel or integrate with LoadRunner Cloud for trend analysis across runs.
 
+---
+
+## LoadRunner-Specific Tips
+
+- **Register correlations before the request** - `web_reg_save_param_regexp` must appear
+  *before* the `web_url`/`web_submit_form` that returns the dynamic value. Placing it after
+  silently captures nothing.
+- **Use `lr_eval_string()` for debugging** - log parameter values during replay
+  (`lr_log_message("Token={AuthToken}")`) to verify correlation is working before scaling VUs.
+- **Avoid `lr_think_time(0)` in Action** - zero think time generates maximum RPS per VU,
+  which never reflects real user behavior. Use `lr_think_time(3)` or `lr_user_think_time()`
+  with a runtime distribution.
+- **Parameterize with data tables, not hardcoded values** - use `lr_paramarr_idx()` or
+  Parameter List in VuGen to feed unique credentials per VU. Hardcoded users cause
+  session collisions and cache-hot results.
+- **Set JVM heap for Load Generators** - default LG memory is often too low for 500+ VUs.
+  Increase via `mdrv -heap_size` or the LG configuration panel.
+- **Use Goal-Oriented scenarios for capacity tests** - instead of guessing VU counts,
+  let Controller auto-adjust to hit a target RPS or response time. This finds the
+  saturation point without manual iteration.
+- **Disable extended logging in CI** - `lr_set_debug_message` and extended logs add
+  20-40% overhead. Use standard logging or disable entirely for large runs.
+
 > For anti-patterns, assertions, think time, and parameterization principles, see **Key Principles** in `SKILL.md`.
 > For CI/CD integration details, see `../topics/test-execution.md`.
+> For correlation strategies across tools, see `../topics/correlation.md`.