Public API¶
Only the symbols re-exported from obslog and the documented submodules
(obslog.sinks, obslog.formats, obslog.processors, obslog.diagnostics,
obslog.testing, obslog.integrations, obslog.plugins) are public API (API-017).
See API stability for the compatibility policy.
Top level¶
obslog.get_logger(name=None)
¶
Return a logger bound to the default provider (API-001).
obslog.configure(*, level=Level.INFO, sinks=None, processors=None, resource=None, clock=None, id_generator=None)
¶
Configure the default provider in place and return it (API-009).
Unspecified options reset to their defaults (this is a full replace, not a merge).
Reconfiguring in place means loggers already obtained from :func:get_logger
observe the new configuration.
obslog.configure_from_file(path, **overrides)
¶
Configure the default provider from a YAML/JSON file (CFG-004, CFG-008).
Precedence is defaults < file < environment variables < overrides (CFG-002).
obslog.configure_from_env(**overrides)
¶
Configure the default provider from OBSLOG_* env vars (CFG-005).
obslog.configure_from_mapping(mapping, **overrides)
¶
Configure the default provider from a config mapping (CFG-003, CFG-004).
obslog.context(**fields)
¶
Bind ambient correlation fields for the duration of the with block.
Fields are merged over the current context; on exit the previous context is restored (CTX-002). Nested blocks compose; unrelated tasks never observe each other's context (CTX-005).
obslog.new_id()
¶
Return a new correlation id from the default provider's generator (API-008).
obslog.lazy(fn)
¶
Wrap fn so it is evaluated only when the log call is emitted (API-007).
Logger¶
obslog.Logger
¶
Immutable structured logger bound to a provider and a logical name.
bind(**fields)
¶
Return a new logger with fields added to its bound context (API-014).
try_unbind(*keys)
¶
Return a new logger without keys; missing keys are ignored (API-004).
trace(event, /, **fields)
¶
Emit a TRACE-level record.
debug(event, /, **fields)
¶
Emit a DEBUG-level record.
info(event, /, **fields)
¶
Emit an INFO-level record.
warning(event, /, **fields)
¶
Emit a WARNING-level record.
error(event, /, *, error=None, error_code=None, **fields)
¶
Emit an ERROR-level record, optionally with an exception and stable code.
critical(event, /, *, error=None, error_code=None, **fields)
¶
Emit a CRITICAL-level record, optionally with an exception and stable code.
log(level, event, /, **fields)
¶
Emit a record at an explicit level (API-003).
operation(name, /, *, phase=None, **fields)
¶
Scope an operation: auto duration, causal linkage, and error capture.
Generates a child execution_id, links parent_execution from the
current ambient context (CTX-004), and on exit emits a completion record
(INFO on success, ERROR on exception) carrying duration_ns. Exceptions are
re-raised unchanged.
Level¶
obslog.Level
¶
Bases: IntEnum
An obslog severity level with an OpenTelemetry-aligned severity number.
severity_number
property
¶
The OpenTelemetry-aligned numeric severity (API-011).
severity_text
property
¶
The canonical text name of this level.
parse(value)
classmethod
¶
Coerce value (a Level, a name, or an exact numeric value) to a Level.
Raises ValueError with the list of valid names for unknown strings
(CFG-007), and TypeError for unsupported types.