Perfiz Demo

An example REST API project to help you get started with Perfiz

What you will learn / setup

Leveraging your Karate API tests as Gatling Performance Tests through Perfiz YAML configuration (without writing a single line Gatling Scala DSL)
Visualizing the above performance test results through Live Grafana Dashboards (which come pre-configured with Perfiz)
Monitoring your application performance through Prometheus and Visualizing it on Grafana
At a high level you will be able to run a sophisticated performance test completely inside Docker without any local setup

What you will need

About 5 minutes
Docker >= 20.10.0
docker-compose >= 1.29.0
Your preferred Text Editor / IDE (to edit Perfiz YAML Configuration)

Instructions

Running the PetStore REST API
- Clone this repo and run below command
```
docker-compose up -d
```
- This will start a REST API app. You can test this with Curl. This is a sample app against which we will run our performance tests.
```
$ curl http://localhost:9999/pets/1
{
    "petid": 444
}
```
Setting up Perfiz - Refer to Installation
Start you Performance Test Monitoring Stack on Docker
- Make sure you are inside perfiz-demo Dir. Run below command.
```
$PERFIZ_HOME/perfiz.sh start
```
- Launch Grafana on your browser on localhost:3000. It may ask you to change the password. You can change it or ignore and proceed by re-entering the same username and password.
  - UserName - admin
  - Password - admin
- On Docker Dashboard you will be able to observe all the containers running under the name "Perfiz"
Running Performance Test on the PetStore REST API with Perfiz
- Make sure you are inside perfiz-demo Dir. Run below command to perform a quick 45 second load test.
```
$PERFIZ_HOME/perfiz.sh test
```
- On Grafana Dashboard (localhost:3000) navigate to "Perfiz Performance Metric Monitor" Dashboard
- Now you should be able to see the performance test metrics in realtime on "Perfiz Performance Metric Monitor" Grafana Dashboard
- Congratulations! You have successfully run a Performance Test on your local machine with little to no setup. To repeat the test you can run "$PERFIZ_HOME/perfiz.sh test" again.
- If you have another 5 minutes
  - Read through the explanation on how this Demo is working. Then you can play around with the load pattern in perfiz.yml, re-run your Perf Test and observe your changes in Grafana.
  - Adding prometheus scrape configs
  - Adding Grafana Dashboards
  - Try the practise-exercise to integrated Perfiz into this demo project from scratch
Stopping Perfiz
- To stop Perfiz run below command
```
$PERFIZ_HOME/perfiz.sh stop
```
- To stop PetStore REST API, run below command
```
docker-compose down
```

Explanation

Demo App - PetStore REST API - ./app and ./docker-compose.yml
- The REST API is a stub server that runs with the help of an interesting project called specmatic
- I have Dockerised this into a simple docker-compose to get you going quickly
Karate Features - ./karate-features
- API Tests for the above project
Perfiz Configuration - ./perfiz.yml
- This file leverages the Karate API test as a load test script
- It also defines the Gatling simulation name and the load pattern
- Please Perfiz Config Syntax for detailed syntax documentation

Prometheus Configuration - Adding Scrape Configs

As an example we will see how to read JVM metrics and setup a Grafana Dashboard for the same. However, these steps are applicable to any Prometheus compatible metrics.

JMX Metrics for Petstore Application
- The example application running on http://localhost:9999 is setup with JMX Exporter and publishes metrics that can be read by Prometheus
- These metrics are available on http://localhost:8089/metrics
Prometheus Configuration
- Now we need to add the scrape configs for the above URL in prometheus.yml
  - All custom Perfiz configurations are inside the perfiz folder
  - Inside this prometheus configurations are inside the prometheus folder
  - The prometheus.yml file has job named java which reads the JVM metrics
- Prometheus is part of the Perfiz stack. You will be able to access the jvm_* metrics on Prometheus Expression Browser

Grafana Dashboards - Adding JVM Dashboard

Let us now setup a dashboard to visualise the above JMX metrics

I have downloaded the JSON for the popular JVM dashboard and have saved it inside dashboards folder
Perfiz automatically loads this Dashboard to Grafana at startup
You can access this dashboard on Grafana
To add other Official Community Built Dashboards
- Download and save JSON to <your project root dir>/perfiz/dashboards
- Perfiz will pick it up at startup and load it into Grafana
- This way you will also be able to checkin these JSONs to your version control and share it with your team
- Example: JVM Dashboard
Custom / Modified Dashboards
- We often have to customize dashboards as per our project context
- After making these changes save the JSON Model to <your project root dir>/perfiz/dashboards

Setting "karate.env"

In our sample karate-config.js located in karate-features folder we have a default env "dev" and other env such as "stage" and "e2e"
To set the environment to a "stage" all you need to do is set "karateEnv" in perfiz config as shown in perfiz-staging-load-test.yml
We can run perfiz with this configuration by passing the specific config file

    $PERFIZ_HOME/perfiz.sh test perfiz-staging-load-test.yml

znsio/perfiz-demo