Metadata-Version: 2.4
Name: lexigram-monitor
Version: 0.1.1
Summary: Monitoring and observability for Lexigram Framework - Health checks, metrics, and system monitoring
Project-URL: Homepage, https://github.com/lexigram-dev/lexigram
Project-URL: Repository, https://github.com/lexigram-dev/lexigram
Project-URL: Documentation, https://docs.lexigram.dev/monitor
Project-URL: Issues, https://github.com/lexigram-dev/lexigram/issues
Project-URL: Changelog, https://github.com/lexigram-dev/lexigram/blob/main/CHANGELOG.md
Author-email: Lexigram Framework Team <team@lexigram.dev>
Maintainer-email: Lexigram Framework Team <team@lexigram.dev>
License: MIT
License-File: LICENSE
Keywords: async,framework,grafana,health-checks,metrics,monitoring,observability,prometheus
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: System :: Monitoring
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: lexigram-contracts>=0.1.0
Requires-Dist: lexigram>=0.1.1
Requires-Dist: typing-extensions>=4.0.0
Provides-Extra: all
Requires-Dist: lexigram-testing>=0.1.1; extra == 'all'
Requires-Dist: opentelemetry-distro>=0.43b0; extra == 'all'
Requires-Dist: opentelemetry-exporter-otlp>=1.22.0; extra == 'all'
Requires-Dist: opentelemetry-instrumentation>=0.43b0; extra == 'all'
Requires-Dist: prometheus-client>=0.19.0; extra == 'all'
Requires-Dist: psutil>=5.9.0; extra == 'all'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'all'
Requires-Dist: pytest-cov>=4.0.0; extra == 'all'
Requires-Dist: pytest-mock>=3.10.0; extra == 'all'
Requires-Dist: pytest>=8.0.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: otel
Requires-Dist: opentelemetry-distro>=0.43b0; extra == 'otel'
Requires-Dist: opentelemetry-exporter-otlp>=1.22.0; extra == 'otel'
Requires-Dist: opentelemetry-instrumentation>=0.43b0; extra == 'otel'
Provides-Extra: prometheus
Requires-Dist: prometheus-client>=0.19.0; extra == 'prometheus'
Provides-Extra: system
Requires-Dist: psutil>=5.9.0; extra == 'system'
Provides-Extra: test
Requires-Dist: lexigram-testing>=0.1.1; extra == 'test'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'test'
Requires-Dist: pytest-cov>=4.0.0; extra == 'test'
Requires-Dist: pytest-mock>=3.10.0; extra == 'test'
Requires-Dist: pytest>=8.0.0; extra == 'test'
Description-Content-Type: text/markdown

# lexigram-monitor

Observability, health checks, and metrics for the Lexigram Framework.
Supports Prometheus, OpenTelemetry, structured log export, and `/health` endpoints
that integrate with Kubernetes probes and load-balancer health checks.

---

## Overview

lexigram-monitor provides metrics collection, distributed tracing, health checks, and alerting for Lexigram applications. It integrates with Prometheus and OpenTelemetry backends, supports composable health checks with liveness and readiness flavours, and includes decorators for instrumenting services with custom metrics and traces. All services are wired via `MonitorProvider`, which registers monitoring protocols with the DI container.

---

## Install

```bash
uv add lexigram-monitor
# Optional extras
uv add "lexigram-monitor[prometheus]"    # Prometheus + Grafana
uv add "lexigram-monitor[opentelemetry]" # OTLP / Jaeger / Zipkin
```

## Quick Start

```python
from lexigram import Application
from lexigram.di.module import Module, module

# Import the module from the package
from lexigram.monitor import MonitorModule

@module(imports=[MonitorModule.configure()])
class AppModule(Module):
    pass

app = Application(modules=[AppModule])
if __name__ == "__main__":
    app.run()
```

## Configuration

> **Zero-config usage:** Call `MonitorModule.configure()` with no arguments to use defaults.

