Integrating Your Library#

This chapter is the practical blueprint for migrating a real, existing package.

First principle#

Treat SMonitor integration as a refactor of diagnostics architecture, not a superficial logging replacement.

Migration phases#

Phase 1: Create a stable diagnostics boundary#

  1. Add _smonitor.py in package root.

  2. Add mylib/_private/smonitor/catalog.py and mylib/_private/smonitor/meta.py.

  3. Add mylib/_private/smonitor/emitter.py with DiagnosticBundle.

  4. Configure on import with ensure_configured(PACKAGE_ROOT).

Checkpoint:

  • your package imports cleanly,

  • a test warning can be emitted from catalog.

Phase 2: Move warnings/errors to catalog-driven flow#

Replace direct message strings with catalog codes in key modules first:

  • entry points,

  • parser/validation layers,

  • dependency/probing paths.

Checkpoint:

  • no new warning/error strings are introduced outside catalog,

  • emitted messages are profile-aware.

Phase 3: Instrument function boundaries#

Apply @signal to:

  • public API functions,

  • orchestration functions that cross subsystem boundaries.

Avoid high-frequency inner loops.

Checkpoint:

  • call chain appears in diagnostics for failure scenarios.

Phase 4: Harden and validate#

  1. Enable strict_signals=True in qa profile tests.

  2. Run bundle export in a smoke test.

  3. Validate representative events under profile="agent".

  4. Verify fallback behavior if a handler fails.

  5. Compare representative bundles when asking what changed between two runs.

Checkpoint:

  • diagnostics are robust and reproducible.

Practical migration order#

Use this order to reduce risk:

  1. one warning family,

  2. one exception family,

  3. one subsystem at a time,

  4. then global rollout.

Instrumentation cost and expectations#

  • @signal adds overhead, but usually acceptable at API/orchestration boundaries.

  • avoid decorating very hot inner loops or tiny utility functions called millions of times.

  • use sampling and profiling in dev/qa to measure impact before broad rollout.

Common concerns#

“Will this break users?”#

Not if you keep code IDs stable and improve messages incrementally.

“Do we need to migrate everything at once?”#

No. Migrate by slices. Keep compatibility bridges during transition.

“Should we expose SMonitor controls to end users?”#

Usually no. Keep defaults safe for users; let developers/QA override in runtime/test/CI.

Next#

Read Edge Cases before broad rollout.

You are done when#

  • diagnostics are emitted from catalog-driven helpers across migrated modules,

  • key API boundaries are instrumented with @signal,

  • QA tests validate strict signal contracts and bundle export,

  • agent-oriented payloads and bundle comparison are usable in practice.

Repeated catalog emission#

From SMonitor 0.23.0, bind an installed provider’s canonical root explicitly when repeated catalog emission would otherwise repeat filesystem resolution:

from smonitor.integrations import bind_provider, emit_from_catalog

BOUND_ROOT = bind_provider(PACKAGE_ROOT)

def report_warning(entry, extra):
    return emit_from_catalog(entry, package_root=BOUND_ROOT, extra=extra)

Binding resolves the root at construction and selects that canonical pathname for subsequent emissions. Rebind to select another relative/cwd/symlink target. Provider files retain their ordinary registration/configuration lifecycle. Ordinary Path/string inputs continue resolving their live target on each call.

Bound emission checks the current manager under the existing setup lock. reset_configured_packages() makes its next bootstrap-enabled call reconsider registration; existing application policy remains authoritative. An explicit ensure_configured(BOUND_ROOT, use_provider_policy=True) applies provider policy. Bound bootstrap_policy=False emission registers once per current manager and keeps runtime policy under the application. A bootstrap-enabled DiagnosticBundle(..., package_root=BOUND_ROOT) can use the same binding.