easy-obs 0.5.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.
easy_obs/__init__.py ADDED
@@ -0,0 +1,20 @@
1
+ from easy_obs.batching_client import BatchingClient
2
+ from easy_obs.client import Client
3
+ from easy_obs.exceptions import ObsAppApiKeyError, ObsAppError, ObsAppRateLimitedError, ObsAppValidationError
4
+ from easy_obs.logging_handler import ObsAppLogHandler
5
+ from easy_obs.tracing import CaptureTrace
6
+ from easy_obs.view_errors import capture_errors
7
+
8
+ __version__ = '0.1.0'
9
+
10
+ __all__ = [
11
+ 'Client',
12
+ 'BatchingClient',
13
+ 'CaptureTrace',
14
+ 'ObsAppLogHandler',
15
+ 'capture_errors',
16
+ 'ObsAppError',
17
+ 'ObsAppApiKeyError',
18
+ 'ObsAppValidationError',
19
+ 'ObsAppRateLimitedError',
20
+ ]
@@ -0,0 +1,311 @@
1
+ from __future__ import annotations
2
+
3
+ import atexit
4
+ import collections
5
+ import threading
6
+ import time
7
+ from datetime import datetime as _datetime, timezone
8
+ from typing import Any, Callable
9
+
10
+ import requests
11
+
12
+ from easy_obs.client import Client
13
+ from easy_obs.exceptions import ObsAppApiKeyError, ObsAppError, ObsAppRateLimitedError, ObsAppValidationError
14
+
15
+
16
+ class BatchingClient(Client):
17
+ '''Client that buffers logs, metrics and traces in memory and sends them from a background
18
+ thread in bulk - one POST /api/ingest/ every flush_interval seconds, or sooner once
19
+ max_batch_size items of any one kind are waiting. log(), add_metric() and send_trace() (and
20
+ so ObsAppLogHandler, CaptureTrace and capture_errors) just append to a buffer and return
21
+ immediately, so they never block on the network and never raise because of it.
22
+
23
+ Because the send happens after the call has returned, errors can't be raised to the caller -
24
+ they're passed to on_error (if given), otherwise dropped. As with Client(background=True),
25
+ only use this for data you can afford to lose occasionally.
26
+
27
+ Delivery behaviour:
28
+ - network errors / 5xx: the request is retried up to max_retries times with exponential
29
+ backoff, then that batch is dropped.
30
+ - 400 (validation) / 401 (bad API key): dropped immediately - retrying can't help. A 400
31
+ drops the whole request, since the server validates /api/ingest/ all-or-nothing.
32
+ - 429 (rate limited): the server blocks the IP for an hour, so the batch is dropped and
33
+ sending pauses for rate_limit_pause seconds (items keep buffering, up to the cap).
34
+ - each buffer holds at most max_queue_size items; once full the oldest are discarded
35
+ (counted in `dropped`) so an outage can't grow memory without bound.
36
+
37
+ Items are stamped with the time they were recorded, not the time they're sent.
38
+
39
+ log_batch, add_metrics and ingest are inherited unchanged and remain synchronous. add_metric
40
+ only supports metric names (not metric_id) because the batch endpoint doesn't.
41
+
42
+ Call close() (or use as a context manager) for a clean shutdown; flush_on_exit=True also
43
+ registers an atexit hook that does it for you, waiting up to 5 seconds.'''
44
+
45
+ def __init__(
46
+ self,
47
+ api_key: str,
48
+ base_url: str = 'https://easy-obs.com',
49
+ timeout: float = 5.0,
50
+ session: requests.Session | None = None,
51
+ on_error: Callable[[Exception], None] | None = None,
52
+ flush_interval: float = 5.0,
53
+ max_batch_size: int = 500,
54
+ max_queue_size: int = 10_000,
55
+ max_retries: int = 3,
56
+ retry_backoff: float = 1.0,
57
+ rate_limit_pause: float = 3600.0,
58
+ flush_on_exit: bool = True,
59
+ ) -> None:
60
+ super().__init__(
61
+ api_key=api_key, base_url=base_url, timeout=timeout, session=session,
62
+ background=False, on_error=on_error,
63
+ )
64
+ self.flush_interval = flush_interval
65
+ self.max_batch_size = max_batch_size
66
+ self.max_queue_size = max_queue_size
67
+ self.max_retries = max_retries
68
+ self.retry_backoff = retry_backoff
69
+ self.rate_limit_pause = rate_limit_pause
70
+ self.dropped = 0 # items discarded: buffer overflow, failed sends, or added after close()
71
+
72
+ self._logs: collections.deque[dict] = collections.deque()
73
+ self._metrics: collections.deque[tuple[bool, dict]] = collections.deque() # (auto_create, entry)
74
+ self._traces: collections.deque[dict] = collections.deque()
75
+
76
+ self._cond = threading.Condition()
77
+ self._flush_requested = False
78
+ self._in_flight = False
79
+ self._closed = False
80
+ self._paused_until = 0.0
81
+ self._stop = threading.Event()
82
+
83
+ self._worker_thread = threading.Thread(
84
+ target=self._run, name='easy-obs-batcher', daemon=True,
85
+ )
86
+ self._worker_thread.start()
87
+ if flush_on_exit:
88
+ atexit.register(self.close, 5.0)
89
+
90
+ def __exit__(self, *exc_info: object) -> None:
91
+ self.close()
92
+
93
+ # ---- public API -------------------------------------------------------------------
94
+
95
+ def log(
96
+ self,
97
+ message: str,
98
+ level: int = 4,
99
+ request_id: str | None = None,
100
+ datetime: _datetime | str | None = None,
101
+ app: str | None = None,
102
+ container_id: str | None = None,
103
+ logger_name: str | None = None,
104
+ domain: str | None = None,
105
+ extra: dict | None = None,
106
+ ) -> None:
107
+ '''Buffer a log entry (see Client.log for the fields). Always returns None - no id
108
+ exists until the batch is sent.'''
109
+ if threading.current_thread() is self._worker_thread:
110
+ # the sender's own HTTP logging (e.g. urllib3 debug output reaching a root-logger
111
+ # handler) must not be queued, or every send would generate more to send
112
+ return
113
+
114
+ entry: dict[str, Any] = {'message': message, 'level': level}
115
+ if request_id is not None:
116
+ entry['request_id'] = request_id
117
+ entry['datetime'] = self._iso(datetime) or _datetime.now(timezone.utc).isoformat()
118
+ if app is not None:
119
+ entry['app'] = app
120
+ if container_id is not None:
121
+ entry['container_id'] = container_id
122
+ if logger_name is not None:
123
+ entry['logger_name'] = logger_name
124
+ if domain is not None:
125
+ entry['domain'] = domain
126
+ if extra is not None:
127
+ entry['extra'] = extra
128
+ self._enqueue(self._logs, entry)
129
+
130
+ def add_metric(
131
+ self,
132
+ value: float,
133
+ metric: str | None = None,
134
+ metric_id: str | None = None,
135
+ timestamp: _datetime | str | None = None,
136
+ auto_create: bool = False,
137
+ ) -> None:
138
+ '''Buffer a metric data point (see Client.add_metric). Only metric names are supported.'''
139
+ if metric_id:
140
+ raise ValueError('metric_id is not supported when batching - use metric (name)')
141
+ if not metric:
142
+ raise ValueError('metric is required')
143
+
144
+ entry = {
145
+ 'metric': metric,
146
+ 'value': value,
147
+ 'timestamp': self._iso(timestamp) or _datetime.now(timezone.utc).isoformat(),
148
+ }
149
+ self._enqueue(self._metrics, (auto_create, entry))
150
+
151
+ def send_trace(self, trace: dict) -> None:
152
+ '''Buffer a finished trace tree. CaptureTrace calls this for you.'''
153
+ self._enqueue(self._traces, trace)
154
+
155
+ def flush(self, timeout: float | None = None) -> bool:
156
+ '''Send everything buffered so far and block until done or timeout elapses. Returns
157
+ True if the buffers are empty and nothing is in flight; False on timeout, or straight
158
+ away if sending is paused by a rate limit.'''
159
+ with self._cond:
160
+ if self._worker_thread.is_alive() and not self._closed_and_stopped():
161
+ self._flush_requested = True
162
+ self._cond.notify_all()
163
+ return self._cond.wait_for(self._is_idle_or_paused_locked, timeout) and self._is_empty_locked()
164
+
165
+ def close(self, timeout: float | None = 5.0) -> bool:
166
+ '''Stop accepting new items, send what's buffered (one attempt per request, no retries)
167
+ and stop the background thread. Returns whether everything was sent within timeout.
168
+ Safe to call more than once.'''
169
+ with self._cond:
170
+ self._closed = True
171
+ self._stop.set()
172
+ self._cond.notify_all()
173
+ self._worker_thread.join(timeout)
174
+ with self._cond:
175
+ return self._is_empty_locked() and not self._in_flight
176
+
177
+ # ---- buffering --------------------------------------------------------------------
178
+
179
+ def _enqueue(self, buffer: collections.deque, item: Any) -> None:
180
+ with self._cond:
181
+ if self._closed:
182
+ self.dropped += 1
183
+ return
184
+ if len(buffer) >= self.max_queue_size:
185
+ buffer.popleft()
186
+ self.dropped += 1
187
+ buffer.append(item)
188
+ if len(buffer) >= self.max_batch_size:
189
+ self._cond.notify_all()
190
+
191
+ def _is_empty_locked(self) -> bool:
192
+ return not (self._logs or self._metrics or self._traces)
193
+
194
+ def _is_idle_or_paused_locked(self) -> bool:
195
+ paused = time.monotonic() < self._paused_until
196
+ return (self._is_empty_locked() and not self._in_flight) or paused
197
+
198
+ def _closed_and_stopped(self) -> bool:
199
+ return self._stop.is_set() and not self._worker_thread.is_alive()
200
+
201
+ def _batch_ready_locked(self) -> bool:
202
+ return (
203
+ len(self._logs) >= self.max_batch_size
204
+ or len(self._metrics) >= self.max_batch_size
205
+ or len(self._traces) >= self.max_batch_size
206
+ )
207
+
208
+ def _drain_locked(self) -> tuple[list[dict], list[dict], list[dict], list[dict]]:
209
+ logs = [self._logs.popleft() for _ in range(min(len(self._logs), self.max_batch_size))]
210
+ traces = [self._traces.popleft() for _ in range(min(len(self._traces), self.max_batch_size))]
211
+ plain_metrics: list[dict] = []
212
+ auto_metrics: list[dict] = []
213
+ for _ in range(min(len(self._metrics), self.max_batch_size)):
214
+ auto_create, entry = self._metrics.popleft()
215
+ (auto_metrics if auto_create else plain_metrics).append(entry)
216
+ return logs, traces, plain_metrics, auto_metrics
217
+
218
+ # ---- background thread ------------------------------------------------------------
219
+
220
+ def _run(self) -> None:
221
+ while True:
222
+ with self._cond:
223
+ if not (self._stop.is_set() or self._flush_requested or self._batch_ready_locked()):
224
+ self._cond.wait(self.flush_interval)
225
+
226
+ stopping = self._stop.is_set()
227
+ paused = not stopping and time.monotonic() < self._paused_until
228
+ if paused or self._is_empty_locked():
229
+ # nothing to send (or sending is paused) - a requested flush is satisfied
230
+ # when there's nothing left, and waiters must be woken either way
231
+ if self._is_empty_locked():
232
+ self._flush_requested = False
233
+ self._cond.notify_all()
234
+ if stopping:
235
+ return
236
+ if paused:
237
+ # don't spin while paused: sleep until the pause ends or we're stopped
238
+ self._cond.wait(min(self.flush_interval, max(self._paused_until - time.monotonic(), 0)))
239
+ continue
240
+
241
+ logs, traces, plain_metrics, auto_metrics = self._drain_locked()
242
+ self._in_flight = True
243
+
244
+ try:
245
+ self._send(logs, traces, plain_metrics, auto_metrics, retry=not stopping)
246
+ finally:
247
+ with self._cond:
248
+ self._in_flight = False
249
+ self._cond.notify_all()
250
+
251
+ # keep draining straight away while anything is left over from a close or flush;
252
+ # otherwise go back to waiting for the next interval
253
+ with self._cond:
254
+ if stopping and self._is_empty_locked():
255
+ return
256
+
257
+ def _send(self, logs: list, traces: list, plain_metrics: list, auto_metrics: list, retry: bool) -> None:
258
+ if logs or traces or plain_metrics:
259
+ payload: dict[str, Any] = {}
260
+ if traces:
261
+ payload['traces'] = traces
262
+ if logs:
263
+ payload['logs'] = {'logs': logs}
264
+ if plain_metrics:
265
+ payload['metrics'] = {'metrics': plain_metrics, 'auto_create': False}
266
+ self._send_with_retry(
267
+ lambda: self._post_sync('/api/ingest/', payload),
268
+ count=len(logs) + len(traces) + len(plain_metrics),
269
+ retry=retry,
270
+ )
271
+ if auto_metrics:
272
+ self._send_with_retry(
273
+ lambda: self._post_sync('/api/ingest/metrics/', {'metrics': auto_metrics, 'auto_create': True}),
274
+ count=len(auto_metrics),
275
+ retry=retry,
276
+ )
277
+
278
+ def _send_with_retry(self, send: Callable[[], Any], count: int, retry: bool) -> None:
279
+ attempts = (self.max_retries if retry else 0) + 1
280
+ for attempt in range(attempts):
281
+ try:
282
+ send()
283
+ return
284
+ except ObsAppRateLimitedError as exc:
285
+ with self._cond:
286
+ self._paused_until = time.monotonic() + self.rate_limit_pause
287
+ self._give_up(exc, count)
288
+ return
289
+ except (ObsAppApiKeyError, ObsAppValidationError) as exc:
290
+ self._give_up(exc, count)
291
+ return
292
+ except ObsAppError as exc:
293
+ if attempt == attempts - 1:
294
+ self._give_up(exc, count)
295
+ return
296
+ # interruptible sleep so close() isn't held up by a long backoff
297
+ if self._stop.wait(min(self.retry_backoff * 2 ** attempt, 30.0)):
298
+ self._give_up(exc, count)
299
+ return
300
+ except Exception as exc: # unexpected - never let it kill the sender thread
301
+ self._give_up(exc, count)
302
+ return
303
+
304
+ def _give_up(self, exc: Exception, count: int) -> None:
305
+ with self._cond:
306
+ self.dropped += count
307
+ if self.on_error is not None:
308
+ try:
309
+ self.on_error(exc)
310
+ except Exception:
311
+ pass # on_error must never kill the sender thread
easy_obs/client.py ADDED
@@ -0,0 +1,266 @@
1
+ from __future__ import annotations
2
+
3
+ import atexit
4
+ import queue
5
+ import threading
6
+ from datetime import datetime
7
+ from typing import Any, Callable
8
+
9
+ import requests
10
+
11
+ from easy_obs.exceptions import ObsAppApiKeyError, ObsAppError, ObsAppRateLimitedError, ObsAppValidationError
12
+
13
+
14
+ class Client:
15
+ '''Thin wrapper around the easy-obs.com ingestion API. Every method makes one
16
+ HTTP call - there's no automatic batching, so batch calls (log_batch, add_metrics, ingest)
17
+ are the way to reduce request count for high-volume callers.
18
+
19
+ By default (background=False) every call is synchronous: it blocks until the response
20
+ arrives and raises on error. Pass background=True to send requests from a single worker
21
+ thread instead - calls return immediately without waiting on the network, and any error
22
+ (auth, validation, rate limit, network) is only ever visible via on_error, never raised to
23
+ the caller, since by the time it happens the call that triggered it has already returned.
24
+ Because of that, background mode is best for logs/metrics where an occasional dropped send
25
+ is tolerable - not for anything the caller needs to confirm succeeded.
26
+
27
+ The queue is unbounded and the worker thread is a daemon, so a burst of calls just before
28
+ process exit can be lost. flush_on_exit=True (the default when background=True) registers
29
+ an atexit hook that gives the queue a few seconds to drain; call flush() directly for more
30
+ control, e.g. before an intentionally fast exit path.'''
31
+
32
+ def __init__(
33
+ self,
34
+ api_key: str,
35
+ base_url: str = 'https://easy-obs.com',
36
+ timeout: float = 5.0,
37
+ session: requests.Session | None = None,
38
+ background: bool = False,
39
+ on_error: Callable[[Exception], None] | None = None,
40
+ flush_on_exit: bool = True,
41
+ ) -> None:
42
+ self.api_key = api_key
43
+ self.base_url = base_url.rstrip('/')
44
+ self.timeout = timeout
45
+ self.session = session or requests.Session()
46
+ self.on_error = on_error
47
+
48
+ self._queue: queue.Queue[tuple[str, dict]] | None = None
49
+ if background:
50
+ self._queue = queue.Queue()
51
+ self._worker_thread = threading.Thread(
52
+ target=self._worker, name='easy-obs-sender', daemon=True,
53
+ )
54
+ self._worker_thread.start()
55
+ if flush_on_exit:
56
+ atexit.register(self.flush, timeout=5.0)
57
+
58
+ def __enter__(self) -> 'Client':
59
+ return self
60
+
61
+ def __exit__(self, *exc_info: object) -> None:
62
+ self.flush()
63
+
64
+ def _worker(self) -> None:
65
+ # runs for the life of the process (daemon thread) pulling queued requests one at a
66
+ # time - a single worker keeps requests in submission order and avoids opening a pile
67
+ # of concurrent connections for what's meant to be a lightweight fire-and-forget path
68
+ while True:
69
+ path, payload = self._queue.get()
70
+ try:
71
+ self._post_sync(path, payload)
72
+ except Exception as exc:
73
+ if self.on_error is not None:
74
+ try:
75
+ self.on_error(exc)
76
+ except Exception:
77
+ pass # on_error must never kill the worker loop
78
+ finally:
79
+ self._queue.task_done()
80
+
81
+ def flush(self, timeout: float | None = None) -> bool:
82
+ '''Block until every request queued so far has been sent (or timeout elapses). No-op
83
+ (returns True immediately) for a client not constructed with background=True. Returns
84
+ whether the queue actually drained within timeout.'''
85
+ if self._queue is None:
86
+ return True
87
+
88
+ drained = threading.Event()
89
+
90
+ def _joiner() -> None:
91
+ self._queue.join()
92
+ drained.set()
93
+
94
+ threading.Thread(target=_joiner, daemon=True).start()
95
+ return drained.wait(timeout)
96
+
97
+ def _post(self, path: str, payload: dict) -> dict | None:
98
+ if self._queue is not None:
99
+ self._queue.put((path, payload))
100
+ return None
101
+ return self._post_sync(path, payload)
102
+
103
+ def _post_sync(self, path: str, payload: dict) -> dict:
104
+ try:
105
+ response = self.session.post(
106
+ f'{self.base_url}{path}',
107
+ json=payload,
108
+ headers={'Authorization': f'Bearer {self.api_key}'},
109
+ timeout=self.timeout,
110
+ )
111
+ except requests.RequestException as exc:
112
+ raise ObsAppError(f'Request to {path} failed: {exc}') from exc
113
+
114
+ if response.status_code == 429:
115
+ # the server blocks the offending IP for 1 hour once the rolling rate-limit window
116
+ # trips - the block response isn't guaranteed to be JSON (some paths render an HTML
117
+ # template instead), so parse defensively. Retrying immediately will not help.
118
+ try:
119
+ message = response.json().get('error', 'Rate limited')
120
+ except ValueError:
121
+ message = 'Rate limited - IP is blocked for up to 1 hour, do not retry immediately'
122
+ raise ObsAppRateLimitedError(message)
123
+
124
+ try:
125
+ body = response.json()
126
+ except ValueError:
127
+ body = {}
128
+
129
+ if response.status_code == 401:
130
+ raise ObsAppApiKeyError(body.get('error', 'Invalid or missing API key'))
131
+
132
+ if response.status_code == 400:
133
+ raise ObsAppValidationError(body.get('error', 'Invalid data'), errors=body.get('errors'))
134
+
135
+ if not response.ok:
136
+ raise ObsAppError(f'{path} returned HTTP {response.status_code}: {body}')
137
+
138
+ return body
139
+
140
+ @staticmethod
141
+ def _iso(value: datetime | str | None) -> str | None:
142
+ if value is None or isinstance(value, str):
143
+ return value
144
+ return value.isoformat()
145
+
146
+ def log(
147
+ self,
148
+ message: str,
149
+ level: int = 4,
150
+ request_id: str | None = None,
151
+ datetime: datetime | str | None = None,
152
+ app: str | None = None,
153
+ container_id: str | None = None,
154
+ logger_name: str | None = None,
155
+ domain: str | None = None,
156
+ extra: dict | None = None,
157
+ ) -> str | None:
158
+ '''POST /api/log/ - level: 1=Critical, 2=Error, 3=Warning, 4=Info (default), 5=Debug.
159
+ datetime defaults server-side to the time of receipt if omitted. app/container_id/
160
+ logger_name/domain are free-form tags for filtering in the dashboard; extra is an
161
+ arbitrary JSON-serializable dict of additional context. Returns the server-assigned log
162
+ id, or None if this client was constructed with background=True - the request is only
163
+ queued at that point, so no id is available yet.'''
164
+ payload: dict[str, Any] = {'message': message, 'level': level}
165
+ if request_id is not None:
166
+ payload['request_id'] = request_id
167
+ iso_datetime = self._iso(datetime)
168
+ if iso_datetime is not None:
169
+ payload['datetime'] = iso_datetime
170
+ if app is not None:
171
+ payload['app'] = app
172
+ if container_id is not None:
173
+ payload['container_id'] = container_id
174
+ if logger_name is not None:
175
+ payload['logger_name'] = logger_name
176
+ if domain is not None:
177
+ payload['domain'] = domain
178
+ if extra is not None:
179
+ payload['extra'] = extra
180
+ result = self._post('/api/log/', payload)
181
+ return result['id'] if result is not None else None
182
+
183
+ def log_batch(self, logs: list[dict], request_id: str | None = None) -> None:
184
+ '''POST /api/ingest/logs/ - each entry in logs is {'message': str, 'level'?: int,
185
+ 'request_id'?: str, 'datetime'?: datetime | str, 'app'?: str, 'container_id'?: str,
186
+ 'logger_name'?: str, 'domain'?: str, 'extra'?: dict}.
187
+ request_id (if given) applies to any entry that doesn't specify its own.'''
188
+ normalized = []
189
+ for entry in logs:
190
+ entry = dict(entry)
191
+ if 'datetime' in entry:
192
+ entry['datetime'] = self._iso(entry['datetime'])
193
+ normalized.append(entry)
194
+
195
+ payload: dict[str, Any] = {'logs': normalized}
196
+ if request_id is not None:
197
+ payload['request_id'] = request_id
198
+ self._post('/api/ingest/logs/', payload)
199
+
200
+ def add_metric(
201
+ self,
202
+ value: float,
203
+ metric: str | None = None,
204
+ metric_id: str | None = None,
205
+ timestamp: datetime | str | None = None,
206
+ auto_create: bool = False,
207
+ ) -> None:
208
+ '''POST /api/metric/ - provide exactly one of metric (name) or metric_id.'''
209
+ if not metric and not metric_id:
210
+ raise ValueError('Either metric or metric_id is required')
211
+ if metric and metric_id:
212
+ raise ValueError('Provide only one of metric or metric_id')
213
+
214
+ payload: dict[str, Any] = {'value': value, 'auto_create': auto_create}
215
+ if metric:
216
+ payload['metric'] = metric
217
+ if metric_id:
218
+ payload['metric_id'] = metric_id
219
+ iso_timestamp = self._iso(timestamp)
220
+ if iso_timestamp is not None:
221
+ payload['timestamp'] = iso_timestamp
222
+
223
+ self._post('/api/metric/', payload)
224
+
225
+ def add_metrics(self, metrics: list[dict], auto_create: bool = False) -> None:
226
+ '''POST /api/ingest/metrics/ - each entry is {'metric': str, 'value': float, 'timestamp'?: ...}.
227
+ Note: unlike add_metric, the server does not support metric_id-based lookup in a batch -
228
+ every entry must use 'metric' (name).'''
229
+ normalized = []
230
+ for entry in metrics:
231
+ entry = dict(entry)
232
+ if 'timestamp' in entry:
233
+ entry['timestamp'] = self._iso(entry['timestamp'])
234
+ normalized.append(entry)
235
+
236
+ payload = {'metrics': normalized, 'auto_create': auto_create}
237
+ self._post('/api/ingest/metrics/', payload)
238
+
239
+ def send_trace(self, trace: dict) -> None:
240
+ '''POST /api/trace/ - trace is a single tree: {'start': ..., 'end': ..., 'text'?: str,
241
+ 'traces'?: [nested trace trees]}. Prefer CaptureTrace over calling this directly.'''
242
+ self._post('/api/trace/', trace)
243
+
244
+ def ingest(
245
+ self,
246
+ traces: list[dict] | None = None,
247
+ logs: dict | None = None,
248
+ metrics: dict | None = None,
249
+ ) -> None:
250
+ '''POST /api/ingest/ - submit traces/logs/metrics in a single request, validated
251
+ all-or-nothing by the server (if any section is invalid, nothing is processed).
252
+ traces is a *list* of trace trees (unlike send_trace, which takes one).
253
+ logs is {'logs': [...], 'request_id'?: str} (same shape as log_batch's payload).
254
+ metrics is {'metrics': [...], 'auto_create'?: bool} (same shape as add_metrics' payload).'''
255
+ if traces is None and logs is None and metrics is None:
256
+ raise ValueError('At least one of traces, logs, or metrics is required')
257
+
258
+ payload: dict[str, Any] = {}
259
+ if traces is not None:
260
+ payload['traces'] = traces
261
+ if logs is not None:
262
+ payload['logs'] = logs
263
+ if metrics is not None:
264
+ payload['metrics'] = metrics
265
+
266
+ self._post('/api/ingest/', payload)
easy_obs/exceptions.py ADDED
@@ -0,0 +1,26 @@
1
+ class ObsAppError(Exception):
2
+ '''Base class for all errors raised by this SDK.'''
3
+
4
+ def __init__(self, message: str) -> None:
5
+ self.message = message
6
+ super().__init__(message)
7
+
8
+
9
+ class ObsAppApiKeyError(ObsAppError):
10
+ '''Raised on a 401 response - the API key is missing or invalid.'''
11
+
12
+
13
+ class ObsAppValidationError(ObsAppError):
14
+ '''Raised on a 400 response. `errors` holds the per-field error dict when the server
15
+ returned one (schema validation failures); it's None for single-message 400s (e.g.
16
+ 'Invalid metrics: ...').'''
17
+
18
+ def __init__(self, message: str, errors: dict | None = None) -> None:
19
+ self.errors = errors
20
+ super().__init__(message)
21
+
22
+
23
+ class ObsAppRateLimitedError(ObsAppError):
24
+ '''Raised on a 429 response. The server enforces a rolling-window rate limit and blocks
25
+ the offending IP for 1 hour once tripped - do not retry immediately, it will not help and
26
+ only keeps the block window extending.'''
@@ -0,0 +1,70 @@
1
+ from __future__ import annotations
2
+
3
+ import logging
4
+ from datetime import datetime, timezone
5
+ from typing import TYPE_CHECKING
6
+
7
+ if TYPE_CHECKING:
8
+ from easy_obs.client import Client
9
+
10
+ # obs_app's own level scale (projects/obs_app/models.py): 1=Critical, 2=Error, 3=Warning,
11
+ # 4=Info, 5=Debug - the reverse of Python's, where higher stdlib levelno means more severe.
12
+ _STDLIB_TO_OBS_APP_LEVEL = {
13
+ logging.CRITICAL: 1,
14
+ logging.ERROR: 2,
15
+ logging.WARNING: 3,
16
+ logging.INFO: 4,
17
+ logging.DEBUG: 5,
18
+ }
19
+
20
+
21
+ def _map_level(levelno: int) -> int:
22
+ for stdlib_level in sorted(_STDLIB_TO_OBS_APP_LEVEL, reverse=True):
23
+ if levelno >= stdlib_level:
24
+ return _STDLIB_TO_OBS_APP_LEVEL[stdlib_level]
25
+ return 5 # anything below DEBUG maps to Debug
26
+
27
+
28
+ class ObsAppLogHandler(logging.Handler):
29
+ '''logging.Handler that forwards records to easy-obs.com via Client.log(). Attach it to
30
+ any stdlib logger to pipe that logger's output to the obs_app dashboard:
31
+
32
+ handler = ObsAppLogHandler(client)
33
+ logging.getLogger().addHandler(handler)
34
+
35
+ Each record is sent as its own HTTP request - for high-volume logging, log directly via
36
+ Client.log_batch() instead rather than relying on this handler.
37
+
38
+ app/domain/container_id are fixed tags stamped on every record this handler emits (e.g.
39
+ which service/environment/container the process is running in) - set them once here rather
40
+ than per log call. logger_name and datetime are filled in automatically from the record
41
+ (record.name, record.created) - the latter is when the record was created, not when it
42
+ reaches this handler.
43
+ '''
44
+
45
+ def __init__(
46
+ self,
47
+ client: 'Client',
48
+ app: str | None = None,
49
+ domain: str | None = None,
50
+ container_id: str | None = None,
51
+ ) -> None:
52
+ super().__init__()
53
+ self.client = client
54
+ self.app = app
55
+ self.domain = domain
56
+ self.container_id = container_id
57
+
58
+ def emit(self, record: logging.LogRecord) -> None:
59
+ try:
60
+ self.client.log(
61
+ message=self.format(record),
62
+ level=_map_level(record.levelno),
63
+ datetime=datetime.fromtimestamp(record.created, tz=timezone.utc),
64
+ logger_name=record.name,
65
+ app=self.app,
66
+ domain=self.domain,
67
+ container_id=self.container_id,
68
+ )
69
+ except Exception:
70
+ self.handleError(record)
easy_obs/py.typed ADDED
File without changes
easy_obs/tracing.py ADDED
@@ -0,0 +1,67 @@
1
+ from __future__ import annotations
2
+
3
+ import contextvars
4
+ from datetime import datetime, timezone
5
+ from typing import TYPE_CHECKING
6
+
7
+ if TYPE_CHECKING:
8
+ from easy_obs.client import Client
9
+
10
+ # thread/async-safe nesting - matches the server-side semantics of the internal
11
+ # obs_app.utils.CaptureTrace: only the root span, on exit, flushes the whole assembled tree.
12
+ _current: contextvars.ContextVar['CaptureTrace | None'] = contextvars.ContextVar('_current', default=None)
13
+
14
+
15
+ class CaptureTrace:
16
+ '''HTTP-backed equivalent of obs_app's internal CaptureTrace context manager. Nested
17
+ instances accumulate into a single tree; only the outermost (root) instance sends the
18
+ whole tree to the server, on exit, via client.send_trace().
19
+
20
+ with CaptureTrace(client, "outer", app="my-app"):
21
+ with CaptureTrace(client, "inner step"):
22
+ do_work()
23
+
24
+ `app` says which of your apps the trace came from (it is what the dashboard's Traces page filters by). Set it on the outermost span: the
25
+ spans inside take it from there, unless one is given its own.
26
+ '''
27
+
28
+ def __init__(self, client: 'Client', text: str = '', app: str | None = None) -> None:
29
+ self.client = client
30
+ self.text = text
31
+ self.app = app
32
+ self.children: list['CaptureTrace'] = []
33
+ self.parent: 'CaptureTrace | None' = None
34
+ self.start: str | None = None
35
+ self.end: str | None = None
36
+ self._token: contextvars.Token | None = None
37
+
38
+ def __enter__(self) -> 'CaptureTrace':
39
+ self.start = datetime.now(timezone.utc).isoformat()
40
+
41
+ parent = _current.get()
42
+ if parent is not None:
43
+ self.parent = parent
44
+ parent.children.append(self)
45
+
46
+ self._token = _current.set(self)
47
+ return self
48
+
49
+ def __exit__(self, *exc_info: object) -> None:
50
+ self.end = datetime.now(timezone.utc).isoformat()
51
+ if self._token is not None:
52
+ _current.reset(self._token)
53
+
54
+ if self.parent is None:
55
+ self.client.send_trace(self.to_dict())
56
+
57
+ def to_dict(self) -> dict:
58
+ data = {'start': self.start, 'end': self.end}
59
+ if self.text:
60
+ data['text'] = self.text
61
+ if self.app:
62
+ data['app'] = self.app
63
+
64
+ if self.children:
65
+ data['traces'] = [child.to_dict() for child in self.children]
66
+
67
+ return data
@@ -0,0 +1,76 @@
1
+ from __future__ import annotations
2
+
3
+ import functools
4
+ import traceback
5
+ from typing import TYPE_CHECKING, Any, Callable, TypeVar
6
+
7
+ if TYPE_CHECKING:
8
+ from easy_obs.client import Client
9
+
10
+ F = TypeVar('F', bound=Callable[..., Any])
11
+
12
+ # repr() of a view argument (e.g. a request body or ORM instance) can be arbitrarily large -
13
+ # cap each one so a single huge argument can't blow past the server's payload size limit and
14
+ # turn error reporting itself into a 400.
15
+ _MAX_REPR_LENGTH = 2000
16
+
17
+
18
+ def _safe_repr(value: Any) -> str:
19
+ try:
20
+ text = repr(value)
21
+ except Exception as exc:
22
+ return f'<repr() failed: {exc!r}>'
23
+ if len(text) > _MAX_REPR_LENGTH:
24
+ return text[:_MAX_REPR_LENGTH] + '...<truncated>'
25
+ return text
26
+
27
+
28
+ def capture_errors(
29
+ client: 'Client',
30
+ app: str | None = None,
31
+ domain: str | None = None,
32
+ container_id: str | None = None,
33
+ logger_name: str | None = None,
34
+ ) -> Callable[[F], F]:
35
+ '''Decorator for view functions. Runs the wrapped function normally; if it raises, reports
36
+ an ERROR-level log to the observability API (exception message, full traceback, and repr()
37
+ of the call's args/kwargs in `extra`), then re-raises so the caller's/framework's own error
38
+ handling (e.g. a 500 response) is unaffected - this decorator only observes, it never
39
+ swallows the exception.
40
+
41
+ If reporting itself fails (network error, bad API key, etc.) that failure is swallowed -
42
+ it must never replace or mask the original exception.
43
+
44
+ @capture_errors(client, app="my-app")
45
+ def my_view(request, user_id):
46
+ ...
47
+
48
+ repr() of every argument is sent as-is - be mindful of passing secrets/PII as view
49
+ arguments if that's a concern for your application.
50
+ '''
51
+ def decorator(func: F) -> F:
52
+ @functools.wraps(func)
53
+ def wrapper(*args: Any, **kwargs: Any) -> Any:
54
+ try:
55
+ return func(*args, **kwargs)
56
+ except Exception as exc:
57
+ try:
58
+ client.log(
59
+ message=f'Unhandled exception in {func.__qualname__}: {exc!r}',
60
+ level=2, # Error
61
+ app=app,
62
+ domain=domain,
63
+ container_id=container_id,
64
+ logger_name=logger_name or func.__module__,
65
+ extra={
66
+ 'exception_type': type(exc).__qualname__,
67
+ 'traceback': traceback.format_exc(),
68
+ 'args': [_safe_repr(a) for a in args],
69
+ 'kwargs': {k: _safe_repr(v) for k, v in kwargs.items()},
70
+ },
71
+ )
72
+ except Exception:
73
+ pass
74
+ raise
75
+ return wrapper
76
+ return decorator
@@ -0,0 +1,180 @@
1
+ Metadata-Version: 2.5
2
+ Name: easy_obs
3
+ Version: 0.5.0
4
+ Summary: Python client for the easy-obs.com (obs_app) ingestion API - logs, metrics and traces.
5
+ Project-URL: Homepage, https://github.com/cturner91/obs-app-sdk
6
+ Project-URL: Repository, https://github.com/cturner91/obs-app-sdk
7
+ Author-email: Conor Turner <conor_turner@hotmail.com>
8
+ License: MIT
9
+ License-File: LICENSE
10
+ Classifier: Intended Audience :: Developers
11
+ Classifier: License :: OSI Approved :: MIT License
12
+ Classifier: Operating System :: OS Independent
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Topic :: System :: Logging
15
+ Classifier: Topic :: System :: Monitoring
16
+ Requires-Python: >=3.9
17
+ Requires-Dist: requests>=2.25
18
+ Provides-Extra: test
19
+ Requires-Dist: pytest>=7.0; extra == 'test'
20
+ Description-Content-Type: text/markdown
21
+
22
+ # easy-obs
23
+
24
+ Python client for the [easy-obs.com](https://easy-obs.com) ingestion API - send logs,
25
+ metrics and traces from your application.
26
+
27
+ ## Install
28
+
29
+ ```bash
30
+ pip install easy_obs
31
+ ```
32
+
33
+ (formerly published as `ct_obs_app` - if you're upgrading, `pip uninstall ct_obs_app` and change imports from `obs_app_sdk` to `easy_obs`)
34
+
35
+ ## Get an API key
36
+
37
+ Log in at the obs_app dashboard and copy your API key from the profile page (rotate it there
38
+ too, if needed). The SDK authenticates every request with it.
39
+
40
+ ## Quickstart
41
+
42
+ ```python
43
+ from datetime import datetime, timezone
44
+
45
+ from easy_obs import Client, CaptureTrace
46
+
47
+ client = Client(api_key="your-api-key")
48
+
49
+ # Logging
50
+ client.log("Something happened", level=4) # 1=Critical .. 5=Debug, default 4=Info
51
+ client.log(
52
+ "Something happened",
53
+ datetime=datetime.now(timezone.utc), # defaults to time of receipt if omitted
54
+ app="my-app", domain="example.com", container_id="ctr-1", logger_name="myapp.worker",
55
+ extra={"user_id": 42},
56
+ )
57
+ client.log_batch([{"message": "a"}, {"message": "b"}])
58
+
59
+ # Metrics
60
+ client.add_metric(value=1.0, metric="request_duration_ms", auto_create=True)
61
+ client.add_metrics([
62
+ {"metric": "request_duration_ms", "value": 12.3},
63
+ {"metric": "queue_depth", "value": 4},
64
+ ], auto_create=True)
65
+
66
+ # Traces - nested context managers build one tree, sent as a single request when the
67
+ # outermost one exits
68
+ with CaptureTrace(client, "handle_request", app="my-app"): # app is optional; the inner spans take it from here
69
+ with CaptureTrace(client, "query_db"):
70
+ ...
71
+ with CaptureTrace(client, "render_response"):
72
+ ...
73
+
74
+ # Or submit logs/metrics/traces together in one request (validated all-or-nothing)
75
+ client.ingest(
76
+ logs={"logs": [{"message": "started"}]},
77
+ metrics={"metrics": [{"metric": "request_duration_ms", "value": 12.3}]},
78
+ traces=[{"start": "...", "end": "...", "text": "handled"}],
79
+ )
80
+ ```
81
+
82
+ ## Stdlib logging integration
83
+
84
+ ```python
85
+ import logging
86
+ from easy_obs import Client, ObsAppLogHandler
87
+
88
+ client = Client(api_key="your-api-key")
89
+ logging.getLogger().addHandler(ObsAppLogHandler(client, app="my-app", domain="example.com"))
90
+ ```
91
+
92
+ Each stdlib log record becomes one `POST /api/log/` call. `logger_name` and `datetime` are
93
+ filled in automatically from the record; `app`/`domain`/`container_id` are fixed tags you set
94
+ once on the handler. For high-volume logging, call `client.log_batch(...)` directly instead of
95
+ relying on the handler.
96
+
97
+ ## Reporting view errors
98
+
99
+ ```python
100
+ from easy_obs import Client, capture_errors
101
+
102
+ client = Client(api_key="your-api-key")
103
+
104
+ @capture_errors(client, app="my-app", domain="example.com")
105
+ def my_view(request, user_id):
106
+ ...
107
+ ```
108
+
109
+ Wrap a view (or any function) with `capture_errors`. If it raises, the decorator sends an
110
+ ERROR-level log (`level=2`) to the API with the exception message, the full traceback, and
111
+ `repr()` of the call's args/kwargs under `extra`, then **re-raises** - your framework's normal
112
+ error handling (e.g. a 500 response) still runs unchanged; this only observes. A failure while
113
+ reporting (network error, bad API key, etc.) is swallowed so it can never replace or mask the
114
+ original exception.
115
+
116
+ `repr()` of every argument is sent as-is (truncated past 2000 characters) - be mindful of
117
+ passing secrets/PII as view arguments if that's a concern for your application.
118
+
119
+ ## Background (fire-and-forget) mode
120
+
121
+ ```python
122
+ client = Client(api_key="your-api-key", background=True, on_error=lambda exc: print("send failed:", exc))
123
+ client.log("Something happened") # returns None immediately - queued, not yet sent
124
+ ```
125
+
126
+ Pass `background=True` and every call is queued and sent from a single background thread
127
+ instead of blocking the caller. Because the call has already returned by the time the request
128
+ actually goes out, errors (auth, validation, rate limit, network) can't be raised back to the
129
+ caller - they're only passed to `on_error`, if you provide one, otherwise dropped. `Client.log`
130
+ returns `None` in this mode instead of the log id, since it isn't known yet. Only use this for
131
+ data you can afford to lose occasionally (logs, metrics) - not for anything you need to confirm
132
+ succeeded.
133
+
134
+ The queue is unbounded and the worker thread is a daemon, so anything queued right before the
135
+ process exits can be lost. `flush_on_exit=True` (the default) registers an `atexit` hook that
136
+ gives the queue a few seconds to drain; call `client.flush(timeout=...)` directly, or use
137
+ `Client` as a context manager, for more control.
138
+
139
+ ## Batching client (background, bulk send)
140
+
141
+ ```python
142
+ from easy_obs import BatchingClient
143
+
144
+ client = BatchingClient(api_key="your-api-key", flush_interval=5.0, on_error=lambda exc: print("send failed:", exc))
145
+ client.log("Something happened") # buffered, returns None immediately
146
+ client.add_metric(1.0, metric="jobs_done", auto_create=True)
147
+ ```
148
+
149
+ `BatchingClient` buffers logs, metrics and traces in memory and a background thread sends them
150
+ together in a single `POST /api/ingest/` every `flush_interval` seconds (default 5), or sooner
151
+ once `max_batch_size` (default 500) items of one kind are waiting. `log`, `add_metric` and
152
+ `send_trace` - and so `ObsAppLogHandler`, `CaptureTrace` and `capture_errors` - work with it
153
+ unchanged and never block on the network.
154
+
155
+ - Network errors / 5xx are retried (`max_retries`, exponential backoff); 400/401 are dropped
156
+ immediately; 429 drops the batch and pauses sending for `rate_limit_pause` seconds.
157
+ - Each buffer is capped at `max_queue_size` (default 10,000); the oldest items are discarded
158
+ when full. `client.dropped` counts everything lost.
159
+ - Errors only reach `on_error`, never the caller. `add_metric` takes metric names only (no `metric_id`).
160
+ - Call `client.flush()` to send now, and `client.close()` (or use it as a context manager) to
161
+ shut down cleanly. An `atexit` hook does this for you by default.
162
+
163
+ ## Error handling
164
+
165
+ All methods raise on non-2xx responses:
166
+
167
+ - `ObsAppApiKeyError` - missing/invalid API key (HTTP 401)
168
+ - `ObsAppValidationError` - invalid request data (HTTP 400); `.errors` holds the server's
169
+ per-field error dict when there is one, else `None`
170
+ - `ObsAppRateLimitedError` - HTTP 429. The API blocks the offending IP for **1 hour** once its
171
+ rolling rate-limit window trips - do not retry in a loop on this error, it won't help
172
+ - `ObsAppError` - base class; also raised for network failures and unexpected status codes
173
+
174
+ ## Notes
175
+
176
+ - This client is synchronous and makes one HTTP request per call - there is no background
177
+ buffering/auto-flush thread. Use the batch methods (`log_batch`, `add_metrics`, `ingest`)
178
+ to reduce request count for high-volume callers.
179
+ - `add_metrics` (batch) only supports metric names, not `metric_id` - use `add_metric`
180
+ (singular) for id-based lookups.
@@ -0,0 +1,12 @@
1
+ easy_obs/__init__.py,sha256=KRt0irkyPJmgFETTXwT2FkQjv1Fs9cz8FPaUv28grBI,584
2
+ easy_obs/batching_client.py,sha256=OI6tLSE9SzLy7nVOpy5rXataVTl3tcUmrRhx7zw3VXQ,13560
3
+ easy_obs/client.py,sha256=RCy7r3wn0Y82bXW4itA-wZAA4kvVNBDmOkJ9oRd90WM,11231
4
+ easy_obs/exceptions.py,sha256=k1G6M0-GtjWnwDxdJH3QT2HrAd-VVP3_OJCrBanRzZI,977
5
+ easy_obs/logging_handler.py,sha256=5c8fNcEkIfRrtsMaasQ7hQnrLYwGp6qJwAiAJ4csCj8,2466
6
+ easy_obs/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
7
+ easy_obs/tracing.py,sha256=dhitCxNC-0NS4Leoso6oRm_7Ei83XCus0HhG3tVVZk4,2365
8
+ easy_obs/view_errors.py,sha256=gwHBt9ZIobsXQni2XWNikhGgximpe6yJ1oKB1oRcJWk,2820
9
+ easy_obs-0.5.0.dist-info/METADATA,sha256=pxnQ4QtehvmpvPctMinOtUuN-zhb6_K9rxzIkbGFnhY,7533
10
+ easy_obs-0.5.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
11
+ easy_obs-0.5.0.dist-info/licenses/LICENSE,sha256=opPlphuph-fe8deDZ3-uKr3Mq8EU_VLjc69MNIB2_4o,1069
12
+ easy_obs-0.5.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Conor Turner
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.