promql-builder


Namepromql-builder JSON
Version 0.0.3 PyPI version JSON
download
home_pageNone
SummaryLibrary to compose PromQL queries in Python.
upload_time2025-02-14 12:55:06
maintainerNone
docs_urlNone
authorGrafana Labs
requires_python>=3.11
licenseNone
keywords builder observability prometheus promql
VCS
bugtrack_url
requirements Babel brotlicffi certifi cffi charset-normalizer click colorama ghp-import idna importlib_metadata Jinja2 Markdown MarkupSafe mergedeep mkdocs mkdocs-get-deps mkdocs-material mkdocs-material-extensions mypy mypy-extensions packaging paginate pathspec platformdirs pycparser Pygments pymdown-extensions python-dateutil PyYAML pyyaml_env_tag regex requests six toml typing_extensions urllib3 watchdog zipp build
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # 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"
}
        
Elapsed time: 1.13254s