{"id":15043087,"url":"https://github.com/codahale/usl4j","last_synced_at":"2025-10-04T05:31:35.420Z","repository":{"id":57718332,"uuid":"89039751","full_name":"codahale/usl4j","owner":"codahale","description":"A reasonably complete implementation of the Universal Scalability Law model.","archived":true,"fork":false,"pushed_at":"2019-03-31T03:40:07.000Z","size":210,"stargazers_count":201,"open_issues_count":0,"forks_count":9,"subscribers_count":11,"default_branch":"master","last_synced_at":"2024-09-29T23:04:27.488Z","etag":null,"topics":["capacity-planning","java","java-8","scalability","universal-scalability-law","usl"],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/codahale.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-04-22T02:48:58.000Z","updated_at":"2024-06-25T17:16:58.000Z","dependencies_parsed_at":"2022-09-13T08:31:40.288Z","dependency_job_id":null,"html_url":"https://github.com/codahale/usl4j","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codahale%2Fusl4j","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codahale%2Fusl4j/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codahale%2Fusl4j/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codahale%2Fusl4j/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codahale","download_url":"https://codeload.github.com/codahale/usl4j/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235222543,"owners_count":18955327,"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":["capacity-planning","java","java-8","scalability","universal-scalability-law","usl"],"created_at":"2024-09-24T20:48:33.085Z","updated_at":"2025-10-04T05:31:30.116Z","avatar_url":"https://github.com/codahale.png","language":"Java","readme":"# usl4j\n\n[![CircleCI](https://circleci.com/gh/codahale/usl4j.svg?style=svg)](https://circleci.com/gh/codahale/usl4j)\n\nusl4j is Java modeler for [Dr. Neil Gunther][NJG]'s [Universal Scalability Law][USL] as described by\n[Baron Schwartz][BS] in his book [Practical Scalability Analysis with the Universal Scalability\nLaw][PSA]. \n\nGiven a handful of measurements of any two [Little's Law][LL] parameters--throughput, latency, and\nconcurrency--the [USL][USL] allows you to make predictions about any of those parameters' values\ngiven an arbitrary value for any another parameter. For example, given a set of measurements of\nconcurrency and throughput, the [USL][USL] will allow you to predict what a system's average latency\nwill look like at a particular throughput, or how many servers you'll need to process requests and\nstay under your SLA's latency requirements.\n\nThe model coefficients and predictions should be within 0.02% of those listed in the book.\n\n## Add to your project\n\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003ecom.codahale\u003c/groupId\u003e\n  \u003cartifactId\u003eusl4j\u003c/artifactId\u003e\n  \u003cversion\u003e0.7.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nIt depends on [DDogleg Numerics][DDogleg] for least-squares regression.\n\n*Note: module name for Java 9+ is `com.codahale.usl4j`.*\n\n## How to use this\n\nAs an example, consider doing load testing and capacity planning for an HTTP server. To model the\nbehavior of the system using the [USL][USL], you must first gather a set of measurements of the\nsystem. These measurements must be of two of the three parameters of [Little's Law][LL]: mean\nresponse time (in seconds), throughput (in requests per second), and concurrency (i.e. the number of\nconcurrent clients).\n\nBecause response time tends to be a property of load (i.e. it rises as throughput or concurrency\nrises), the dependent variable in your tests should be mean response time. This leaves either\nthroughput or concurrency as your independent variable, but thanks to [Little's Law][LL] it doesn't\nmatter which one you use. For the purposes of discussion, let's say you measure throughput as a\nfunction of the number of concurrent clients working at a fixed rate (e.g. you used\n[`wrk2`][wrk2]).\n\nAfter your load testing is done, you should have a set of measurements shaped like this:\n\n|concurrency|throughput|\n|-----------|----------|\n|          1|    955.16|\n|          2|   1878.91|\n|          3|   2688.01|\n|          4|   3548.68|\n|          5|   4315.54|\n|          6|   5130.43|\n|          7|   5931.37|\n|          8|   6531.08|\n\nFor simplicity's sake, let's assume you're storing this as a `double[][]`. Now you can build a model\nand begin estimating things:\n\n```java\nimport com.codahale.usl4j.Measurement;\nimport com.codahale.usl4j.Model;\nimport java.util.Arrays;\n\nclass Example {\n  void buildModel() {\n    final double[][] points = {{1, 955.16}, {2, 1878.91}, {3, 2688.01}}; // etc.\n  \n    // Map the points to measurements of concurrency and throughput, then build a model from them. \n    final Model model = Arrays.stream(points)\n                              .map(Measurement.ofConcurrency()::andThroughput)\n                              .collect(Model.toModel());\n    for (int i = 10; i \u003c 200; i+=10) {\n      System.out.printf(\"At %d workers, expect %f req/sec\\n\", i, model.throughputAtConcurrency(i));\n    }\n  }\n}\n```\n\n## Performance\n\nBuilding models is pretty fast:\n\n```\nBenchmark         (size)  Mode  Cnt   Score   Error  Units\nBenchmarks.build      10  avgt    5   0.507 ± 0.061  us/op\nBenchmarks.build     100  avgt    5   1.242 ± 0.266  us/op\nBenchmarks.build    1000  avgt    5   7.499 ± 0.157  us/op\nBenchmarks.build   10000  avgt    5  72.321 ± 2.681  us/op\n```\n\n## Further reading\n\nI strongly recommend [Practical Scalability Analysis with the Universal Scalability Law][PSA], a\nfree e-book by [Baron Schwartz][BS], author of [High Performance MySQL][MySQL] and CEO of\n[VividCortex][VC]. Trying to use this library without actually understanding the concepts behind\n[Little's Law][LL], [Amdahl's Law][AL], and the [Universal Scalability Law][USL] will be difficult\nand potentially misleading.\n\nI also [wrote a blog post about this library][usl4j].\n\n## License\n\nCopyright © 2017 Coda Hale\n\nDistributed under the Apache License 2.0.\n\n[NJG]: http://www.perfdynamics.com/Bio/njg.html\n[AL]: https://en.wikipedia.org/wiki/Amdahl%27s_law\n[LL]: https://en.wikipedia.org/wiki/Little%27s_law\n[PSA]: https://www.vividcortex.com/resources/universal-scalability-law/\n[USL]: http://www.perfdynamics.com/Manifesto/USLscalability.html\n[BS]: https://www.xaprb.com/\n[MySQL]: http://shop.oreilly.com/product/0636920022343.do\n[VC]: https://www.vividcortex.com/\n[DDogleg]: http://ddogleg.org/\n[wrk2]: https://github.com/giltene/wrk2\n[usl4j]: https://codahale.com/usl4j-and-you/","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodahale%2Fusl4j","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodahale%2Fusl4j","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodahale%2Fusl4j/lists"}