diff --git a/CHANGELOG.md b/CHANGELOG.md index 240123e..27f6a2e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,15 @@ 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}`, + `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. @@ -34,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 2684635..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" ``` @@ -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/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/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 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" },