snoozeml.logging — Structured Logging & Secret Redaction#

Structured logging and credential sanitization utilities for the SnoozeML Python SDK.

Provides a hierarchical logger rooted at "snoozeml", automatic redaction of API keys and JWT bearer tokens from log records, and a helper to configure human-readable or JSON-formatted structured output.

snoozeml.logging.mask_secret(secret)[source]#

Masks a sensitive credential string so raw secrets are never exposed.

Parameters:

secret (str | None) – The raw credential (API key, JWT token, etc.) or None.

Returns:

"None" if secret is None, "***REDACTED***" otherwise.

Return type:

str

snoozeml.logging.sanitize_text(text, known_secrets=None)[source]#

Scrubs Bearer tokens, API key key-value pairs, and registered secrets from text.

Parameters:

  • text (str) – Input string potentially containing credentials.

  • known_secrets (Set[str] | None) – Optional set of exact secret strings to replace.

Returns:

Sanitized string with credentials replaced by ***REDACTED***.

Return type:

str

snoozeml.logging.sanitize_mapping(mapping, known_secrets=None)[source]#

Returns a shallow copy of a dictionary with sensitive keys redacted.

Parameters:

  • mapping (Dict[str, Any] | MutableMapping[str, Any]) – Dictionary or mapping (such as HTTP headers or gRPC metadata).

  • known_secrets (Set[str] | None) – Optional set of exact secret strings to replace.

Returns:

A sanitized dictionary safe for logging.

Return type:

Dict[str, Any]

class snoozeml.logging.RedactingFilter(name='')[source]#

Bases: Filter

Logging filter that strips API keys, JWTs, and registered secrets from log records.

Parameters:

name (str)

register_secret(secret)[source]#

Registers a secret string to be unconditionally scrubbed from log messages.

Parameters:

secret (str | None) – Raw API key or token string.

Return type:

None

filter(record)[source]#

Sanitizes record.msg, record.args, and structured extra fields in-place.

Parameters:

record (LogRecord)

Return type:

bool

class snoozeml.logging.StructuredFormatter(*, format_json=False)[source]#

Bases: Formatter

Formats log records as structured key-value lines or JSON objects.

Parameters:

format_json (bool)

format(record)[source]#

Formats the log record including any structured extra fields.

Parameters:

record (LogRecord)

Return type:

str

snoozeml.logging.get_logger(name=None)[source]#

Returns a child logger under the "snoozeml" hierarchy with secret redaction enabled.

Parameters:

name (str | None) – Sub-module name (e.g. "client", "converters"). If None, returns the root "snoozeml" logger.

Returns:

Configured logging.Logger instance.

Return type:

Logger

snoozeml.logging.configure_logging(level=20, *, format_json=False, stream=None)[source]#

Configures structured console or JSON logging for the snoozeml package.

Parameters:

  • level (int | str) – Logging level (e.g. logging.DEBUG, "INFO", "WARNING").

  • format_json (bool) – If True, emit single-line JSON records; otherwise emit human-readable structured key-value lines.

  • stream (TextIO | None) – Output stream (defaults to sys.stderr).

Returns:

The configured root "snoozeml" logging.Logger.

Return type:

Logger