SMonitor

Coverage: SMonitor Python tests, uploaded by the routine Linux/Python 3.14 CI lane. The badge reflects the last uploaded report, which may lag later direct or skip-CI commits; it does not certify a full matrix or scientific correctness.

Precision diagnostics for scientific Python ecosystems.

Overview

SMonitor (Signal Monitor) is a centralized diagnostics and telemetry layer for scientific Python libraries.

It unifies warnings, logging-derived events, exceptions, and execution context into one consistent operational model.

Why teams adopt SMonitor

• Clear user-facing diagnostics with actionable hints.
• Stable diagnostic contracts (code, signal) for QA and automation.
• Cross-library traceability with breadcrumb context.
• Local-first reproducibility with bundle export.
• One configuration model across an entire library ecosystem.

Who it is for

• Host-library maintainers integrating diagnostics in package mylib.
• End users of host libraries who need clearer warnings/errors and rescue guidance.
• QA and automation teams validating contracts and machine-readable outputs.

For AI agents

SMonitor helps agents produce higher-quality diagnosis with lower ambiguity:

• stable machine keys (code, signal) for deterministic triage,
• profile-specific machine-oriented output (profile="agent"),
• local reproducibility artifacts (bundles) for replay and verification.

For safe autonomous workflows:

• keep contracts stable,
• avoid hardcoded diagnostic strings outside catalogs,
• require human review before merging agent-suggested fixes.

Why SMonitor

• Single configuration surface for diagnostics across multiple libraries.
• Traceability with breadcrumbs (call-chain context).
• Profile-aware messaging (user, dev, qa, agent, debug).
• Structured events for telemetry and tooling.
• Policy engine for routing/filtering/transforms.

Install

conda install -c uibcdf smonitor

60-second quick start

import smonitor

smonitor.configure(profile="user", theme="plain")

@smonitor.signal(name="mylib.compute")
def do_work(x):
    if x < 0:
        smonitor.emit(
            "ERROR",
            "Input is invalid.",
            code="MYLIB-E001",
            source="mylib.compute",
            extra={"hint": "Use a non-negative value."},
        )
        return None
    return x * 2

do_work(-1)

Before vs after diagnostics quality

• Less actionable:
  • ValueError: invalid argument
• With SMonitor:
  • ERROR [MYLIB-E001]: Input is invalid. Hint: Use a non-negative value.

Core capabilities

• Config precedence: runtime configure() > env vars > _smonitor.py.
• Catalog-driven diagnostics (CODES/SIGNALS) for stable contracts.
• Policy engine (ROUTES/FILTERS) with rate limiting/sampling/transforms.
• Multi-profile output for users, developers, QA, agents, and debug sessions.
• Handlers: console (plain/rich), file, JSON, memory buffer.
• Integration API (DiagnosticBundle, CatalogException, CatalogWarning).
• Event schema checks and strict signal contracts in dev/qa.
• Stable incident fingerprints and run/session/correlation identifiers for reproducible triage.
• Explicit human_summary plus normalized machine payloads for dual human/agent workflows.
• CLI for validation, checks, report, bundle export, and bundle comparison.
• Local bundle export (bundle.json, optional events.jsonl) for support workflows.
• Operational triage summaries in reports/bundles (top_codes, top_sources, top_fingerprints, recurrent/actionable/blocking summaries).
• Profiling features:
  • decorator timing,
  • manual spans,
  • timeline buffering,
  • sampling (profiling_sample_rate),
  • timeline export (json/csv).

Configuration

Project-wide configuration is read from _smonitor.py at the package root. Precedence is: runtime configure() > environment variables > _smonitor.py.

# _smonitor.py (package root)
PROFILE = "user"

SMONITOR = {
    "level": "WARNING",
    "trace_depth": 3,
    "capture_warnings": True,
    "capture_logging": True,
    "theme": "plain",
    "strict_config": False,
}

CODES = {
    "MSM-W010": {
        "title": "Selection ambiguous",
        "user_message": "Selection {selection} is ambiguous.",
        "user_hint": "Use a more specific selection (example: {example}).",
    }
}

Package Catalogs

Libraries can keep their diagnostics catalog in mylib/_private/smonitor/catalog.py (CODES/SIGNALS + metadata) and call smonitor.integrations.emit_from_catalog(...) to emit structured events.

Canonical Guide

The canonical integration guide is standards/SMONITOR_GUIDE.md. MolSysSuite's registered synchronizer distributes its exact bytes to sibling repositories. To inspect local copies without changing them, run:

python devtools/sync_smonitor_guide.py

Profiling example

from smonitor.profiling import span, export_timeline

smonitor.configure(profiling=True, profiling_sample_rate=1.0)

with span("io.load", path="data.h5"):
    pass

export_timeline("timeline.json", format="json")

SMonitor profiling is lightweight observability for library workflows (not a full replacement for dedicated low-level profilers).

Bundles

Generate a local diagnostics bundle for reproducible troubleshooting:

smonitor export --out smonitor_bundle --max-events 500
smonitor compare current_bundle.json previous_bundle.json --format markdown

This creates bundle.json and events.jsonl (if buffering is enabled). Bundle comparison highlights new/disappeared/recurrent fingerprints and count deltas between runs.

Policy Engine

Use ROUTES and FILTERS in _smonitor.py to route or filter events.

ROUTES = [
  {"when": {"level": "WARNING"}, "send_to": ["console", "json"]}
]

FILTERS = [
  {"when": {"code": "MSM-W010"}, "rate_limit": "1/100@60"},
  {"when": {"level": "INFO"}, "sample": 0.1}
]

CLI

smonitor --validate-config
smonitor --check
smonitor --check --check-event '{"level":"WARNING","message":"check event"}'
smonitor export --out smonitor_bundle --max-events 500
smonitor compare current_bundle.json previous_bundle.json --format markdown

For opt-in pytest QA, install smonitor[pytest] and inspect Pytest Receptor's canonical artifact after the run:

mkdir -p .pytest-receptor
python -m pytest --receptor=ci --receptor-events=.pytest-receptor/events.jsonl
smonitor pytest-check .pytest-receptor/events.jsonl --provider-root ./my_library

See the pytest diagnostic policy guide for identity baselines, forbidden codes, and evidence-completeness rules.

Ecosystem adoption

MolSysSuite maintains the registered guide owners and client repositories in its central inventory. The canonical client guide describes integration contracts and the capability floor for optional features. Receiving a guide copy does not establish runtime adoption or raise a client's dependency floor.

devtools/sync_smonitor_guide.py audits local copies without changing them. MolSysSuite's registered synchronizer owns their delivery.

Documentation

• Website: https://www.uibcdf.org/smonitor
• User guide (integrators + end users): docs/content/user/
• Developer guide: devguide/
• Canonical standards: standards/

Development

pytest
ruff check .

Docs build:

make -C docs html

Status

Current stable release: GitHub Releases (latest). Published noarch: python packages are available from the UIBCDF Conda channel for Python 3.11--3.14. Zenodo's SMonitor record lists independently archived source snapshots; it does not archive Conda packages. Next milestone: 1.0.0 (stable), focused on hardening, API/contract freeze, and sustained CI stability.

AI Support (Future)

SMonitor is designed to enable opt‑in AI/LLM support workflows:

• structured CODES/SIGNALS for triage,
• local bundles for reproducible diagnosis,
• guarded repair suggestions with human review.

License

MIT