{"id":23155928,"url":"https://github.com/hyp3rd/heracles","last_synced_at":"2025-10-12T02:35:29.745Z","repository":{"id":240389473,"uuid":"802502853","full_name":"hyp3rd/heracles","owner":"hyp3rd","description":"Heracles provides a Prometheus middleware for the go-chi router. It enables the collection of HTTP request metrics such as request counts, latencies, and detailed error metrics. The middleware is highly configurable using functional options.","archived":false,"fork":false,"pushed_at":"2024-05-19T14:36:53.000Z","size":42,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-05-19T14:37:35.034Z","etag":null,"topics":["go","go-chi","golang","metrics","monitoring","prometheus","prometheus-exporter","prometheus-metrics"],"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/hyp3rd.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["hyp3rd"]}},"created_at":"2024-05-18T13:29:53.000Z","updated_at":"2024-05-20T17:50:00.511Z","dependencies_parsed_at":"2024-05-20T18:11:19.584Z","dependency_job_id":null,"html_url":"https://github.com/hyp3rd/heracles","commit_stats":null,"previous_names":["hyp3rd/heracles"],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyp3rd%2Fheracles","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyp3rd%2Fheracles/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyp3rd%2Fheracles/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyp3rd%2Fheracles/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hyp3rd","download_url":"https://codeload.github.com/hyp3rd/heracles/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247219118,"owners_count":20903370,"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":["go","go-chi","golang","metrics","monitoring","prometheus","prometheus-exporter","prometheus-metrics"],"created_at":"2024-12-17T21:11:58.878Z","updated_at":"2025-10-12T02:35:24.679Z","avatar_url":"https://github.com/hyp3rd.png","language":"Go","funding_links":["https://github.com/sponsors/hyp3rd"],"categories":[],"sub_categories":[],"readme":"# Heracles: a Prometheus Middleware for go-chi\n\n[![Go Reference](https://pkg.go.dev/badge/github.com/hyp3rd/heracles.svg)](https://pkg.go.dev/github.com/hyp3rd/heracles) [![Go](https://github.com/hyp3rd/heracles/actions/workflows/go.yml/badge.svg?branch=main)](https://github.com/hyp3rd/heracles/actions/workflows/go.yml) [![Go Report Card](https://goreportcard.com/badge/github.com/hyp3rd/heracles)](https://goreportcard.com/report/github.com/hyp3rd/heracles)  ![coverage](./coverage.svg) [![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n\n_**Prometheus was freed by the hero Heracles.**_\n\n**Heracles** provides a Prometheus middleware for the [go-chi](https://github.com/go-chi/chi) router. It enables the collection of HTTP request metrics such as request counts, latencies, and detailed error metrics. The middleware is highly configurable using functional options.\n\n## Features\n\n- **Request Count Metrics**: Track the number of HTTP requests partitioned by status code, method, and path.\n- **Latency Metrics**: Measure the latency of HTTP requests.\n- **Detailed Error Metrics**: Track detailed client and server error metrics.\n- **Request Size Metrics**: Collect request size metrics.\n- **Response Size Metrics**: Collect response size metrics.\n- **Custom Labels**: Add custom labels to metrics.\n- **Configurable Buckets**: Configure latency histogram buckets.\n\n## Installation\n\n```bash\ngo get github.com/hyp3rd/heracles\n```\n\n## Usage\n\n### Configuration\n\nThe Prometheus middleware can be configured using functional options. The following options are available:\n\n- `WithRequestsEnabled`: Enable request count metrics. Default: `false`.\n- `WithLatencyEnabled`: Enable latency metrics. Default: `false`.\n- `WithCustomLabels`: Add custom labels to metrics.\n- `WithLatencyBuckets`: Configure latency histogram buckets.\n- `WithRequestSizeEnabled`: Enable the collection of request size metrics. Default: `false`.\n- `WithResponseSizeEnabled`: Enable the collection of response size metrics. Default: `false`.\n\n### Example\n\n```go\npackage main\n\nimport (\n    \"net/http\"\n    \"github.com/go-chi/chi/v5\"\n    \"github.com/hyp3rd/heracles/v1\"\n    \"github.com/prometheus/client_golang/prometheus\"\n    \"github.com/prometheus/client_golang/prometheus/promhttp\"\n)\n\nfunc main() {\n    r := chi.NewRouter()\n\n    // Create a new Prometheus middleware instance with custom options\n    promMiddleware, err := heracles.NewMiddleware(\n        \"my_service\",\n        heracles.WithRequestsEnabled(),\n        heracles.WithLatencyEnabled(),\n        heracles.WithCustomLabels(\"X-Request-ID\"),\n        heracles.WithLatencyBuckets([]float64{0.1, 0.5, 1.0, 2.5, 5.0}),\n    )\n    if err != nil {\n        panic(err)\n    }\n\n    reg := prometheus.NewRegistry()\n    reg.MustRegister(promMiddleware.Collectors()...)\n\n    // Register the middleware\n    r.Use(promMiddleware.Handler)\n\n    // Define your routes\n    r.Get(\"/\", func(w http.ResponseWriter, r *http.Request) {\n        w.Write([]byte(\"Hello, World!\"))\n    })\n\n    r.Handle(\"/metrics\", promhttp.HandlerFor(reg, promhttp.HandlerOpts{}))\n\n    http.ListenAndServe(\":8080\", r)\n}\n```\n\n## Metrics\n\nThe middleware exposes the following metrics:\n\n- **chi_requests_total**: The total number of HTTP requests partitioned by status code, method, and path.\n- **chi_request_duration_seconds**: The duration of HTTP requests in seconds partitioned by status code, method, and path.\n- **chi_detailed_errors_total**: Detailed error counts partitioned by type (client_error, server_error), status code, method, and path.\n\n## Registering Collectors\n\nTo register the collectors with the default Prometheus registerer:\n\n```go\npromMiddleware.MustRegisterDefault()\n```\n\nIf you are using a custom Prometheus registerer, you can retrieve the collectors and register them manually:\n\n```go\ncollectors := promMiddleware.Collectors()\nfor _, collector := range collectors {\n    prometheus.MustRegister(collector)\n}\n```\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Contributing\n\nContributions are welcome. Please open an issue or submit a pull request for any bugs, improvements, or feature requests.\n\n## Author\n\nI'm a surfer, a trader, and a software architect with 15 years of experience designing highly available distributed production environments and developing cloud-native apps in public and private clouds. Just your average bloke. Feel free to connect with me on LinkedIn, but no funny business.\n\n[![LinkedIn](https://img.shields.io/badge/LinkedIn-0077B5?style=for-the-badge\u0026logo=linkedin\u0026logoColor=white)](https://www.linkedin.com/in/francesco-cosentino/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyp3rd%2Fheracles","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhyp3rd%2Fheracles","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyp3rd%2Fheracles/lists"}