{"id":15062650,"url":"https://github.com/jrhrmsll/tsgen","last_synced_at":"2026-02-22T02:02:53.149Z","repository":{"id":65952100,"uuid":"403159198","full_name":"jrhrmsll/tsgen","owner":"jrhrmsll","description":"tsgen is a little Go program to simulate HTTP requests faults and show how Prometheus alerts based on the Multiwindow, Multi-Burn-Rate Alerts works.","archived":false,"fork":false,"pushed_at":"2023-02-18T03:38:17.000Z","size":112,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-01-22T04:33:16.542Z","etag":null,"topics":["golang","grafana","monitoring","prometheus","sre"],"latest_commit_sha":null,"homepage":"","language":"Go","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/jrhrmsll.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-09-04T21:27:23.000Z","updated_at":"2021-11-13T20:57:41.000Z","dependencies_parsed_at":"2023-05-22T12:45:37.198Z","dependency_job_id":null,"html_url":"https://github.com/jrhrmsll/tsgen","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/jrhrmsll%2Ftsgen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jrhrmsll%2Ftsgen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jrhrmsll%2Ftsgen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jrhrmsll%2Ftsgen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jrhrmsll","download_url":"https://codeload.github.com/jrhrmsll/tsgen/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243741206,"owners_count":20340423,"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":["golang","grafana","monitoring","prometheus","sre"],"created_at":"2024-09-24T23:44:07.773Z","updated_at":"2025-10-24T01:29:47.626Z","avatar_url":"https://github.com/jrhrmsll.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# tsgen\n\n`tsgen` is a little Go program to simulate HTTP requests faults and show how Prometheus alerts based on the [Multiwindow, Multi-Burn-Rate Alerts](https://sre.google/workbook/alerting-on-slos/) works.\nUsing it is easy, just define some paths, attach some faults and start to make requests.\n\n## Config\n`tsgen` requires a YAML config file to define a list of paths; each path has some faults, formed by a HTTP Status Code with an error rate.\n\ne.g.:\n```\npaths:\n  - name: hello\n    faults:\n      - code: 500\n        rate: 0.001\n      - code: 401\n        rate: 0.1\n\n  - name: world\n    faults:\n      - code: 502\n        rate: 0.005\n```\n\n## API\n\n`tsgen` has a very simple API, as follows\n\n- GET `/api/health`\n- GET `/api/faults`\n- GET `/api/config`\n- PUT `/api/paths/:path/faults/:code`\n\nThe last option is designed to changes faults errors rates at runtime, using a JSON payload\n\n```\n{\"rate\": float32}\n```\n\ne.g.:\n```\ncurl -X PUT -H \"Content-Type: application/json\" http://localhost:8080/api/paths/hello/faults/500 --data '{\"rate\": 0.1}'\n```\n\n## Usage\n\nTo build `tsgen` Docker image just run\n\n```\ndocker build -t tsgen .\n```\n\n## Examples\nThree examples are included in a directory with the same name:\n- basic\n- errors-rates\n- multi-shop\n\nAs its name points, *basic* is the most trivial, just to show how `tsgen` works.\n\nThe *errors-rates* example is designed to prove how the [Multiwindow, Multi-Burn-Rate Alerts](https://sre.google/workbook/alerting-on-slos/) works.\n\nThe last case, *multi-shop*, is intended to show how the Grafana \"Services\" dashboard is useful for multiple services when some conventions in the metrics names and labels are followed.\n\nA directory named `_common` contains common Prometheus rules (`_common/promtheus/etc`). and Grafana Dashboards (`_common/grafana/dashboards`).\n\n### Errors Rates\nAs the two other examples, a structure similar to the next is included\n\n```\n├── docker-compose.yml\n├── prometheus\n│   ├── data\n│   └── etc\n│       └── prometheus.yml\n└── tsgen\n    └── config.yml\n```\n\nTo run it go to the corresponding directory first\n```\ncd examples/errors-rates\n```\nand then execute\n```\ndocker-compose up\n```\n\nafter that, the following services will start:\n- `tsgen` at [localhost:8080](http://localhost:8080)\n- Prometheus at [localhost:9090](http://localhost:9090)\n- Grafana at [localhost:3000](http://localhost:3000)\n- Pushgateway (if included) at [localhost:9091](http://localhost:9091)\n\nTo login in Grafana use default config values\n```\nusername: admin\npassword: admin\n```\n\nThe `tsgen` config file for this example contains nine paths, following a sequence of Fibonacci numbers (from 2 to 89): `e0002pct`, `e0008pct` until `e0089pct`.\n\nFor each path, the error rate is set to 0.001, and during the simulation is changed (using the API) to a value corresponding to the sequence number divided by 100. This way the path `e0002pct` will respond with a 0.02 rate of errors while the last path fails almost all requests. The direct consequence of this is observed in the time required to trigger the corresponding alert for each path.\n\nTo start making requests a load generator is useful; in particular a Constant Throughput style is convenient to keep the number of requests stable. For this purpose https://github.com/jrhrmsll/stress is used, but other solutions are available.\n\nWith `stress` a script similar to the next could be used\n```\n#!/usr/bin/env bash\n\npaths=(\"e0002pct\" \"e0003pct\" \"e0005pct\" \"e0008pct\" \"e0013pct\" \"e0021pct\" \"e0034pct\" \"e0055pct\" \"e0089pct\")\n\nfor path in ${paths[@]}; do\n    nohup go run github.com/jrhrmsll/stress@latest -throughput 15 -duration 3h -url http://localhost:8080/${path} \u0026\ndone\n\nexit 0\n```\n\nA hour later a second script should be executed to change the error rates as was described above. Finally, when all the alerts become triggered (around 30 minutes later) a last script execution changes the errors rates to the initial values.\n\nAll these scripts are include inside the directory `examples/errors-rates/scripts` using meaningful names:\n- incident-start.sh\n- incident-stop.sh\n- run.sh\n\nBoth the \"start\" and \"stop\" scripts push a metric named `tsgen_incident_status` to Pushgateway. This is useful for some Grafana Dashboard to establish the beginning and end of errors.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjrhrmsll%2Ftsgen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjrhrmsll%2Ftsgen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjrhrmsll%2Ftsgen/lists"}