linearjeph 1.2.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
linearjeph/__init__.py ADDED
@@ -0,0 +1,13 @@
1
+ """LINEARJEPH error tracking, metrics, logs, tracing, cron monitoring and release tracking. Zero dependencies."""
2
+ from .client import (SDK_VERSION, capture_exception, capture_message, capture_transaction, close, flush, heartbeat,
3
+ init, report_packages, scrub, serialize_exception, set_tag, set_user, start_transaction, transaction)
4
+ from .telemetry import (LinearjephHandler, checkin, current_span, deploy, finish_span, gauge, histogram, inject_headers, incr,
5
+ install_logging, log_event, monitor, release, scrub_pii, span, start_span, timer)
6
+ from . import health
7
+ from . import prophecy
8
+
9
+ __all__ = ["init", "close", "flush", "capture_exception", "capture_message", "capture_transaction", "start_transaction",
10
+ "transaction", "heartbeat", "monitor", "checkin", "report_packages", "set_tag", "set_user", "scrub", "scrub_pii",
11
+ "serialize_exception", "incr", "gauge", "histogram", "timer", "log_event", "LinearjephHandler", "install_logging",
12
+ "span", "start_span", "finish_span", "current_span", "inject_headers", "release", "deploy", "health", "prophecy"]
13
+ __version__ = SDK_VERSION
linearjeph/client.py ADDED
@@ -0,0 +1,632 @@
1
+ """LINEARJEPH Python SDK core. Standard library only.
2
+
3
+ Design rules: every public function swallows its own failures (the SDK must never crash the host app), sending happens
4
+ on one background daemon thread with a bounded queue, and everything pending is flushed at interpreter exit.
5
+ """
6
+ import atexit
7
+ import contextlib
8
+ import functools
9
+ import gzip
10
+ import json
11
+ import logging
12
+ import os
13
+ import queue
14
+ import random
15
+ import re
16
+ import sys
17
+ import threading
18
+ import time
19
+ import traceback
20
+ import urllib.error
21
+ import urllib.request
22
+ from datetime import datetime, timezone
23
+
24
+ __all__ = ["init", "close", "flush", "capture_exception", "capture_message", "capture_transaction", "start_transaction",
25
+ "transaction", "heartbeat", "monitor", "report_packages", "set_tag", "set_user", "scrub",
26
+ "serialize_exception", "Options", "SDK_VERSION", "DEFAULT_ENDPOINT"]
27
+
28
+ SDK_VERSION = "1.2.0"
29
+ DEFAULT_ENDPOINT = "https://linearjeph.cc"
30
+ EVENTS_PATH = "/ingest/v1/events"
31
+ HEARTBEAT_PATH = "/ingest/v1/heartbeat"
32
+ PACKAGES_PATH = "/ingest/v1/packages"
33
+ METRICS_PATH = "/ingest/v1/metrics"
34
+ LOGS_PATH = "/ingest/v1/logs"
35
+ SPANS_PATH = "/ingest/v1/spans"
36
+ CHECKIN_PATH = "/ingest/v1/checkin"
37
+ RELEASES_PATH = "/ingest/v1/releases"
38
+ DEPLOYS_PATH = "/ingest/v1/deploys"
39
+ BATCH_KEYS = {EVENTS_PATH: "events", LOGS_PATH: "logs", SPANS_PATH: "spans"} # paths whose items are batched into one request
40
+ GZIP_PATHS = (METRICS_PATH, LOGS_PATH, SPANS_PATH) # endpoints that accept Content-Encoding: gzip
41
+
42
+ # Server limits (apps/api-core/errortrack, monitoring, audits).
43
+ MAX_FRAMES = 50
44
+ MAX_TAGS = 20
45
+ MAX_BODY_BYTES = 256 * 1024
46
+ BATCH_BYTES = 200 * 1024
47
+ MAX_EVENTS_PER_REQUEST = 100
48
+ HEARTBEAT_NAME_RE = re.compile(r"^[A-Za-z0-9._-]{1,64}$")
49
+ PKG_NAME_RE = re.compile(r"^[\w@./+~:-]{1,200}$")
50
+ PKG_VER_RE = re.compile(r"^[\w.+~!:-]{1,100}$")
51
+ FILTERED = "[Filtered]"
52
+
53
+ log = logging.getLogger("linearjeph")
54
+
55
+ _SENSITIVE_KEY = re.compile(
56
+ r"(pass(word|wd)?|secret|token|authorization|auth|cookie|api[_-]?key|apikey|x-lj-key|private[_-]?key|credential|session|csrf|bearer)",
57
+ re.I)
58
+ _SENSITIVE_TEXT = re.compile(
59
+ r"(?i)\b(password|passwd|pwd|secret|token|api[_-]?key|apikey|authorization|access[_-]?key)\b(\s*[=:]\s*)(?:bearer\s+)?[^\s,;&'\"]+")
60
+ _BEARER = re.compile(r"(?i)\bbearer\s+[A-Za-z0-9._~+/=-]{8,}")
61
+
62
+
63
+ def _rate(v):
64
+ try:
65
+ return max(0.0, min(1.0, float(v)))
66
+ except (TypeError, ValueError):
67
+ return 1.0
68
+
69
+
70
+ class Options(object):
71
+ """Resolved configuration. See docs/sdk/python.md for every field."""
72
+
73
+ def __init__(self, key, release=None, environment="production", endpoint=DEFAULT_ENDPOINT, sample_rate=1.0,
74
+ traces_sample_rate=1.0, before_send=None, max_queue=100, batch_size=20, retries=4, backoff=0.5,
75
+ timeout=10.0, debug=False, scrub_keys=(), in_app_exclude=None, hooks=True, flush_timeout=5.0,
76
+ metrics_interval=10.0, pii_scrub=True, max_metric_series=500, log_level="info", sample_logs=1.0,
77
+ before_send_log=None, logging_level=None):
78
+ self.key = key
79
+ self.release = release
80
+ self.environment = environment or "production"
81
+ self.endpoint = (endpoint or DEFAULT_ENDPOINT).rstrip("/")
82
+ self.sample_rate = _rate(sample_rate)
83
+ self.traces_sample_rate = _rate(traces_sample_rate)
84
+ self.before_send = before_send
85
+ self.max_queue = max(1, int(max_queue))
86
+ self.batch_size = max(1, min(int(batch_size), MAX_EVENTS_PER_REQUEST))
87
+ self.retries = max(0, int(retries))
88
+ self.backoff = float(backoff)
89
+ self.timeout = float(timeout)
90
+ self.debug = bool(debug)
91
+ self.scrub_keys = tuple(str(k).lower() for k in (scrub_keys or ()))
92
+ self.in_app_exclude = tuple(in_app_exclude) if in_app_exclude is not None else (
93
+ "site-packages", "dist-packages", "/lib/python", "\\lib\\python")
94
+ self.hooks = bool(hooks)
95
+ self.flush_timeout = float(flush_timeout)
96
+ self.metrics_interval = max(1.0, float(metrics_interval))
97
+ self.pii_scrub = bool(pii_scrub)
98
+ self.max_metric_series = max(1, int(max_metric_series))
99
+ self.log_level = log_level
100
+ self.sample_logs = _rate(sample_logs)
101
+ self.before_send_log = before_send_log
102
+ self.logging_level = logging_level
103
+
104
+
105
+ _lock = threading.RLock()
106
+ _state = {"opts": None, "sender": None, "tags": {}, "user": {}, "release": None, "environment": "production",
107
+ "key": None, "endpoint": DEFAULT_ENDPOINT,
108
+ "in_app_exclude": ("site-packages", "dist-packages", "/lib/python", "\\lib\\python")}
109
+ _hooked = False
110
+ _atexit_registered = False
111
+
112
+
113
+ def _now():
114
+ return datetime.now(timezone.utc).isoformat()
115
+
116
+
117
+ def _safe(fn):
118
+ """Public API wrapper: log (debug) and swallow anything, so the SDK can never break the host application."""
119
+ @functools.wraps(fn)
120
+ def wrapper(*a, **kw):
121
+ try:
122
+ return fn(*a, **kw)
123
+ except Exception: # noqa: BLE001 - by design
124
+ log.debug("linearjeph: %s failed", fn.__name__, exc_info=True)
125
+ return None
126
+ return wrapper
127
+
128
+
129
+ # ------------------------------------------------------------------ scrubbing
130
+
131
+ def _is_sensitive(key):
132
+ k = str(key)
133
+ if _SENSITIVE_KEY.search(k):
134
+ return True
135
+ opts = _state["opts"]
136
+ return bool(opts and any(x in k.lower() for x in opts.scrub_keys))
137
+
138
+
139
+ def scrub(data, _depth=0):
140
+ """Return a copy of data (dict/list/str) with values under sensitive keys replaced by "[Filtered]".
141
+
142
+ Sensitive keys: password, secret, token, authorization, auth, cookie, api_key, session, csrf, bearer, credential,
143
+ private_key, x-lj-key, plus any `scrub_keys` passed to init(). Strings also lose `password=...` / `Bearer ...` text.
144
+ """
145
+ if _depth > 8:
146
+ return FILTERED
147
+ if isinstance(data, dict):
148
+ return {k: (FILTERED if _is_sensitive(k) else scrub(v, _depth + 1)) for k, v in data.items()}
149
+ if isinstance(data, (list, tuple)):
150
+ return [scrub(v, _depth + 1) for v in data]
151
+ if isinstance(data, str):
152
+ return _BEARER.sub("Bearer " + FILTERED, _SENSITIVE_TEXT.sub(lambda m: m.group(1) + m.group(2) + FILTERED, data))
153
+ return data
154
+
155
+
156
+ def _s(v, n):
157
+ return v[:n] if isinstance(v, str) else ("" if v is None else str(v)[:n])
158
+
159
+
160
+ def _clean_tags(tags):
161
+ out = {}
162
+ for k, v in list((tags or {}).items())[:MAX_TAGS]:
163
+ k = _s(k, 50)
164
+ out[k] = FILTERED if _is_sensitive(k) else _s(scrub(v if isinstance(v, str) else str(v)), 200)
165
+ return out
166
+
167
+
168
+ # ------------------------------------------------------------------ event building
169
+
170
+ def _in_app(filename):
171
+ return not filename.startswith("<") and not any(p in filename for p in _state["in_app_exclude"])
172
+
173
+
174
+ def serialize_exception(exc_type, exc, tb, release=None, environment=None):
175
+ """Build one contract `error` event (stack oldest -> newest, as the ingest expects)."""
176
+ frames = []
177
+ for fs in traceback.extract_tb(tb)[-MAX_FRAMES:]:
178
+ frames.append({"filename": fs.filename, "function": fs.name, "lineno": fs.lineno or 0,
179
+ "in_app": _in_app(fs.filename)})
180
+ return {"type": "error", "timestamp": _now(),
181
+ "release": release if release is not None else (_state["release"] or ""),
182
+ "environment": environment or _state["environment"],
183
+ "exception": {"type": getattr(exc_type, "__name__", str(exc_type)),
184
+ "value": _s(scrub(str(exc)), 500), "stacktrace": frames},
185
+ "tags": {}, "user": {}}
186
+
187
+
188
+ def _finish(ev, tags, rate):
189
+ """Sampling, scope tags, scrubbing, before_send. Returns the event or None."""
190
+ opts = _state["opts"]
191
+ if opts is None or not opts.key:
192
+ return None
193
+ if rate < 1.0 and random.random() >= rate:
194
+ return None
195
+ merged = dict(_state["tags"])
196
+ merged.update(tags or {})
197
+ merged.update(ev.get("tags") or {})
198
+ ev["tags"] = _clean_tags(merged)
199
+ uid = _state["user"].get("id")
200
+ ev["user"] = {"id": _s(uid, 100)} if uid else {}
201
+ if opts.before_send is not None:
202
+ try:
203
+ ev = opts.before_send(ev)
204
+ except Exception: # noqa: BLE001 - a broken hook must not leak unfiltered data
205
+ log.warning("linearjeph: before_send raised; event dropped", exc_info=opts.debug)
206
+ return None
207
+ if not isinstance(ev, dict):
208
+ return None
209
+ ev["tags"] = _clean_tags(ev.get("tags"))
210
+ return ev
211
+
212
+
213
+ def _emit(ev, tags=None, rate=None):
214
+ opts = _state["opts"]
215
+ sender = _state["sender"]
216
+ if opts is None or sender is None:
217
+ return
218
+ ev = _finish(ev, tags, opts.sample_rate if rate is None else rate)
219
+ if ev is not None:
220
+ sender.put(EVENTS_PATH, ev)
221
+
222
+
223
+ # ------------------------------------------------------------------ sender
224
+
225
+ class Sender(object):
226
+ """Bounded queue + one background daemon thread. Batches events, retries with backoff, honours Retry-After.
227
+
228
+ 401 disables sending (the key is wrong or rotated); 400/403/404 drop the item; 413 splits a batch or drops a single
229
+ item; 429, 5xx and network errors retry with exponential backoff and jitter.
230
+ """
231
+
232
+ def __init__(self, opts):
233
+ self.opts = opts
234
+ self.q = queue.Queue(maxsize=opts.max_queue)
235
+ self.dropped = 0
236
+ self.disabled = False
237
+ self._stop = threading.Event()
238
+ self._thread = None
239
+ self._pid = None
240
+ self._tlock = threading.Lock()
241
+ self.on_tick = None # called every metrics_interval seconds on the sender thread (metric flush)
242
+ self.pre_flush = None # called by flush()/close() before waiting (drains in-process aggregates)
243
+
244
+ def _ensure_thread(self):
245
+ pid = os.getpid()
246
+ if self._thread is not None and self._thread.is_alive() and self._pid == pid:
247
+ return
248
+ with self._tlock:
249
+ if self._thread is not None and self._thread.is_alive() and self._pid == pid:
250
+ return
251
+ if self._pid is not None and self._pid != pid: # forked worker (gunicorn, multiprocessing): fresh queue
252
+ self.q = queue.Queue(maxsize=self.opts.max_queue)
253
+ self._pid = pid
254
+ self._thread = threading.Thread(target=self._run, args=(self.q,), name="linearjeph-sender", daemon=True)
255
+ self._thread.start()
256
+
257
+ def put(self, path, body):
258
+ if self.disabled or self._stop.is_set():
259
+ return False
260
+ try:
261
+ self._ensure_thread()
262
+ self.q.put_nowait((path, body))
263
+ return True
264
+ except queue.Full:
265
+ self.dropped += 1 # never block, never grow without bound inside the customer's process
266
+ return False
267
+
268
+ # -- transport
269
+ def _post(self, path, body):
270
+ data = json.dumps(body, default=str, separators=(",", ":")).encode()
271
+ headers = {"Content-Type": "application/json", "X-LJ-Key": self.opts.key, "User-Agent": "linearjeph-python/" + SDK_VERSION}
272
+ if path in GZIP_PATHS and len(data) > 1024:
273
+ data = gzip.compress(data, 5)
274
+ headers["Content-Encoding"] = "gzip"
275
+ req = urllib.request.Request(self.opts.endpoint + path, data=data, method="POST", headers=headers)
276
+ with urllib.request.urlopen(req, timeout=self.opts.timeout) as r: # noqa: S310 - endpoint is operator-set
277
+ r.read()
278
+ return r.status
279
+
280
+ def _send(self, path, body):
281
+ """True when finished (delivered or undeliverable); False only for a 413 that may be split."""
282
+ for attempt in range(self.opts.retries + 1):
283
+ delay = None
284
+ try:
285
+ self._post(path, body)
286
+ return True
287
+ except urllib.error.HTTPError as e:
288
+ code = e.code
289
+ if code == 401:
290
+ self.disabled = True
291
+ log.warning("linearjeph: ingest key rejected (401); sending disabled")
292
+ return True
293
+ if code == 413:
294
+ return not (isinstance(body, dict) and any(len(v) > 1 for v in body.values() if isinstance(v, list)))
295
+ if code not in (429, 500, 502, 503, 504):
296
+ log.debug("linearjeph: %s -> %s dropped", path, code)
297
+ return True
298
+ if code == 429:
299
+ try:
300
+ delay = min(60.0, float(e.headers.get("Retry-After") or 0)) or None
301
+ except (TypeError, ValueError):
302
+ delay = None
303
+ except Exception: # noqa: BLE001 - network error, retry
304
+ pass
305
+ if attempt < self.opts.retries:
306
+ if delay is None:
307
+ delay = self.opts.backoff * (2 ** attempt) * (0.5 + random.random() / 2)
308
+ if self._stop.wait(delay):
309
+ return True
310
+ log.debug("linearjeph: gave up sending to %s", path)
311
+ return True
312
+
313
+ def _send_events(self, events):
314
+ self._send_batch(EVENTS_PATH, events)
315
+
316
+ def _send_batch(self, path, items):
317
+ if self.disabled:
318
+ return
319
+ key = BATCH_KEYS[path]
320
+ if not self._send(path, {key: items}): # 413 on a multi-item batch: split
321
+ mid = len(items) // 2
322
+ self._send_batch(path, items[:mid])
323
+ self._send_batch(path, items[mid:])
324
+
325
+ # -- worker
326
+ def _run(self, q):
327
+ last_tick = time.time()
328
+ while not self._stop.is_set() or not q.empty():
329
+ if self.on_tick is not None and time.time() - last_tick >= self.opts.metrics_interval:
330
+ last_tick = time.time()
331
+ try:
332
+ self.on_tick()
333
+ except Exception: # noqa: BLE001
334
+ log.debug("linearjeph: tick failed", exc_info=True)
335
+ try:
336
+ path, body = q.get(timeout=0.2)
337
+ except queue.Empty:
338
+ continue
339
+ taken = 1
340
+ try:
341
+ if path in BATCH_KEYS:
342
+ items, size = [body], len(json.dumps(body, default=str))
343
+ others = []
344
+ while len(items) < self.opts.batch_size and size < BATCH_BYTES:
345
+ try:
346
+ p2, b2 = q.get_nowait()
347
+ except queue.Empty:
348
+ break
349
+ taken += 1
350
+ if p2 != path:
351
+ others.append((p2, b2))
352
+ continue
353
+ items.append(b2)
354
+ size += len(json.dumps(b2, default=str))
355
+ self._send_events(items) if path == EVENTS_PATH else self._send_batch(path, items)
356
+ for p2, b2 in others:
357
+ if p2 in BATCH_KEYS:
358
+ self._send_events([b2]) if p2 == EVENTS_PATH else self._send_batch(p2, [b2])
359
+ elif not self.disabled:
360
+ self._send(p2, b2)
361
+ elif not self.disabled:
362
+ self._send(path, body)
363
+ except Exception: # noqa: BLE001
364
+ log.debug("linearjeph: sender error", exc_info=True)
365
+ finally:
366
+ for _ in range(taken):
367
+ q.task_done()
368
+
369
+ def flush(self, timeout=5.0):
370
+ if self.pre_flush is not None:
371
+ try:
372
+ self.pre_flush()
373
+ except Exception: # noqa: BLE001
374
+ pass
375
+ end = time.time() + timeout
376
+ while self.q.unfinished_tasks and time.time() < end and not self.disabled:
377
+ time.sleep(0.02)
378
+ return self.disabled or not self.q.unfinished_tasks
379
+
380
+ def close(self, timeout=5.0):
381
+ ok = self.flush(timeout)
382
+ self._stop.set()
383
+ return ok
384
+
385
+
386
+ # ------------------------------------------------------------------ public API
387
+
388
+ def init(key, release=None, environment="production", endpoint=DEFAULT_ENDPOINT, **options):
389
+ """Configure the SDK. Safe to call more than once (the last call wins). Never raises; returns True when enabled.
390
+
391
+ Options: sample_rate, traces_sample_rate, before_send, max_queue, batch_size, retries, backoff, timeout, debug,
392
+ scrub_keys, in_app_exclude, hooks, flush_timeout. `hooks=False` skips installing sys/threading excepthooks.
393
+ """
394
+ global _atexit_registered
395
+ try:
396
+ if not key or not isinstance(key, str):
397
+ log.warning("linearjeph: init() without an ingest key; the SDK stays disabled")
398
+ return False
399
+ opts = Options(key, release=release, environment=environment, endpoint=endpoint, **options)
400
+ with _lock:
401
+ old = _state["sender"]
402
+ if old is not None:
403
+ old.close(1.0)
404
+ _state.update(opts=opts, key=key, endpoint=opts.endpoint, release=release, environment=opts.environment,
405
+ in_app_exclude=opts.in_app_exclude, sender=Sender(opts))
406
+ if opts.debug:
407
+ logging.basicConfig()
408
+ log.setLevel(logging.DEBUG)
409
+ from . import telemetry
410
+ telemetry.attach(_state["sender"])
411
+ if opts.logging_level is not None:
412
+ telemetry.install_logging(opts.logging_level)
413
+ if opts.hooks:
414
+ _install_hooks()
415
+ if not _atexit_registered:
416
+ _atexit_registered = True
417
+ atexit.register(_at_exit)
418
+ return True
419
+ except Exception: # noqa: BLE001
420
+ log.debug("linearjeph: init failed", exc_info=True)
421
+ return False
422
+
423
+
424
+ def _at_exit():
425
+ s, opts = _state["sender"], _state["opts"]
426
+ if s is not None:
427
+ try:
428
+ s.close(opts.flush_timeout if opts else 5.0)
429
+ except Exception: # noqa: BLE001
430
+ pass
431
+
432
+
433
+ @_safe
434
+ def close(timeout=5.0):
435
+ """Flush and stop the sender. Calling init() again starts a new one."""
436
+ s = _state["sender"]
437
+ if s is None:
438
+ return True
439
+ ok = s.close(timeout)
440
+ _state["sender"] = None
441
+ _state["opts"] = None
442
+ return ok
443
+
444
+
445
+ @_safe
446
+ def flush(timeout=5.0):
447
+ """Block up to timeout seconds until the queue is delivered. True when empty."""
448
+ s = _state["sender"]
449
+ return s.flush(timeout) if s else True
450
+
451
+
452
+ @_safe
453
+ def set_tag(key, value):
454
+ """Attach a tag to every later event (max 20 tags; key 50 chars, value 200)."""
455
+ _state["tags"][str(key)] = value
456
+
457
+
458
+ @_safe
459
+ def set_user(user_id):
460
+ """Attach a user id (a string you choose) to later events. None clears it."""
461
+ _state["user"] = {"id": str(user_id)} if user_id not in (None, "") else {}
462
+
463
+
464
+ @_safe
465
+ def capture_exception(exc=None, tags=None):
466
+ """Report an exception (default: the one being handled). Fire-and-forget."""
467
+ if exc is None or exc is True:
468
+ t, v, tb = sys.exc_info()
469
+ elif isinstance(exc, tuple) and len(exc) == 3:
470
+ t, v, tb = exc
471
+ else:
472
+ t, v, tb = type(exc), exc, getattr(exc, "__traceback__", None)
473
+ if t is None:
474
+ return
475
+ _emit(serialize_exception(t, v, tb), tags)
476
+
477
+
478
+ @_safe
479
+ def capture_message(message, level="info", tags=None):
480
+ """Report a message. The ingest stores it as an error event of type "Message" (grouped by its text)."""
481
+ ev = {"type": "error", "timestamp": _now(), "release": _state["release"] or "", "environment": _state["environment"],
482
+ "exception": {"type": "Message", "value": _s(scrub(str(message)), 500), "stacktrace": []},
483
+ "tags": {"level": str(level)}}
484
+ _emit(ev, tags)
485
+
486
+
487
+ @_safe
488
+ def capture_transaction(name, duration_ms, status="ok", tags=None):
489
+ """Report one timed operation (counts towards p50/p95/throughput). Needs a plan with performance monitoring."""
490
+ ev = {"type": "transaction", "timestamp": _now(), "release": _state["release"] or "",
491
+ "environment": _state["environment"],
492
+ "transaction": {"name": _s(name, 200), "duration_ms": float(duration_ms), "status": _s(status, 20) or "ok"},
493
+ "tags": {}}
494
+ opts = _state["opts"]
495
+ _emit(ev, tags, opts.traces_sample_rate if opts else 1.0)
496
+
497
+
498
+ class start_transaction(contextlib.ContextDecorator):
499
+ """Time a block or function: `with start_transaction("checkout"):` or `@start_transaction("job")`.
500
+
501
+ Status becomes "error" if the block raises. The exception is neither swallowed nor captured.
502
+ """
503
+
504
+ def __init__(self, name):
505
+ self.name = name
506
+ self.status = "ok"
507
+ self._t0 = None
508
+
509
+ def __enter__(self):
510
+ self._t0 = time.perf_counter()
511
+ return self
512
+
513
+ def __exit__(self, et, ev, tb):
514
+ try:
515
+ if et is not None:
516
+ self.status = "error"
517
+ capture_transaction(self.name, (time.perf_counter() - self._t0) * 1000.0, self.status)
518
+ except Exception: # noqa: BLE001
519
+ pass
520
+ return False
521
+
522
+ def _recreate_cm(self): # a fresh timer per call when used as a decorator
523
+ return type(self)(self.name)
524
+
525
+
526
+ transaction = start_transaction
527
+
528
+
529
+ @_safe
530
+ def heartbeat(name, status="ok", interval_s=None):
531
+ """Check in for a cron job / worker. `interval_s` (30 .. 2592000) tells the monitor how often to expect you."""
532
+ if not HEARTBEAT_NAME_RE.match(str(name)):
533
+ log.warning("linearjeph: heartbeat name must match [A-Za-z0-9._-]{1,64}; ignored")
534
+ return
535
+ if status not in ("ok", "error"):
536
+ status = "error"
537
+ body = {"name": str(name), "status": status}
538
+ if interval_s:
539
+ body["interval_s"] = max(30, min(int(interval_s), 30 * 86400))
540
+ s = _state["sender"]
541
+ if s:
542
+ s.put(HEARTBEAT_PATH, body)
543
+
544
+
545
+ class monitor(contextlib.ContextDecorator):
546
+ """Cron/worker wrapper: heartbeat "ok" on success, "error" if the block raises (then re-raises).
547
+
548
+ @linearjeph.monitor("nightly-report", interval_s=86400)
549
+ def run(): ...
550
+
551
+ with linearjeph.monitor("sync", interval_s=900):
552
+ ...
553
+
554
+ Pass `capture=True` to also report the exception as an error event.
555
+ """
556
+
557
+ def __init__(self, name, interval_s=None, capture=False):
558
+ self.name, self.interval_s, self.capture = name, interval_s, capture
559
+
560
+ def __enter__(self):
561
+ return self
562
+
563
+ def __exit__(self, et, ev, tb):
564
+ try:
565
+ if et is not None and self.capture and not issubclass(et, (SystemExit, KeyboardInterrupt)):
566
+ capture_exception((et, ev, tb))
567
+ heartbeat(self.name, "ok" if et is None else "error", self.interval_s)
568
+ except Exception: # noqa: BLE001
569
+ pass
570
+ return False
571
+
572
+
573
+ def _distributions():
574
+ from importlib import metadata
575
+ pk = {}
576
+ for d in metadata.distributions():
577
+ n = d.metadata["Name"]
578
+ if n and PKG_NAME_RE.match(n) and PKG_VER_RE.match(d.version or ""):
579
+ pk[n.lower()] = d.version
580
+ return pk
581
+
582
+
583
+ @_safe
584
+ def report_packages():
585
+ """Send installed distributions (PyPI) for the dependency audit. Replaces the previous SDK-reported list.
586
+
587
+ Returns the number of packages queued (0 when the SDK is not initialised)."""
588
+ s = _state["sender"]
589
+ if not s:
590
+ return 0
591
+ out, size = [], 64
592
+ for n, v in sorted(_distributions().items()):
593
+ # the server replaces the whole list per request, so one request must hold everything: cap by size
594
+ add = len(n) + len(v) + 30
595
+ if len(out) >= 5000 or size + add > BATCH_BYTES:
596
+ break
597
+ out.append({"name": n, "version": v})
598
+ size += add
599
+ s.put(PACKAGES_PATH, {"ecosystem": "PyPI", "packages": out})
600
+ return len(out)
601
+
602
+
603
+ # ------------------------------------------------------------------ automatic capture
604
+
605
+ def _install_hooks():
606
+ global _hooked
607
+ if _hooked:
608
+ return
609
+ _hooked = True
610
+ prev = sys.excepthook
611
+
612
+ def hook(t, v, tb):
613
+ try:
614
+ if not issubclass(t, KeyboardInterrupt):
615
+ _emit(serialize_exception(t, v, tb))
616
+ flush(2.0)
617
+ except Exception: # noqa: BLE001
618
+ pass
619
+ prev(t, v, tb)
620
+
621
+ sys.excepthook = hook
622
+ prev_t = threading.excepthook
623
+
624
+ def thook(args):
625
+ try:
626
+ if args.exc_type is not SystemExit:
627
+ _emit(serialize_exception(args.exc_type, args.exc_value, args.exc_traceback))
628
+ except Exception: # noqa: BLE001
629
+ pass
630
+ prev_t(args)
631
+
632
+ threading.excepthook = thook