{"id":22188543,"url":"https://github.com/rishabhkailey/grafana-query-cache","last_synced_at":"2026-05-09T17:39:27.707Z","repository":{"id":218255974,"uuid":"737964372","full_name":"rishabhkailey/Grafana-Query-Cache","owner":"rishabhkailey","description":"Grafana Query Cache is an Nginx-powered proxy that accelerates dashboard loading and reduces data source load by caching query results.","archived":false,"fork":false,"pushed_at":"2024-02-20T20:20:14.000Z","size":211,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-30T00:30:30.340Z","etag":null,"topics":["cache","grafana","lua","nginx","openresty"],"latest_commit_sha":null,"homepage":"","language":"Lua","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/rishabhkailey.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-01-02T04:47:49.000Z","updated_at":"2024-02-22T14:32:21.000Z","dependencies_parsed_at":"2024-02-20T20:48:41.255Z","dependency_job_id":null,"html_url":"https://github.com/rishabhkailey/Grafana-Query-Cache","commit_stats":null,"previous_names":["rishabhkailey/grafana-query-cache"],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rishabhkailey%2FGrafana-Query-Cache","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rishabhkailey%2FGrafana-Query-Cache/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rishabhkailey%2FGrafana-Query-Cache/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rishabhkailey%2FGrafana-Query-Cache/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rishabhkailey","download_url":"https://codeload.github.com/rishabhkailey/Grafana-Query-Cache/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245344005,"owners_count":20599867,"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":["cache","grafana","lua","nginx","openresty"],"created_at":"2024-12-02T11:11:25.203Z","updated_at":"2026-05-09T17:39:22.680Z","avatar_url":"https://github.com/rishabhkailey.png","language":"Lua","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Grafana Query Cache\n\nGrafana Query Cache is an Nginx-powered proxy that accelerates dashboard loading and reduces data source load by caching query results.\n\n## Key Features:\n\n**High-Performance Caching**: Leverages Nginx's performant proxy cache for fast query response retrieval.\n\n\n**Reduced Data Source Load**: Grafana Query Cache handles duplicate queries by forwarding only the first to Grafana and serving subsequent identical requests directly from its cache, significantly reducing the load on your data source.\"\n\n**Configurable Caching**: Tailored to Your Needs\n\n* Lua-powered cache key generation for precise control over caching behavior.\n* Define cache lifecycle:\n  * Set `MAX_INACTIVE_TIME` to control how long cached items remain valid without access.\n  * Set `CACHE_EXPIRE_TIME` to enforce a maximum lifespan for cached items.\n\n**Label-Based Query Caching**: This feature allow you to configure query caching granularity by associating labels with Grafana panels and constructing specific caching rules using grafana panel selectors that target those labels.\n\n## How it works\n1. (optional) label grafana data panel using comments in query.\n![./docs/images/panel-labels-example-01.webp](./docs/images/panel-labels-example-01.webp)\n2. configure cache rules \n    ```yaml\n    # default cache config for query requests that either have no labels or whose labels don't match any of the explicitly defined cache rules\n    default:\n      enabled: true\n      acceptable_time_delta_seconds: 111\n      acceptable_time_range_delta_seconds: 11\n      acceptable_max_points_delta: 1111\n      id: default\n    # (optional) Determines the caching behavior for queries that match the panel_selector.\n    cache_rules:\n      - panel_selector:\n          datasource: timescaledb\n        cache_config:\n          enabled: true\n          acceptable_time_delta_seconds: 333\n          acceptable_time_range_delta_seconds: 33\n          acceptable_max_points_delta: 3333\n          id: timescaledb\n    ```\n3. run the grafana-query-cache\n    ```bash\n    docker run -it --network host \\\n      -e GRAFANA_SCHEME=http \\\n      -e GRAFANA_HOST=localhost:3000 \\\n      -e LISTEN=8080 \\\n      -v ./cache_rules.yaml:/etc/grafana-query-cache/cache_rules.yaml \\\n      rishabhveer/grafana-query-cache:latest\n    ```\n\n4. access grafana from the grafana-query-cache proxy http://localhost:8080.\n\n5. enjoy the performace\n\n\n## Getting Started:\n\n\n### Using Docker\nTo test Grafana Query Cache locally without a complex network setup, utilize Docker's host network mode for a streamlined experience.\n```bash\ndocker run -it --network host \\\n  -e GRAFANA_SCHEME=http \\\n  -e GRAFANA_HOST=localhost:3000 \\\n  -e LISTEN=8080 \\\n  rishabhveer/grafana-query-cache:latest\n```\nGrafana should be accessible on [http://localhost:8080/](http://localhost:8080/)\n\n\n\n### Using Docker Compose\nIntegrate Grafana Query Cache by adding the following service to your Docker Compose configuration: \n```yaml\nservices:\n  grafana-query-cache:\n    image: rishabhveer/grafana-query-cache:latest\n    environment: \n      GRAFANA_SCHEME: http\n      GRAFANA_HOST: grafana:3000\n      LISTEN: 8080\n      CACHE_RULES_FILE_PATH: /etc/grafana-query-cache/cache_rules.yaml\n    volumes:\n      - ./cache_rules.yaml:/etc/grafana-query-cache/cache_rules.yaml\n    depends_on:\n      grafana:\n        condition: service_healthy\n```\n\n### Integrating Grafana Query Cache into Your Existing Nginx Setup\n\n**Prerequisites:**\n* Nginx with Lua support: Please make sure your Nginx installation includes Lua capabilities.\n* Lua md5 package: Install the Lua md5 package, available at https://lunarmodules.github.io/md5/.\n\n**Steps:**\n1. Obtain grafana_request.lua:\n\n    Download the grafana_request.lua file from https://github.com/rishabhkailey/Grafana-Query-Cache/blob/main/grafana_request.lua.\n2. Place grafana_request.lua:\n\n    Copy the downloaded grafana_request.lua file into a directory within your Nginx's LUA_PATH.\n3. Generate Nginx configuration:\n    \n    Execute the following command to generate the necessary Nginx configuration:\n    ```bash\n    docker run -it --network host \\\n      -e GRAFANA_SCHEME=http \\\n      -e GRAFANA_HOST=localhost:3000 \\\n      -e LISTEN=8080 \\\n      rishabhveer/grafana-query-cache:latest \\\n      /opt/entrypoint.sh test -v\n    ```\n    \u003e Note: Adjust environment variables in the above command to match your specific deployment needs.\n\n4. Locate generated configuration:\n\n    Find the generated configuration in the output under the comment `# configuration file /etc/nginx/conf.d/grafana.conf`.\n\n    ![Screenshot](docs/images/generate-nginx-config.webp)\n\n5. Incorporate configuration:\n\n    Integrate the generated configuration into your Nginx setup by placing it within your /etc/nginx/conf.d directory.\n6. Restart Nginx:\n\n    After adding the configuration, restart Nginx to apply the changes.\n\n\n## Configuration\ncheck [configuration.md](./docs/configuration.md) for details.\n\n## Key Considerations \n* User Access Verification: To ensure data security, Grafana Query Cache always verifies user access permissions with Grafana for each query request, even when serving from the cache. \n* Time Range Variability:\n  * Be mindful of Grafana's potential time range variations of ±1 second.\n  * To prevent cache misses due to this behavior, choose values for `acceptable_time_range_delta_seconds` that don't evenly divide common time ranges used in your Grafana dashboards. For instance, consider using 599 instead of 600.\n  * This ensures consistent cache keys for queries with slightly differing time ranges, maximizing cache efficiency.\n\n## Ideal Scenarios for Caching:\n\n* **Relatively Static Data**: Maximize cache efficiency by using it for data sources that don't experience frequent updates.\n* **High User Volume**: Effectively handle large numbers of concurrent users with the cache, reducing the load on your data source.\n* **Resource-Intensive Queries**: Optimize performance for expensive or time-consuming queries by caching their results.\n\n## When to Avoid Caching:\n\n* **Highly Dynamic Data**: For data sources with frequent updates or real-time monitoring needs, caching might lead to outdated information and is generally not recommended.\n\n\n\n\n## Supported Data Sources\nIdeally, Grafana Query Cache should support any data source that utilizes [Grafana's Data Source Query API](https://grafana.com/docs/grafana/latest/developers/http_api/data_source/#query-a-data-source).\n\n### Tested and Verified Data Sources:\n* Prometheus\n* Timescale/Postgres\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frishabhkailey%2Fgrafana-query-cache","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frishabhkailey%2Fgrafana-query-cache","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frishabhkailey%2Fgrafana-query-cache/lists"}