___               ___  __  __         _   __ 
  / _ \ ___   ____  / _/ / / / /  ___   (_) / /_
 / ___// -_) / __/ / _/ / /_/ /  / _ \ / / / __/
/_/    \__/ /_/   /_/   \____/  /_//_//_/  \__/ 

PerfUnit

take control over application bottlenecks

Report Bug · Request Feature

About The Project

This is Java Agent which helps to take control over applications bottlenecks, expensive calls or simply control your performance SLO budget.

You can use PerfUnit in your integrations/unit/performance tests in your CI or even in run-time on testing environments.

See an example of usage with JUnit here and here

Key features:

• Limit method call count per working unit (eg HTTP request, Job run, etc)
• Limit single method call execution time
• Limit total method execution time per working unit
• Log rules violation to the console or markdown report
• Throw an exception if rule violated

Getting Started

Prerequisites

For statistic aggregation PerfUnit uses Mapped Diagnostic Context (MDC)

You need to put tracing id (for example unique HTTP request ID) to the MDC using any key.

If you use Spring Boot you can do this with Spring Cloud Sleuth or manually

Usage

1. Download the latest release from GitHub release
2. Prepare configuration (see sample below)
3. Run your application with PerfUnit agent

-javaagent:/<full_path>/perfunit-1.0.0.jar=/<full_config_path>/perfunit.yml

Configuration sample

storageLimit: 1_000_000_000  # Store last 1M calls (default 1M), specify -1 for unlimited storage (may cause out of memory)

reportPath: ./perfunit-report        # Root path for reports (default ./perfunit-report )

reporters:
  saveTraces: true                      # Save thread threads (default: true)
  periodicallySaveReportToDisk: 30000   # Save report each 30 sec (default: -1). It also save report on application exit (enabled by default)

  console:
    enable: true
    printTrace: false                   # Print stack trace when rule is violated (default: false) 

  markdown:
    enable: true

rules:
  # dev.techh.perfunit.integration.service.ExpensiveService - set shared limit to all methods' in the specified class
  # dev.techh.perfunit.integration.service.ExpensiveService#testWithArgs - set shared limit to all methods with name testWithArgs
  # dev.techh.perfunit.integration.service.ExpensiveService#testWithArgs(java.lang.String) - set limit testWithArgs with one String argument
  dev.techh.perfunit.integration.service.ExpensiveService#count5InvocationsAllowed:
     description: Method testNoArgs call to often                # Optional: text description
     allowUnknownCalls: true                                     # Optional: allow invocation without tracing id (default: true)
     allowFail: true                                             # Optional: if "fail" and quota will be reach exception will be thrown  (default: false)
     tracingKey: traceId                                         # Optional: key which be used for tracking quota usage. This key should be present in MDC (default: traceId)
     onlyPublic: true                                            # Optional: instrument only public methods (default: true)
     limit:
         # One or multiple limit can be used at the same time.
         count: 10                                   #  Numbers of call allowed
         timeSingle: 200                             #  Single call limit in msec
         timeTotal: 500                              #  Total time limit in msec

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

Distributed under the Apache License Version 2.0 License. See LICENSE.md for more information.

---