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#
Add
_smonitor.pyin package root.Add
mylib/_private/smonitor/catalog.pyandmylib/_private/smonitor/meta.py.Add
mylib/_private/smonitor/emitter.pywithDiagnosticBundle.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#
Enable
strict_signals=Trueinqaprofile tests.Run bundle export in a smoke test.
Validate representative events under
profile="agent".Verify fallback behavior if a handler fails.
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:
one warning family,
one exception family,
one subsystem at a time,
then global rollout.
Instrumentation cost and expectations#
@signaladds 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/qato 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.