uptime-agent 0.1.0__py3-none-any.whl

uptime_agent-0.1.0.dist-info/METADATA

@@ -0,0 +1,288 @@
+Metadata-Version: 2.4
+Name: uptime-agent
+Version: 0.1.0
+Summary: Ship the errors your Python app already logs to UptimeAgent, so incidents arrive with your own error lines attached. Evidence only, never a vote on uptime. Zero dependencies.
+Project-URL: Homepage, https://uptimeagent.com
+Project-URL: Repository, https://bitbucket.org/webyes-apps/uptime-agent-python
+Project-URL: Changelog, https://bitbucket.org/webyes-apps/uptime-agent-python/src/main/CHANGELOG.md
+Project-URL: Wire protocol, https://bitbucket.org/webyes-apps/uptime-agent-python/src/main/docs/wire-protocol-v1.md
+Author: UptimeAgent
+License-Expression: MIT
+License-File: LICENSE
+Keywords: asgi,errors,incident,lambda,logging,logs,monitoring,observability,uptime,uptimeagent,wsgi
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: Topic :: System :: Logging
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# uptime-agent
+
+Ship the errors your Python app already logs to UptimeAgent, so an incident arrives
+with your own error lines attached to the outside-in probe evidence.
+
+**Status: 0.x.** Minor versions may break until 1.0.0. The wire protocol is frozen and
+executable (`docs/wire-protocol-v1.md`, `conformance/`), and this package passes every
+fixture in it.
+
+```bash
+pip install uptime-agent
+```
+
+The distribution is `uptime-agent`; the import is `uptimeagent`.
+
+```python
+import uptimeagent
+
+agent = uptimeagent.uptime_agent(
+    service="checkout-api",  # required: how the Agents screen groups instances
+    serves=["checkout.acme.com"],  # the hostnames exactly as they appear in Monitors
+)
+# token comes from UPTIMEAGENT_TOKEN
+```
+
+## The boundary: evidence, never detection
+
+A quiet package is **never** read as downtime, and a package reporting healthy is
+**never** read as uptime. A process that has stopped answering cannot vote on its own
+health, so detection belongs entirely to UptimeAgent's external probe regions. Nothing
+this package sends, or fails to send, can open, close or influence an incident.
+
+## What it never does
+
+- **Never raises into your code** after `uptime_agent()` returns. Every public method
+  and every hook is wrapped; a failure drops the event and bumps a counter you can read
+  with `agent.stats()`.
+- **Never blocks your request path.** `emit` is a redaction walk with a hard budget and
+  a buffer append. Network I/O happens on one daemon thread that holds nothing open.
+- **Never grows without bound.** The buffer is hard-capped (lines and bytes), drop-oldest,
+  with the in-flight batch still counted against the cap.
+- **Never opens a listening socket, never installs a signal handler, never patches
+  `print` or `sys.stdout`.** There is no inbound control path.
+- **Never reads an environment variable outside the documented list**: the
+  `UPTIMEAGENT_*` options, the deprecated `UA_TOKEN`, and `uptimeagent.PLATFORM_ENV_VARS`
+  (platform detection, proxies, and the three variables the standard library's TLS
+  setup reads: `SSL_CERT_FILE`, `SSL_CERT_DIR`, `SSLKEYLOGFILE`). A test wraps
+  `os.environ` and fails on any read outside that list.
+- **Zero runtime dependencies.** `pip show uptimeagent` prints an empty `Requires:` line.
+  The sdist on PyPI is the exact source that runs in your process.
+
+## What it collects
+
+Only what you point it at. Lines at or above `min_level` (default `warn`) from the
+hooks you attach, plus three synthesised kinds: an uncaught exception (`source=exception`),
+a failing HTTP request (`source=http`: method, route, status, duration), and process
+start and exit (`source=process`). Every line is redacted in-process before it is
+buffered.
+
+## Redaction
+
+Runs before anything leaves the process, with a fixed node, depth and byte budget so a
+large or cyclic object cannot slow a request. Two categories, two markers:
+
+- **Keys**: `[redacted:keys]`. A key is split into words and every contiguous run of
+  words is matched against the rules, over the whole flattened path, so `body.card.number`
+  matches `cardnumber`. Defaults: `password passwd pwd secret token apikey accesskey
+  authorization auth cookie session credential privatekey clientsecret otp cvv cardnumber ssn`.
+- **Patterns**: `[redacted:patterns]` over the message and every string value, in a
+  fixed order: bearer tokens, URL credentials, JWTs, AWS access key ids, private key
+  blocks, email addresses.
+
+Your rules extend the defaults; they never replace them.
+
+```python
+import re
+
+agent = uptimeagent.uptime_agent(
+    service="checkout-api",
+    redact={
+        "keys": ["customer_ref"],
+        "patterns": [
+            re.compile(r"\bACC-\d{8}\b"),
+            {"name": "iban", "regex": r"\b[A-Z]{2}\d{2}[A-Z0-9]{11,30}\b", "flags": ""},
+        ],
+    },
+)
+```
+
+Default patterns use ASCII `\b` and `\s` (`re.ASCII`), matching the ingest backstop.
+Your own compiled patterns are used exactly as you compiled them.
+
+## Wiring
+
+### stdlib `logging`
+
+```python
+import logging
+
+logging.getLogger().addHandler(agent.logging_handler())
+```
+
+Or `capture_logging=True` (root logger, level from `min_level`) or
+`capture_logging={"level": "WARNING", "logger": "myapp"}` at init. Levels map by name
+(`CRITICAL`/`ERROR` → `error`, `WARNING` → `warn`, everything else → `info`), `extra=`
+fields become attrs, `exc_info` becomes the traceback plus `exception.name` and
+`exception.message`, and the logger's name rides in `attrs.logger`. Records ship as
+`source="logging"`. structlog and loguru both bridge to stdlib logging; wire the handler
+there.
+
+### WSGI and ASGI
+
+```python
+# Flask
+app.wsgi_app = agent.wsgi_middleware(app.wsgi_app)
+# Django: wrap get_wsgi_application() in wsgi.py
+application = agent.wsgi_middleware(get_wsgi_application())
+# Starlette / FastAPI, or any ASGI app
+app = agent.asgi_middleware(app, route=route_template)
+```
+
+`route=` is called when the response starts, after routing. For Starlette:
+
+```python
+def route_template(scope):
+    endpoint = scope.get("endpoint")
+    for r in getattr(scope.get("router"), "routes", []):
+        if getattr(r, "endpoint", None) is endpoint:
+            return r.path  # "/orders/{order_id}"
+    return None
+```
+
+A request with status ≥ `min_status` (default 500) records a `source=http` line with
+`http.method`, `http.path`, `http.status` and `http.duration_ms`. An exception out of
+the app is recorded and re-raised. The request context is ambient (`contextvars`), so
+an error logged three calls down carries the path that produced it. Pass `route=` to
+map a request to a low-cardinality template; the default is the raw path without the
+query string.
+
+```python
+with agent.context({"reqId": rid}):
+    ...  # every line inside carries reqId
+```
+
+Threads you spawn do not inherit the context; run them with `contextvars.copy_context().run`.
+
+### AWS Lambda
+
+```python
+handler = agent.wrap_handler(handler)
+```
+
+On a detected serverless platform (Lambda, Vercel, GCP Functions, Azure Functions) no
+background thread is started. The buffer is drained at handler end, inside a budget
+derived from `context.get_remaining_time_in_millis()`, and the heartbeat rides along.
+
+## What it does to your process on a crash
+
+- **Uncaught exception on the main thread**: `sys.excepthook` is chained. The line is
+  captured, a synchronous flush runs for at most `fatal_flush_timeout_ms` (default 2 s),
+  then the previous hook runs. Python prints its own traceback and picks its own exit
+  code; nothing is reproduced or suppressed.
+- **Uncaught exception in a thread**: `threading.excepthook` is chained. Captured, no
+  flush; the process survives exactly as it would have.
+- **Exit**: an `atexit` handler records `process exiting` and flushes with the same
+  deadline. `process.exit_code` is `null` unless an uncaught exception was observed
+  (then `1`): `atexit` cannot see the status passed to `sys.exit()`.
+- **Not captured**: `os._exit`, `SIGKILL`/OOM, signals whose default action terminates
+  (add your own `SIGTERM` handler and call `agent.close()`), `KeyboardInterrupt` (passed
+  straight through, not recorded), and an app that replaces `sys.excepthook` after init.
+
+`capture_exceptions=False` and `capture_process_events=False` turn these off.
+
+## Configuration
+
+Every option has an environment variable. Explicit kwargs win over the environment.
+
+| option | env | default |
+|---|---|---|
+| `service` | `UPTIMEAGENT_SERVICE` | required |
+| `serves` / `site` | `UPTIMEAGENT_SERVES` (comma-separated) / `UPTIMEAGENT_SITE` | absent |
+| `token` | `UPTIMEAGENT_TOKEN` (`UA_TOKEN` deprecated) | none: installed and inert |
+| `environment` | `UPTIMEAGENT_ENVIRONMENT` | `production` (a display label; never affects routing) |
+| `instance` | `UPTIMEAGENT_INSTANCE` | platform id → hostname → generated |
+| `endpoint` | `UPTIMEAGENT_ENDPOINT` | `https://ingest.uptimeagent.com` |
+| `mode` | `UPTIMEAGENT_MODE`; `UPTIMEAGENT_DISABLED=1` forces `off` | `send` |
+| `min_level` | `UPTIMEAGENT_MIN_LEVEL` | `warn` |
+| `redact` | | `{}` |
+| `capture_exceptions` | `UPTIMEAGENT_CAPTURE_EXCEPTIONS` | `True` |
+| `capture_logging` | `UPTIMEAGENT_CAPTURE_LOGGING` | `False` |
+| `capture_process_events` | `UPTIMEAGENT_CAPTURE_PROCESS` | `True` |
+| `flush_interval_ms` | `UPTIMEAGENT_FLUSH_INTERVAL_MS` | 2000 |
+| `heartbeat_interval_ms` | `UPTIMEAGENT_HEARTBEAT_INTERVAL_MS` | 30000 |
+| `request_timeout_ms` | `UPTIMEAGENT_REQUEST_TIMEOUT_MS` | 10000 |
+| `fatal_flush_timeout_ms` | `UPTIMEAGENT_FATAL_FLUSH_TIMEOUT_MS` | 2000 |
+| `max_buffer_lines` / `max_buffer_bytes` | `UPTIMEAGENT_MAX_BUFFER_LINES` / `_BYTES` | 10000 / 8 MiB |
+| `max_batch_lines` / `max_batch_bytes` | `UPTIMEAGENT_MAX_BATCH_LINES` / `_BYTES` | 500 / 256 KiB |
+| `max_lines_per_second` / `max_bytes_per_second` | `UPTIMEAGENT_MAX_LINES_PER_SECOND` / `_MAX_BYTES_PER_SECOND` | 500 / 1 MiB |
+| `serverless` | `UPTIMEAGENT_SERVERLESS` | `auto` |
+| `debug` | `UPTIMEAGENT_DEBUG` | `False` |
+| `on_error(err, ctx)` | | none |
+| `on_config_error` | | `throw` (or `disable`) |
+
+`uptime_agent()` raises `ConfigError` only for malformed configuration: a missing
+`service`, an unrecognised `mode`, or a non-HTTPS endpoint (allowed only for
+`localhost`, `127.0.0.1`, `::1`). It happens at startup, before any socket opens. Pass
+`on_config_error="disable"` for a warning and an inert agent instead. A missing token
+never raises: the agent warns once and stays inert.
+
+### `mode="log"`: the development path
+
+Renders each batch to stdout as NDJSON and never opens a socket. Needs no backend at all.
+It is explicit only, never inferred from `environment`.
+
+### Endpoint and environment
+
+The endpoint is never derived from `environment`. Your staging belongs on the
+production backend, labelled `environment="staging"`. Proxies: `HTTPS_PROXY`,
+`HTTP_PROXY` and `NO_PROXY` are honoured (CONNECT tunnelling via `urllib`); macOS system
+proxy settings are not consulted. HTTP redirects are not followed.
+
+## Failure mode
+
+Everything the SDK cannot do is counted, never raised:
+
+```python
+>>> agent.stats().as_dict()
+{'service': 'checkout-api', 'instance': 'ip-10-2-3-41', ..., 'enabled': True,
+ 'disabled_reason': None, 'buffered': {'lines': 0, 'bytes': 0},
+ 'sent': {'lines': 1204, 'batches': 17},
+ 'dropped': {'buffer': 0, 'throttle': 0, 'oversize': 0, 'transport': 2, 'internal': 0, 'filtered': 184}}
+```
+
+`filtered` is lines below `min_level`. A `401`/`403` from ingest disables the transport
+for the life of the process and calls `on_error` once; after that every line counts as
+`dropped.transport`. `tests/test_never_hurt_the_app.py` is the suite that holds these
+claims up.
+
+## Verification
+
+| command | what it proves |
+|---|---|
+| `make test` | ~260 tests, including the 89 protocol conformance fixtures and subprocess crash scenarios |
+| `make test-matrix` | the same on CPython 3.9 through 3.13 |
+| `make integration` | the built wheel under real Flask, Starlette/uvicorn and gunicorn prefork, against a local ingest stub, with a byte scan for planted secrets |
+| `make verify` | lint, types, tests, package checks: what `deploy.sh` gates on |
+
+## Where it runs
+
+CPython 3.9 to 3.13. PyPy is best-effort. gunicorn and uwsgi prefork are handled with
+`os.register_at_fork`: a forked worker starts its own sender thread lazily and gets a
+`#<pid>` instance suffix. asyncio apps use the ASGI middleware; `flush()` and `close()`
+are synchronous and should not be awaited on an event loop (`await asyncio.to_thread(agent.flush)`).
+
+Differences from the Node SDK: `docs/differences-from-node.md`. Publishing:
+`docs/publishing.md`. Internal staging notes: `docs/staging.md`.
+
+MIT. Zero dependencies. Python 3.9+.

