CodeNSM Python SDK
Treat every Python function like an employee. The SDK auto-instruments the functions and methods in your packages — no decorating each one — and tracks how often each runs, how reliably, and how slowly. Those signals roll up, in the cloud, into departments, KPIs and a single North-Star Metric on your dashboard.
1 · Install
pip install https://thinknorth.consulting/static/codensm/codensm-0.1.0-py3-none-any.whl
Hosted build (interim). pip install codensm from PyPI is coming. Pure standard library — no third-party dependencies pulled into your app. Python 3.8+.
2 · Quickstart
Call init() once, as early as possible at startup — before your app's submodules import, so the import hook can wrap them.
import codensm codensm.init( api_key="cnsm_…", # Project → ingest key, from your dashboard include=["myapp"], # your own top-level packages weights={"myapp.checkout": 9}, # optional business value-weights )
That's it. Every function/method under myapp — already imported or imported later — is now tracked. Nothing else to wire.
3 · Configuration
| Option | Default | What it does |
|---|---|---|
| api_key | — | Required. Your project's ingest key (Bearer token). |
| include | — | Required. Package prefixes to auto-instrument, e.g. ["myapp"]. |
| endpoint | …/codensm/ingest | Ingest URL. Defaults to hosted CodeNSM. |
| exclude | () | Prefixes to skip even if under include (hot inner loops, etc.). |
| department | auto | callable(module)->str or {prefix: dept}. Defaults to the package path. |
| weights | 1.0 | {name-or-prefix: value_weight} — business value per successful call (longest-prefix match). |
| flush_interval | 15.0 | Seconds between background flushes. |
| instrument | True | Set False to only enable @track (no auto-wrap). |
4 · Overriding or opting in one function
Use the decorator only to override a function's department/weight, or to instrument something outside include.
@codensm.track(department="payments", value_weight=9) def charge(card): ...
5 · Short-lived scripts
The flusher runs in the background and on exit; force it when a script ends fast:
codensm.flush() # send now codensm.shutdown() # final send + stop
6 · What leaves your process (and what never does)
CodeNSM is deliberately a thin collector. The interpretation happens in the cloud — your machine ships only lightweight counters.
Sent
Never sent
Wrappers never swallow exceptions or change return values — your behaviour is unchanged. Counters live in memory; a daemon thread batches deltas every flush_interval seconds; a failed send is retried (merged back, never dropped).
7 · Any other language
The SDK is just a client for one HTTP contract. Push per-function aggregate deltas from anything:
POST https://thinknorth.consulting/codensm/ingest
Authorization: Bearer <project ingest key>
Content-Type: application/json
{"functions":[
{"name":"checkout.apply_coupon","department":"engine",
"value_weight":9,"calls":1240,"errors":3,"total_ms":47000}
]}
8 · Where it shows up
Calls, errors and latency roll up — in the cloud — into per-department KPIs, a debt-that-hurts heatmap, underuse detection, and a single North-Star Metric, all on your project dashboard. Functions appear as they're actually called.
9 · Overhead
One thin wrapper call per instrumented call. Scope include tightly, use exclude for very hot inner loops, and remember dunder methods are skipped. Sync, async def, and instance/class/static methods are all covered.