Metadata-Version: 2.4
Name: sgnmon
Version: 0.3.0
Summary: Monitoring and metrics for SGN streaming pipelines
Project-URL: Homepage, https://git.ligo.org/greg/sgnmon
Project-URL: Documentation, https://greg.docs.ligo.org/sgnmon
Project-URL: Repository, https://git.ligo.org/greg/sgnmon.git
Project-URL: Issues, https://git.ligo.org/greg/sgnmon/issues
Author-email: Olivia Godwin <olivia.godwin@ligo.org>
Maintainer-email: Olivia Godwin <olivia.godwin@ligo.org>
License-Expression: LGPL-3.0-or-later
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.11
Requires-Dist: gpstime
Requires-Dist: prometheus-client>=0.20
Requires-Dist: sgn-ts>=0.11
Requires-Dist: sgn>=0.12.2
Requires-Dist: starlette>=0.37
Requires-Dist: typer>=0.12
Requires-Dist: uvicorn>=0.30
Provides-Extra: dev
Requires-Dist: httpx; extra == 'dev'
Requires-Dist: markdown-callouts>=0.2; extra == 'dev'
Requires-Dist: markdown-exec>=0.5; extra == 'dev'
Requires-Dist: mkdocs-coverage>=0.2; extra == 'dev'
Requires-Dist: mkdocs-gen-files>=0.3; extra == 'dev'
Requires-Dist: mkdocs-literate-nav>=0.4; extra == 'dev'
Requires-Dist: mkdocs-material-igwn; extra == 'dev'
Requires-Dist: mkdocs-section-index>=0.3; extra == 'dev'
Requires-Dist: mkdocs>=1.3; extra == 'dev'
Requires-Dist: mkdocstrings[python]; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: mypy-extensions; extra == 'dev'
Requires-Dist: pip; extra == 'dev'
Requires-Dist: playwright; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Requires-Dist: toml>=0.10; extra == 'dev'
Provides-Extra: docs
Requires-Dist: markdown-callouts>=0.2; extra == 'docs'
Requires-Dist: markdown-exec>=0.5; extra == 'docs'
Requires-Dist: mkdocs-coverage>=0.2; extra == 'docs'
Requires-Dist: mkdocs-gen-files>=0.3; extra == 'docs'
Requires-Dist: mkdocs-literate-nav>=0.4; extra == 'docs'
Requires-Dist: mkdocs-material-igwn; extra == 'docs'
Requires-Dist: mkdocs-section-index>=0.3; extra == 'docs'
Requires-Dist: mkdocs>=1.3; extra == 'docs'
Requires-Dist: mkdocstrings[python]; extra == 'docs'
Requires-Dist: toml>=0.10; extra == 'docs'
Provides-Extra: lint
Requires-Dist: mypy; extra == 'lint'
Requires-Dist: mypy-extensions; extra == 'lint'
Requires-Dist: pip; extra == 'lint'
Requires-Dist: ruff; extra == 'lint'
Provides-Extra: test
Requires-Dist: httpx; extra == 'test'
Requires-Dist: playwright; extra == 'test'
Requires-Dist: pytest; extra == 'test'
Requires-Dist: pytest-cov; extra == 'test'
Description-Content-Type: text/markdown

<h1 align="center">sgnmon</h1>

<p align="center">Monitoring and metrics for SGN streaming pipelines</p>

<p align="center">
  <a href="https://git.ligo.org/greg/sgnmon/-/pipelines/latest">
    <img alt="ci" src="https://git.ligo.org/greg/sgnmon/badges/main/pipeline.svg" />
  </a>
  <a href="https://git.ligo.org/greg/sgnmon/-/pipelines/latest">
    <img alt="coverage" src="https://git.ligo.org/greg/sgnmon/badges/main/coverage.svg" />
  </a>
  <a href="https://greg.docs.ligo.org/sgnmon">
    <img alt="documentation" src="https://img.shields.io/badge/docs-mkdocs%20material-blue.svg?style=flat" />
  </a>
  <a href="https://pypi.org/project/sgnmon/">
    <img alt="pypi version" src="https://img.shields.io/pypi/v/sgnmon.svg" />
  </a>
</p>

---

Prometheus metrics, health checks, and a live dashboard for
[SGN](https://greg.docs.ligo.org/sgn/) pipelines, attached without
changing the pipeline graph.

* [Documentation](https://greg.docs.ligo.org/sgnmon)
* [Source Code](https://git.ligo.org/greg/sgnmon)
* [Issue Tracker](https://git.ligo.org/greg/sgnmon/-/issues)

## Installation

```
pip install sgnmon
```

## Quickstart

Any sgn application, no code changes:

```
$ sgnmon run --port 9090 -- sgn-cal --config config.yaml --model model.npz
[sgnmon] dashboard: http://localhost:9090/
```

A pipeline you build yourself:

```python
from sgnmon import Monitor, MonitorServer

monitor = Monitor()
monitor.tap(pipeline)  # observe every pad, no graph changes

with MonitorServer(monitor, port=9090):
    pipeline.run(health=monitor)  # lifecycle for /readyz and /healthz
```

From the shell:

```
$ sgnmon check http://localhost:9090   # health report; exit 0 / 1 / 2
$ sgnmon demo --port 9090              # a monitored example pipeline
```

## What you get

| | |
| --- | --- |
| **Attach** | Taps at three observation points per element (frames produced, received, and consumed after the audioadapter), in-graph `MonitorTransform`/`MonitorSink` elements, or `sgnmon run` for zero-code attach |
| **Metrics** | `/metrics`: frame and gap counts, data/gap seconds, samples, latency histograms, per-pad execution time, freshness, EOS; opt-in process metrics; application metrics via `MetricSpec`/`MetricsMixin` |
| **Windows** | Rates, gap fractions and latencies over a 5 s ... 6 h trailing-window ladder on `/status`, for sub-minute resolution and consumers without PromQL |
| **Health** | Default checks (data freshness, throughput, latency drift) that self-pace their startup, opt-in latency/gap/EOS checks; `/health` and `/health/<check>` (503 on failure), `/readyz` and `/healthz` driven by the pipeline's own lifecycle |
| **Dashboard** | A self-contained live view of the pipeline graph with per-element rates, latencies, gap fractions and health; composed elements expand in place |
| **Push** | `PushExporter` POSTs the exposition to VictoriaMetrics (or any store taking it) on a timer, for anything Prometheus cannot scrape; lifecycle metrics make a hung run loop a one-term alert |
| **CLI** | `sgnmon run`, `sgnmon check` (plugin-friendly exit codes), `sgnmon demo` |

See the user guide:
[Attaching to Pipelines](https://greg.docs.ligo.org/sgnmon/user/attaching/),
[Health Checks](https://greg.docs.ligo.org/sgnmon/user/health/),
[The Monitoring Server](https://greg.docs.ligo.org/sgnmon/user/server/),
[Metrics Reference](https://greg.docs.ligo.org/sgnmon/user/metrics/).
