{"id":21528257,"url":"https://github.com/znsio/perfiz-demo","last_synced_at":"2025-03-17T18:44:49.854Z","repository":{"id":50130273,"uuid":"348038771","full_name":"znsio/perfiz-demo","owner":"znsio","description":"A Dockerised REST Api and related Karate API tests to Demoonstrate Perfiz Performance Testing Setup","archived":false,"fork":false,"pushed_at":"2022-06-09T15:37:34.000Z","size":378,"stargazers_count":2,"open_issues_count":1,"forks_count":1,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-01-24T06:09:39.782Z","etag":null,"topics":["demo","gatling","grafana","karate","perfiz","performance-monitoring","performance-testing","prometheus"],"latest_commit_sha":null,"homepage":"https://github.com/znsio/perfiz","language":"Dockerfile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/znsio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-03-15T16:11:59.000Z","updated_at":"2024-01-09T00:04:44.000Z","dependencies_parsed_at":"2022-08-26T23:10:20.626Z","dependency_job_id":null,"html_url":"https://github.com/znsio/perfiz-demo","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/znsio%2Fperfiz-demo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/znsio%2Fperfiz-demo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/znsio%2Fperfiz-demo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/znsio%2Fperfiz-demo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/znsio","download_url":"https://codeload.github.com/znsio/perfiz-demo/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244091767,"owners_count":20396667,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["demo","gatling","grafana","karate","perfiz","performance-monitoring","performance-testing","prometheus"],"created_at":"2024-11-24T01:52:24.356Z","updated_at":"2025-03-17T18:44:49.831Z","avatar_url":"https://github.com/znsio.png","language":"Dockerfile","funding_links":[],"categories":[],"sub_categories":[],"readme":"# [Perfiz](https://perfiz.com) Demo\n\nAn example REST API project to help you get started with [Perfiz](https://perfiz.com)\n\n## What you will learn / setup\n\n* Leveraging your Karate API tests as Gatling Performance Tests through Perfiz YAML configuration (without writing a single line Gatling Scala DSL)\n* Visualizing the above performance test results through Live Grafana Dashboards (which come pre-configured with Perfiz)\n* Monitoring your application performance through Prometheus and Visualizing it on Grafana\n* At a high level you will be able to run a sophisticated performance test completely inside Docker without any local setup\n\n## What you will need\n\n* About **5 minutes**\n* Docker \u003e= 20.10.0\n* docker-compose \u003e= 1.29.0\n* Your preferred Text Editor / IDE (to edit Perfiz YAML Configuration)\n\n## Instructions\n\n* Running the PetStore REST API\n    * Clone this repo and run below command\n    ```shell script\n    docker-compose up -d\n    ```\n    * 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.\n    ```shell script\n    $ curl http://localhost:9999/pets/1\n    {\n        \"petid\": 444\n    }\n    ```\n* Setting up **Perfiz** - Refer to [Installation](https://perfiz.com/installation.html#installation)\n* Start you Performance Test Monitoring Stack on Docker\n    * Make sure you are inside perfiz-demo Dir. Run below command.\n    ```shell script\n    $PERFIZ_HOME/perfiz.sh start\n    ```\n    * 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.\n      * UserName - admin\n      * Password - admin\n    * On Docker Dashboard you will be able to observe all the containers running under the name \"Perfiz\"\n* Running Performance Test on the PetStore REST API with Perfiz\n    * Make sure you are inside perfiz-demo Dir. Run below command to perform a quick 45 second load test.\n    ```shell script\n    $PERFIZ_HOME/perfiz.sh test\n    ```\n    * On Grafana Dashboard (localhost:3000) navigate to [\"Perfiz Performance Metric Monitor\"](http://localhost:3000/d/4l-HfCPMk/perfiz-performance-metric-monitor) Dashboard\n    * Now you should be able to see the performance test metrics in realtime on \"Perfiz Performance Metric Monitor\" Grafana Dashboard\n    ![Grafana Screenshot](https://github.com/znsio/perfiz-demo/blob/main/assets/grafana-test.png)\n    * **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.\n    * If you have another 5 minutes\n        * Read through the [explanation](https://github.com/znsio/perfiz-demo#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.\n        * [Adding prometheus scrape configs](https://github.com/znsio/perfiz-demo#prometheus-configuration---adding-scrape-configs)\n        * [Adding Grafana Dashboards](https://github.com/znsio/perfiz-demo#prometheus-configuration---adding-scrape-configs)\n        * Try the [practise-exercise](https://github.com/znsio/perfiz-demo/tree/practise-exercise) to integrated Perfiz into this demo project from scratch\n* Stopping Perfiz\n    * To stop Perfiz run below command\n    ```shell script\n    $PERFIZ_HOME/perfiz.sh stop\n    ```\n    * To stop PetStore REST API, run below command\n    ```shell script\n    docker-compose down\n    ```\n  \n## Explanation\n\n* Demo App - PetStore REST API - ```./app``` and ```./docker-compose.yml```\n  * The REST API is a stub server that runs with the help of an interesting project called [specmatic](https://github.com/znsio/specmatic)\n  * I have Dockerised this into a simple docker-compose to get you going quickly\n* Karate Features - ```./karate-features```\n  * API Tests for the above project\n* Perfiz Configuration - ```./perfiz.yml```\n  * This file leverages the Karate API test as a load test script\n  * It also defines the Gatling simulation name and the load pattern\n  * Please [Perfiz Config Syntax](https://perfiz.com/perfiz-config-syntax.html) for detailed syntax documentation\n\n## Prometheus Configuration - Adding Scrape Configs\n\nAs an example we will see how to read JVM metrics and setup a Grafana Dashboard for the same.\nHowever, these steps are applicable to any Prometheus compatible metrics.\n\n* **JMX Metrics for Petstore Application**\n    * The example application running on [http://localhost:9999](http://localhost:9999/pets/1) is setup with [JMX Exporter](https://github.com/prometheus/jmx_exporter) and publishes metrics that can be read by Prometheus\n    * These metrics are available on [http://localhost:8089/metrics](http://localhost:8089/metrics)\n* **Prometheus Configuration**\n    * Now we need to add the scrape configs for the above URL in ```prometheus.yml```\n        * All custom Perfiz configurations are inside the [perfiz folder](https://github.com/znsio/perfiz-demo/tree/main/perfiz)\n        * Inside this prometheus configurations are inside the [prometheus folder](https://github.com/znsio/perfiz-demo/tree/main/perfiz/prometheus)\n        * The ```prometheus.yml``` file has job named ```java``` which reads the JVM metrics\n    * Prometheus is part of the Perfiz stack. You will be able to access the ```jvm_*``` metrics on [Prometheus Expression Browser](http://localhost:9090/graph)\n\n## Grafana Dashboards - Adding JVM Dashboard\nLet us now setup a dashboard to visualise the above JMX metrics\n    \n* I have downloaded the JSON for the popular [JVM dashboard](https://grafana.com/grafana/dashboards/8563) and have saved it inside [dashboards folder](https://github.com/znsio/perfiz-demo/tree/main/perfiz/dashboards)\n* Perfiz automatically loads this Dashboard to Grafana at startup\n* You can access this dashboard on [Grafana](http://localhost:3000/d/chanjarster-jvm-dashboard/jvm-dashboard)\n* To add other [Official Community Built Dashboards](https://grafana.com/grafana/dashboards)\n    * Download and save JSON to ```\u003cyour project root dir\u003e/perfiz/dashboards```\n    * Perfiz will pick it up at startup and load it into Grafana\n    * This way you will also be able to checkin these JSONs to your version control and share it with your team\n    * Example: [JVM Dashboard](https://github.com/znsio/perfiz-demo/blob/main/perfiz/dashboards/jvm-dashboard_rev17.json)\n* Custom / Modified Dashboards\n    * We often have to customize dashboards as per our project context\n    * After making these changes save the [JSON Model](https://grafana.com/docs/grafana/latest/dashboards/json-model/) to ```\u003cyour project root dir\u003e/perfiz/dashboards```\n\n## Setting \"karate.env\"\n\n* In our sample [karate-config.js](https://github.com/znsio/perfiz-demo/blob/main/karate-features/karate-config.js) located in karate-features folder we have a default env \"dev\" and other env such as \"stage\" and \"e2e\"\n* 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\n* We can run perfiz with this configuration by passing the specific config file \n```shell script\n    $PERFIZ_HOME/perfiz.sh test perfiz-staging-load-test.yml\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fznsio%2Fperfiz-demo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fznsio%2Fperfiz-demo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fznsio%2Fperfiz-demo/lists"}