{"id":13461392,"url":"https://github.com/pyrra-dev/pyrra","last_synced_at":"2025-05-14T11:12:52.859Z","repository":{"id":36952172,"uuid":"363204786","full_name":"pyrra-dev/pyrra","owner":"pyrra-dev","description":"Making SLOs with Prometheus manageable, accessible, and easy to use for everyone!","archived":false,"fork":false,"pushed_at":"2025-03-13T01:53:28.000Z","size":22823,"stargazers_count":1334,"open_issues_count":112,"forks_count":113,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-03-13T02:03:19.828Z","etag":null,"topics":["docker","golang","kubernetes","metrics","monitoring","prometheus","slo","thanos","time-series"],"latest_commit_sha":null,"homepage":"https://demo.pyrra.dev","language":"Go","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/pyrra-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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-04-30T16:52:40.000Z","updated_at":"2025-03-12T15:21:05.000Z","dependencies_parsed_at":"2023-10-24T13:41:25.933Z","dependency_job_id":"3eb987b1-da80-4c8f-afec-3b7d3bf63fef","html_url":"https://github.com/pyrra-dev/pyrra","commit_stats":{"total_commits":1113,"total_committers":50,"mean_commits":22.26,"dds":0.5453728661275832,"last_synced_commit":"bcfded5156244ee412a5d4a72b6688bc2fb88851"},"previous_names":[],"tags_count":40,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyrra-dev%2Fpyrra","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyrra-dev%2Fpyrra/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyrra-dev%2Fpyrra/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyrra-dev%2Fpyrra/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pyrra-dev","download_url":"https://codeload.github.com/pyrra-dev/pyrra/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248420024,"owners_count":21100293,"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":["docker","golang","kubernetes","metrics","monitoring","prometheus","slo","thanos","time-series"],"created_at":"2024-07-31T11:00:37.650Z","updated_at":"2025-04-11T14:38:48.654Z","avatar_url":"https://github.com/pyrra-dev.png","language":"Go","funding_links":[],"categories":["Go","11. Tools","monitoring","Observability","Tools","📊 SLIs, SLOs e SLAs"],"sub_categories":["SLO Management","Ferramentas"],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"ui/src/logo.svg\" alt=\"Pyrra: SLOs with Prometheus\" height=\"75\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003eMaking SLOs with Prometheus manageable, accessible, and easy to use for everyone!\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\u003cimg src=\"docs/screenshot-readme.png\" width=700 alt=\"Screenshot of Pyrra\"\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\u003ca href=\"https://github.com/pyrra-dev/pyrra/tree/main/examples/grafana\"\u003eDashboards\u003c/a\u003e to visualize SLOs in Grafana:\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\u003cimg src=\"examples/grafana/detail.png\" width=700 alt=\"Pyrra Grafana dashboard\"\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003eWatch the 5min lightning talk at Prometheus Day 2022:\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.youtube.com/watch?v=8Ox0M6HIE3w\"\u003e\n    \u003cimg src=\"docs/youtube.jpg\" width=700 alt=\"PrometheusDay 2022: Lightning Talk Pyrra\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n## Features\n\n- Support for Kubernetes, Docker, and reading from the filesystem\n- Alerting: Generates 4 Multi Burn Rate Alerts with different severity\n- Page listing all Service Level Objectives\n  - Search through names and labels\n  - Sorted by remaining error budget to see the worst ones quickly\n  - All columns sortable\n  - View and hide individual columns\n  - Clicking on labels to filter SLOs that contain the label  \n  - Tool-tips when hovering for extra context\n- Page with details for a Service Level Objective\n  - Objective, Availability, Error Budget highlighted as 3 most important numbers\n  - Graph to see how the error budget develops over time\n  - Time range picker to change graphs\n  - Switch between absolute and relative chart scales\n  - Request, Errors, Duration (RED) graphs for the underlying service\n  - Multi Burn Rate Alerts overview table\n- Caching of Prometheus query results\n- Thanos: Disabling of partial responses and downsampling to 5m and 1h\n- connect-go and connect-web generate protobuf APIs\n- Grafana dashboard via `--generic-rules` generation\n\n## Feedback \u0026 Support\n\nIf you have any feedback, please open a discussion in the GitHub Discussions of this project.  \nWe would love to learn what you think!\n\n## Demo\n\nCheck out our live demo on [demo.pyrra.dev](https://demo.pyrra.dev)!  \nGrafana dashboards are available as demo on [demo.pyrra.dev/grafana](https://demo.pyrra.dev/grafana/d/ccssRIenz/pyrra-detail?orgId=1\u0026refresh=10s\u0026from=now-7d\u0026to=now)!\n\nFeel free to give it a try there!\n\n## How It Works\n\nThere are three components of Pyrra, all of which work through a single binary:\n\n- The UI displays SLOs, error budgets, burn rates, etc.\n- The API delivers information about SLOs from a backend (like Kubernetes) to the UI.\n- A backend watches for new SLO objects and then creates Prometheus recording rules for each.\n  - For Kubernetes, there is a Kubernetes Operator available\n  - For everything else, there is a filesystem-based Operator available\n\nFor the backend/operator to do its work, an SLO object has to be provided in\nYAML-format:\n\n```yaml\napiVersion: pyrra.dev/v1alpha1\nkind: ServiceLevelObjective\nmetadata:\n  name: pyrra-api-errors\n  namespace: monitoring\n  labels:\n    prometheus: k8s\n    role: alert-rules\n    pyrra.dev/team: operations # Any labels prefixed with 'pyrra.dev/' will be propagated as Prometheus labels, while stripping the prefix.\nspec:\n  target: \"99\"\n  window: 2w\n  description: Pyrra's API requests and response errors over time grouped by route.\n  indicator:\n    ratio:\n      errors:\n        metric: http_requests_total{job=\"pyrra\",code=~\"5..\"}\n      total:\n        metric: http_requests_total{job=\"pyrra\"}\n      grouping:\n        - route\n```\n\nDepending on your mode of operation, this information is provided through an\nobject in Kubernetes, or read from a static file.\n\nIn order to calculate error budget burn rates, Pyrra will then proceed to create\n[Prometheus recording rules](https://prometheus.io/docs/prometheus/latest/configuration/recording_rules/#recording-rules)\nfor each SLO.\n\nThe following rules would be created for the above example:\n\n```\nhttp_requests:increase2w\n\nhttp_requests:burnrate3m\nhttp_requests:burnrate15m\nhttp_requests:burnrate30m\nhttp_requests:burnrate1h\nhttp_requests:burnrate3h\nhttp_requests:burnrate12h\nhttp_requests:burnrate2d\n```\n\nThe recording rules names are based on the originally provided metric.\nThe recording rules contain the necessary labels to uniquely identify the recording rules in case there are multiple ones available.\n\n### Running inside a Kubernetes cluster\n\n\u003e An example for this mode of operation can be found in [examples/kubernetes](examples/kubernetes).\n\n\u003cimg src=\"docs/architecture-kubernetes.png\" alt=\"Kubernetes Architecture\" height=\"300\"\u003e\n\nHere two deployments are needed: one for the API / UI and one for the\noperator. For the first deployment, start the binary with the `api` argument.\n\nWhen starting the binary with the `kubernetes` argument, the service will watch\nthe apiserver for `ServiceLevelObjectives`. Once a new SLO is picked up,\nPyrra will create [PrometheusRule](https://prometheus-operator.dev/docs/operator/design/#prometheusrule)\nobjects that are automatically picked up by the [Prometheus Operator](https://prometheus-operator.dev).\n\nIf you're unable to run the Prometheus Operator inside your cluster, you can add\nthe `--config-map-mode=true` flag after the `kubernetes` argument. This will\nsave each recording rule in a separate `ConfigMap`.\n\n#### Applying YAML\n\nThis repository contains generated YAML files in the [examples/kubernetes/manifests](examples/kubernetes/manifests) folder.\nYou can use the following commands to deploy them to a cluster right away.\n\n```bash\nkubectl apply --server-side -f ./example/kubernetes/manifests/setup\nkubectl apply --server-side -f ./example/kubernetes/manifests\nkubectl apply --server-side -f ./example/kubernetes/manifests/slos\n```\n\n##### Applying YAML and validating webhooks via cert-manager\n\nThis repository contains more generated YAML files in the [examples/kubernetes/manifests-webhook](examples/kubernetes/manifests-webhook) folder.\n\nThis example deployment additionally applies and self-sign Issuer and requests a certificate via cert-manager,\nso that the Kubernetes APIServer can connect to Pyrra to validate any configuration object before applying it to the cluster.\n\n```bash\nkubectl apply --server-side -f ./example/kubernetes/manifests-webhook/setup\nkubectl apply --server-side -f ./example/kubernetes/manifests-webhook\nkubectl apply --server-side -f ./example/kubernetes/manifests-webhook/slos\n```\n\n##### kube-prometheus\n\nThe underlying jsonnet code is imported by the [kube-prometheus](https://github.com/prometheus-operator/kube-prometheus) project. \nIf you want to install an entire monitoring stack including Pyrra we highly recommend using kube-prometheus.\n\n#### Install with Helm\n\nThanks to [@rlex](https://github.com/rlex) there is a [Helm chart](https://artifacthub.io/packages/helm/rlex/pyrra) for deploying Pyrra too. \n\n### Running inside Docker / Filesystem\n\n\u003e An example for this mode of operation can be found in [examples/docker-compose](examples/docker-compose).\n\n\u003cimg src=\"docs/architecture-filesystem.png\" alt=\"Filesystem Architecture\" height=\"300\"\u003e\n\nYou can easily start Pyrra on its own via the provided Docker image:\n\n```bash\ndocker pull ghcr.io/pyrra-dev/pyrra:v0.7.0\n```\n\nWhen running Pyrra outside of Kubernetes, the SLO object can be provided through\na YAML file read from the file system. For this, one container or binary needs to\nbe started with the `api` argument and the reconciler with the `filesystem`\nargument.\n\nHere, Pyrra will save the generated recording rules to disk where they can be\npicked up by a Prometheus instance. While running Pyrra on its own works, there\nwon't be any SLO configured, nor will there be any data from a Prometheus to\nwork with. It's designed to work alongside a Prometheus.\n\n## Tech Stack\n\n**Client:** TypeScript with React, Bootstrap, and uPlot.\n\n**Server:** Go with libraries such as: chi, ristretto, xxhash, client-go.\n\nGenerated protobuf APIs with connect-go for Go and connect-web for TypeScript. \n\n## Roadmap\n\nBest to check the [Projects board](https://github.com/pyrra-dev/pyrra/projects) and if you cannot find what you're looking for feel free to open an issue!\n\n## Contributing\n\nContributions are always welcome!\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for ways to get started.\n\nPlease adhere to this project's `code of conduct`.\n\n## Maintainers\n\n| Name           | Area        | GitHub                                             | Twitter                                             | Company       |\n| :------------- | :---------- | :------------------------------------------------- | :-------------------------------------------------- | :------------ |\n| Nadine Vehling | UX/UI       | [@nadinevehling](https://github.com/nadinevehling) | [@nadinevehling](https://twitter.com/nadinevehling) | Grafana Labs  |\n| Matthias Loibl | Engineering | [@metalmatze](https://github.com/metalmatze)       | [@metalmatze](https://twitter.com/MetalMatze)       | Polar Signals |\n\nWe are mostly maintaining Pyrra in our free time.\n\n## Acknowledgements\n\n[@aditya-konarde](https://github.com/aditya-konarde),\n[@brancz](https://github.com/brancz),\n[@cbrgm](https://github.com/cbrgm),\n[@codesome](https://github.com/codesome),\n[@ekeih](https://github.com/ekeih),\n[@guusvw](https://github.com/guusvw),\n[@jzelinskie](https://github.com/jzelinskie),\n[@kakkoyun](https://github.com/kakkoyun),\n[@lilic](https://github.com/lilic),\n[@markusressel](https://github.com/markusressel),\n[@morremeyer](https://github.com/morremeyer),\n[@mxinden](https://github.com/mxinden),\n[@numbleroot](https://github.com/numbleroot),\n[@paulfantom](https://github.com/paulfantom),\n[@RiRa12621](https://github.com/RiRa12621),\n[@tboerger](https://github.com/tboerger),\nand Maria Franke.\n\nWhile we were working on Pyrra in private these amazing people helped us with a look of feedback and some even took an extra hour for a in-depth testing! Thank you all so much!\n\nAdditionally, [@metalmatze](https://github.com/metalmatze) would like to thank [Polar Signals](https://www.polarsignals.com/) for allowing us to work on this project in his 20% time.\n\n## FAQ\n\n#### Why not use Grafana in this particular use case?\n\nRight now we could have used Grafana indeed. In upcoming releases, we plan to add more interactive features to give you better context when coming up with new SLOs. This is something we couldn't do with Grafana.\n\n#### Do I still need Grafana?\n\nYes, Grafana is an amazing data visualization tool for Prometheus metrics. You can create your own custom dashboards and dive a lot deeper into each component while debugging.\n\n#### Does it work with Thanos too?\n\nYes, in fact I've been developing this against my little Thanos cluster most of the time.  \nThe queries even dynamically add headers for downsampling and disable partial responses.\n\n#### How many instances should I deploy?\n\nIt depends on the topology of your infrastructure, however, we think that alerting should still happen within each individual Prometheus and therefore running one instance with one Prometheus (pair) makes the most sense. Pyrra itself only needs one instance per Prometheus (pair).\n\n#### Why don't you support more complex SLOs?\n\nFor now, we try to accomplish an easy-to-setup workflow for the most common SLOs.\nIt is still possible to write these more complex SLOs manually and deploy them to Prometheus along those generated.\nYou can base more complex SLOs on the output of one SLO from this tool.\n\n#### Why is the objective target a string not a float?\n\n[Kubebuilder doesn't support floats in CRDs](https://github.com/kubernetes-sigs/controller-tools/issues/245)...  \nTherefore, we need to pass it as string and internally convert it from string to float64.\n\n## Related\n\nHere are some related projects:\n\n- [slok/sloth](https://github.com/slok/sloth)\n- [metalmatze/slo-libsonnet](https://github.com/metalmatze/slo-libsonnet)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpyrra-dev%2Fpyrra","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpyrra-dev%2Fpyrra","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpyrra-dev%2Fpyrra/lists"}