In this example study we’ll tune the parameters of PageRank, one of the benchmarks available in the Renaissance suite, with the goal of minimizing its memory usage. Application monitoring is provided by Prometheus, leveraging a JMX exporter.

Environment setup

The test environment includes the following instances:

• Akamas: instance running Akamas

• PageRank: instance running the PageRank benchmark and the Prometheus monitoring service

Telemetry Infrastructure setup

To gather metrics about PageRank we will use a Prometheus and a JMX exporter. Here’s the scraper to add to the Prometheus configuration to extract the metrics from the exporter:

- job_name: jmx-exporter
  static_configs:
    - targets: ['pagerank.akamas.io:5556']
      labels:
      instance: jvm

Application and Test tool

To run and monitor the benchmark we’ll require on the PageRank instance:

• The Renaissance jar

• The JMX exporter agent, plus a configuration file to expose the required classes

Here’s the snippet of code to configure the instance as required for this guide:

mkdir renaissance; cd renaissance
wget -O renaissance.jar https://github.com/renaissance-benchmarks/renaissance/releases/download/v0.10.0/renaissance-gpl-0.10.0.jar
wget -O jmx_exporter.jar https://repo1.maven.org/maven2/io/prometheus/jmx/jmx_prometheus_javaagent/0.14.0/jmx_prometheus_javaagent-0.14.0.jar
echo -e '--\nwhitelistObjectNames: ["java.lang:*"]' > conf.yaml

Optimization setup

In this section, we will guide you through the steps required to set up the optimization on Akamas.

If you have not installed the Java OpenJDK optimization pack yet, take a look at the optimization pack page Java OpenJDK to proceed with the installation.

System

System pagerank

Here’s the definition of the system we will use to group our components and telemetry instances for this example:

name: pagerank
description: A system to tune the pagerank benchmark

To create the system run the following command:

akamas create system pagerank.yaml

Component jvm

We’ll use a component of type Java OpenJDK 11 to represent the JVM underlying the PageRank benchmark. To identify the JMX-related metrics in Prometheus the configuration requires the prometheus property for the telemetry service, detailed later in this guide.

Here’s the definition of the component:

name: jvm
componentType: openjdk-11
properties:
  prometheus:
    instance: jvm
    job: jmx-exporter

To create the component in the system run the following command:

akamas create component jvm.yaml pagerank

Workflow

The workflow used for this study consists of two main stages:

• generate the configuration file containing the tested Java parameters

• run the execution using previously written parameters

Here’s the definition of the workflow:

name: run-pagerank
tasks:
  - name: Configure parameters
    operator: FileConfigurator
    arguments:
      source:
        hostname: pagerank.akamas.io
        username: ubuntu
        path: /home/ubuntu/renaissance/java_opts.template
        key: key
      target:
        hostname: pagerank.akamas.io
        username: ubuntu
        path: /home/ubuntu/renaissance/java_opts
        key: key

  - name: Run benchmark
    operator: Executor
    arguments:
      command: "cd renaissance; java -javaagent:./jmx_exporter.jar=5556:conf.yaml $(cat java_opts) -jar renaissance.jar -r 2 page-rank"
      host:
        hostname: pagerank.akamas.io
        username: ubuntu
        key: key

Where the configuration template is java_opts.template is defined as follows:

 ${jvm.jvm_gcType} ${jvm.jvm_maxHeapSize} ${jvm.jvm_newSize} ${jvm.jvm_survivorRatio} ${jvm.jvm_maxTenuringThreshold}

To create the workflow run the following command:

akamas create workflow workflow.yaml

Telemetry

The following is the definition of the telemetry instance that fetches metrics from the Prometheus service:

provider: Prometheus
config:
  address: pagerank.akamas.io
  port: 9090

To create the telemetry instance in the system run the following command:

akamas create telemetry-instance prometheus.yaml pagerank

This telemetry instance will be able to bind the fetched metrics to the related jvm component thanks to the prometheus attribute we previously added in its definition.

Study

The goal of this study is to find a JVM configuration that minimizes the peak memory used by the benchmark.

The optimized parameters are the maximum heap size, the garbage collector used and several other parameters managing the new and old heap areas. We also specify a constraint stating that the GC regions can’t exceed the total heap available, to avoid experimenting with parameter configurations that can’t start in the first place.

Here’s the definition of the study:

name: Optimize PageRank
description: Tweaking the JVM parameters to optimize the page-rank benchmark.
system: pagerank
workflow: run-pagerank

goal:
  objective: minimize
  function:
    formula: memory_used
    variables:
      memory_used:
        metric: jvm.jvm_memory_used

parametersSelection:
  - name: jvm.jvm_gcType
  - name: jvm.jvm_maxHeapSize
    domain: [1250, 2000]
  - name: jvm.jvm_newSize
    domain: [350, 2000]
  - name: jvm.jvm_survivorRatio
  - name: jvm.jvm_maxTenuringThreshold

parameterConstraints:
  - name: Max heap must always be greater than new size
    formula: jvm.jvm_maxHeapSize > jvm.jvm_newSize

steps:
  - name: baseline
    type: baseline
    values:
      jvm.jvm_gcType: G1
      jvm.jvm_maxHeapSize: 2000

  - name: optimize
    type: optimize
    numberOfExperiments: 30

To create and run the study execute the following commands:

akamas create study study.yaml
akamas start study 'Optimize PageRank'

Offline optimizations