### Option 1 — YAML file

```yaml
# application.yaml
monitor:
  prometheus:
    enabled: true
    port: 9090
    path: /metrics
  tracing:
    enabled: false
    sample_rate: 1.0
  health:
    path: /health
    interval: 30
  logging:
    level: INFO
    format: json
```

### Option 2 — Profiles + Environment Variables *(recommended)*

```bash
export LEX_MONITOR__ENABLED=true
# Environment variables for each field
```

### Option 3 — Python

```python
from lexigram.monitor.config import MonitorConfig
from lexigram.monitor import MonitorModule

config = MonitorConfig(...)
MonitorModule.configure(backend=backend, config=config)
```

### Config reference

| Field | Default | Env var | Description |
|-------|---------|---------|-------------|
| `prometheus.enabled` | `true` | `LEX_MONITOR__PROMETHEUS__ENABLED` | Expose the `/metrics` scrape endpoint |
| `prometheus.port` | `9090` | `LEX_MONITOR__PROMETHEUS__PORT` | Port for the Prometheus metrics endpoint |
| `prometheus.path` | `/metrics` | `LEX_MONITOR__PROMETHEUS__PATH` | URL path for metrics scraping |
| `tracing.enabled` | `false` | `LEX_MONITOR__TRACING__ENABLED` | Enable distributed tracing via OTLP |
| `tracing.sample_rate` | `1.0` | `LEX_MONITOR__TRACING__SAMPLE_RATE` | Trace sampling rate (0.0–1.0; use 0.1 in production) |
| `health.path` | `/health` | `LEX_MONITOR__HEALTH__PATH` | Base path for health check endpoints |
| `health.interval` | `30` | `LEX_MONITOR__HEALTH__INTERVAL` | Seconds between background health polls |
| `health.timeout` | `5` | `LEX_MONITOR__HEALTH__TIMEOUT` | Per-check timeout in seconds |
| `logging.level` | `INFO` | `LEX_MONITOR__LOGGING__LEVEL` | Minimum log level (`DEBUG`, `INFO`, `WARNING`, `ERROR`) |
| `logging.format` | `json` | `LEX_MONITOR__LOGGING__FORMAT` | Log output format (`json` or `text`) |

## Module Factory Methods

| Method | Description |
|--------|-------------|
| `MonitorModule.configure(backend, config)` | Configure with explicit backend and optional MonitorConfig |
| `MonitorModule.stub()` | Minimal config for testing |

## Key Features

- **Prometheus** — Auto `/metrics` endpoint; request counters, histograms, gauges
- **OpenTelemetry** — Distributed tracing via OTLP exporter to Jaeger / Honeycomb
- **Health checks** — Composable checks with liveness + readiness flavours
- **Cached checks** — Per-check TTL to avoid thundering-herd on slow dependencies
- **DB instrumentation** — Automatic query timing and error tagging
- **HTTP instrumentation** — Outbound request tracking for `lexigram-http`
- **Messaging instrumentation** — Kafka / RabbitMQ consumer lag, publish rate
- **Alerting** — Configurable alert rules with webhook delivery
- **Log export** — Structured log export to OTLP log backend
- **Grafana dashboards** — Pre-built dashboard JSON in `lexigram-monitor/dashboards/`

## Testing

```python
async with Application.boot(modules=[MonitorModule.stub()]) as app:
    # your test code
    ...
```

## Key Source Files

| File | What it contains |
|------|----------------|
| `src/lexigram/monitor/module.py` | `MonitorModule` class with factory methods |
| `src/lexigram/monitor/di/provider.py` | `MonitorProvider` — wires monitoring protocols into DI container |
| `src/lexigram/monitor/config.py` | `MonitorConfig` and sub-config dataclasses |
| `src/lexigram/monitor/health.py` | Health check registration and registry |
| `src/lexigram/monitor/instrumentation/decorators.py` | `@metered` and `@traced` decorators |