Skip to content

A Dockerised REST Api and related Karate API tests to Demoonstrate Perfiz Performance Testing Setup

License

Notifications You must be signed in to change notification settings

znsio/perfiz-demo

Repository files navigation

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 Grafana Screenshot
    • 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
  • 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
  • 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