cayu.providers.diagnostics

Public Cayu API. Definitions are grouped by their public source module, and definitions from private implementation modules appear on their package’s page; adding a symbol does not move existing links. The import shown at each entry is a supported public namespace. Read the Python API overview and install the required extra.

capture_provider_errors

from cayu.providers import capture_provider_errors

Opt into private HTTP/SSE error details for operations in this scope.

No capture occurs by default. An explicit workload SecretRedactor is required; use an empty registry only when the workload contains no secrets. Request header credentials are additionally redacted by bundled transports. Unknown customer data is NOT anonymized. Store records separately from events/logs/support bundles, with restricted access and short retention.

Scopes are task-local and nestable. Child tasks inherit the active scope but must finish before it exits. The optional local capture ID must be a UUID; it is distinct from the upstream provider request ID and is not sent to it. This scope makes no requests, adds no headers and changes no retry policy.

capture_provider_errors(sink: Callable[[dict[str, Any]], None], *, redactor: SecretRedactor, capture_id: str | None=None) -> Iterator[ProviderErrorCapture]

Release source · Runtime guarantees · Capability guides

ProviderErrorCapture

from cayu.providers import ProviderErrorCapture

One explicit capture scope; inspect counters after leaving the scope.

Use capture_provider_errors to create this object. Sink failures are counted, never substituted for the original provider failure or retried. A sink must complete promptly and must not log the supplied record publicly.

Decorators: @dataclass(slots=True).

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
capture_id	str	required
records_attempted	int	0
records_written	int	0
sink_failures	int	0
records_dropped	int	0

record_error (method)

ProviderErrorCapture.record_error(error: Mapping[str, Any], *, boundary: _Boundary, headers: Mapping[str, str] | None=None, http_status_code: int | None=None, provider_request_id: str | None=None, request_id_source: Literal['header', 'body', 'unavailable']='unavailable', body_state: Literal['available', 'unavailable']='available', status_fields: Mapping[str, Any] | None=None) -> None

Capture an OpenAI-shaped error from a custom transport, if needed.

Bundled HTTP transports call this automatically. headers are request headers used ONLY to register credentials for redaction, never persisted. http_status_code is the transport status (possibly 200 for SSE), not an inferred error status. status_fields can supply explicit body statuses at the fixed status_code/error/response paths; arbitrary keys and non-status values are ignored. By default, error’s status_code is used. No field here authorizes retries or recovery.

Release source · Runtime guarantees · Capability guides