Configuration Guide

obslog runs with zero configuration (CFG-001, CFG-006): the first get_logger installs a sane default — INFO level, a console formatter on a TTY and JSON otherwise, writing to stderr. Configure it when you need more.

Precedence

From highest priority to lowest (CFG-002):

1. Runtime overrides (keyword arguments to configure_*)
2. Environment variables (OBSLOG_*)
3. Config file (YAML or JSON)
4. Built-in defaults

In code

import obslog
from obslog.sinks import Stream

obslog.configure(
    level="INFO",
    sinks=[Stream(format=obslog.formats.json())],
    resource={"service.name": "checkout", "deployment.environment": "prod"},
)

configure() reconfigures the default provider in place, so loggers already obtained from get_logger observe the change. For isolation (libraries, tests) build a separate provider:

telemetry = obslog.Telemetry(level="DEBUG", sinks=[obslog.sinks.Memory()])
log = telemetry.get_logger("mylib")

From a file

obslog.configure_from_file("observability.yaml")  # or .json

level: INFO
format: json          # auto | json | console
sink: stderr          # stderr | stdout
redact: [password, token, secret]
sample_rate: 1.0
resource:
  service.name: checkout
  deployment.environment: prod

YAML support requires the extra: pip install "obslog[yaml]" (CFG-008). JSON works with no extra.

From the environment

obslog.configure_from_env()

Variable	Maps to
OBSLOG_LEVEL	level
OBSLOG_FORMAT	auto / json / console
OBSLOG_SINK	stderr / stdout
OBSLOG_REDACT	comma-separated redaction keys
OBSLOG_SAMPLE_RATE	float sampling rate
OBSLOG_SERVICE_NAME	resource["service.name"]
OBSLOG_ENV	resource["deployment.environment"]

Processors

redact and sample_rate install processors that run inside the sink pipeline before any formatter/exporter (NFR-SEC-002). Compose them explicitly for full control:

from obslog.sinks import Pipeline, Stream
from obslog.processors import Redact, Sample

obslog.configure(
    sinks=[
        Pipeline([Redact(["password"]), Sample(0.1)], Stream()),
    ]
)

Invalid values fail fast with actionable messages — an unknown level lists the valid level names (CFG-007).