uptime_agent-0.1.0.dist-info/RECORD

@@ -0,0 +1,29 @@
+uptimeagent/__init__.py,sha256=fKnPNGQdO8707Dz30jNpGMJngiaDdcqptRGnIsQ3K78,10418
+uptimeagent/_bytes.py,sha256=UeRhIdQdXc01VsLSGYFSQFMT8ddfC6w3SlxJ4nRtErY,1626
+uptimeagent/_json.py,sha256=rzkdVVpoScaJqIHu8RZKHT7fbNGz3Rv46FgwM0Ze5mM,3286
+uptimeagent/_version.py,sha256=01VPrjjB-7V2AubGKa6GCpy776SB05kd5_fMXYvo1Ng,280
+uptimeagent/agent.py,sha256=0b3Q_V6liUrtundRZUDlH9Zyaydv-rWzyMTZ5zZRhKY,29385
+uptimeagent/backoff.py,sha256=hiA1X0eSMomEJPruudX_vVfYHvq7h4RlnB5vNY66xk8,2429
+uptimeagent/buffer.py,sha256=371CRJArTqT9c2ZDObPgaHtVMN70HRXqyvXmto76TVQ,3126
+uptimeagent/config.py,sha256=_BMe3WlsPkpobKQieMPYBo8a56M6RWlrLKtPniT4ojA,11380
+uptimeagent/instance.py,sha256=A2QEzf_gZ0df9uyQhSPMJcL9CNczeUL5onYd5LQut4U,5273
+uptimeagent/levels.py,sha256=D66g-SMZQjPWofaia9Bq0qIXxa9flBsOHnMmx-yqy_U,1136
+uptimeagent/line.py,sha256=-7Slm6GwwDkCIHb12pYNKd57qHRQiFuzyyhiqCOmPRQ,5439
+uptimeagent/protocol.py,sha256=wo9wd0n9YMD9epeeQ4lyuurZCEgo2azVw3Kbv6MaXB8,6160
+uptimeagent/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+uptimeagent/ratelimit.py,sha256=t8-Zw3oiXMlKZ9g4eCzKhOjJFXDwXFTOjKOtswBUdl4,1524
+uptimeagent/redact.py,sha256=9P4MKliuyF1cnqRHMosTgO5ok2K6n9oS1a76RJl0asw,11458
+uptimeagent/runtime.py,sha256=V0XNzi6T-ye7t7PQGXPSezcvDBNx206yKjfXYqLElVE,1684
+uptimeagent/safe.py,sha256=uIq61S0MehSZmiXuassy3hVbtPV0AvBrqzrh4HdOGhI,2294
+uptimeagent/serverless.py,sha256=QTE1G1oIkmSl-sDEqqw_GGxgn7q3dEqIS9tp9kzh7Wc,1687
+uptimeagent/transport.py,sha256=kAaKhjkxRrYPTVw9C-qGzFUWCwJd4AJfohVl06XGZoA,6763
+uptimeagent/hooks/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+uptimeagent/hooks/asgi.py,sha256=a77wnNNqCFQyac3j881ZAtwPO2NbVGjNLmjSqyp7OaQ,4547
+uptimeagent/hooks/context.py,sha256=Ae_tTXE_W_vsT9PKu2YxBZsijiAUHooFD41iw2s0kjY,1357
+uptimeagent/hooks/exceptions.py,sha256=y1czwx_363oQXYsDUby53kgC3XUTyRf1sLjL2zI7c38,5334
+uptimeagent/hooks/logging_handler.py,sha256=gdYyGWjGsxGfGYvL0q3KNSMqog3av7UtllQlrMwtp1w,3891
+uptimeagent/hooks/wsgi.py,sha256=BqXFsvRyE40tTQY9x_DR28QkNs4HUNA5FgdgCPXzRwI,5201
+uptime_agent-0.1.0.dist-info/METADATA,sha256=ExlPrKyI3z-GkkDammvoUUb_JDA28BvmZkyVDhR08uc,13221
+uptime_agent-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+uptime_agent-0.1.0.dist-info/licenses/LICENSE,sha256=PhLFceKziIxkjbxaGiqOyKmdocuP2lIaCjNShmx0dZs,1068
+uptime_agent-0.1.0.dist-info/RECORD,,

