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 +20 -0
- easy_obs/batching_client.py +311 -0
- easy_obs/client.py +266 -0
- easy_obs/exceptions.py +26 -0
- easy_obs/logging_handler.py +70 -0
- easy_obs/py.typed +0 -0
- easy_obs/tracing.py +67 -0
- easy_obs/view_errors.py +76 -0
- easy_obs-0.5.0.dist-info/METADATA +180 -0
- easy_obs-0.5.0.dist-info/RECORD +12 -0
- easy_obs-0.5.0.dist-info/WHEEL +4 -0
- easy_obs-0.5.0.dist-info/licenses/LICENSE +21 -0
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
|
easy_obs/view_errors.py
ADDED
|
@@ -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,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.
|