Dynatrace integration for Gatling

Send load test metrics to Dynatrace and set custom test headers on all generated requests.

Gatling Enterprise Edition Integration#

Introduction#

The Dynatrace integration allows Gatling Enterprise Edition to send load-test metrics - such as response times, throughput, and error rates - directly into Dynatrace’s observability platform. Once enabled, performance data from Gatling Enterprise Edition is sent to Dynatrace, where it can be correlated with infrastructure and application metrics already collected in your Dynatrace account.

With this integration in place, you can:

• Monitor Gatling scenarios alongside server-level KPIs (CPU, memory, network) in a single dashboard.
• Investigate performance issues more effectively by overlaying load-test metrics on traces, logs, and resource utilization charts.

Prerequisites#

• A valid Dynatrace API key
• Your Dynatrace site identifier
• A Gatling Enterprise Edition account with private locations that can connect to the Dynatrace network.

Install the Dynatrace integration#

The Dynatrace integration requires installation steps in your Dynatrace account and on your private locations control plane.

1. See the official Dynatrace API key documentation for creating an API key in your Dynatrace account. Ensure your API key has the following permissions:

   • Ingest metrics (metrics.ingest)
   • Ingest events (events.ingest)

2. Identify your Dynatrace site identifier from your Dynatrace URL. For example, if your Dynatrace environment URL is https://abc12345.apps.dynatrace.com, your environment ID is abc12345.

3. In your control-plane configuration, in the section system-properties, add:

control-plane {
  locations = [
    {
      system-properties {
        "gatling.enterprise.dt.api.key" = "<your Dynatrace api key>"
        "gatling.enterprise.dt.site" = "<your Dynatrace site identifier>"
      }
    }
  ]
}

Uninstall the Dynatrace integration#

To remove the link between Gatling Enterprise Edition and Dynatrace, remove the lines containing gatling.enterprise.dt in your control-plane configuration.

Events pushed to Dynatrace#

Gatling Enterprise Edition generates custom information events for load test injection start and end.

All events are of type CUSTOM_INFO with the following properties:

See the official Dynatrace documentation for exploring events.

Metrics pushed to Dynatrace#

Gatling Enterprise Edition pushes the following list of load test metrics to Dynatrace:

See the official Dynatrace documentation for exploring metrics.

Use metric dimensions to enhance your Dynatrace dashboard#

Default Dimensions#

Gatling Enterprise Edition pushes the following dimensions to Dynatrace:

Custom Dimensions#

You can add custom dimensions by adding system properties, either at the control-plane level or in your test configuration (except for no-code tests): gatling.enterprise.dt.dimensions.<custom_dimension> = <your value>

HTTP Request Integration#

Using Gatling and Dynatrace to capture request attributes#

Pass Gatling load test request attributes to Dynatrace using additional HTTP headers. Dynatrace can handle, extract, and tag information from incoming HTTP headers containing information such as:

• script name,
• test step name, and
• virtual user ID.

You can then filter your monitoring data based on the defined tags.

Configure Dynatrace extraction rules#

You can use any HTTP headers or HTTP parameters to pass contextual information. To configure the extraction rules in Dynatrace reference the extraction rules documentation.

Add contextual information to headers#

The header x-dynatrace-test is used in the following example with the following set of key/value pairs for the header:

Defining a global signing function (example)#

The idea here is to use sign on the HttpProtocol to define a global signing function to be applied on all generated requests.

private static final String Hostname;

static {
  try {
    Hostname = InetAddress.getLocalHost().getHostName();
  } catch (UnknownHostException e) {
    throw new ExceptionInInitializerError(e);
  }
}

// Source Id identifies the product that triggered the request
private static final String SI = "GATLING";

// The Load Test Name uniquely identifies a test execution
private final String LTN =
  getClass().getSimpleName() +
    "_" +
    LocalDateTime.now().format(DateTimeFormatter.ISO_LOCAL_DATE_TIME);

HttpProtocolBuilder httpProtocol = http
  .sign((request, session) -> {
    // Virtual User ID of the unique user who sent the request
    String VU = Hostname + "_" + session.scenario() + "_" + session.userId();

    // Test Step Name is a logical test step within your load testing script
    String TSN = request.getName();

    // Load Script Name - name of the load testing script.
    String LSN = session.scenario();

    // Page Context provides information about the document
    String PC = String.join(",", session.groups());

    request.getHeaders()
      .set(
        "x-dynaTrace",
        "VU=" + VU + ";SI=" + SI + ";TSN=" + TSN + ";LSN=" + LSN + ";LTN=" + LTN + ";PC=" + PC
      );

    return request;
  });

private val Hostname: String = InetAddress.getLocalHost().getHostName()

// Source Id identifies the product that triggered the request
private val SI = "GATLING"

// The Load Test Name uniquely identifies a test execution
private val LTN =
  javaClass.simpleName +
  "_" +
  LocalDateTime.now().format(DateTimeFormatter.ISO_LOCAL_DATE_TIME)

val httpProtocol = http
  .sign { request: Request, session: Session ->
    // Virtual User ID of the unique user who sent the request
    val VU = "${Hostname}_${session.scenario()}_${session.userId()}"

    // Test Step Name is a logical test step within your load testing script
    val TSN = request.name

    // Load Script Name - name of the load testing script.
    val LSN = session.scenario()

    // Page Context provides information about the document
    val PC = session.groups().joinToString(",")

    request.headers["x-dynaTrace"] =
      "VU=$VU;SI=$SI;TSN=$TSN;LSN=$LSN;LTN=$LTN;PC=$PC"

    request
  }

private val Hostname = InetAddress.getLocalHost.getHostName

// Source Id identifies the product that triggered the request
private val SI = "GATLING"

// The Load Test Name uniquely identifies a test execution
private val LTN =
  getClass.getSimpleName +
    "_" +
    LocalDateTime.now.format(DateTimeFormatter.ISO_LOCAL_DATE_TIME)

val httpProtocol = http
  .sign { (request, session) =>
    // Virtual User ID of the unique user who sent the request
    val VU = s"${Hostname}_${session.scenario}_${session.userId}"

    // Test Step Name is a logical test step within your load testing script
    val TSN = request.getName

    // Load Script Name - name of the load testing script.
    val LSN = session.scenario

    // Page Context provides information about the document
    val PC = session.groups.mkString(",")

    request.getHeaders.set(
      "x-dynaTrace",
      s"VU=$VU;SI=$SI;TSN=$TSN;LSN=$LSN;LTN=$LTN;PC=$PC"
    )
    request
  }

Edit this page on GitHub