uptime_agent-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

uptime_agent-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 UptimeAgent
+
+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.

uptimeagent/__init__.py

@@ -0,0 +1,302 @@
+"""uptimeagent: the public entry point.
+
+THE BOUNDARY, first, because it is a product decision and not a detail: this package
+is EVIDENCE, never detection. A quiet package is never read as downtime, and a package
+reporting healthy is never read as uptime. Nothing this package sends, or fails to
+send, can open, close or influence an incident.
+"""
+
+from __future__ import annotations
+
+import functools
+import logging
+from collections.abc import Iterator, Mapping
+from contextlib import contextmanager
+from typing import Any, Callable, TypeVar, cast
+
+from ._version import __version__
+from .agent import Agent, AgentStats, Counter
+from .config import ConfigError, resolve_config
+from .hooks.asgi import AsgiMiddleware
+from .hooks.context import context as _context
+from .hooks.context import current_context, run_with_context
+from .hooks.exceptions import install_exception_capture, install_process_events
+from .hooks.logging_handler import UptimeAgentHandler
+from .hooks.wsgi import WsgiMiddleware
+from .instance import PLATFORM_ENV_VARS, default_hostname
+from .protocol import LEVELS, MARKERS, PROTOCOL_VERSION, SOURCES
+from .runtime import write_err
+from .safe import ErrorContext
+from .serverless import wrap_handler as _wrap_handler
+from .transport import HttpTransport, UrllibTransport
+
+__all__ = [
+    "LEVELS",
+    "MARKERS",
+    "PLATFORM_ENV_VARS",
+    "PROTOCOL_VERSION",
+    "SOURCES",
+    "AgentStats",
+    "ConfigError",
+    "ErrorContext",
+    "HttpTransport",
+    "UptimeAgent",
+    "UptimeAgentHandler",
+    "__version__",
+    "current_context",
+    "get_agent",
+    "run_with_context",
+    "uptime_agent",
+]
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def _guarded(fallback: Any = None, stage: str = "hook") -> Callable[[F], F]:
+    """Every public entry point is wrapped, so even a bug in this file cannot reach the
+    customer's stack. Only `Exception`: KeyboardInterrupt/SystemExit propagate."""
+
+    def deco(fn: F) -> F:
+        @functools.wraps(fn)
+        def wrapper(self: Any, *args: Any, **kwargs: Any) -> Any:
+            try:
+                return fn(self, *args, **kwargs)
+            except Exception as e:
+                try:
+                    self._agent.report_internal(e, stage)
+                except Exception:
+                    pass
+                return fallback
+
+        return wrapper  # type: ignore[return-value]
+
+    return deco
+
+
+class UptimeAgent:
+    """The handle `uptime_agent()` returns. Every method is safe to call at any time."""
+
+    def __init__(self, agent: Agent) -> None:
+        self._agent = agent
+
+    @property
+    def enabled(self) -> bool:
+        return self._agent.enabled
+
+    @_guarded()
+    def log(
+        self, level: str, message: Any, attrs: Mapping[str, Any] | None = None, **extra: Any
+    ) -> None:
+        self._agent.emit(level=level, source="sdk", message=message, attrs=_merge(attrs, extra))
+
+    @_guarded()
+    def info(self, message: Any, attrs: Mapping[str, Any] | None = None, **extra: Any) -> None:
+        self._agent.emit(level="info", source="sdk", message=message, attrs=_merge(attrs, extra))
+
+    @_guarded()
+    def warn(self, message: Any, attrs: Mapping[str, Any] | None = None, **extra: Any) -> None:
+        self._agent.emit(level="warn", source="sdk", message=message, attrs=_merge(attrs, extra))
+
+    @_guarded()
+    def error(self, message: Any, attrs: Mapping[str, Any] | None = None, **extra: Any) -> None:
+        self._agent.emit(level="error", source="sdk", message=message, attrs=_merge(attrs, extra))
+
+    @_guarded()
+    def capture_exception(
+        self, exc: BaseException, attrs: Mapping[str, Any] | None = None, **extra: Any
+    ) -> None:
+        merged = dict(_merge(attrs, extra) or {})
+        merged.setdefault("exception.origin", "capture_exception")
+        merged.setdefault("exception.name", type(exc).__name__)
+        try:
+            merged.setdefault("exception.message", str(exc))
+        except Exception:
+            pass
+        self._agent.emit(level="error", source="exception", message=exc, attrs=merged)
+
+    @_guarded(stage="flush")
+    def flush(self, timeout_ms: int | None = None) -> None:
+        """Drain what is buffered. Synchronous, bounded; never sits through a backoff."""
+        self._agent.flush(timeout_ms=timeout_ms)
+
+    @_guarded(stage="shutdown")
+    def close(self) -> None:
+        """Detach every hook and flush once. Safe to call more than once."""
+        self._agent.close()
+
+    def stats(self) -> AgentStats:
+        return self._agent.stats()
+
+    @_guarded(fallback=logging.NullHandler())
+    def logging_handler(self, level: int | None = None) -> logging.Handler:
+        """`logging.getLogger().addHandler(agent.logging_handler())`"""
+        return UptimeAgentHandler(self._agent, level)
+
+    def wsgi_middleware(
+        self, app: Any, min_status: int = 500, route: Callable[[Any], str | None] | None = None
+    ) -> Any:
+        try:
+            return WsgiMiddleware(app, self._agent, min_status=min_status, route=route)
+        except Exception as e:
+            self._agent.report_internal(e, "hook")
+            return app
+
+    def asgi_middleware(
+        self, app: Any, min_status: int = 500, route: Callable[[Any], str | None] | None = None
+    ) -> Any:
+        try:
+            return AsgiMiddleware(app, self._agent, min_status=min_status, route=route)
+        except Exception as e:
+            self._agent.report_internal(e, "hook")
+            return app
+
+    def run_with_context(
+        self, attrs: Mapping[str, Any], fn: Callable[..., Any], *args: Any, **kwargs: Any
+    ) -> Any:
+        return run_with_context(attrs, fn, *args, **kwargs)
+
+    @contextmanager
+    def context(self, attrs: Mapping[str, Any]) -> Iterator[None]:
+        """`with agent.context({"reqId": rid}): ...` attaches attrs to every line inside."""
+        with _context(attrs):
+            yield
+
+    def wrap_handler(self, handler: F) -> F:
+        """AWS Lambda: `handler = agent.wrap_handler(handler)`."""
+        try:
+            return cast(F, _wrap_handler(self._agent, handler))
+        except Exception as e:
+            self._agent.report_internal(e, "hook")
+            return handler
+
+
+class _InertAgent(UptimeAgent):
+    """What a disabled agent looks like: every hook present, every hook inert."""
+
+    def __init__(self) -> None:
+        self._agent = None  # type: ignore[assignment]
+
+    @property
+    def enabled(self) -> bool:
+        return False
+
+    def log(self, *a: Any, **k: Any) -> None:
+        return None
+
+    info = warn = error = capture_exception = log
+
+    def flush(self, timeout_ms: int | None = None) -> None:
+        return None
+
+    def close(self) -> None:
+        return None
+
+    def stats(self) -> AgentStats:
+        return AgentStats(
+            service="",
+            instance="",
+            environment="",
+            serves=None,
+            runtime="",
+            platform="unknown",
+            serverless=False,
+            mode="off",
+            enabled=False,
+            disabled_reason="invalid configuration",
+            buffered=Counter(lines=0, bytes=0),
+            sent=Counter(lines=0, batches=0),
+            dropped=Counter(buffer=0, throttle=0, oversize=0, transport=0, internal=0, filtered=0),
+        )
+
+    def logging_handler(self, level: int | None = None) -> logging.Handler:
+        return logging.NullHandler()
+
+    def wsgi_middleware(self, app: Any, min_status: int = 500, route: Any = None) -> Any:
+        return app
+
+    def asgi_middleware(self, app: Any, min_status: int = 500, route: Any = None) -> Any:
+        return app
+
+    def wrap_handler(self, handler: F) -> F:
+        return handler
+
+
+def _merge(attrs: Mapping[str, Any] | None, extra: Mapping[str, Any]) -> Mapping[str, Any] | None:
+    if not extra:
+        return attrs
+    merged = dict(attrs) if isinstance(attrs, Mapping) else {}
+    merged.update(extra)
+    return merged
+
+
+_current: UptimeAgent | None = None
+
+
+def get_agent() -> UptimeAgent | None:
+    """The agent created by the most recent `uptime_agent()` call, if any."""
+    return _current
+
+
+def uptime_agent(
+    *,
+    transport: HttpTransport | None = None,
+    on_config_error: str = "throw",
+    **options: Any,
+) -> UptimeAgent:
+    """Start the agent.
+
+    This is the only function in the package that can raise, and only on MALFORMED
+    configuration (`ConfigError`): a non-HTTPS endpoint, a missing `service`, an
+    unrecognised `mode`. Pass `on_config_error="disable"` for a warning and an inert
+    agent instead.
+    """
+    global _current
+    try:
+        if "hostname" not in options:
+            options["hostname"] = default_hostname
+        config = resolve_config(**options)
+        for w in config.warnings:
+            write_err(f"[uptimeagent] {w}\n")
+        agent = Agent(config, transport if transport is not None else UrllibTransport(config.env))
+        agent.set_context_provider(current_context)
+        if config.capture_exceptions:
+            install_exception_capture(agent)
+        if config.capture_process_events:
+            install_process_events(agent)
+        if config.capture_logging:
+            _install_logging(agent, config.capture_logging)
+        agent.start_heartbeat()
+        if config.debug:
+            s = agent.stats()
+            write_err(
+                f"[uptimeagent] {s.service} · {s.instance} · {s.environment} · {s.runtime}"
+                f" · mode={s.mode}{' · serverless' if s.serverless else ''}\n"
+            )
+    except ConfigError as e:
+        if on_config_error == "disable":
+            write_err(f"[uptimeagent] disabled — {e}\n")
+            _current = _InertAgent()
+            return _current
+        raise
+    _current = UptimeAgent(agent)
+    return _current
+
+
+def _install_logging(agent: Agent, spec: Any) -> None:
+    level: int | None = None
+    logger_name = ""
+    if isinstance(spec, Mapping):
+        lv = spec.get("level")
+        if isinstance(lv, str):
+            level = (
+                logging.getLevelName(lv.upper())
+                if isinstance(logging.getLevelName(lv.upper()), int)
+                else None
+            )
+        elif isinstance(lv, int):
+            level = lv
+        logger_name = str(spec.get("logger") or "")
+    handler = UptimeAgentHandler(agent, level)
+    target = logging.getLogger(logger_name)
+    target.addHandler(handler)
+    agent.register_teardown(lambda: target.removeHandler(handler))