Monitor (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

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

Quick Start

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

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)

export LEX_MONITOR__ENABLED=true
# Environment variables for each field

Option 3 — 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

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