ct-obs-app 0.1.0__tar.gz

ct_obs_app-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,37 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+      - run: pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for PyPI trusted publishing (OIDC) - no token/secret needed
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

ct_obs_app-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+htmlcov/
+.coverage
+build/
+dist/

ct_obs_app-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Conor Turner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ct_obs_app-0.1.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.5
+Name: ct_obs_app
+Version: 0.1.0
+Summary: Python client for the obs-app.ctsoftware.co.uk (obs_app) ingestion API - logs, metrics and traces.
+Project-URL: Homepage, https://github.com/cturner91/obs-app-sdk
+Project-URL: Repository, https://github.com/cturner91/obs-app-sdk
+Author-email: Conor Turner <conor_turner@hotmail.com>
+License: MIT
+License-File: LICENSE
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Logging
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.9
+Requires-Dist: requests>=2.25
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# obs-app-sdk
+
+Python client for the [obs-app.ctsoftware.co.uk](https://obs-app.ctsoftware.co.uk) ingestion API - send logs,
+metrics and traces from your application.
+
+## Install
+
+```bash
+pip install ct_obs_app
+```
+
+(the PyPI project is named `ct_obs_app`; the importable module is `obs_app_sdk` - see Quickstart below)
+
+## Get an API key
+
+Log in at the obs_app dashboard and copy your API key from the profile page (rotate it there
+too, if needed). The SDK authenticates every request with it.
+
+## Quickstart
+
+```python
+from obs_app_sdk import Client, CaptureTrace
+
+client = Client(api_key="your-api-key")
+
+# Logging
+client.log("Something happened", level=4)  # 1=Critical .. 5=Debug, default 4=Info
+client.log_batch([{"message": "a"}, {"message": "b"}])
+
+# Metrics
+client.add_metric(value=1.0, metric="request_duration_ms", auto_create=True)
+client.add_metrics([
+    {"metric": "request_duration_ms", "value": 12.3},
+    {"metric": "queue_depth", "value": 4},
+], auto_create=True)
+
+# Traces - nested context managers build one tree, sent as a single request when the
+# outermost one exits
+with CaptureTrace(client, "handle_request"):
+    with CaptureTrace(client, "query_db"):
+        ...
+    with CaptureTrace(client, "render_response"):
+        ...
+
+# Or submit logs/metrics/traces together in one request (validated all-or-nothing)
+client.ingest(
+    logs={"logs": [{"message": "started"}]},
+    metrics={"metrics": [{"metric": "request_duration_ms", "value": 12.3}]},
+    traces=[{"start": "...", "end": "...", "text": "handled"}],
+)
+```
+
+## Stdlib logging integration
+
+```python
+import logging
+from obs_app_sdk import Client, ObsAppLogHandler
+
+client = Client(api_key="your-api-key")
+logging.getLogger().addHandler(ObsAppLogHandler(client))
+```
+
+Each stdlib log record becomes one `POST /api/log/` call. For high-volume logging, call
+`client.log_batch(...)` directly instead of relying on the handler.
+
+## Error handling
+
+All methods raise on non-2xx responses:
+
+- `ObsAppApiKeyError` - missing/invalid API key (HTTP 401)
+- `ObsAppValidationError` - invalid request data (HTTP 400); `.errors` holds the server's
+  per-field error dict when there is one, else `None`
+- `ObsAppRateLimitedError` - HTTP 429. The API blocks the offending IP for **1 hour** once its
+  rolling rate-limit window trips - do not retry in a loop on this error, it won't help
+- `ObsAppError` - base class; also raised for network failures and unexpected status codes
+
+## Notes
+
+- This client is synchronous and makes one HTTP request per call - there is no background
+  buffering/auto-flush thread. Use the batch methods (`log_batch`, `add_metrics`, `ingest`)
+  to reduce request count for high-volume callers.
+- `add_metrics` (batch) only supports metric names, not `metric_id` - use `add_metric`
+  (singular) for id-based lookups.

ct_obs_app-0.1.0/README.md

@@ -0,0 +1,83 @@
+# obs-app-sdk
+
+Python client for the [obs-app.ctsoftware.co.uk](https://obs-app.ctsoftware.co.uk) ingestion API - send logs,
+metrics and traces from your application.
+
+## Install
+
+```bash
+pip install ct_obs_app
+```
+
+(the PyPI project is named `ct_obs_app`; the importable module is `obs_app_sdk` - see Quickstart below)
+
+## Get an API key
+
+Log in at the obs_app dashboard and copy your API key from the profile page (rotate it there
+too, if needed). The SDK authenticates every request with it.
+
+## Quickstart
+
+```python
+from obs_app_sdk import Client, CaptureTrace
+
+client = Client(api_key="your-api-key")
+
+# Logging
+client.log("Something happened", level=4)  # 1=Critical .. 5=Debug, default 4=Info
+client.log_batch([{"message": "a"}, {"message": "b"}])
+
+# Metrics
+client.add_metric(value=1.0, metric="request_duration_ms", auto_create=True)
+client.add_metrics([
+    {"metric": "request_duration_ms", "value": 12.3},
+    {"metric": "queue_depth", "value": 4},
+], auto_create=True)
+
+# Traces - nested context managers build one tree, sent as a single request when the
+# outermost one exits
+with CaptureTrace(client, "handle_request"):
+    with CaptureTrace(client, "query_db"):
+        ...
+    with CaptureTrace(client, "render_response"):
+        ...
+
+# Or submit logs/metrics/traces together in one request (validated all-or-nothing)
+client.ingest(
+    logs={"logs": [{"message": "started"}]},
+    metrics={"metrics": [{"metric": "request_duration_ms", "value": 12.3}]},
+    traces=[{"start": "...", "end": "...", "text": "handled"}],
+)
+```
+
+## Stdlib logging integration
+
+```python
+import logging
+from obs_app_sdk import Client, ObsAppLogHandler
+
+client = Client(api_key="your-api-key")
+logging.getLogger().addHandler(ObsAppLogHandler(client))
+```
+
+Each stdlib log record becomes one `POST /api/log/` call. For high-volume logging, call
+`client.log_batch(...)` directly instead of relying on the handler.
+
+## Error handling
+
+All methods raise on non-2xx responses:
+
+- `ObsAppApiKeyError` - missing/invalid API key (HTTP 401)
+- `ObsAppValidationError` - invalid request data (HTTP 400); `.errors` holds the server's
+  per-field error dict when there is one, else `None`
+- `ObsAppRateLimitedError` - HTTP 429. The API blocks the offending IP for **1 hour** once its
+  rolling rate-limit window trips - do not retry in a loop on this error, it won't help
+- `ObsAppError` - base class; also raised for network failures and unexpected status codes
+
+## Notes
+
+- This client is synchronous and makes one HTTP request per call - there is no background
+  buffering/auto-flush thread. Use the batch methods (`log_batch`, `add_metrics`, `ingest`)
+  to reduce request count for high-volume callers.
+- `add_metrics` (batch) only supports metric names, not `metric_id` - use `add_metric`
+  (singular) for id-based lookups.

ct_obs_app-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ct_obs_app"
+version = "0.1.0"
+description = "Python client for the obs-app.ctsoftware.co.uk (obs_app) ingestion API - logs, metrics and traces."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [
+    { name = "Conor Turner", email = "conor_turner@hotmail.com" },
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Developers",
+    "Topic :: System :: Logging",
+    "Topic :: System :: Monitoring",
+]
+dependencies = [
+    "requests>=2.25",
+]
+
+[project.urls]
+Homepage = "https://github.com/cturner91/obs-app-sdk"
+Repository = "https://github.com/cturner91/obs-app-sdk"
+
+[project.optional-dependencies]
+test = [
+    "pytest>=7.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/obs_app_sdk"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

ct_obs_app-0.1.0/src/obs_app_sdk/__init__.py

@@ -0,0 +1,16 @@
+from obs_app_sdk.client import Client
+from obs_app_sdk.exceptions import ObsAppApiKeyError, ObsAppError, ObsAppRateLimitedError, ObsAppValidationError
+from obs_app_sdk.logging_handler import ObsAppLogHandler
+from obs_app_sdk.tracing import CaptureTrace
+
+__version__ = '0.1.0'
+
+__all__ = [
+    'Client',
+    'CaptureTrace',
+    'ObsAppLogHandler',
+    'ObsAppError',
+    'ObsAppApiKeyError',
+    'ObsAppValidationError',
+    'ObsAppRateLimitedError',
+]

ct_obs_app-0.1.0/src/obs_app_sdk/client.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+import requests
+
+from obs_app_sdk.exceptions import ObsAppApiKeyError, ObsAppError, ObsAppRateLimitedError, ObsAppValidationError
+
+
+class Client:
+    '''Thin synchronous wrapper around the obs-app.ctsoftware.co.uk ingestion API. Every method makes
+    one HTTP call - there's no background buffering/auto-flush, so batch calls (log_batch,
+    add_metrics, ingest) are the way to reduce request count for high-volume callers.'''
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = 'https://obs-app.ctsoftware.co.uk',
+        timeout: float = 5.0,
+        session: requests.Session | None = None,
+    ) -> None:
+        self.api_key = api_key
+        self.base_url = base_url.rstrip('/')
+        self.timeout = timeout
+        self.session = session or requests.Session()
+
+    def _post(self, path: str, payload: dict) -> dict:
+        try:
+            response = self.session.post(
+                f'{self.base_url}{path}',
+                json=payload,
+                headers={'Authorization': f'Bearer {self.api_key}'},
+                timeout=self.timeout,
+            )
+        except requests.RequestException as exc:
+            raise ObsAppError(f'Request to {path} failed: {exc}') from exc
+
+        if response.status_code == 429:
+            # the server blocks the offending IP for 1 hour once the rolling rate-limit window
+            # trips - the block response isn't guaranteed to be JSON (some paths render an HTML
+            # template instead), so parse defensively. Retrying immediately will not help.
+            try:
+                message = response.json().get('error', 'Rate limited')
+            except ValueError:
+                message = 'Rate limited - IP is blocked for up to 1 hour, do not retry immediately'
+            raise ObsAppRateLimitedError(message)
+
+        try:
+            body = response.json()
+        except ValueError:
+            body = {}
+
+        if response.status_code == 401:
+            raise ObsAppApiKeyError(body.get('error', 'Invalid or missing API key'))
+
+        if response.status_code == 400:
+            raise ObsAppValidationError(body.get('error', 'Invalid data'), errors=body.get('errors'))
+
+        if not response.ok:
+            raise ObsAppError(f'{path} returned HTTP {response.status_code}: {body}')
+
+        return body
+
+    @staticmethod
+    def _iso(value: datetime | str | None) -> str | None:
+        if value is None or isinstance(value, str):
+            return value
+        return value.isoformat()
+
+    def log(self, message: str, level: int = 4, request_id: str | None = None) -> str:
+        '''POST /api/log/ - level: 1=Critical, 2=Error, 3=Warning, 4=Info (default), 5=Debug.
+        Returns the server-assigned log id.'''
+        payload: dict[str, Any] = {'message': message, 'level': level}
+        if request_id is not None:
+            payload['request_id'] = request_id
+        return self._post('/api/log/', payload)['id']
+
+    def log_batch(self, logs: list[dict], request_id: str | None = None) -> None:
+        '''POST /api/logs/ - each entry in logs is {'message': str, 'level'?: int, 'request_id'?: str}.
+        request_id (if given) applies to any entry that doesn't specify its own.'''
+        payload: dict[str, Any] = {'logs': logs}
+        if request_id is not None:
+            payload['request_id'] = request_id
+        self._post('/api/logs/', payload)
+
+    def add_metric(
+        self,
+        value: float,
+        metric: str | None = None,
+        metric_id: str | None = None,
+        timestamp: datetime | str | None = None,
+        auto_create: bool = False,
+    ) -> None:
+        '''POST /api/metric/ - provide exactly one of metric (name) or metric_id.'''
+        if not metric and not metric_id:
+            raise ValueError('Either metric or metric_id is required')
+        if metric and metric_id:
+            raise ValueError('Provide only one of metric or metric_id')
+
+        payload: dict[str, Any] = {'value': value, 'auto_create': auto_create}
+        if metric:
+            payload['metric'] = metric
+        if metric_id:
+            payload['metric_id'] = metric_id
+        iso_timestamp = self._iso(timestamp)
+        if iso_timestamp is not None:
+            payload['timestamp'] = iso_timestamp
+
+        self._post('/api/metric/', payload)
+
+    def add_metrics(self, metrics: list[dict], auto_create: bool = False) -> None:
+        '''POST /api/metrics/ - each entry is {'metric': str, 'value': float, 'timestamp'?: ...}.
+        Note: unlike add_metric, the server does not support metric_id-based lookup in a batch -
+        every entry must use 'metric' (name).'''
+        normalized = []
+        for entry in metrics:
+            entry = dict(entry)
+            if 'timestamp' in entry:
+                entry['timestamp'] = self._iso(entry['timestamp'])
+            normalized.append(entry)
+
+        payload = {'metrics': normalized, 'auto_create': auto_create}
+        self._post('/api/metrics/', payload)
+
+    def send_trace(self, trace: dict) -> None:
+        '''POST /api/trace/ - trace is a single tree: {'start': ..., 'end': ..., 'text'?: str,
+        'traces'?: [nested trace trees]}. Prefer CaptureTrace over calling this directly.'''
+        self._post('/api/trace/', trace)
+
+    def ingest(
+        self,
+        traces: list[dict] | None = None,
+        logs: dict | None = None,
+        metrics: dict | None = None,
+    ) -> None:
+        '''POST /api/ingest/ - submit traces/logs/metrics in a single request, validated
+        all-or-nothing by the server (if any section is invalid, nothing is processed).
+        traces is a *list* of trace trees (unlike send_trace, which takes one).
+        logs is {'logs': [...], 'request_id'?: str} (same shape as log_batch's payload).
+        metrics is {'metrics': [...], 'auto_create'?: bool} (same shape as add_metrics' payload).'''
+        if traces is None and logs is None and metrics is None:
+            raise ValueError('At least one of traces, logs, or metrics is required')
+
+        payload: dict[str, Any] = {}
+        if traces is not None:
+            payload['traces'] = traces
+        if logs is not None:
+            payload['logs'] = logs
+        if metrics is not None:
+            payload['metrics'] = metrics
+
+        self._post('/api/ingest/', payload)

ct_obs_app-0.1.0/src/obs_app_sdk/exceptions.py

@@ -0,0 +1,26 @@
+class ObsAppError(Exception):
+    '''Base class for all errors raised by this SDK.'''
+
+    def __init__(self, message: str) -> None:
+        self.message = message
+        super().__init__(message)
+
+
+class ObsAppApiKeyError(ObsAppError):
+    '''Raised on a 401 response - the API key is missing or invalid.'''
+
+
+class ObsAppValidationError(ObsAppError):
+    '''Raised on a 400 response. `errors` holds the per-field error dict when the server
+    returned one (schema validation failures); it's None for single-message 400s (e.g.
+    'Invalid metrics: ...').'''
+
+    def __init__(self, message: str, errors: dict | None = None) -> None:
+        self.errors = errors
+        super().__init__(message)
+
+
+class ObsAppRateLimitedError(ObsAppError):
+    '''Raised on a 429 response. The server enforces a rolling-window rate limit and blocks
+    the offending IP for 1 hour once tripped - do not retry immediately, it will not help and
+    only keeps the block window extending.'''

ct_obs_app-0.1.0/src/obs_app_sdk/logging_handler.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from obs_app_sdk.client import Client
+
+# obs_app's own level scale (projects/obs_app/models.py): 1=Critical, 2=Error, 3=Warning,
+# 4=Info, 5=Debug - the reverse of Python's, where higher stdlib levelno means more severe.
+_STDLIB_TO_OBS_APP_LEVEL = {
+    logging.CRITICAL: 1,
+    logging.ERROR: 2,
+    logging.WARNING: 3,
+    logging.INFO: 4,
+    logging.DEBUG: 5,
+}
+
+
+def _map_level(levelno: int) -> int:
+    for stdlib_level in sorted(_STDLIB_TO_OBS_APP_LEVEL, reverse=True):
+        if levelno >= stdlib_level:
+            return _STDLIB_TO_OBS_APP_LEVEL[stdlib_level]
+    return 5  # anything below DEBUG maps to Debug
+
+
+class ObsAppLogHandler(logging.Handler):
+    '''logging.Handler that forwards records to obs-app.ctsoftware.co.uk via Client.log(). Attach it to
+    any stdlib logger to pipe that logger's output to the obs_app dashboard:
+
+    handler = ObsAppLogHandler(client)
+    logging.getLogger().addHandler(handler)
+
+    Each record is sent as its own HTTP request - for high-volume logging, log directly via
+    Client.log_batch() instead rather than relying on this handler.
+    '''
+
+    def __init__(self, client: 'Client') -> None:
+        super().__init__()
+        self.client = client
+
+    def emit(self, record: logging.LogRecord) -> None:
+        try:
+            self.client.log(message=self.format(record), level=_map_level(record.levelno))
+        except Exception:
+            self.handleError(record)

ct_obs_app-0.1.0/src/obs_app_sdk/tracing.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+import contextvars
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from obs_app_sdk.client import Client
+
+# thread/async-safe nesting - matches the server-side semantics of the internal
+# obs_app.utils.CaptureTrace: only the root span, on exit, flushes the whole assembled tree.
+_current: contextvars.ContextVar['CaptureTrace | None'] = contextvars.ContextVar('_current', default=None)
+
+
+class CaptureTrace:
+    '''HTTP-backed equivalent of obs_app's internal CaptureTrace context manager. Nested
+    instances accumulate into a single tree; only the outermost (root) instance sends the
+    whole tree to the server, on exit, via client.send_trace().
+
+    with CaptureTrace(client, "outer"):
+        with CaptureTrace(client, "inner step"):
+            do_work()
+    '''
+
+    def __init__(self, client: 'Client', text: str = '') -> None:
+        self.client = client
+        self.text = text
+        self.children: list['CaptureTrace'] = []
+        self.parent: 'CaptureTrace | None' = None
+        self.start: str | None = None
+        self.end: str | None = None
+        self._token: contextvars.Token | None = None
+
+    def __enter__(self) -> 'CaptureTrace':
+        self.start = datetime.now(timezone.utc).isoformat()
+
+        parent = _current.get()
+        if parent is not None:
+            self.parent = parent
+            parent.children.append(self)
+
+        self._token = _current.set(self)
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.end = datetime.now(timezone.utc).isoformat()
+        if self._token is not None:
+            _current.reset(self._token)
+
+        if self.parent is None:
+            self.client.send_trace(self.to_dict())
+
+    def to_dict(self) -> dict:
+        data = {'start': self.start, 'end': self.end}
+        if self.text:
+            data['text'] = self.text
+
+        if self.children:
+            data['traces'] = [child.to_dict() for child in self.children]
+
+        return data

ct_obs_app-0.1.0/tests/conftest.py

@@ -0,0 +1,29 @@
+from unittest.mock import MagicMock
+
+import pytest
+
+from obs_app_sdk.client import Client
+
+
+class FakeResponse:
+    '''Minimal stand-in for requests.Response, enough to drive Client._post's branching.'''
+
+    def __init__(self, status_code: int, json_body: dict | None = None) -> None:
+        self.status_code = status_code
+        self._json_body = json_body
+        self.ok = 200 <= status_code < 300
+
+    def json(self) -> dict:
+        if self._json_body is None:
+            raise ValueError('response has no JSON body')
+        return self._json_body
+
+
+@pytest.fixture
+def mock_session() -> MagicMock:
+    return MagicMock()
+
+
+@pytest.fixture
+def client(mock_session: MagicMock) -> Client:
+    return Client(api_key='test-api-key', base_url='https://obs-app.ctsoftware.co.uk', session=mock_session)

ct_obs_app-0.1.0/tests/test_client.py

@@ -0,0 +1,163 @@
+from datetime import datetime, timezone
+
+import pytest
+import requests
+
+from obs_app_sdk.exceptions import ObsAppApiKeyError, ObsAppError, ObsAppRateLimitedError, ObsAppValidationError
+
+from .conftest import FakeResponse
+
+
+def test__log__success(client, mock_session):
+    mock_session.post.return_value = FakeResponse(201, {'message': 'OK', 'id': 'abc-123'})
+
+    log_id = client.log('Bad seafood', level=2, request_id='req-1')
+
+    assert log_id == 'abc-123'
+    call = mock_session.post.call_args
+    assert call.args == ('https://obs-app.ctsoftware.co.uk/api/log/',)
+    assert call.kwargs['json'] == {'message': 'Bad seafood', 'level': 2, 'request_id': 'req-1'}
+    assert call.kwargs['headers'] == {'Authorization': 'Bearer test-api-key'}
+
+
+def test__log_batch__success(client, mock_session):
+    mock_session.post.return_value = FakeResponse(201, {'message': 'OK'})
+
+    client.log_batch([{'message': 'a'}, {'message': 'b'}], request_id='req-1')
+
+    call = mock_session.post.call_args
+    assert call.args == ('https://obs-app.ctsoftware.co.uk/api/logs/',)
+    assert call.kwargs['json'] == {'logs': [{'message': 'a'}, {'message': 'b'}], 'request_id': 'req-1'}
+
+
+def test__add_metric__requires_metric_or_metric_id(client):
+    with pytest.raises(ValueError):
+        client.add_metric(value=1.0)
+
+
+def test__add_metric__rejects_both_metric_and_metric_id(client):
+    with pytest.raises(ValueError):
+        client.add_metric(value=1.0, metric='TIME', metric_id='some-id')
+
+
+def test__add_metric__success_converts_datetime_timestamp(client, mock_session):
+    mock_session.post.return_value = FakeResponse(200, {'message': 'OK'})
+    ts = datetime(2025, 4, 30, 12, 1, 2, tzinfo=timezone.utc)
+
+    client.add_metric(value=1.0, metric='TIME', timestamp=ts, auto_create=True)
+
+    call = mock_session.post.call_args
+    assert call.args == ('https://obs-app.ctsoftware.co.uk/api/metric/',)
+    assert call.kwargs['json'] == {
+        'value': 1.0, 'auto_create': True, 'metric': 'TIME', 'timestamp': ts.isoformat(),
+    }
+
+
+def test__add_metrics__normalizes_per_entry_timestamps(client, mock_session):
+    mock_session.post.return_value = FakeResponse(200, {'message': 'OK'})
+    ts = datetime(2025, 4, 30, 12, 1, 2, tzinfo=timezone.utc)
+
+    client.add_metrics([
+        {'metric': 'TIME', 'value': 1.0, 'timestamp': ts},
+        {'metric': 'TIME2', 'value': 2.0},
+    ], auto_create=True)
+
+    call = mock_session.post.call_args
+    assert call.args == ('https://obs-app.ctsoftware.co.uk/api/metrics/',)
+    assert call.kwargs['json'] == {
+        'metrics': [
+            {'metric': 'TIME', 'value': 1.0, 'timestamp': ts.isoformat()},
+            {'metric': 'TIME2', 'value': 2.0},
+        ],
+        'auto_create': True,
+    }
+
+
+def test__send_trace__success(client, mock_session):
+    mock_session.post.return_value = FakeResponse(201, {'message': 'OK'})
+    trace = {'start': 'a', 'end': 'b'}
+
+    client.send_trace(trace)
+
+    call = mock_session.post.call_args
+    assert call.args == ('https://obs-app.ctsoftware.co.uk/api/trace/',)
+    assert call.kwargs['json'] == trace
+
+
+def test__ingest__requires_at_least_one_section(client):
+    with pytest.raises(ValueError):
+        client.ingest()
+
+
+def test__ingest__success_with_all_sections(client, mock_session):
+    mock_session.post.return_value = FakeResponse(201, {'message': 'OK'})
+
+    client.ingest(
+        traces=[{'start': 'a', 'end': 'b'}],
+        logs={'logs': [{'message': 'hi'}]},
+        metrics={'metrics': [{'metric': 'TIME', 'value': 1.0}], 'auto_create': True},
+    )
+
+    call = mock_session.post.call_args
+    assert call.args == ('https://obs-app.ctsoftware.co.uk/api/ingest/',)
+    assert call.kwargs['json'] == {
+        'traces': [{'start': 'a', 'end': 'b'}],
+        'logs': {'logs': [{'message': 'hi'}]},
+        'metrics': {'metrics': [{'metric': 'TIME', 'value': 1.0}], 'auto_create': True},
+    }
+
+
+def test__error__401_raises_api_key_error(client, mock_session):
+    mock_session.post.return_value = FakeResponse(401, {'error': 'Invalid API key'})
+
+    with pytest.raises(ObsAppApiKeyError) as exc_info:
+        client.log('hi')
+    assert exc_info.value.message == 'Invalid API key'
+
+
+def test__error__400_with_errors_dict_raises_validation_error(client, mock_session):
+    mock_session.post.return_value = FakeResponse(400, {'error': 'Invalid data', 'errors': {'message': 'Value cannot be null'}})
+
+    with pytest.raises(ObsAppValidationError) as exc_info:
+        client.log('hi')
+    assert exc_info.value.message == 'Invalid data'
+    assert exc_info.value.errors == {'message': 'Value cannot be null'}
+
+
+def test__error__400_without_errors_dict(client, mock_session):
+    mock_session.post.return_value = FakeResponse(400, {'error': 'Invalid metrics: TIME'})
+
+    with pytest.raises(ObsAppValidationError) as exc_info:
+        client.add_metrics([{'metric': 'TIME', 'value': 1.0}])
+    assert exc_info.value.message == 'Invalid metrics: TIME'
+    assert exc_info.value.errors is None
+
+
+def test__error__429_with_json_body(client, mock_session):
+    mock_session.post.return_value = FakeResponse(429, {'error': 'Blocked'})
+
+    with pytest.raises(ObsAppRateLimitedError) as exc_info:
+        client.log('hi')
+    assert exc_info.value.message == 'Blocked'
+
+
+def test__error__429_with_non_json_body(client, mock_session):
+    # the block response isn't guaranteed to be JSON - some paths render an HTML template
+    mock_session.post.return_value = FakeResponse(429, json_body=None)
+
+    with pytest.raises(ObsAppRateLimitedError):
+        client.log('hi')
+
+
+def test__error__network_failure_raises_obs_app_error(client, mock_session):
+    mock_session.post.side_effect = requests.ConnectionError('boom')
+
+    with pytest.raises(ObsAppError):
+        client.log('hi')
+
+
+def test__error__unexpected_status_raises_obs_app_error(client, mock_session):
+    mock_session.post.return_value = FakeResponse(500, {'error': 'Server error'})
+
+    with pytest.raises(ObsAppError):
+        client.log('hi')

ct_obs_app-0.1.0/tests/test_logging_handler.py

@@ -0,0 +1,58 @@
+import logging
+from unittest.mock import MagicMock
+
+from obs_app_sdk.logging_handler import ObsAppLogHandler
+
+
+def _record(level: int, message: str) -> logging.LogRecord:
+    return logging.LogRecord(
+        name='test', level=level, pathname=__file__, lineno=1,
+        msg=message, args=(), exc_info=None,
+    )
+
+
+def test__emit_maps_levels_and_calls_client_log():
+    client = MagicMock()
+    handler = ObsAppLogHandler(client)
+
+    handler.emit(_record(logging.ERROR, 'boom'))
+
+    client.log.assert_called_once_with(message='boom', level=2)
+
+
+def test__level_mapping_table():
+    client = MagicMock()
+    handler = ObsAppLogHandler(client)
+
+    expected = {
+        logging.CRITICAL: 1,
+        logging.ERROR: 2,
+        logging.WARNING: 3,
+        logging.INFO: 4,
+        logging.DEBUG: 5,
+    }
+    for stdlib_level, obs_level in expected.items():
+        client.reset_mock()
+        handler.emit(_record(stdlib_level, 'msg'))
+        assert client.log.call_args.kwargs['level'] == obs_level
+
+
+def test__custom_level_between_standard_levels_maps_to_lower_severity():
+    # 25 sits between INFO (20) and WARNING (30) - hasn't reached WARNING, so maps to INFO's level
+    client = MagicMock()
+    handler = ObsAppLogHandler(client)
+
+    handler.emit(_record(25, 'msg'))
+
+    assert client.log.call_args.kwargs['level'] == 4
+
+
+def test__emit_swallows_client_errors_via_handle_error():
+    client = MagicMock()
+    client.log.side_effect = Exception('network down')
+    handler = ObsAppLogHandler(client)
+    handler.handleError = MagicMock()
+
+    handler.emit(_record(logging.INFO, 'msg'))
+
+    handler.handleError.assert_called_once()

ct_obs_app-0.1.0/tests/test_tracing.py

@@ -0,0 +1,62 @@
+from unittest.mock import MagicMock
+
+from obs_app_sdk.tracing import CaptureTrace
+
+
+def test__single_trace_sends_on_exit():
+    client = MagicMock()
+    with CaptureTrace(client, 'root'):
+        pass
+
+    client.send_trace.assert_called_once()
+    sent = client.send_trace.call_args.args[0]
+    assert sent['text'] == 'root'
+    assert 'start' in sent and 'end' in sent
+    assert 'traces' not in sent
+
+
+def test__nested_traces_send_once_as_one_tree():
+    client = MagicMock()
+    with CaptureTrace(client, 'outer'):
+        with CaptureTrace(client, 'inner-a'):
+            pass
+        with CaptureTrace(client, 'inner-b'):
+            pass
+
+    client.send_trace.assert_called_once()
+    sent = client.send_trace.call_args.args[0]
+    assert sent['text'] == 'outer'
+    assert [t['text'] for t in sent['traces']] == ['inner-a', 'inner-b']
+
+
+def test__deeply_nested_traces():
+    client = MagicMock()
+    with CaptureTrace(client, 'l1'):
+        with CaptureTrace(client, 'l2'):
+            with CaptureTrace(client, 'l3'):
+                pass
+
+    client.send_trace.assert_called_once()
+    sent = client.send_trace.call_args.args[0]
+    assert sent['text'] == 'l1'
+    assert sent['traces'][0]['text'] == 'l2'
+    assert sent['traces'][0]['traces'][0]['text'] == 'l3'
+
+
+def test__text_omitted_when_empty():
+    client = MagicMock()
+    with CaptureTrace(client):
+        pass
+
+    sent = client.send_trace.call_args.args[0]
+    assert 'text' not in sent
+
+
+def test__sibling_root_traces_send_independently():
+    client = MagicMock()
+    with CaptureTrace(client, 'first'):
+        pass
+    with CaptureTrace(client, 'second'):
+        pass
+
+    assert client.send_trace.call_count == 2