easy-obs 0.5.0__tar.gz

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.
@@ -0,0 +1,37 @@
1
+ name: Publish to PyPI
2
+
3
+ on:
4
+ push:
5
+ tags:
6
+ - 'v*'
7
+
8
+ permissions:
9
+ contents: read
10
+
11
+ jobs:
12
+ build:
13
+ runs-on: ubuntu-latest
14
+ steps:
15
+ - uses: actions/checkout@v4
16
+ - uses: actions/setup-python@v5
17
+ with:
18
+ python-version: "3.x"
19
+ - run: pip install build
20
+ - run: python -m build
21
+ - uses: actions/upload-artifact@v4
22
+ with:
23
+ name: dist
24
+ path: dist/
25
+
26
+ publish:
27
+ needs: build
28
+ runs-on: ubuntu-latest
29
+ environment: pypi
30
+ permissions:
31
+ id-token: write # required for PyPI trusted publishing (OIDC) - no token/secret needed
32
+ steps:
33
+ - uses: actions/download-artifact@v4
34
+ with:
35
+ name: dist
36
+ path: dist/
37
+ - uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,8 @@
1
+ .venv/
2
+ __pycache__/
3
+ *.egg-info/
4
+ .pytest_cache/
5
+ htmlcov/
6
+ .coverage
7
+ build/
8
+ dist/
easy_obs-0.5.0/LICENSE ADDED
@@ -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.
@@ -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,159 @@
1
+ # easy-obs
2
+
3
+ Python client for the [easy-obs.com](https://easy-obs.com) ingestion API - send logs,
4
+ metrics and traces from your application.
5
+
6
+ ## Install
7
+
8
+ ```bash
9
+ pip install easy_obs
10
+ ```
11
+
12
+ (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`)
13
+
14
+ ## Get an API key
15
+
16
+ Log in at the obs_app dashboard and copy your API key from the profile page (rotate it there
17
+ too, if needed). The SDK authenticates every request with it.
18
+
19
+ ## Quickstart
20
+
21
+ ```python
22
+ from datetime import datetime, timezone
23
+
24
+ from easy_obs import Client, CaptureTrace
25
+
26
+ client = Client(api_key="your-api-key")
27
+
28
+ # Logging
29
+ client.log("Something happened", level=4) # 1=Critical .. 5=Debug, default 4=Info
30
+ client.log(
31
+ "Something happened",
32
+ datetime=datetime.now(timezone.utc), # defaults to time of receipt if omitted
33
+ app="my-app", domain="example.com", container_id="ctr-1", logger_name="myapp.worker",
34
+ extra={"user_id": 42},
35
+ )
36
+ client.log_batch([{"message": "a"}, {"message": "b"}])
37
+
38
+ # Metrics
39
+ client.add_metric(value=1.0, metric="request_duration_ms", auto_create=True)
40
+ client.add_metrics([
41
+ {"metric": "request_duration_ms", "value": 12.3},
42
+ {"metric": "queue_depth", "value": 4},
43
+ ], auto_create=True)
44
+
45
+ # Traces - nested context managers build one tree, sent as a single request when the
46
+ # outermost one exits
47
+ with CaptureTrace(client, "handle_request", app="my-app"): # app is optional; the inner spans take it from here
48
+ with CaptureTrace(client, "query_db"):
49
+ ...
50
+ with CaptureTrace(client, "render_response"):
51
+ ...
52
+
53
+ # Or submit logs/metrics/traces together in one request (validated all-or-nothing)
54
+ client.ingest(
55
+ logs={"logs": [{"message": "started"}]},
56
+ metrics={"metrics": [{"metric": "request_duration_ms", "value": 12.3}]},
57
+ traces=[{"start": "...", "end": "...", "text": "handled"}],
58
+ )
59
+ ```
60
+
61
+ ## Stdlib logging integration
62
+
63
+ ```python
64
+ import logging
65
+ from easy_obs import Client, ObsAppLogHandler
66
+
67
+ client = Client(api_key="your-api-key")
68
+ logging.getLogger().addHandler(ObsAppLogHandler(client, app="my-app", domain="example.com"))
69
+ ```
70
+
71
+ Each stdlib log record becomes one `POST /api/log/` call. `logger_name` and `datetime` are
72
+ filled in automatically from the record; `app`/`domain`/`container_id` are fixed tags you set
73
+ once on the handler. For high-volume logging, call `client.log_batch(...)` directly instead of
74
+ relying on the handler.
75
+
76
+ ## Reporting view errors
77
+
78
+ ```python
79
+ from easy_obs import Client, capture_errors
80
+
81
+ client = Client(api_key="your-api-key")
82
+
83
+ @capture_errors(client, app="my-app", domain="example.com")
84
+ def my_view(request, user_id):
85
+ ...
86
+ ```
87
+
88
+ Wrap a view (or any function) with `capture_errors`. If it raises, the decorator sends an
89
+ ERROR-level log (`level=2`) to the API with the exception message, the full traceback, and
90
+ `repr()` of the call's args/kwargs under `extra`, then **re-raises** - your framework's normal
91
+ error handling (e.g. a 500 response) still runs unchanged; this only observes. A failure while
92
+ reporting (network error, bad API key, etc.) is swallowed so it can never replace or mask the
93
+ original exception.
94
+
95
+ `repr()` of every argument is sent as-is (truncated past 2000 characters) - be mindful of
96
+ passing secrets/PII as view arguments if that's a concern for your application.
97
+
98
+ ## Background (fire-and-forget) mode
99
+
100
+ ```python
101
+ client = Client(api_key="your-api-key", background=True, on_error=lambda exc: print("send failed:", exc))
102
+ client.log("Something happened") # returns None immediately - queued, not yet sent
103
+ ```
104
+
105
+ Pass `background=True` and every call is queued and sent from a single background thread
106
+ instead of blocking the caller. Because the call has already returned by the time the request
107
+ actually goes out, errors (auth, validation, rate limit, network) can't be raised back to the
108
+ caller - they're only passed to `on_error`, if you provide one, otherwise dropped. `Client.log`
109
+ returns `None` in this mode instead of the log id, since it isn't known yet. Only use this for
110
+ data you can afford to lose occasionally (logs, metrics) - not for anything you need to confirm
111
+ succeeded.
112
+
113
+ The queue is unbounded and the worker thread is a daemon, so anything queued right before the
114
+ process exits can be lost. `flush_on_exit=True` (the default) registers an `atexit` hook that
115
+ gives the queue a few seconds to drain; call `client.flush(timeout=...)` directly, or use
116
+ `Client` as a context manager, for more control.
117
+
118
+ ## Batching client (background, bulk send)
119
+
120
+ ```python
121
+ from easy_obs import BatchingClient
122
+
123
+ client = BatchingClient(api_key="your-api-key", flush_interval=5.0, on_error=lambda exc: print("send failed:", exc))
124
+ client.log("Something happened") # buffered, returns None immediately
125
+ client.add_metric(1.0, metric="jobs_done", auto_create=True)
126
+ ```
127
+
128
+ `BatchingClient` buffers logs, metrics and traces in memory and a background thread sends them
129
+ together in a single `POST /api/ingest/` every `flush_interval` seconds (default 5), or sooner
130
+ once `max_batch_size` (default 500) items of one kind are waiting. `log`, `add_metric` and
131
+ `send_trace` - and so `ObsAppLogHandler`, `CaptureTrace` and `capture_errors` - work with it
132
+ unchanged and never block on the network.
133
+
134
+ - Network errors / 5xx are retried (`max_retries`, exponential backoff); 400/401 are dropped
135
+ immediately; 429 drops the batch and pauses sending for `rate_limit_pause` seconds.
136
+ - Each buffer is capped at `max_queue_size` (default 10,000); the oldest items are discarded
137
+ when full. `client.dropped` counts everything lost.
138
+ - Errors only reach `on_error`, never the caller. `add_metric` takes metric names only (no `metric_id`).
139
+ - Call `client.flush()` to send now, and `client.close()` (or use it as a context manager) to
140
+ shut down cleanly. An `atexit` hook does this for you by default.
141
+
142
+ ## Error handling
143
+
144
+ All methods raise on non-2xx responses:
145
+
146
+ - `ObsAppApiKeyError` - missing/invalid API key (HTTP 401)
147
+ - `ObsAppValidationError` - invalid request data (HTTP 400); `.errors` holds the server's
148
+ per-field error dict when there is one, else `None`
149
+ - `ObsAppRateLimitedError` - HTTP 429. The API blocks the offending IP for **1 hour** once its
150
+ rolling rate-limit window trips - do not retry in a loop on this error, it won't help
151
+ - `ObsAppError` - base class; also raised for network failures and unexpected status codes
152
+
153
+ ## Notes
154
+
155
+ - This client is synchronous and makes one HTTP request per call - there is no background
156
+ buffering/auto-flush thread. Use the batch methods (`log_batch`, `add_metrics`, `ingest`)
157
+ to reduce request count for high-volume callers.
158
+ - `add_metrics` (batch) only supports metric names, not `metric_id` - use `add_metric`
159
+ (singular) for id-based lookups.
@@ -0,0 +1,60 @@
1
+ #!/usr/bin/env bash
2
+ # Bump the package version and push a tag to trigger the PyPI publish workflow.
3
+ #
4
+ # Usage: ./bump-version.sh PATCH|MINOR|MAJOR
5
+ set -euo pipefail
6
+
7
+ cd "$(dirname "${BASH_SOURCE[0]}")"
8
+
9
+ TYPE="${1:-}"
10
+ if [[ -z "$TYPE" ]]; then
11
+ echo "Usage: $0 PATCH|MINOR|MAJOR" >&2
12
+ exit 1
13
+ fi
14
+ TYPE="$(echo "$TYPE" | tr '[:lower:]' '[:upper:]')"
15
+ if [[ "$TYPE" != "PATCH" && "$TYPE" != "MINOR" && "$TYPE" != "MAJOR" ]]; then
16
+ echo "Error: TYPE must be PATCH, MINOR or MAJOR (got '$1')" >&2
17
+ exit 1
18
+ fi
19
+
20
+ if [[ -n "$(git status --porcelain)" ]]; then
21
+ echo "Error: working tree is not clean. Commit or stash changes first." >&2
22
+ exit 1
23
+ fi
24
+
25
+ CURRENT_VERSION="$(grep -m1 '^version = ' pyproject.toml | sed -E 's/version = "([^"]+)"/\1/')"
26
+ if [[ -z "$CURRENT_VERSION" ]]; then
27
+ echo "Error: could not find version in pyproject.toml" >&2
28
+ exit 1
29
+ fi
30
+
31
+ IFS='.' read -r MAJOR MINOR PATCH <<< "$CURRENT_VERSION"
32
+
33
+ case "$TYPE" in
34
+ MAJOR)
35
+ MAJOR=$((MAJOR + 1)); MINOR=0; PATCH=0
36
+ ;;
37
+ MINOR)
38
+ MINOR=$((MINOR + 1)); PATCH=0
39
+ ;;
40
+ PATCH)
41
+ PATCH=$((PATCH + 1))
42
+ ;;
43
+ esac
44
+
45
+ NEW_VERSION="${MAJOR}.${MINOR}.${PATCH}"
46
+ NEW_TAG="v${NEW_VERSION}"
47
+
48
+ echo "Bumping version: ${CURRENT_VERSION} -> ${NEW_VERSION}"
49
+
50
+ sed -i.bak -E "s/^version = \"[^\"]+\"/version = \"${NEW_VERSION}\"/" pyproject.toml
51
+ rm -f pyproject.toml.bak
52
+
53
+ git add pyproject.toml
54
+ git commit -m "Bump version to ${NEW_VERSION}"
55
+ git push origin HEAD
56
+
57
+ git tag "$NEW_TAG"
58
+ git push origin "$NEW_TAG"
59
+
60
+ echo "Pushed ${NEW_TAG}. The publish.yml workflow will build and publish to PyPI."
@@ -0,0 +1,40 @@
1
+ [build-system]
2
+ requires = ["hatchling"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "easy_obs"
7
+ version = "0.5.0"
8
+ description = "Python client for the easy-obs.com (obs_app) ingestion API - logs, metrics and traces."
9
+ readme = "README.md"
10
+ requires-python = ">=3.9"
11
+ license = { text = "MIT" }
12
+ authors = [
13
+ { name = "Conor Turner", email = "conor_turner@hotmail.com" },
14
+ ]
15
+ classifiers = [
16
+ "Programming Language :: Python :: 3",
17
+ "License :: OSI Approved :: MIT License",
18
+ "Operating System :: OS Independent",
19
+ "Intended Audience :: Developers",
20
+ "Topic :: System :: Logging",
21
+ "Topic :: System :: Monitoring",
22
+ ]
23
+ dependencies = [
24
+ "requests>=2.25",
25
+ ]
26
+
27
+ [project.urls]
28
+ Homepage = "https://github.com/cturner91/obs-app-sdk"
29
+ Repository = "https://github.com/cturner91/obs-app-sdk"
30
+
31
+ [project.optional-dependencies]
32
+ test = [
33
+ "pytest>=7.0",
34
+ ]
35
+
36
+ [tool.hatch.build.targets.wheel]
37
+ packages = ["src/easy_obs"]
38
+
39
+ [tool.pytest.ini_options]
40
+ testpaths = ["tests"]
@@ -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
+ ]