# PromQL builder
A set of libraries for writing and composing PromQL queries as-code in Go,
Python or Typescript.
## Go
```go
package main
import (
"fmt"
"github.com/grafana/promql-builder/go/promql"
)
// time() - demo_batch_last_success_timestamp_seconds > 3600
func batchJobsWithNoSuccessInLastHour() *promql.BinaryExprBuilder {
return promql.Gt(
promql.Sub(
promql.Time(),
promql.Vector("demo_batch_last_success_timestamp_seconds"),
),
promql.N(3600),
)
}
// method_code:http_errors:rate5m{code="500"} / ignoring(code) method:http_requests:rate5m
func errorRatioPerHTTPMethod() *promql.BinaryExprBuilder {
return promql.Div(
promql.Vector("method_code:http_errors:rate5m").Label("code", "500"),
promql.Vector("method:http_requests:rate5m"),
).Ignoring([]string{"code"})
}
// sum by(device) (node_filesystem_free_bytes)
func freeDiskSpacePerDevice() *promql.AggregationExprBuilder {
return promql.Sum(
promql.Vector("free_disk_space_per_device"),
).By([]string{"device"})
}
// 90th percentile request latency over last 5 minutes per path and method
// histogram_quantile(0.9, sum by(le, path, method) (
// rate(demo_api_request_duration_seconds_bucket[5m])
// ))
func requestLatency90thPercentilePerPathAndMethod() *promql.FuncCallExprBuilder {
return promql.HistogramQuantile(0.9,
promql.Sum(
promql.Rate(
promql.Vector("demo_api_request_duration_seconds_bucket").Range("5m"),
),
).By([]string{"le", "path", "method"}),
)
}
func main() {
fmt.Println(batchJobsWithNoSuccessInLastHour().String())
fmt.Println(errorRatioPerHTTPMethod().String())
fmt.Println(freeDiskSpacePerDevice().String())
fmt.Println(requestLatency90thPercentilePerPathAndMethod().String())
}
```
## Python
```python
from promql_builder.builders.promql import (
div,
gt,
histogram_quantile,
n,
rate,
sub,
sum,
time,
vector,
)
# time() - demo_batch_last_success_timestamp_seconds > 3600
def batch_jobs_with_no_success_in_last_hour():
return gt(
sub(
time(),
vector("demo_batch_last_success_timestamp_seconds"),
),
n(3600),
)
# method_code:http_errors:rate5m{code="500"} / ignoring(code) method:http_requests:rate5m
def error_ratio_per_http_method():
return div(
vector("method_code:http_errors:rate5m").label("code", "500"),
vector("method:http_requests:rate5m"),
).ignoring(['code'])
# sum by(device) (node_filesystem_free_bytes)
def free_disk_space_per_device():
return sum(
vector("free_disk_space_per_device"),
).by(["device"])
# 90th percentile request latency over last 5 minutes per path and method
# histogram_quantile(0.9, sum by(le, path, method) (
# rate(demo_api_request_duration_seconds_bucket[5m])
# ))
def request_latency_90th_percentile_per_path_and_method():
return histogram_quantile(0.9,
sum(
rate(vector("demo_api_request_duration_seconds_bucket").range("5m")),
).by(["le", "path", "method"]),
)
if __name__ == '__main__':
print(str(batch_jobs_with_no_success_in_last_hour()))
print(str(error_ratio_per_http_method()))
print(str(free_disk_space_per_device()))
print(str(request_latency_90th_percentile_per_path_and_method()))
```
## Maturity
This project should be considered as "public preview". While it is used by
Grafana Labs, it is still under active development.
Additional information can be found in
[Release life cycle for Grafana Labs](https://grafana.com/docs/release-life-cycle/).
> [!NOTE]
> Bugs and issues are handled solely by Engineering teams. On-call support
> or SLAs are not available.
## License
[Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0)
Raw data
{
"_id": null,
"home_page": null,
"name": "promql-builder",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "builder, observability, prometheus, promql",
"author": "Grafana Labs",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/12/11/684ef9ca65f4e82bd5cc84ca48b82f966496e2f71fc855bc64adfa0761e3/promql_builder-0.0.3.tar.gz",
"platform": null,
"description": "# PromQL builder\n\nA set of libraries for writing and composing PromQL queries as-code in Go,\nPython or Typescript.\n\n## Go\n\n```go\npackage main\n\nimport (\n \"fmt\"\n\n \"github.com/grafana/promql-builder/go/promql\"\n)\n\n// time() - demo_batch_last_success_timestamp_seconds > 3600\nfunc batchJobsWithNoSuccessInLastHour() *promql.BinaryExprBuilder {\n return promql.Gt(\n promql.Sub(\n promql.Time(),\n promql.Vector(\"demo_batch_last_success_timestamp_seconds\"),\n ),\n promql.N(3600),\n )\n}\n\n// method_code:http_errors:rate5m{code=\"500\"} / ignoring(code) method:http_requests:rate5m\nfunc errorRatioPerHTTPMethod() *promql.BinaryExprBuilder {\n return promql.Div(\n promql.Vector(\"method_code:http_errors:rate5m\").Label(\"code\", \"500\"),\n promql.Vector(\"method:http_requests:rate5m\"),\n ).Ignoring([]string{\"code\"})\n}\n\n// sum by(device) (node_filesystem_free_bytes)\nfunc freeDiskSpacePerDevice() *promql.AggregationExprBuilder {\n return promql.Sum(\n promql.Vector(\"free_disk_space_per_device\"),\n ).By([]string{\"device\"})\n}\n\n// 90th percentile request latency over last 5 minutes per path and method\n// histogram_quantile(0.9, sum by(le, path, method) (\n//\trate(demo_api_request_duration_seconds_bucket[5m])\n// ))\nfunc requestLatency90thPercentilePerPathAndMethod() *promql.FuncCallExprBuilder {\n return promql.HistogramQuantile(0.9,\n promql.Sum(\n promql.Rate(\n promql.Vector(\"demo_api_request_duration_seconds_bucket\").Range(\"5m\"),\n ),\n ).By([]string{\"le\", \"path\", \"method\"}),\n )\n}\n\nfunc main() {\n fmt.Println(batchJobsWithNoSuccessInLastHour().String())\n fmt.Println(errorRatioPerHTTPMethod().String())\n fmt.Println(freeDiskSpacePerDevice().String())\n fmt.Println(requestLatency90thPercentilePerPathAndMethod().String())\n}\n```\n\n## Python\n\n```python\nfrom promql_builder.builders.promql import (\n div,\n gt,\n histogram_quantile,\n n,\n rate,\n sub,\n sum,\n time,\n vector,\n)\n\n# time() - demo_batch_last_success_timestamp_seconds > 3600\ndef batch_jobs_with_no_success_in_last_hour():\n return gt(\n sub(\n time(),\n vector(\"demo_batch_last_success_timestamp_seconds\"),\n ),\n n(3600),\n )\n\n\n# method_code:http_errors:rate5m{code=\"500\"} / ignoring(code) method:http_requests:rate5m\ndef error_ratio_per_http_method():\n return div(\n vector(\"method_code:http_errors:rate5m\").label(\"code\", \"500\"),\n vector(\"method:http_requests:rate5m\"),\n ).ignoring(['code'])\n\n\n# sum by(device) (node_filesystem_free_bytes)\ndef free_disk_space_per_device():\n return sum(\n vector(\"free_disk_space_per_device\"),\n ).by([\"device\"])\n\n\n# 90th percentile request latency over last 5 minutes per path and method\n# histogram_quantile(0.9, sum by(le, path, method) (\n#\trate(demo_api_request_duration_seconds_bucket[5m])\n# ))\ndef request_latency_90th_percentile_per_path_and_method():\n return histogram_quantile(0.9,\n sum(\n rate(vector(\"demo_api_request_duration_seconds_bucket\").range(\"5m\")),\n ).by([\"le\", \"path\", \"method\"]),\n )\n\n\nif __name__ == '__main__':\n print(str(batch_jobs_with_no_success_in_last_hour()))\n print(str(error_ratio_per_http_method()))\n print(str(free_disk_space_per_device()))\n print(str(request_latency_90th_percentile_per_path_and_method()))\n```\n\n## Maturity\n\nThis project should be considered as \"public preview\". While it is used by\nGrafana Labs, it is still under active development.\n\nAdditional information can be found in\n[Release life cycle for Grafana Labs](https://grafana.com/docs/release-life-cycle/).\n\n> [!NOTE]\n> Bugs and issues are handled solely by Engineering teams. On-call support\n> or SLAs are not available.\n\n## License\n\n[Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0)\n",
"bugtrack_url": null,
"license": null,
"summary": "Library to compose PromQL queries in Python.",
"version": "0.0.3",
"project_urls": {
"Homepage": "https://github.com/grafana/promql-builder",
"Issues": "https://github.com/grafana/promql-builder/issues",
"Repository": "https://github.com/grafana/promql-builder.git"
},
"split_keywords": [
"builder",
" observability",
" prometheus",
" promql"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "511b30d3f9ff6967e5e1fafe5017e1739219ef1aed69734758ad0fa49f9d183a",
"md5": "3d81d789513a4c516cc661085cb96db6",
"sha256": "10ced1bc36f433398d9a67584b23dec3447905dd42358fe7cff71a7db038a97e"
},
"downloads": -1,
"filename": "promql_builder-0.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3d81d789513a4c516cc661085cb96db6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 13734,
"upload_time": "2025-02-14T12:55:05",
"upload_time_iso_8601": "2025-02-14T12:55:05.277271Z",
"url": "https://files.pythonhosted.org/packages/51/1b/30d3f9ff6967e5e1fafe5017e1739219ef1aed69734758ad0fa49f9d183a/promql_builder-0.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1211684ef9ca65f4e82bd5cc84ca48b82f966496e2f71fc855bc64adfa0761e3",
"md5": "a20b35406abd5494d29087a6f8f17f6c",
"sha256": "d593f1379bc249140d74b94db653f765cf74105dc6f2527313501330a1842571"
},
"downloads": -1,
"filename": "promql_builder-0.0.3.tar.gz",
"has_sig": false,
"md5_digest": "a20b35406abd5494d29087a6f8f17f6c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 19651,
"upload_time": "2025-02-14T12:55:06",
"upload_time_iso_8601": "2025-02-14T12:55:06.283556Z",
"url": "https://files.pythonhosted.org/packages/12/11/684ef9ca65f4e82bd5cc84ca48b82f966496e2f71fc855bc64adfa0761e3/promql_builder-0.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-14 12:55:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "grafana",
"github_project": "promql-builder",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "Babel",
"specs": [
[
"==",
"2.15.0"
]
]
},
{
"name": "brotlicffi",
"specs": [
[
"==",
"1.1.0.0"
]
]
},
{
"name": "certifi",
"specs": [
[
"==",
"2024.7.4"
]
]
},
{
"name": "cffi",
"specs": [
[
"==",
"1.17.1"
]
]
},
{
"name": "charset-normalizer",
"specs": [
[
"==",
"3.3.2"
]
]
},
{
"name": "click",
"specs": [
[
"==",
"8.1.7"
]
]
},
{
"name": "colorama",
"specs": [
[
"==",
"0.4.6"
]
]
},
{
"name": "ghp-import",
"specs": [
[
"==",
"2.1.0"
]
]
},
{
"name": "idna",
"specs": [
[
"==",
"3.7"
]
]
},
{
"name": "importlib_metadata",
"specs": [
[
"==",
"7.1.0"
]
]
},
{
"name": "Jinja2",
"specs": [
[
"==",
"3.1.4"
]
]
},
{
"name": "Markdown",
"specs": [
[
"==",
"3.7"
]
]
},
{
"name": "MarkupSafe",
"specs": [
[
"==",
"2.1.5"
]
]
},
{
"name": "mergedeep",
"specs": [
[
"==",
"1.3.4"
]
]
},
{
"name": "mkdocs",
"specs": [
[
"==",
"1.6.1"
]
]
},
{
"name": "mkdocs-get-deps",
"specs": [
[
"==",
"0.2.0"
]
]
},
{
"name": "mkdocs-material",
"specs": [
[
"==",
"9.5.39"
]
]
},
{
"name": "mkdocs-material-extensions",
"specs": [
[
"==",
"1.3.1"
]
]
},
{
"name": "mypy",
"specs": [
[
"==",
"1.10.0"
]
]
},
{
"name": "mypy-extensions",
"specs": [
[
"==",
"1.0.0"
]
]
},
{
"name": "packaging",
"specs": [
[
"==",
"24.1"
]
]
},
{
"name": "paginate",
"specs": [
[
"==",
"0.5.7"
]
]
},
{
"name": "pathspec",
"specs": [
[
"==",
"0.12.1"
]
]
},
{
"name": "platformdirs",
"specs": [
[
"==",
"4.2.2"
]
]
},
{
"name": "pycparser",
"specs": [
[
"==",
"2.22"
]
]
},
{
"name": "Pygments",
"specs": [
[
"==",
"2.18.0"
]
]
},
{
"name": "pymdown-extensions",
"specs": [
[
"==",
"10.11.2"
]
]
},
{
"name": "python-dateutil",
"specs": [
[
"==",
"2.9.0.post0"
]
]
},
{
"name": "PyYAML",
"specs": [
[
"==",
"6.0.2"
]
]
},
{
"name": "pyyaml_env_tag",
"specs": [
[
"==",
"0.1"
]
]
},
{
"name": "regex",
"specs": [
[
"==",
"2024.5.15"
]
]
},
{
"name": "requests",
"specs": [
[
"==",
"2.32.3"
]
]
},
{
"name": "six",
"specs": [
[
"==",
"1.16.0"
]
]
},
{
"name": "toml",
"specs": [
[
"==",
"0.10.2"
]
]
},
{
"name": "typing_extensions",
"specs": [
[
"==",
"4.12.2"
]
]
},
{
"name": "urllib3",
"specs": [
[
"==",
"2.2.2"
]
]
},
{
"name": "watchdog",
"specs": [
[
"==",
"4.0.1"
]
]
},
{
"name": "zipp",
"specs": [
[
"==",
"3.19.2"
]
]
},
{
"name": "build",
"specs": [
[
"==",
"1.2.2.post1"
]
]
}
],
"lcname": "promql-builder"
}
JSON
