{"id":34159819,"url":"https://github.com/chalabi2/caddy-usage","last_synced_at":"2026-03-12T10:10:09.613Z","repository":{"id":297834787,"uuid":"998040889","full_name":"chalabi2/caddy-usage","owner":"chalabi2","description":"better http request metrics for caddy","archived":false,"fork":false,"pushed_at":"2025-06-07T19:25:20.000Z","size":0,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-06-07T19:32:51.556Z","etag":null,"topics":["caddy","caddy-module","caddy-plugin"],"latest_commit_sha":null,"homepage":"","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/chalabi2.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,"zenodo":null}},"created_at":"2025-06-07T18:34:27.000Z","updated_at":"2025-06-07T19:26:33.000Z","dependencies_parsed_at":"2025-06-07T19:44:16.409Z","dependency_job_id":null,"html_url":"https://github.com/chalabi2/caddy-usage","commit_stats":null,"previous_names":["chalabi2/caddy-usage"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/chalabi2/caddy-usage","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chalabi2%2Fcaddy-usage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chalabi2%2Fcaddy-usage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chalabi2%2Fcaddy-usage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chalabi2%2Fcaddy-usage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chalabi2","download_url":"https://codeload.github.com/chalabi2/caddy-usage/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chalabi2%2Fcaddy-usage/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":27747218,"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","status":"online","status_checked_at":"2025-12-15T02:00:09.782Z","response_time":96,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["caddy","caddy-module","caddy-plugin"],"created_at":"2025-12-15T08:03:21.120Z","updated_at":"2025-12-15T08:04:33.287Z","avatar_url":"https://github.com/chalabi2.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Caddy Usage Metrics Plugin\n\n[![codecov](https://codecov.io/gh/chalabi2/caddy-usage/graph/badge.svg)](https://codecov.io/gh/chalabi2/caddy-usage)\n[![Go Report Card](https://goreportcard.com/badge/github.com/chalabi2/caddy-usage)](https://goreportcard.com/report/github.com/chalabi2/caddy-usage)\n[![Go Reference](https://pkg.go.dev/badge/github.com/chalabi2/caddy-usage.svg)](https://pkg.go.dev/github.com/chalabi2/caddy-usage)\n\nA comprehensive request metrics collection plugin for Caddy that integrates with the existing caddy metrics collector to provide detailed analytics about your web server usage.\n\n\u003e [!NOTE]\n\u003e This is not an official repository of the [Caddy Web Server](https://github.com/caddyserver) organization.\n\n## Features\n\n- **Comprehensive Metrics**: Track requests by status code, method, host, path, client IP, and headers\n- **Request Analytics**: Monitor URL patterns, client behavior, and traffic sources\n- **Performance Monitoring**: Request duration histograms for performance analysis\n- **Header Tracking**: Analyze User-Agent, Referer, and other important HTTP headers\n- **Security Conscious**: Sensitive headers like Authorization are handled securely\n- **Already integrated**: Passed through caddys metrics collector\n\n## Installation\n\nBuild Caddy with this plugin using [xcaddy](https://github.com/caddyserver/xcaddy):\n\n```bash\nxcaddy build --with github.com/chalabi2/caddy-usage\n```\n\nOr add to your `xcaddy.json`:\n\n```json\n{\n  \"dependencies\": [\n    {\n      \"module\": \"github.com/chalabi2/caddy-usage\",\n      \"version\": \"latest\"\n    }\n  ]\n}\n```\n\n## Metrics Exposed\n\nThe plugin exposes the following Prometheus metrics:\n\n### `caddy_usage_requests_total`\n\n**Type:** Counter  \n**Description:** Total number of HTTP requests by status code, method, and host  \n**Labels:**\n\n- `status_code` - HTTP response status code (200, 404, 500, etc.)\n- `method` - HTTP method (GET, POST, PUT, etc.)\n- `host` - Host header value\n- `path` - URL path\n\n### `caddy_usage_requests_by_ip_total`\n\n**Type:** Counter  \n**Description:** Total number of requests by client IP address  \n**Labels:**\n\n- `client_ip` - Client's IP address (handles X-Forwarded-For, X-Real-IP)\n- `status_code` - HTTP response status code\n- `method` - HTTP method\n\n### `caddy_usage_requests_by_url_total`\n\n**Type:** Counter  \n**Description:** Total number of requests by exact URL path and query parameters  \n**Labels:**\n\n- `full_url` - Complete URL with query parameters\n- `method` - HTTP method\n- `status_code` - HTTP response status code\n\n### `caddy_usage_requests_by_headers_total`\n\n**Type:** Counter  \n**Description:** Total number of requests by specific header values  \n**Labels:**\n\n- `header_name` - Header name (User-Agent, Referer, Accept, etc.)\n- `header_value` - Header value (truncated if \u003e 100 chars)\n- `method` - HTTP method\n- `status_code` - HTTP response status code\n\n**Tracked Headers:**\n\n- User-Agent\n- Referer\n- Accept\n- Accept-Language\n- Accept-Encoding\n- Content-Type\n- Authorization (value replaced with \"present\" for security)\n- X-Forwarded-For\n- X-Real-IP\n- Origin\n\n### `caddy_usage_request_duration_seconds`\n\n**Type:** Histogram  \n**Description:** HTTP request duration in seconds  \n**Labels:**\n\n- `method` - HTTP method\n- `status_code` - HTTP response status code\n- `host` - Host header value\n\n## Configuration\n\n\u003e **Note:** Complete example configurations are available in the [`example-configs/`](example-configs/) directory.\n\n### Caddyfile\n\nSimple usage - add the `usage` directive to any site or route:\n\n```caddyfile\n{\n    # Enable Caddy's metrics system globally\n    metrics\n    admin localhost:2019\n}\n\nexample.com {\n    # Enable usage metrics collection for all requests\n    usage\n    file_server\n}\n\n# Or add to specific routes\napi.example.com {\n    usage\n\n    handle /api/* {\n        usage  # Additional tracking for API routes\n        reverse_proxy localhost:8080\n    }\n\n    handle /health {\n        usage\n        respond \"OK\" 200\n    }\n}\n```\n\n### JSON Configuration\n\n```json\n{\n  \"admin\": {\n    \"listen\": \"localhost:2019\"\n  },\n  \"metrics\": {\n    \"per_host\": true\n  },\n  \"apps\": {\n    \"http\": {\n      \"servers\": {\n        \"srv0\": {\n          \"listen\": [\":80\", \":443\"],\n          \"routes\": [\n            {\n              \"match\": [{ \"host\": [\"example.com\"] }],\n              \"handle\": [\n                {\n                  \"handler\": \"usage\"\n                },\n                {\n                  \"handler\": \"file_server\",\n                  \"root\": \"/var/www/html\"\n                }\n              ]\n            }\n          ]\n        }\n      }\n    }\n  }\n}\n```\n\n## Usage Examples\n\n### Basic Setup\n\n1. **Enable metrics in your Caddyfile:**\n\n```caddyfile\n{\n    # Enable metrics globally\n    metrics\n    admin localhost:2019\n}\n\nlocalhost {\n    usage\n    respond \"Hello World\"\n}\n```\n\n2. **Start Caddy:**\n\n```bash\n# Build with xcaddy first\nmake xcaddy-build\n\n# Or run directly (if you have the example Caddyfile)\nmake xcaddy-run\n```\n\n3. **Generate some traffic:**\n\n```bash\n# Basic requests\ncurl localhost\ncurl localhost/api\ncurl localhost/health\n\n# Test with different headers\ncurl -H 'User-Agent: MyBot/1.0' localhost\ncurl -H 'Authorization: Bearer test-token' localhost/api\ncurl -X POST localhost/api/users\n```\n\n4. **View metrics:**\n\n```bash\n# View all usage metrics\ncurl localhost:2019/metrics | grep caddy_usage\n\n# Or view specific metrics\ncurl -s localhost:2019/metrics | grep caddy_usage_requests_total\ncurl -s localhost:2019/metrics | grep caddy_usage_requests_by_ip\n```\n\n### Sample Metrics Output\n\n```prometheus\n# HELP caddy_usage_requests_total Total number of HTTP requests by status code, method, and host\n# TYPE caddy_usage_requests_total counter\ncaddy_usage_requests_total{host=\"localhost\",method=\"GET\",path=\"/\",status_code=\"200\"} 5\ncaddy_usage_requests_total{host=\"localhost\",method=\"GET\",path=\"/api\",status_code=\"404\"} 2\n\n# HELP caddy_usage_requests_by_ip_total Total number of requests by client IP address\n# TYPE caddy_usage_requests_by_ip_total counter\ncaddy_usage_requests_by_ip_total{client_ip=\"127.0.0.1\",method=\"GET\",status_code=\"200\"} 7\n\n# HELP caddy_usage_request_duration_seconds HTTP request duration in seconds\n# TYPE caddy_usage_request_duration_seconds histogram\ncaddy_usage_request_duration_seconds_bucket{host=\"localhost\",method=\"GET\",status_code=\"200\",le=\"0.005\"} 5\ncaddy_usage_request_duration_seconds_bucket{host=\"localhost\",method=\"GET\",status_code=\"200\",le=\"0.01\"} 7\n```\n\n### Grafana Dashboard Queries\n\nMonitor your web server with these example Prometheus queries:\n\n```promql\n# Request rate by status code\nrate(caddy_usage_requests_total[5m])\n\n# Top client IPs\ntopk(10, sum by (client_ip) (caddy_usage_requests_by_ip_total))\n\n# Most popular URLs\ntopk(10, sum by (full_url) (caddy_usage_requests_by_url_total))\n\n# Average request duration\navg(rate(caddy_usage_request_duration_seconds_sum[5m])) / avg(rate(caddy_usage_request_duration_seconds_count[5m]))\n\n# Top User-Agents\ntopk(10, sum by (header_value) (caddy_usage_requests_by_headers_total{header_name=\"User-Agent\"}))\n```\n\n## Requirements\n\n- **Caddy:** v2.7.0 or higher\n- **Go:** 1.21 or higher\n- **Prometheus:** For metrics collection (optional)\n\n## Building from Source\n\n```bash\ngit clone https://github.com/chalabi2/caddy-usage\ncd caddy-usage\nmake deps\nmake xcaddy-build\n```\n\n## Testing\n\nRun the test suite:\n\n```bash\nmake test        # Run unit tests\nmake benchmark   # Run benchmarks\nmake ci          # Run all CI checks\n```\n\n## License\n\nApache License 2.0\n\n## Bug Reports\n\nWhen reporting bugs, include:\n\n- Caddy version\n- Plugin version\n- Configuration (Caddyfile or JSON)\n- Steps to reproduce\n- Expected vs actual behavior\n- Relevant logs\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchalabi2%2Fcaddy-usage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchalabi2%2Fcaddy-usage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchalabi2%2Fcaddy-usage/lists"}