From 535b746e200ef3339cf97970740a26ec5e01903f Mon Sep 17 00:00:00 2001 From: Renato Garita Figueiredo Date: Tue, 3 Nov 2026 21:54:10 +0100 Subject: [PATCH 1/2] fix(metrics): export every labelled series from startup, at zero prometheus_client emits a labelled series only after its first observation. A freshly started adapter therefore exported no ocr_documents_total, ocr_pages_total, ocr_errors_total or ocr_page_seconds at all, and the Grafana panels built on them showed "No data" instead of zero until the next document -- in practice most of the time, since the hosts reboot for kernel updates every few days and OCR traffic is sporadic. Create the children for every known label value in Metrics.__init__: the two page sources, the document statuses a run can end in, and every error type. --- CHANGELOG.md | 7 +++++++ README.md | 3 +++ src/ocr_adapter/metrics.py | 28 ++++++++++++++++++++++++++++ tests/test_metrics.py | 14 ++++++++++++++ 4 files changed, 52 insertions(+) create mode 100644 tests/test_metrics.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 240123e..addbde7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,13 @@ All notable changes to this project are documented here. The format follows ## [Unreleased] +### Fixed + +- Every labelled series (`ocr_documents_total{status}`, `ocr_pages_total{source}`, + `ocr_errors_total{type}`, `ocr_page_seconds{source}`) is exported from startup, at zero. Before, + a series appeared only after its first observation, so a freshly (re)started adapter exported + none of them and a Grafana panel showed "No data" instead of zero until the next document. + ### Changed - The image carries the `LICENSE` file in the package metadata. diff --git a/README.md b/README.md index 2684635..cfe1d55 100644 --- a/README.md +++ b/README.md @@ -156,6 +156,9 @@ Errors are JSON `{"message", "type"}`: 400 `invalid_request`, 404 `not_found`, 4 | `ocr_page_seconds{source}` | histogram of per-page processing time | | `ocr_document_seconds` | histogram of per-document processing time | +Every labelled series exists from startup, at zero, so a restart shows as a counter reset rather +than as a gap. + Put the route behind authentication too (basic auth on the proxy, as in the Caddy example's style) before pointing a Prometheus at it. diff --git a/src/ocr_adapter/metrics.py b/src/ocr_adapter/metrics.py index 4d79773..961de55 100644 --- a/src/ocr_adapter/metrics.py +++ b/src/ocr_adapter/metrics.py @@ -6,6 +6,27 @@ generate_latest, ) +from ocr_adapter.errors import AdapterError + +# Every labelled series is created at startup, at zero. prometheus_client emits +# a labelled series only after its first observation, so a freshly started +# adapter would otherwise export no ocr_documents_total, ocr_pages_total, +# ocr_errors_total or ocr_page_seconds at all, and a dashboard would show +# "No data" instead of zero until the first document arrives. +PAGE_SOURCES = ("text", "ocr") +# "ok", the document deadline, and the errors a page task can raise +# (Pipeline.process reports the first of them as the document's status). +DOCUMENT_STATUSES = ( + "ok", + "timeout", + "client_disconnected", + "too_large", + "unprocessable", + "upstream_error", + "upstream_unavailable", +) +ERROR_TYPES = tuple(cls.type for cls in (AdapterError, *AdapterError.__subclasses__())) + class Metrics: """One registry per instance so tests never collide on metric names.""" @@ -40,6 +61,13 @@ def __init__(self, registry: CollectorRegistry | None = None): buckets=(0.5, 1, 2, 5, 10, 30, 60, 120, 300, 600, 1200), registry=r, ) + for status in DOCUMENT_STATUSES: + self.documents.labels(status=status) + for source in PAGE_SOURCES: + self.pages.labels(source=source) + self.page_seconds.labels(source=source) + for type_ in ERROR_TYPES: + self.errors.labels(type=type_) def render(self) -> bytes: return generate_latest(self.registry) diff --git a/tests/test_metrics.py b/tests/test_metrics.py new file mode 100644 index 0000000..dbcc047 --- /dev/null +++ b/tests/test_metrics.py @@ -0,0 +1,14 @@ +"""The labelled series exist from the first scrape, at zero.""" + +from ocr_adapter.metrics import Metrics + + +def test_labelled_series_exist_before_the_first_observation(): + text = Metrics().render().decode() + assert 'ocr_documents_total{status="ok"} 0.0' in text + assert 'ocr_documents_total{status="timeout"} 0.0' in text + assert 'ocr_pages_total{source="text"} 0.0' in text + assert 'ocr_pages_total{source="ocr"} 0.0' in text + assert 'ocr_page_seconds_count{source="ocr"} 0.0' in text + assert 'ocr_errors_total{type="upstream_error"} 0.0' in text + assert 'ocr_errors_total{type="internal_error"} 0.0' in text From 0cb6bfd9c8b27ad533b457db1455a174c6c6eaba Mon Sep 17 00:00:00 2001 From: Renato Garita Figueiredo Date: Tue, 3 Nov 2026 21:54:36 +0100 Subject: [PATCH 2/2] chore: release 0.1.1 --- CHANGELOG.md | 5 ++++- README.md | 4 ++-- examples/docker-compose.yml | 2 +- pyproject.toml | 2 +- uv.lock | 2 +- 5 files changed, 9 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index addbde7..27f6a2e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,8 @@ All notable changes to this project are documented here. The format follows ## [Unreleased] +## [0.1.1] - 2026-11-03 + ### Fixed - Every labelled series (`ocr_documents_total{status}`, `ocr_pages_total{source}`, @@ -41,5 +43,6 @@ Osnabrück University since 2026-10-16. - Container image `ghcr.io/virtuos/librechat-ocr-adapter` for `linux/amd64` and `linux/arm64`, installed from `uv.lock`. -[Unreleased]: https://github.com/virtUOS/librechat-ocr-adapter/compare/v0.1.0...HEAD +[Unreleased]: https://github.com/virtUOS/librechat-ocr-adapter/compare/v0.1.1...HEAD +[0.1.1]: https://github.com/virtUOS/librechat-ocr-adapter/compare/v0.1.0...v0.1.1 [0.1.0]: https://github.com/virtUOS/librechat-ocr-adapter/releases/tag/v0.1.0 diff --git a/README.md b/README.md index cfe1d55..59f1106 100644 --- a/README.md +++ b/README.md @@ -113,14 +113,14 @@ URL, `/ocr`, delete) and prints the Markdown joined like LibreChat (`# PAGE n` h raw JSON with `--json`. Page count, time and per-page sources go to stderr. ``` -uvx --from git+https://github.com/virtUOS/librechat-ocr-adapter@v0.1.0 librechat-ocr \ +uvx --from git+https://github.com/virtUOS/librechat-ocr-adapter@v0.1.1 librechat-ocr \ document.pdf --base-url https://ocr.example.org --key "$OCR_API_KEY" [--pages 115-121] [--json] ``` The same from the image: ``` -docker run --rm -v "$PWD:/data" ghcr.io/virtuos/librechat-ocr-adapter:0.1.0 \ +docker run --rm -v "$PWD:/data" ghcr.io/virtuos/librechat-ocr-adapter:0.1.1 \ librechat-ocr /data/document.pdf --base-url https://ocr.example.org --key "$OCR_API_KEY" ``` diff --git a/examples/docker-compose.yml b/examples/docker-compose.yml index e967a2a..790c253 100644 --- a/examples/docker-compose.yml +++ b/examples/docker-compose.yml @@ -34,7 +34,7 @@ services: retries: 3 ocr-adapter: - image: ghcr.io/virtuos/librechat-ocr-adapter:0.1.0 + image: ghcr.io/virtuos/librechat-ocr-adapter:0.1.1 environment: OCR_VLLM_URL: http://vllm:8000 OCR_PUBLIC_URL: https://ocr.example.org diff --git a/pyproject.toml b/pyproject.toml index 348522e..9d8c34e 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "librechat-ocr-adapter" -version = "0.1.0" +version = "0.1.1" description = "Mistral-OCR-compatible document OCR service for LibreChat on top of vLLM and LightOnOCR" readme = "README.md" license = "MIT" diff --git a/uv.lock b/uv.lock index 873a18d..7c5fb7b 100644 --- a/uv.lock +++ b/uv.lock @@ -322,7 +322,7 @@ wheels = [ [[package]] name = "librechat-ocr-adapter" -version = "0.1.0" +version = "0.1.1" source = { editable = "." } dependencies = [ { name = "fastapi" },