promtext-cli 0.1.0__tar.gz

promtext_cli-0.1.0/.github/workflows/lint.yaml

@@ -0,0 +1,14 @@
+---
+name: Lint
+on:
+  push:
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - run: pipx install hatch
+      - run: hatch run ci:check
+      - run: hatch run ci:lint

promtext_cli-0.1.0/.github/workflows/publish.yaml

@@ -0,0 +1,87 @@
+name: Publish Python 🐍 distribution 📦 to PyPI and TestPyPI
+# based on https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows
+
+on: push
+
+jobs:
+  build:
+    name: Build distribution 📦
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0  # fetch all history for tags, allowing to build proper dev version
+    - run: pipx install hatch
+    - run: hatch build
+    - name: Store the distribution packages
+      uses: actions/upload-artifact@v3
+      with:
+        name: python-package-distributions
+        path: dist/
+
+  publish-to-pypi:
+    name: >-
+      Publish Python 🐍 distribution 📦 to PyPI
+    if: startsWith(github.ref, 'refs/tags/') || github.ref == 'refs/heads/main' # only publish to PyPI on tag pushes or dev version for main
+    needs:
+    - build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/promtext-cli
+    permissions:
+      id-token: write  # IMPORTANT: mandatory for trusted publishing
+
+    steps:
+    - name: Download all the dists
+      uses: actions/download-artifact@v3
+      with:
+        name: python-package-distributions
+        path: dist/
+    - name: Publish distribution 📦 to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: >-
+      Sign the Python 🐍 distribution 📦 with Sigstore
+      and upload them to GitHub Release
+    if: startsWith(github.ref, 'refs/tags/')  # only publish to PyPI on tag pushes
+    needs:
+    - publish-to-pypi
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write  # IMPORTANT: mandatory for making GitHub Releases
+      id-token: write  # IMPORTANT: mandatory for sigstore
+
+    steps:
+    - name: Download all the dists
+      uses: actions/download-artifact@v3
+      with:
+        name: python-package-distributions
+        path: dist/
+    - name: Sign the dists with Sigstore
+      uses: sigstore/gh-action-sigstore-python@v1.2.3
+      with:
+        inputs: >-
+          ./dist/*.tar.gz
+          ./dist/*.whl
+    - name: Create GitHub Release
+      env:
+        GITHUB_TOKEN: ${{ github.token }}
+      run: >-
+        gh release create
+        '${{ github.ref_name }}'
+        --repo '${{ github.repository }}'
+        --notes ""
+    - name: Upload artifact signatures to GitHub Release
+      env:
+        GITHUB_TOKEN: ${{ github.token }}
+      # Upload to GitHub Release using the `gh` CLI.
+      # `dist/` contains the built packages, and the
+      # sigstore-produced signatures and certificates.
+      run: >-
+        gh release upload
+        '${{ github.ref_name }}' dist/**
+        --repo '${{ github.repository }}'

promtext_cli-0.1.0/.gitignore

@@ -0,0 +1,3 @@
+tmp/
+/dist
+__pycache__

promtext_cli-0.1.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.3
+Name: promtext-cli
+Version: 0.1.0
+Summary: Prometheus Textfile Tooling
+Project-URL: Issues, https://github.com/margau/promtext-cli/issues
+Project-URL: Source, https://github.com/margau/promtext-cli
+Author-email: margau <dev@marvingaube.de>
+License-Expression: GPL-3.0
+Keywords: Prometheus
+Requires-Python: >=3.7
+Requires-Dist: prometheus-client
+Description-Content-Type: text/markdown
+
+# promtext-cli
+
+promtext-cli is a tool for creating prometheus text files from a simple cli command.
+
+It is intended for use with cronjob scripts (e.g. backups).
+
+Features:
+- supports merging new metrics into existing files
+- metrics will be updated (same labelset or no labels given), or appended to existing metrics as new timeseries
+- currently only supports gauge metrics
+
+## Usage
+```
+promtext -h
+usage: main.py [-h] [--docs DOCS] [--label KEY=VALUE] [-v] filename metric value
+
+Prometheus textfile helper
+
+positional arguments:
+  filename           Path to existing or new prometheus textfile, will be updated
+  metric             metric name (new or updated)
+  value              metric value
+
+options:
+  -h, --help         show this help message and exit
+  --docs DOCS        metric documentation
+  --label KEY=VALUE  label key=value pairs
+  -v, --verbose
+```
+
+## Examples
+`tmp/backup.prom` before:
+```
+# HELP backup_last_start 
+# TYPE backup_last_start gauge
+backup_last_start{backup="example_1"} 1.721923501e+09
+# HELP backup_last_end 
+# TYPE backup_last_end gauge
+backup_last_end{backup="example_1"} 1.721989156e+09
+# HELP backup_last_exit 
+# TYPE backup_last_exit gauge
+backup_last_exit{backup="example_1"} 2.0
+```
+
+Updating existing timeseries: `promtext tmp/backup.prom backup_last_start 0 --label backup=example_1`:
+```
+# HELP backup_last_start 
+# TYPE backup_last_start gauge
+backup_last_start{backup="example_1"} 0.0
+# HELP backup_last_end 
+# TYPE backup_last_end gauge
+backup_last_end{backup="example_1"} 1.721989156e+09
+# HELP backup_last_exit 
+# TYPE backup_last_exit gauge
+backup_last_exit{backup="example_1"} 2.0
+```
+
+Adding a new label: `promtext tmp/backup.prom backup_last_start 0 --label backup=example_2`
+```
+# HELP backup_last_start 
+# TYPE backup_last_start gauge
+backup_last_start{backup="example_1"} 0.0
+backup_last_start{backup="example_2"} 0.0
+# HELP backup_last_end 
+# TYPE backup_last_end gauge
+backup_last_end{backup="example_1"} 1.721989156e+09
+# HELP backup_last_exit 
+# TYPE backup_last_exit gauge
+backup_last_exit{backup="example_1"} 2.0
+```
+
+Adding a new metric: `promtext tmp/backup.prom some_other_state 0 --label new_label=foo_bar`
+```
+# HELP backup_last_start 
+# TYPE backup_last_start gauge
+backup_last_start{backup="example_1"} 0.0
+backup_last_start{backup="example_2"} 0.0
+# HELP backup_last_end 
+# TYPE backup_last_end gauge
+backup_last_end{backup="example_1"} 1.721989156e+09
+# HELP backup_last_exit 
+# TYPE backup_last_exit gauge
+backup_last_exit{backup="example_1"} 2.0
+# HELP some_other_state metric appended by promtext-cli
+# TYPE some_other_state gauge
+some_other_state{new_label="foo_bar"} 0.0
+```
+
+However, changing the label keys does not work:
+```
+promtext tmp/backup.prom some_other_state 0 --label foo_bar=foo_bar  
+ERROR:promtext_cli.main:labelnames for metric some_other_state not compatible, cannot update! Old: ['new_label'], New: ['foo_bar']
+```

promtext_cli-0.1.0/README.md

@@ -0,0 +1,93 @@
+# promtext-cli
+
+promtext-cli is a tool for creating prometheus text files from a simple cli command.
+
+It is intended for use with cronjob scripts (e.g. backups).
+
+Features:
+- supports merging new metrics into existing files
+- metrics will be updated (same labelset or no labels given), or appended to existing metrics as new timeseries
+- currently only supports gauge metrics
+
+## Usage
+```
+promtext -h
+usage: main.py [-h] [--docs DOCS] [--label KEY=VALUE] [-v] filename metric value
+
+Prometheus textfile helper
+
+positional arguments:
+  filename           Path to existing or new prometheus textfile, will be updated
+  metric             metric name (new or updated)
+  value              metric value
+
+options:
+  -h, --help         show this help message and exit
+  --docs DOCS        metric documentation
+  --label KEY=VALUE  label key=value pairs
+  -v, --verbose
+```
+
+## Examples
+`tmp/backup.prom` before:
+```
+# HELP backup_last_start 
+# TYPE backup_last_start gauge
+backup_last_start{backup="example_1"} 1.721923501e+09
+# HELP backup_last_end 
+# TYPE backup_last_end gauge
+backup_last_end{backup="example_1"} 1.721989156e+09
+# HELP backup_last_exit 
+# TYPE backup_last_exit gauge
+backup_last_exit{backup="example_1"} 2.0
+```
+
+Updating existing timeseries: `promtext tmp/backup.prom backup_last_start 0 --label backup=example_1`:
+```
+# HELP backup_last_start 
+# TYPE backup_last_start gauge
+backup_last_start{backup="example_1"} 0.0
+# HELP backup_last_end 
+# TYPE backup_last_end gauge
+backup_last_end{backup="example_1"} 1.721989156e+09
+# HELP backup_last_exit 
+# TYPE backup_last_exit gauge
+backup_last_exit{backup="example_1"} 2.0
+```
+
+Adding a new label: `promtext tmp/backup.prom backup_last_start 0 --label backup=example_2`
+```
+# HELP backup_last_start 
+# TYPE backup_last_start gauge
+backup_last_start{backup="example_1"} 0.0
+backup_last_start{backup="example_2"} 0.0
+# HELP backup_last_end 
+# TYPE backup_last_end gauge
+backup_last_end{backup="example_1"} 1.721989156e+09
+# HELP backup_last_exit 
+# TYPE backup_last_exit gauge
+backup_last_exit{backup="example_1"} 2.0
+```
+
+Adding a new metric: `promtext tmp/backup.prom some_other_state 0 --label new_label=foo_bar`
+```
+# HELP backup_last_start 
+# TYPE backup_last_start gauge
+backup_last_start{backup="example_1"} 0.0
+backup_last_start{backup="example_2"} 0.0
+# HELP backup_last_end 
+# TYPE backup_last_end gauge
+backup_last_end{backup="example_1"} 1.721989156e+09
+# HELP backup_last_exit 
+# TYPE backup_last_exit gauge
+backup_last_exit{backup="example_1"} 2.0
+# HELP some_other_state metric appended by promtext-cli
+# TYPE some_other_state gauge
+some_other_state{new_label="foo_bar"} 0.0
+```
+
+However, changing the label keys does not work:
+```
+promtext tmp/backup.prom some_other_state 0 --label foo_bar=foo_bar  
+ERROR:promtext_cli.main:labelnames for metric some_other_state not compatible, cannot update! Old: ['new_label'], New: ['foo_bar']
+```

promtext_cli-0.1.0/promtext_cli/main.py

@@ -0,0 +1,120 @@
+"""promtext_cli is providing a CLI to cleanly update prometheus textfiles from scripts"""
+
+import argparse
+from pathlib import Path
+import logging
+import sys
+
+from prometheus_client.parser import text_string_to_metric_families
+from prometheus_client import CollectorRegistry, Gauge, write_to_textfile
+
+def promtext():
+    # setup argpars
+    # required file first
+    parser = argparse.ArgumentParser(description='Prometheus textfile helper')
+    parser.add_argument(
+        'filename', 
+        type=str,
+        help='Path to existing or new prometheus textfile, will be updated'
+        )
+
+    # metric name, required
+    parser.add_argument(
+        'metric', 
+        type=str,
+        help='metric name (new or updated)')
+
+    # metric value as int/float, required
+    parser.add_argument('value', type=float, help='metric value')
+
+    # metric documentation as optional argument
+    parser.add_argument(
+        '--docs', type=str, 
+        help='metric documentation', default="metric appended by promtext-cli")
+
+    # labels, key-value, minimum 0, repeatable
+    parser.add_argument("--label", metavar="KEY=VALUE", help='label key=value pairs', action='append')
+
+    # log level from argparse
+    parser.add_argument(
+        '-v', '--verbose',
+        action="store_const", dest="loglevel", const=logging.INFO,
+    )
+    args = parser.parse_args()
+    logging.basicConfig(level=args.loglevel)
+    logger = logging.getLogger(__name__)
+
+    # processing: check if file is available, if yes, parse
+    textfile = Path(args.filename)
+
+    registry = CollectorRegistry()
+    metrics = {}
+
+    # check if args.filename exists with pathlib
+    if textfile.is_file():
+        for f in text_string_to_metric_families(textfile.read_text()):
+            # per metric: iterate over samples, create metric in registry
+            m = False
+            samples = []
+            for s in f.samples:
+                samples.append(s)
+            if len(samples) > 0:
+                # if we have samples, use the labelnames from them
+                labelnames = list(samples[0].labels.keys())
+                # metric-type specific init
+                if f.type == "gauge":
+                    m = Gauge(f.name, f.documentation,
+                        unit=f.unit, labelnames=labelnames, registry=registry)
+                else:
+                    # we don't support other types yet, continue in these cases
+                    logger.warning("unsupported metric type %s, dropping", f.type)
+                    continue
+                for s in samples:
+                    if len(labelnames) > 0:
+                        labelvalues = list(s.labels.values())
+                        m.labels(*labelvalues).set(s.value)
+                    else:
+                        m.set(s.value)
+                metrics[f.name] = m
+                logger.info("copy gauge metric %s with labels %s from old file",
+                    f.name, ', '.join(labelnames))
+            else:
+                logger.warning("got empty metric %s from old file, dropping", f.name)
+
+    # add new metric from commandline
+    m = False
+
+    # figure out labelkey- and values
+    labelnames = []
+    labelvalues = []
+    if args.label:
+        for lpair in args.label:
+            k, v = lpair.split("=")
+            labelnames.append(k)
+            labelvalues.append(v)
+
+    # here, we use a new metric
+    if args.metric not in metrics:
+        logger.info("adding new metric %s", args.metric)
+        m = Gauge(args.metric, args.docs, registry=registry, labelnames=labelnames)
+    else:
+        m = metrics[args.metric]
+        old_labelnames = list(m._labelnames)
+        if old_labelnames != labelnames:
+            logger.error("labelnames for metric %s not compatible, cannot update! Old: %s, New: %s",
+                args.metric, old_labelnames, labelnames)
+            sys.exit(1)
+        logger.info("updating metric %s", args.metric)
+
+    # actually set the value
+    if len(labelnames) > 0:
+        m.labels(*labelvalues).set(args.value)
+    else:
+        m.set(args.value)
+
+    # write to file
+    write_to_textfile(args.filename, registry)
+    logger.info("wrote to %s", args.filename)
+
+if __name__ == '__main__':
+    promtext()

promtext_cli-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[project]
+name = "promtext-cli"
+description = 'Prometheus Textfile Tooling'
+readme = "README.md"
+requires-python = ">=3.7"
+license = "GPL-3.0"
+keywords = [
+  "Prometheus"
+]
+authors = [
+  { name = "margau", email = "dev@marvingaube.de" }
+]
+classifiers = []
+dependencies = [
+  "prometheus_client"
+]
+dynamic = ["version"]
+
+[project.urls]
+Issues = "https://github.com/margau/promtext-cli/issues"
+Source = "https://github.com/margau/promtext-cli"
+
+[project.scripts]
+promtext = "promtext_cli.main:promtext"
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.envs.ci]
+dependencies = [
+  "pylint",
+  "ruff",
+]
+
+[tool.hatch.envs.ci.scripts]
+check = "ruff check promtext_cli"
+lint = "pylint promtext_cli || exit 0"