canyonlabz/jmeter-correlation-naming

JMeter Correlation Naming

Overview

The correlation_naming.json file maps each correlation_id from a correlation_spec.json to a meaningful JMeter variable name, extractor type, and extractor expression. It is consumed by generate_jmeter_script to produce the parameterized JMX.

Auto-Generated by Default

The analyze_network_traffic MCP tool automatically generates correlation_naming.json as Phase 4 of the correlation analysis pipeline. The algorithmic naming engine (services/correlations/naming.py) applies deterministic rules:

1. Custom mappings from correlation_config.yaml (highest priority)
2. OAuth parameter lookups (e.g., state -> oauth_state)
3. OAuth token field lookups (e.g., cdssotoken -> cdsso_token)
4. Timestamp URL-pattern matching (e.g., SignalR URLs -> signalr_timestamp_N)
5. Algorithmic camelCase -> snake_case conversion (e.g., entityGuid -> entity_guid)
6. De-duplication suffixes when the same base name is assigned to multiple correlations

Configuration: correlation_config.yaml

The naming engine reads customizable mappings from jmeter-mcp/correlation_config.yaml. Falls back to jmeter-mcp/correlation_config.example.yaml if the local file does not exist.

To customize naming for your application:

1. Copy correlation_config.example.yaml to correlation_config.yaml
2. Add entries under naming.custom_mappings for application-specific field names
3. The local file is git-ignored

naming:
  custom_mappings:
    entityGuid: "product_guid"
    productDataSourceId: "data_source_id"

---

When to Use This Skill

• Reviewing the auto-generated correlation_naming.json for clarity and accuracy
• Adjusting variable names after auto-generation (manual overrides)
• Generating correlation_naming.json from scratch for older correlation specs that were produced before algorithmic naming was added

---

Scenario A: Reviewing Auto-Generated Output

When analyze_network_traffic has already produced correlation_naming.json:

1. Read both correlation_naming.json and the corresponding correlation_spec.json
2. Review each variable name:
   • Does the name reflect the domain entity? (e.g., entity_guid for an entity GUID)
   • Are OAuth parameters using the standard names? (see naming-conventions.md)
   • Are orphan variables descriptively named (not generic like corr_var)?
3. If adjustments are needed, update correlation_naming.json directly
4. If the same pattern will recur, suggest adding a custom_mappings entry to correlation_config.yaml so the engine handles it automatically next time

Scenario B: Generating from Scratch

When no correlation_naming.json exists (e.g., older correlation specs):

1. Read the entire correlation_spec.json
2. For each correlation with correlation_found: true:
   • Infer the resource/purpose from source_key, source_json_path, URLs, and step labels
   • Generate a descriptive variable_name following the naming conventions
   • Set jmeter_extractor_type based on source_location
   • Generate jmeter_extractor_expression (JSONPath or regex)
3. For each correlation with correlation_found: false:
   • Place in orphan_variables array
   • Suggest parameterization strategy based on parameterization_hint
4. Return valid JSON matching the output schema (see naming-conventions.md)

---

Validation Rules (Mandatory — Both Scenarios)

Uniqueness

• Every variable_name across both variables and orphan_variables MUST be unique
• If duplicates exist, rename using more specific context (source_key, location_key, or numeric suffix as last resort)

Name Quality

Variable names MUST NOT be:

• Empty or blank
• Just a number suffix (e.g., _22, _23)
• Overly generic (e.g., value, value_19, id)

If any fail validation, re-derive using the orphan naming rules in naming-conventions.md.

---

Quick Reference: Naming Rules

General

• Use snake_case for all variable names
• Use singular nouns for IDs (product_id not products_id)
• Do not embed literal values in variable names

By Correlation Type

| Type | Pattern | Examples | |------|---------|----------| | business_id | <resource>_id | product_id, order_id, customer_id | | correlation_id | <purpose>_id | request_id, trace_id, session_id | | oauth_param | Standard OAuth names | oauth_state, oauth_nonce, oauth_client_id |

Extractor Type Selection

| source_location | Extractor Type | |-----------------|---------------| | response_json | json_extractor | | response_header | regex_extractor | | response_redirect_url | regex_extractor | | response_set_cookie | regex_extractor | | response_html_form | regex_extractor |

Context-Based Naming (Inference Order)

1. source.source_key — the JSON field name (e.g., productId -> product_id)
2. source.source_json_path — path context (e.g., $.items[0].orderId -> order_id)
3. source.request_url — API endpoint (e.g., /products/ -> product_id)
4. usages[*].request_url — where it's used
5. source.step_label — business context from step description

---

Additional Resources

For detailed schemas, full naming tables, OAuth parameter mappings, orphan naming rules, SignalR patterns, and input/output examples, see naming-conventions.md.