Skip to content

Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.

feature/Log-redaction · L-260916-4837d4 — scrub secrets, safe values (#1207)

Louis Choquel9a9bb479a3ff
diff --git a/.drift/acks/cli-docs.toml b/.drift/acks/cli-docs.toml
index f4686d8a3..204eb8ffe 100644
--- a/.drift/acks/cli-docs.toml
+++ b/.drift/acks/cli-docs.toml
@@ -1,8 +1,8 @@
contract = "cli-docs"
-digest = "sha256:28dfaac2f38ffb7bebd4e7aaf1e872dcf8a1ff0401e91b846006b6a001a28d89"
+digest = "sha256:2ac30bcfcf3e7d174db15b59fa2df4e9cb64c5c6a2c64f1d9e8bef415a4efd8f"
reviewed_by = "Claude (Opus 5.5)"
-reviewed_at = "2026-09-25T12:38:13Z"
-rationale = "Merge of origin/feature/Log-fields-context (carrying dev's releases v0.61.0 through v0.65.0) into feature/Log-sink-seam: the merged trigger set is the union of two changes each acked on its own side, with no trigger file changed on both. This branch's side (agent_cli_factory.py and both doctor_cmd.py) is covered by the checks.log_sink row in pipelex/cli/agent_cli/CLAUDE.md, present in the merged tree. The parent's side is check_model_cmd.py's argument-help example moving from the retired @best-claude alias to @best-gpt; neither docs/tools/cli/ nor the agent-CLI contract doc quotes that example or any deck alias (grep for best-claude, best-gemini and best-mistral finds nothing in either target). The ack file's line-wise auto-merge kept each side's trigger snapshot, so this re-ack records the merged tree as reviewed as a whole. No doc change needed."
+reviewed_at = "2026-09-25T12:48:43Z"
+rationale = "Merge of origin/feature/Log-sink-seam (carrying dev's releases v0.61.0 through v0.65.0) into feature/Log-redaction. Against the parent the only trigger change is this branch's doctor_cmd.py arm that keeps an installed sink which failed during the replay of the held records, and the checks.log_sink row in pipelex/cli/agent_cli/CLAUDE.md carries that fourth case in the merged tree. Against this branch's previous head the only trigger change is the parent's check_model_cmd.py argument-help example moving from the retired @best-claude alias to @best-gpt, and neither docs/tools/cli/ nor the agent-CLI contract doc quotes that example or any retired deck alias (a grep for best-claude, best-gemini and best-mistral over both targets finds nothing). docs/tools/cli/agent-cli.md describes the doctor command by its flags and formats only, so nothing there is stale. The ack file's merge spliced the parent's header onto this branch's trigger snapshot, so this re-ack records the merged tree as reviewed as a whole. No doc change needed."
[trigger_files]
"pipelex/cli/__init__.py" = "blob:8b137891791fe96927ad78e64b0aad7bded08bdc"
@@ -82,7 +82,7 @@ rationale = "Merge of origin/feature/Log-fields-context (carrying dev's releases
"pipelex/cli/commands/codegen/inputs_cmd.py" = "blob:20738a9e42f0e5ef7ffc489093348af3cb4643a0"
"pipelex/cli/commands/codegen/types_cmd.py" = "blob:b7c9c7a3664c9fbe66f9b4c3c5ebf9ea1322445c"
"pipelex/cli/commands/crate_loading.py" = "blob:3d7d651931ecf1a15a3e2d72411b3212b55d74ef"
-"pipelex/cli/commands/doctor_cmd.py" = "blob:7ea6e1b0f260a0de8cceae4e5c2deede7b0abbd7"
+"pipelex/cli/commands/doctor_cmd.py" = "blob:26db32ff20d1c064bc421093825a05e980c9b770"
"pipelex/cli/commands/fix/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
"pipelex/cli/commands/fix/_diff_sandbox.py" = "blob:5ce264f5b0ab4ff4172f4d8789450916947f5c0e"
"pipelex/cli/commands/fix/_fix_core.py" = "blob:8f6a187a0fb42c498629b177753d81620800b0da"
diff --git a/.drift/acks/config-docs.toml b/.drift/acks/config-docs.toml
index 1e9468137..6ec091d1d 100644
--- a/.drift/acks/config-docs.toml
+++ b/.drift/acks/config-docs.toml
@@ -1,13 +1,13 @@
contract = "config-docs"
-digest = "sha256:6c7a74ebfa3059f589421b8f984df95feb1aabc705950eb48b0ff2322e4141c6"
+digest = "sha256:c92f24eeb4684a4bcfb92ea177fd96943be6bd045c04881bee14fafb6388166b"
reviewed_by = "Louis Choquel"
-reviewed_at = "2026-09-16T18:14:03Z"
-rationale = "Log sinks replace the log mode: log_config.py loses LogMode, log_mode, poor_loggers, generic_poor_logger and is_console_logging_enabled and gains the sink key and the [runtime.log.otlp] table (endpoint, headers); pipelex.toml ships sink = console and the otlp table. docs/configuration/config-practical/logging-config.md is rewritten around the sink key with a section per shipped sink and a migration paragraph, and migration ledger entry pipelex-config@5 deletes the four retired keys with the goldens regenerated by make umig. No validator moved."
+reviewed_at = "2026-09-17T13:32:03Z"
+rationale = "The only trigger change is the extra_patterns validator, which now also refuses a regular expression matching the empty string: x* where x+ was meant matches at every position and replaces the whole of every log line the process writes, for the life of the process, so it is named where the pattern is still in front of whoever typed it. It narrows the accepted domain and no fingerprint can see it, which is what this contract asks about, and it takes no migration ledger entry: the shipped default is an empty list, a file already holding such a pattern was already having every line destroyed by it, and no migration can guess what pattern was meant. No field was added, renamed or removed and no other validator moved; check-migration-schemas reports the surfaces accounted for. The review targets were read: docs/configuration/config-practical/logging-config.md now says the refusal beside the one for a pattern re refuses, and names what each shipped family actually reads, since the families were rewritten in the same change; configs.py and config_cogt.py are untouched by it."
[trigger_files]
"pipelex/cogt/config_cogt.py" = "blob:02f71cb4a6b01aebda59c2e31f262ef9c865e17b"
"pipelex/cogt/img_gen/img_gen_job_components.py" = "blob:084985080413fd8d6c3b1b9b0747020cb0161858"
-"pipelex/pipelex.toml" = "blob:3fb0bd5076a7d2993502159a121a69fe03210086"
+"pipelex/pipelex.toml" = "blob:6140d1296b800011b423e75f421ec4a951efda89"
"pipelex/system/configuration/__init__.py" = "blob:8b137891791fe96927ad78e64b0aad7bded08bdc"
"pipelex/system/configuration/config_check.py" = "blob:88e15a92b186088a5ea1c7c4ebcedac830707d3a"
"pipelex/system/configuration/config_loader.py" = "blob:ac384ce993933656682999c26afffb4c9f9b1975"
@@ -18,4 +18,4 @@ rationale = "Log sinks replace the log mode: log_config.py loses LogMode, log_mo
"pipelex/system/configuration/pipe_func_config.py" = "blob:dc8890e914fbcdb611147e42eaa0cd87b32288a5"
"pipelex/system/telemetry/telemetry_config.py" = "blob:7070951a6d3e4c10cb7d59822ce168c6590c53be"
"pipelex/tools/aws/aws_config.py" = "blob:c1aeafeae08d3921464db33795f11a29ff3892ba"
-"pipelex/tools/log/log_config.py" = "blob:a32629f52056364493e96f071e7b6814cefaeeb9"
+"pipelex/tools/log/log_config.py" = "blob:d42123b1bbd64383447e35414a8c4bcbf073b890"
diff --git a/.pipelex/pipelex.toml b/.pipelex/pipelex.toml
index dd73e4c41..8100c079a 100644
--- a/.pipelex/pipelex.toml
+++ b/.pipelex/pipelex.toml
@@ -101,6 +101,14 @@ console_print_target = "stdout"
# collector), or a token an installed plugin registers.
sink = "console"
+# redaction scrubs known secret shapes (bearer tokens, api-key and signature headers, OAuth code
+# parameters, cookies, JSON secret entries, the sk_ / plx_sk_ / pk_ / bl_ key prefixes) out of the
+# message and of every string a field carries, and neutralises control characters in a field value so
+# a caller-supplied string cannot forge a line. Add this project's own secret shapes to extra_patterns.
+[runtime.log.redaction]
+is_enabled = true
+extra_patterns = []
+
[runtime.log.package_log_levels]
# Log levels for specific packages (use "-" instead of "." in package names)
pipelex = "INFO"
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4b552b0fa..c86d2d9f4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,7 @@
- **Named fields and a run-scoped context on the log calls**: the seven `log.*` methods take a keyword-only `fields={...}`, carried as attributes of the stdlib `LogRecord` and never rendered into the message, and `with log.context(request_id=..., pipeline_run_id=..., pipe_run_id=...)` stamps the run's identifiers onto every record emitted in scope, nested bindings merging and an absent identifier staying absent rather than reading `None`. `PipeRun.run` binds the request and pipeline identifiers from the job's metadata for a direct-mode run, and every pipe binds its own `pipe_run_id` around the whole of its run, its announcement and its failure included. A `dict` or `list` content is carried as the record's `data` attribute beside its console rendering, a JSON-ready snapshot of the call rather than the caller's live object, and an entry named like an attribute the record already owns, a record factory's included, or like one of the names set after the fields are attached — the formatter's, and the internal marker that tells a sink a record reached it already — is carried under a `field_` prefix instead of raising or steering delivery, whatever the order the names arrive in — a field spelling `data` beside structured content included, so the content keeps the name a sink reads it under and the field keeps its value beside it, as [Logging](tools/logging.md) describes.
- **Log sinks are a plugin capability selected by `[runtime.log] sink` (Breaking)**: where the records go is a registered sink token, `console` (the Rich handler, the default so the CLI keeps its rendering), `json` (one JSON object per line carrying `time`, `severity`, `logger`, `message`, the fields, the context identifiers and the exception, with no ANSI ever, for a server behind a log agent) or `otlp` (the OpenTelemetry logs signal, configured under `[runtime.log.otlp]`, so a collector receives the logs beside the spans), each of the two reserving the keys it writes itself so that a field named like one of them rides under a `field_` prefix rather than overwriting it, or a token an installed plugin registers through `add_log_sink`, and a token nobody provides stops the boot naming the registered ones, while `pipelex doctor` reports it in a row of its own and carries on through the console sink. `log_mode`, `poor_loggers`, `generic_poor_logger` and `is_console_logging_enabled` are gone with the rich-or-poor mode, and `set_log_mode`, `set_poor_log_formatter` and `LevelAndEmojiLogFormatter` with them, so a server that wants plain output selects `json` and a host that wants Pipelex silent sets `pipelex = "OFF"` under `[runtime.log.package_log_levels]`. **Migration:** run `pipelex migrate`; ledger entry `pipelex-config@5` deletes the four retired keys from `~/.pipelex/` and every project `.pipelex/` file, after which the defaults supply `sink = "console"`. A file that had `log_mode = "poor"` or `is_console_logging_enabled = false` chose a behaviour that deletion undoes and no migration may write back, so such a file sets `sink = "json"` or `pipelex = "OFF"` under `[runtime.log.package_log_levels]` by hand, as the entry's title says. [Log Sink Plugins](under-the-hood/log-sink-plugins.md) documents the seam.
+- **Secrets are scrubbed and field values made injection-safe before any sink sees a record**: one processor, configured under `[runtime.log.redaction]` and on by default, replaces an `Authorization` header's credential whichever scheme carries it, an api-key or signature header value, an OAuth `code` parameter read through the delimiter that ends it so a percent-encoded code goes whole, a cookie header's every crumb, a secret entry written as a serialised entry or plainly as `name=value`, and an `sk_` / `plx_sk_` / `pk_` / `bl_` key spelled with a dash as with an underscore, with `[REDACTED]`, in the message, in the exception's rendered text and in every string a field carries. Each family reads the shape a secret is actually written in rather than running to the end of the line, so a sentence that merely says "cookie:" keeps its words and an identifier like `pk_customer_reference_index` is left alone, and the key family keeps the prefix that named the secret as every other family keeps its carrier. A field of the record, or a mapping entry at any depth, whose own name is a secret's (`authorization`, `password`, `api_key`, `access_token` and the like, read in any case and with a dash as an underscore) loses its value whatever it holds, judged by the name the call used so a field carried under the `field_` collision prefix is covered too, and a structured content is redacted by name before it is rendered, so the message says exactly what `data` holds even where the secret sat in a nested object or in a number, content JSON refuses and falls back to its `repr` included; a pydantic model or any other object is rendered before the walk exactly as the wire sinks would have rendered it after, and one that refuses to render becomes an `[UNRENDERABLE: …]` marker costing that value alone. Each control character in a field's string values becomes its printable escape so a caller-supplied string cannot forge a line, a field separator or a colour on a terminal; the message and the `data` attribute keep theirs, being the runtime's own rendering, and `data` is the runtime's name alone, a call that passes a field of that name having it carried as `field_data` and escaped like any other. It is installed by `log.install_sink` in front of whatever the sink appended, so every sink is behind it, and it edits the record the root logger shares rather than a copy, so a handler ordered after the sink is behind it too, and a boot that dies before its sink arrives runs it over the records held since `log.configure` before they reach the stdlib's last resort on stderr; `extra_patterns` adds the secret shapes only a deployment knows, and a pattern the `re` module refuses is a configuration error named at load, as is one that matches the empty string, which would replace every line the process writes. The `otlp` sink emits `exception.type` and `exception.stacktrace` and no `exception.message`, so what it exports is the scrubbed text, an exception carrying no traceback rendering as its own last line. A sink processor that raises is now reported on stderr by its type and its name, never by its text, instead of raising out of the log call or going to the stdlib's `handleError`, which prints the exception and the record's raw arguments; a record whose arguments do not fit its format string keeps the scrubbed format string and an `[ARGUMENTS WITHHELD: …]` notice for the same reason, and the redaction processor fails closed, stripping the record to a `[REDACTION FAILED: …]` notice before it reports and dropping the record outright where even that stripping could not complete, as [Logging](tools/logging.md#redaction) describes.
### Changed
@@ -20,6 +21,9 @@
- **A log call before `log.configure` no longer raises**: it goes to the stdlib's default handling at the stdlib's default level, so a library that logs before Pipelex boots, or a boot that logs while it configures, cannot crash on the log line itself. Between `log.configure` and the sink's arrival at boot, every record is held and replayed through the selected sink in order, so a boot's own lines are rendered by the sink the configuration chose, and a boot that dies before the sink arrives sends all of them to stderr rather than only a warning or worse: each one passed the level the configuration set, and a failed boot is when that trail is worth most.
- **A log call never raises on a value the record or JSON refuses**: a field named like an attribute the `LogRecord` class owns (`__class__`, `__dict__`, `getMessage`) is prefixed like any other collision instead of raising `TypeError` or shadowing the method every formatter calls, and a content `json` refuses, a circular reference or a mapping with a non-string key, is rendered as its `repr` with no `data` instead of raising `ValueError` or `TypeError` out of `log.info`. A non-finite float nested inside a pydantic model is spelled as text like one at the top level, so a single `NaN` costs that one float its type and no other value on the line its structure. On the `console` sink the same promise needed the stdlib's own guard put back: Rich overrides `emit` without it, so a message carrying a tag-shaped span — `list[int]` in a type complaint, or a bracketed path, which Rich reads as a closing tag — raised `MarkupError` out of the log call and replaced the failure being reported with itself. Such a line now costs at most its own rendering, and an error assembled from an exception is rendered verbatim rather than read as markup, so the brackets and the type names in it reach the terminal as they were written.
+- **A field named `_pipelex_forwarded` no longer deletes its own record**: the name the holding handler stamps on a record it has already forwarded was treated as unspellable because it starts with an underscore, but a fresh record does not carry it, so a caller's `fields={"_pipelex_forwarded": ...}` landed unprefixed and had the record rejected from every sink by the guard that exists to stop a double delivery. Such an entry is now carried under the `field_` prefix like any other collision, and the line is delivered.
+- **A sink object installed again after a reset builds a fresh handler, or refuses to**: the teardown closed the handler and the sink then handed that same closed handler back, so a sink whose `close()` really releases its target was re-installed dead, accepting every record and exporting none, with nothing raised to say so; the forwarded-record filter stacked up on it besides, one more at every install. A sink whose target is opened in `make_handler` now works across a configure/reset cycle, which is what the tests and an embedding host do. The `otlp` sink cannot, since it is constructed around its processor and its close shuts that processor down with the logger provider, so installing the same `OtlpLogSink` object a second time now raises instead of exporting nothing; the registered factory builds a new one at every boot, so a boot through the registry never meets it.
+- **`pipelex doctor` no longer dies on a log sink that failed after it was installed**: the fallback to the console sink ran on any exception out of `log.install_sink`, on the assumption that a failed install leaves nothing installed. That holds for a failed handler build only — the sink is recorded before the records held since `log.configure` are replayed through it, so a handler that cannot render one of them and cannot report it either, which is what a closed stderr produces, leaves the sink installed and made the fallback raise "A log sink is already installed" out of the command. The fallback now runs only when nothing is installed; otherwise the row reports the failure and the installed sink is kept.
## [v0.65.0] - 2026-09-25
diff --git a/docs/configuration/config-practical/logging-config.md b/docs/configuration/config-practical/logging-config.md
index 934b3f986..87914ab2f 100644
--- a/docs/configuration/config-practical/logging-config.md
+++ b/docs/configuration/config-practical/logging-config.md
@@ -100,6 +100,44 @@ Available templates:
- `"func_module"`: "function_name module"
- `"func_module_line"`: "function_name module 123"
+### Redaction
+
+```toml
+[runtime.log.redaction]
+is_enabled = true
+extra_patterns = []
+```
+
+One processor, applied to every record before any sink renders it, whichever sink is selected. It does two things, and the difference between them matters.
+
+**It scrubs secrets** from the message, from the exception's rendered text and from every string a field carries, replacing what a pattern matched with `[REDACTED]` and keeping whatever named the secret, so a reader still sees which header or which entry was carrying it. The shipped families are the ones the hosted plane already ran over its own records:
+
+- an `Authorization` header, whichever scheme it carries — `Bearer`, `Basic`, `Token`, `Digest`, `Negotiate`, `HMAC` — the scheme kept and the credential after it removed,
+- an api-key header or entry, however it is spelled (`x-api-key`, `api-key`, `api_key`),
+- a webhook signature header (`x-signature`, `x-completion-signature`),
+- an OAuth authorization code in a query string (`?code=…`, `&code=…`), read to the `&` or the `#` that ends the parameter rather than through an alphabet of its own, so a percent-encoded code goes whole,
+- a `Cookie` or `Set-Cookie` header's whole value, every crumb and every flag attribute of it. The value has to be a cookie header's own `name=value` grammar, which is what tells a header from a sentence: a quoted crumb is read to its closing quote and a crumb holding an apostrophe is read whole, while prose that merely says "cookie:" before ordinary words keeps its line,
+- a serialised entry, in a JSON object or a Python `repr` alike, whose name is one of the secret names below: its value is removed whether it is quoted — with either quote character, and whichever quoted the name — or a bare number or boolean,
+- those same names again in the plain `name=value` or `name: value` form a query string, a form-encoded body or a header line writes them in, which is the shape a raw request reaches the processor in,
+- a key recognisable by its prefix alone: `sk_`, `plx_sk_`, `pk_`, `bl_`, each spelled with a dash as with an underscore, so `sk-proj-…` and `sk-ant-api03-…` go the way `sk_live_…` does. The prefix is kept and what follows it removed, and what follows has to end in a long unbroken run of letters and digits — which is what keeps this family off an ordinary snake_case identifier, a table or a partition named `pk_customer_reference_index` being words all the way down.
+
+Every family but the serialised entry asks for at least eight characters of what a secret is written in. That bound is what keeps a family reading a `name: value` shape off ordinary prose, and it is the one the hosted plane's own scrubber was written with; a secret shorter than it is below what the shipped families read at all.
+
+The **secret names** are `password`, `pipelex_api_key`, `gateway_api_key`, `jwt_secret_key`, `portkey_api_key`, `client_secret`, `access_token`, `refresh_token`, `id_token`, `authorization`, `api_key`, `x_api_key`, `x_signature`, `x_completion_signature`, `cookie` and `set_cookie`, read in any case and with a dash as an underscore. A **field of the record whose own name is one of them** loses its value whatever it holds — judged by the name the call used, so a field carried under the `field_` collision prefix because the record already owned that name is covered too — and so does a **mapping entry** at any depth, since the mapping split the name from the value the families read together. `code` is deliberately not a secret name: it is the runtime's own identifier for a pipe, a domain and an error, and the OAuth code has its query-string family.
+
+A structured value, a field's `dict` or `list` or the `data` a structured content produces, is walked to any depth, and its strings go through the families above. A pydantic model is dumped and any other object rendered as text before the walk, exactly as the `json` and `otlp` sinks would have done after it, so neither carries a secret past the scrub; a model or an object that refuses to render becomes an `[UNRENDERABLE: <exception type>]` marker, which costs that one value and leaves the record and every other value it carries. A container that contains itself is cut at the cycle with a `[cycle]` marker.
+
+A structured content is redacted by name **before the message is rendered**, so the line a sink writes beside `data` says exactly what `data` holds: a secret nested in an object or held as a number is beyond what a pattern can read back out of text. That holds for content JSON refuses outright too — a circular reference, a mapping with a non-string key — which is rendered as its `repr` and carries no `data`: the names are redacted on that path as well, since a `repr` is no more readable to a pattern than a rendering is. Text a call rendered itself, an f-string of a dictionary for one, is covered by the serialised-entry family alone, which does not see into a nested object.
+
+**It neutralises control characters** in a field's string values, and only there: each becomes its printable escape, so a newline in a caller-supplied value cannot forge a line and a tab cannot forge a field separator, and an escape byte cannot colour a terminal. The message and the `data` attribute keep their control characters, because they are the runtime's own rendering — a titled call and a structured content both put a newline there deliberately, and the wire sinks escape `data` themselves, so a logged prompt keeps its line breaks. `data` is the runtime's name alone: a call that passes a field of that name has it carried as `field_data`, and escaped like every other field.
+
+**It fails closed.** A scrub that raises costs that record its processing, never the log call, and the record it hands on carries nothing of the call: the message becomes `[REDACTION FAILED: <exception type>]` and every field the record carried becomes `[REDACTED]`. Where even that stripping cannot complete — a stack that has run out is the usual reason the scrub failed in the first place, and it can run out again a line later — the record is dropped instead of emitted, so no sink ever receives one the scrub did not read.
+
+- `is_enabled`: `true` by default. `false` turns the processor off for a process that redacts downstream, or one whose records must be reproduced exactly as the calls made them
+- `extra_patterns`: regular expressions added to the shipped families, for the secret shapes only this deployment knows. Every match is replaced by `[REDACTED]`. A pattern the `re` module refuses is a configuration error named when the configuration loads, and so is one that matches the empty string — `x*` where `x+` was meant matches at every position of every line, which would replace the whole of every line the process writes
+
+What the processor does not reach is the `console` sink's Rich traceback, rendered from the exception object rather than from the scrubbed text, so on a person's terminal an exception reads as it was raised. Where the processor runs, and why it edits the record rather than a copy of it, is in [Logging](../../tools/logging.md#redaction).
+
### Problem Silencing
```toml
@@ -196,6 +234,10 @@ is_caller_info_enabled = true
caller_info_template = "file_line_func"
silenced_problem_ids = []
+[runtime.log.redaction]
+is_enabled = true
+extra_patterns = ["tnt-[0-9]+"]
+
[runtime.log.package_log_levels]
pipelex = "INFO"
openai = "WARNING"
diff --git a/docs/tools/logging.md b/docs/tools/logging.md
index 33563b85d..45cfa95c8 100644
--- a/docs/tools/logging.md
+++ b/docs/tools/logging.md
@@ -70,7 +70,7 @@ A value can be anything. It rides the record by reference and the sink serialize
- A field name is a `snake_case` identifier, spelled the way the value is spelled where it comes from: a field carrying a payload's `pipeline_run_id` is `pipeline_run_id`, not `pipelineRunId` or `run`.
- Where the [OpenTelemetry semantic conventions](https://opentelemetry.io/docs/specs/semconv/general/logs/) define a key for the concept, use that key verbatim, dots included (`http.response.status_code`, `code.function.name`), so an OTLP sink emits it without translation. The three run identifiers have no such key and keep their payload names.
-- `request_id`, `pipeline_run_id` and `pipe_run_id` are reserved for the [run-scoped context](#the-run-scoped-context), and `data` is reserved for [structured content](#structured-content). A field of one of those names is accepted and never dropped: it takes precedence over the context for the three identifiers, and it rides under `field_data` beside structured content. Nothing else should use them.
+- `request_id`, `pipeline_run_id` and `pipe_run_id` are reserved for the [run-scoped context](#the-run-scoped-context), and `data` is reserved for [structured content](#structured-content). A field of one of those names is accepted and never dropped: it takes precedence over the context for the three identifiers, and a `data` field rides under `field_data` whatever the content is. Nothing else should use them.
### Names that are not yours to give
@@ -125,7 +125,29 @@ When the content is not a string, it is rendered as JSON for the message, indent
A `NaN` or an infinity survives the round trip as a float; a wire sink writes it as the string `"NaN"`, `"Infinity"` or `"-Infinity"`, since JSON has no token for it that a strict parser accepts.
-Structured content owns the `data` name: a `data` entry in `fields` beside a non-string content keeps its value and is carried under `field_data`, the same prefix a field named like a record attribute or like a sink's reserved key gets. Nothing passed in `fields` is dropped for a name collision.
+Structured content owns the `data` name, on every call: a `data` entry in `fields` keeps its value and is carried under `field_data` whatever the content is, a string included — the same prefix a field named like a record attribute or like a sink's reserved key gets. Nothing passed in `fields` is dropped for a name collision.
+
+## Redaction
+
+Every record is scrubbed once, before any sink renders it. The processor replaces what a secret pattern matched with `[REDACTED]`, in the message, in the exception's rendered text and in every string a field carries, and a field or a mapping entry whose own name is a secret's loses its value whatever it holds. It also replaces each control character in a field's string values with its printable escape, so a caller-supplied string cannot forge a line, a field separator or a colour on a terminal. The message keeps its control characters, which are the runtime's own rendering: a titled call and a structured content both put a newline there on purpose. The families, the secret names, the two configuration keys and the limits are in [Logging Configuration](../configuration/config-practical/logging-config.md#redaction).
+
+A structured content is redacted by name before the dispatch renders it, so the message and the `data` attribute agree: `log.info({"password": {"nested": "hunter2"}})` writes `[REDACTED]` in both, where a pattern reading the rendered text could not have seen into the nested object. Content that JSON refuses outright — a circular reference, a mapping with a non-string key — falls back to its `repr` and carries no `data`, and is redacted by name on that path too: the `repr` of an object-valued entry is no more readable to a pattern than the rendering was.
+
+An exception is scrubbed as text: the processor renders the traceback the way the stdlib would, chain included, scrubs it and stores it as the record's `exc_text`, which is what the stdlib formatter, the `json` sink and the `otlp` sink write. The exception object stays on the record, and the `otlp` sink emits `exception.type` and `exception.stacktrace` and no `exception.message`, since that one would be the exception's own text and nothing can scrub an exception. The one boundary that leaves is the `console` sink with `is_rich_tracebacks = true`, the default: Rich renders its traceback from the exception object, so on a person's terminal the exception reads as it was raised. A structured sink a collector reads is scrubbed.
+
+**It runs on the sink's handler, not at the call sites, and it edits the record rather than a copy of it.** Both halves of that are deliberate.
+
+On the handler, because that is where every record passes: a line a third-party library emitted with a raw request in it is exactly the line most likely to carry a bearer token, and no call site of ours is behind it. Scrubbing at the call sites would cover only what the facade emitted, which is the smaller and safer half.
+
+In place, because what the processor does is *remove* something. A record that has lost a secret is strictly safer for any handler that sees it afterwards, so the edit is shared rather than kept to the sink: a handler an integration attached to the root logger after Pipelex booted is behind the scrub too. Handing the sink a redacted copy would have guaranteed the opposite — every other handler on the root logger would receive the secret the sink was spared. One limit follows, and it is the one the runtime cannot close: a handler already on the root logger *before* Pipelex booted runs ahead of the sink's and sees the record as the call made it. Redaction reaches the handlers Pipelex is in front of, and a host that installs its own handler first is in front of Pipelex.
+
+`log.install_sink` is what puts the processor in front of the sink's own, so every sink gets it — the built-in ones, an out-of-tree one, and the console sink `pipelex doctor` falls back to — and no sink knows about it. A boot that dies before its sink arrives runs the same processor, behind the same guard, over every record it held before handing them to the stdlib's last resort on stderr, so the trail a failed boot leaves is scrubbed too. `[runtime.log.redaction] is_enabled = false` installs nothing at all.
+
+The processor fails closed. A sink processor that raises is reported on stderr and the record is handed on, which is the right rule for a processor that enriches; for one that removes, it would mean the secret ships. So when the scrub itself fails, a value nested past the interpreter's recursion limit for one, the record is stripped before the failure is reported: its message becomes `[REDACTION FAILED: <exception type>]`, every field and the `data` attribute become `[REDACTED]`, and the exception text is dropped. The line says the scrub failed, and nothing of the call leaves with it.
+
+The stripping can fail in its turn, and that case is closed too. The commonest reason the scrub fails is a stack that has run out — a `log.<level>(...)` call made a few frames from the limit, by a recursive walker or by an `except RecursionError:` handler — and a stack that could not take the scrub cannot always take the stripping of what it left behind a line later. So the record is marked before the stripping starts, by a plain assignment into its own dictionary that pushes no frame, and unmarked only once the stripping has gone all the way through; a record still carrying the mark when the processors are done is **dropped** rather than emitted. A notice saying the record was quarantined while it still carried the field the scrub never read would be worse than no line at all.
+
+That report names the processor and the type of what it raised, and withholds the exception's own text and traceback — which the stdlib's `handleError` would have printed in full. A processor fails *on the record's values*, so its exception is exactly where they end up: the secret the scrub was removing among them. The same rule covers a record whose arguments do not fit its format string: rather than leave the handler to fail on it and have the stdlib print the format string and every argument raw, the processor renders the scrubbed format string alone, followed by `[ARGUMENTS WITHHELD: the message could not be rendered]`.
## Logger names and levels
@@ -146,7 +168,7 @@ A filter attached to `logging.getLogger("pipelex")` never sees these records: th
## Before configuration
-Logging is configured in two steps at boot. `log.configure` sets the levels and installs a holding handler on the root logger; then, once the plugin registrar is built, the configured sink is looked up, its handler is installed and the held records are replayed to it in order, so the boot's own lines reach the sink selected for them. A record emitted during the handoff reaches the sink either way, replayed or forwarded, and one held record the sink cannot render gets the stdlib's own recovery and costs none of the others. A call before `configure` never raises: the record goes to the stdlib's default handling at the stdlib's default level, so an `INFO` is dropped and a warning reaches stderr through `logging.lastResort`. A boot that fails between the two steps closes the holding handler, which hands what it held at `WARNING` and above to `logging.lastResort` and drops the rest. No handler is installed before `configure`, and nothing is swallowed. A library that logs before Pipelex boots, and the boot itself while it configures, are both safe.
+Logging is configured in two steps at boot. `log.configure` sets the levels and installs a holding handler on the root logger; then, once the plugin registrar is built, the configured sink is looked up, its handler is installed and the held records are replayed to it in order, so the boot's own lines reach the sink selected for them. A record emitted during the handoff reaches the sink either way, replayed or forwarded, and one held record the sink cannot render gets the stdlib's own recovery and costs none of the others. A call before `configure` never raises: the record goes to the stdlib's default handling at the stdlib's default level, so an `INFO` is dropped and a warning reaches stderr through `logging.lastResort`. A boot that fails between the two steps closes the holding handler, which hands every record it held to `logging.lastResort`, once the [redaction](#redaction) has run over each: they all passed the level the configuration set, and a boot that died is when that trail is read. No handler is installed before `configure`, and nothing is swallowed. A library that logs before Pipelex boots, and the boot itself while it configures, are both safe.
## Console rendering
diff --git a/docs/under-the-hood/log-sink-plugins.md b/docs/under-the-hood/log-sink-plugins.md
index 20d1e5d14..e0266b363 100644
--- a/docs/under-the-hood/log-sink-plugins.md
+++ b/docs/under-the-hood/log-sink-plugins.md
@@ -46,7 +46,7 @@ teardown
Logging is configured as soon as the configuration is read, in `RuntimeBoot.__init__`, so that everything the boot says afterwards is a record on a module-named logger at the configured level. The sink, though, is a plugin capability, and plugin discovery runs a little later, in `setup()`, once the boot knows which built-ins and which entry-point groups it reads. Rather than choose a default renderer for that window, `configure` installs a **holding handler** that keeps every record, and `install_sink` replays them through the selected sink's handler the moment it is installed, in the order they were emitted. A boot's own lines are therefore rendered by the sink the configuration chose, never dropped and never written in a shape nothing chose.
-The sink is the first capability resolved out of the registrar, ahead of secrets and storage, precisely so that every later line of the boot goes through it. A boot that dies before that point, on the gateway terms gate for instance, releases its process globals through `log.reset()`, which closes the holding handler: what it still holds gets the stdlib's last-resort treatment, a warning or worse reaches stderr and the rest is dropped, exactly as a record emitted before `configure` would be.
+The sink is the first capability resolved out of the registrar, ahead of secrets and storage, precisely so that every later line of the boot goes through it. A boot that dies before that point, on the gateway terms gate for instance, releases its process globals through `log.reset()`, which closes the holding handler: what it still holds gets the stdlib's last-resort treatment: every held record reaches stderr, since each passed the level the configuration set, and the redaction processor runs over each one first, behind the guard a sink's handler would have put it behind.
`pipelex doctor`, which deliberately bypasses `Pipelex.make` to diagnose a broken configuration, selects its sink the same way: the pure `build_registrar` discovery, then the `runtime.log.sink` lookup. Where boot stops on a token nobody registered, the doctor installs the console sink instead and reports the token in a row of its own, naming the registered sinks, so the report it exists to produce is still produced.
@@ -87,8 +87,8 @@ class LogSink(ABC):
def redirect_to_stderr(self) -> None: ... # a no-op unless the sink writes to a process stream
```
-- **`make_handler`** builds the stdlib handler the sink installs on the root logger, and is where a heavy import belongs. It is called once, when boot installs the sink, so selecting a sink is what pays for its dependency and a sink whose package is missing fails there, at boot, with `MissingDependencyError` naming the extra.
-- **`processors`** is the slot a cross-cutting transformation hooks into. A processor is a callable that edits a record in place, `Callable[[logging.LogRecord], None]`, and the base runs every processor over each record before the handler formats it, through a filter on the sink's own handler. Redaction is the intended one: appended to the base's list, it reaches every sink, built-in or external, with no sink knowing about it. A processor sees the record the root logger shares with every other handler, so a handler an integration attached to the root logger sees the record as the processors left it only if it runs after this one.
+- **`make_handler`** builds the stdlib handler the sink installs on the root logger, and is where a heavy import belongs. It is called once per install, so selecting a sink is what pays for its dependency and a sink whose package is missing fails there, at boot, with `MissingDependencyError` naming the extra. A sink object installed again after a `reset` builds a second handler rather than being handed the first one back, because the teardown closed it — and a close is terminal for a sink that really releases what it writes to, so a reused handler would accept every record and drop the lot with nothing raised to say so. **Open the target in `make_handler`, not in `__init__`**, or the second install writes to something already closed. A sink that cannot, because it is handed its target already built, refuses a second handler from `make_handler` instead of building one on the closed target: the built-in `otlp` sink is constructed around its processor and shuts it down with its provider at close, so installing the same `OtlpLogSink` object again raises, and its factory builds a new one at every boot.
+- **`processors`** is the slot a cross-cutting transformation hooks into. A processor is a callable that edits a record in place, `Callable[[logging.LogRecord], None]`, and the base runs every processor over each record before the handler formats it, through a filter on the sink's own handler. Each one is guarded on its own: the stdlib runs a handler's filters outside any `try`, so a processor that raised would raise out of the `log.<level>(...)` call that emitted the record, and instead what it raises is reported on stderr by its type and the processor's name — never its text or its traceback, since a processor fails on the record's own values and its exception is where those end up — guarded in its turn since a closed stderr makes the reporter raise, the processors after it still run, and the record is handed on. A failing processor costs that record its processing, never the call and never the line; the redaction processor, which must not hand on what it failed to scrub, strips the record down to a `[REDACTION FAILED: <exception type>]` notice before it raises, and where even that stripping could not complete it leaves a mark that has the record dropped rather than emitted — the one case in which a sink does not see a record its logger accepted. **Redaction is the first processor, and the base is not what appends it**: `log.install_sink` puts it in front of the sink's own list, so every sink gets it, built-in, out-of-tree or the doctor's fallback, with none of them knowing about it — see [Redaction](../tools/logging.md#redaction) for why it edits the record every root handler shares instead of a copy.
- **`redirect_to_stderr`** exists for the agent CLI, whose stdout is reserved for its structured envelope: a sink that writes to a process stream moves it to stderr, and one that writes to a collector ignores the call.
### What a sink reads off a record
diff --git a/pipelex/cli/agent_cli/CLAUDE.md b/pipelex/cli/agent_cli/CLAUDE.md
index 1de00b1aa..882d93a14 100644
--- a/pipelex/cli/agent_cli/CLAUDE.md
+++ b/pipelex/cli/agent_cli/CLAUDE.md
@@ -97,7 +97,7 @@ commands/
| `models` | Lists available model presets, aliases, and waterfalls. `--format markdown\|json` (success, default: markdown) + `--error-format markdown\|json` (errors, defaults to `--format`'s value) |
| `check-model` | Validates a model reference and suggests alternatives if invalid. `--type`/`-t` for model category, `--format markdown\|json` (success, default: markdown) + `--error-format markdown\|json` (errors, defaults to `--format`'s value) |
| `migrate` | Migrates this machine's configuration files (global `~/.pipelex/` and project `.pipelex/`, non-recursively) to the current schema by replaying each surface's ledger. Does **not** boot — it is the command for a configuration that cannot load. Writes only with `--yes`; `--dry-run` plans and is the default; the two together are refused with exit 2. `--format markdown\|json` (success, default: markdown) + `--error-format markdown\|json`. The verdict is the structured `needs_attention`, not the exit code. |
-| `doctor` | Checks config, credentials, models health. `--global`/`-g` for global dir. `--format markdown\|json` (success, default: markdown) + `--error-format markdown\|json` (errors, defaults to `--format`'s value). The telemetry check carries a `finding` (`healthy`/`not_found`/`unparseable`/`out_of_date`/`invalid`) beside its `healthy` and `message`; branch on that, and note `out_of_date` is `pipelex migrate`'s and never `pipelex init telemetry`'s — a reset would discard the settings the migration keeps — and that it means the migration would actually rewrite that file, so a file it would only report on is `invalid`. `checks.pending_migrations` is the machine-wide half: a `finding` (`up_to_date`/`pending`/`needs_attention`/`unavailable`) plus `migratable_files` and `attention_files`. It is the only channel a machine has for a pending migration — a tolerated boot warns a person and this CLI silences logging — and it is **not** scoped by `--global`, because it answers for `pipelex migrate`, which walks both directories. `checks.plugins` is present once the runtime setup discovered the plugins the way boot does: `healthy` and `message`, not healthy when the plugin registry did not build, in which case the message names the plugin error. `checks.log_sink` is present once the runtime setup ran: `healthy` and `message`, not healthy when `[runtime.log] sink` names no registered sink, when the configured sink failed to install or when the registry did not build. The message says why, and says where the report's own lines went: onto the console sink on stderr, which the doctor installs in place of the one that failed, or onto a sink already recorded, which it leaves alone rather than installing over — a sink is recorded before the held records are replayed, so a failed installation does not always leave nothing behind. |
+| `doctor` | Checks config, credentials, models health. `--global`/`-g` for global dir. `--format markdown\|json` (success, default: markdown) + `--error-format markdown\|json` (errors, defaults to `--format`'s value). The telemetry check carries a `finding` (`healthy`/`not_found`/`unparseable`/`out_of_date`/`invalid`) beside its `healthy` and `message`; branch on that, and note `out_of_date` is `pipelex migrate`'s and never `pipelex init telemetry`'s — a reset would discard the settings the migration keeps — and that it means the migration would actually rewrite that file, so a file it would only report on is `invalid`. `checks.pending_migrations` is the machine-wide half: a `finding` (`up_to_date`/`pending`/`needs_attention`/`unavailable`) plus `migratable_files` and `attention_files`. It is the only channel a machine has for a pending migration — a tolerated boot warns a person and this CLI silences logging — and it is **not** scoped by `--global`, because it answers for `pipelex migrate`, which walks both directories. `checks.plugins` is present once the runtime setup discovered the plugins the way boot does: `healthy` and `message`, not healthy when the plugin registry did not build, in which case the message names the plugin error. `checks.log_sink` is present once the runtime setup ran: `healthy` and `message`, not healthy when `[runtime.log] sink` names no registered sink, when the configured sink failed to install or when the registry did not build. The message says why, and says where the report's own lines went: onto the console sink on stderr, which the doctor installs in place of the one that failed, or onto a sink already recorded, which it leaves alone rather than installing over — a sink is recorded before the held records are replayed, so a failed installation does not always leave nothing behind. The fourth case is its own: a sink that was installed and then failed while the records held since logging was configured were replayed through it, where the report runs on that sink, which stays installed, and the message says what it raised. |
## Key Patterns
diff --git a/pipelex/cli/commands/doctor_cmd.py b/pipelex/cli/commands/doctor_cmd.py
index 7ea6e1b0f..26db32ff2 100644
--- a/pipelex/cli/commands/doctor_cmd.py
+++ b/pipelex/cli/commands/doctor_cmd.py
@@ -1133,6 +1133,12 @@ def install_doctor_log_sink(*, registry: LogSinkRegistry | None, log_config: Log
handler before it touches the root logger, so a sink that failed to build left nothing installed —
but not always, which is why the fallback is the one that decides whether it can stand in and
hands back the note the row carries.
+
+ Which failure it was is read off ``log.sink`` rather than assumed from the exception. The sink is
+ recorded before the held records are replayed through it, so a failure out of that replay — a
+ handler that cannot render a record and whose ``handleError`` cannot say so either, which is what a
+ closed stderr produces — leaves the sink installed. There is nothing for a fallback to stand in for
+ there, so that row names the replay as what failed and the installed sink is kept.
"""
if registry is None:
note = _install_fallback_log_sink(log_config=log_config)
@@ -1151,6 +1157,9 @@ def install_doctor_log_sink(*, registry: LogSinkRegistry | None, log_config: Log
except Exception as exc: # ruff: ignore[blind-except]
# A factory or a handler that raises on this configuration, a console target no sink writes
# to or a dependency the sink needs: the row says so, and the report goes on.
+ if log.sink is not None:
+ failure = f"was installed but then failed while the records held since logging was configured were replayed through it: {exc}"
+ return LogSinkCheck(is_healthy=False, message=f"The log sink '{log_config.sink}' {failure}")
note = _install_fallback_log_sink(log_config=log_config)
return LogSinkCheck(is_healthy=False, message=f"The log sink '{log_config.sink}' could not be installed: {exc}; {note}")
return LogSinkCheck(is_healthy=True, message=f"Log sink '{log_config.sink}' installed")
diff --git a/pipelex/kit/configs/pipelex.toml b/pipelex/kit/configs/pipelex.toml
index dd73e4c41..8100c079a 100644
--- a/pipelex/kit/configs/pipelex.toml
+++ b/pipelex/kit/configs/pipelex.toml
@@ -101,6 +101,14 @@ console_print_target = "stdout"
# collector), or a token an installed plugin registers.
sink = "console"
+# redaction scrubs known secret shapes (bearer tokens, api-key and signature headers, OAuth code
+# parameters, cookies, JSON secret entries, the sk_ / plx_sk_ / pk_ / bl_ key prefixes) out of the
+# message and of every string a field carries, and neutralises control characters in a field value so
+# a caller-supplied string cannot forge a line. Add this project's own secret shapes to extra_patterns.
+[runtime.log.redaction]
+is_enabled = true
+extra_patterns = []
+
[runtime.log.package_log_levels]
# Log levels for specific packages (use "-" instead of "." in package names)
pipelex = "INFO"
diff --git a/pipelex/migration/goldens/pipelex-config/[email protected] b/pipelex/migration/goldens/pipelex-config/[email protected]
index 3fb0bd507..6140d1296 100644
--- a/pipelex/migration/goldens/pipelex-config/[email protected]
+++ b/pipelex/migration/goldens/pipelex-config/[email protected]
@@ -105,6 +105,18 @@ keywords_to_hilight = []
[runtime.log.otlp]
headers = {}
+# [runtime.log.redaction] governs the one processor every sink is behind: it scrubs the secret shapes
+# the workspace already knows (an Authorization bearer token, an api-key or signature header, an OAuth
+# code parameter, a cookie, a JSON secret entry, and the sk_ / plx_sk_ / pk_ / bl_ key prefixes) out of
+# the message and out of every string a field carries, and neutralises the control characters in a
+# field value so a caller-supplied string cannot forge a line or a field separator. is_enabled = false
+# turns it off for a process that redacts downstream. extra_patterns are regular expressions added to
+# the shipped families for the secret shapes only this deployment knows; every match is replaced by
+# "[REDACTED]", and a pattern the re module refuses is a configuration error named at load.
+[runtime.log.redaction]
+is_enabled = true
+extra_patterns = []
+
[runtime.aws]
api_key_method = "env"
bedrock_access_variant = "aws_access"
diff --git a/pipelex/migration/goldens/pipelex-config/[email protected] b/pipelex/migration/goldens/pipelex-config/[email protected]
index cfe308d3e..7eebe7542 100644
--- a/pipelex/migration/goldens/pipelex-config/[email protected]
+++ b/pipelex/migration/goldens/pipelex-config/[email protected]
@@ -1128,6 +1128,23 @@
"default": "rich",
"open_node": false
},
+ "runtime.log.redaction": {
+ "value_type": "table",
+ "required": true,
+ "open_node": false
+ },
+ "runtime.log.redaction.extra_patterns": {
+ "value_type": "list[str]",
+ "required": true,
+ "default": [],
+ "open_node": false
+ },
+ "runtime.log.redaction.is_enabled": {
+ "value_type": "bool",
+ "required": true,
+ "default": true,
+ "open_node": false
+ },
"runtime.log.rich_log": {
"value_type": "table",
"required": true,
diff --git a/pipelex/pipelex.toml b/pipelex/pipelex.toml
index 3fb0bd507..6140d1296 100644
--- a/pipelex/pipelex.toml
+++ b/pipelex/pipelex.toml
@@ -105,6 +105,18 @@ keywords_to_hilight = []
[runtime.log.otlp]
headers = {}
+# [runtime.log.redaction] governs the one processor every sink is behind: it scrubs the secret shapes
+# the workspace already knows (an Authorization bearer token, an api-key or signature header, an OAuth
+# code parameter, a cookie, a JSON secret entry, and the sk_ / plx_sk_ / pk_ / bl_ key prefixes) out of
+# the message and out of every string a field carries, and neutralises the control characters in a
+# field value so a caller-supplied string cannot forge a line or a field separator. is_enabled = false
+# turns it off for a process that redacts downstream. extra_patterns are regular expressions added to
+# the shipped families for the secret shapes only this deployment knows; every match is replaced by
+# "[REDACTED]", and a pattern the re module refuses is a configuration error named at load.
+[runtime.log.redaction]
+is_enabled = true
+extra_patterns = []
+
[runtime.aws]
api_key_method = "env"
bedrock_access_variant = "aws_access"
diff --git a/pipelex/tools/log/log.py b/pipelex/tools/log/log.py
index 554eb604a..bd2f43835 100644
--- a/pipelex/tools/log/log.py
+++ b/pipelex/tools/log/log.py
@@ -9,6 +9,8 @@ from pipelex.tools.log.log_context import bind_log_context
from pipelex.tools.log.log_dispatch import LogDispatch
from pipelex.tools.log.log_holding import ForwardedRecordFilter, HoldingLogHandler
from pipelex.tools.log.log_levels import LOGGING_LEVEL_DEV, LOGGING_LEVEL_OFF, LOGGING_LEVEL_VERBOSE, LogLevel
+from pipelex.tools.log.log_redaction import make_redaction_processor
+from pipelex.tools.log.log_sink import ProcessorFilter
if TYPE_CHECKING:
from collections.abc import Callable, Mapping
@@ -16,7 +18,7 @@ if TYPE_CHECKING:
from pipelex.tools.log.log_config import LogConfig
from pipelex.tools.log.log_context import LogContext
- from pipelex.tools.log.log_sink import LogSink
+ from pipelex.tools.log.log_sink import LogRecordProcessor, LogSink
def _finish_teardown_step(*, sink: LogSink, verb: str, step: Callable[[], None]) -> None:
@@ -57,6 +59,8 @@ class Log:
self._log_config_instance: LogConfig | None = None
self._holding_handler: HoldingLogHandler | None = None
self._sink: LogSink | None = None
+ # The redaction processor ``install_sink`` put on the sink, so ``reset`` can take it back.
+ self._redaction_processor: LogRecordProcessor | None = None
self.log_dispatch: LogDispatch = LogDispatch()
@property
@@ -76,9 +80,13 @@ class Log:
holds, and nothing that flush or close raises escapes: this runs first in the runtime's release
of its process globals, and an error out of it would skip the rest and leave the process
unbootable. The close runs whatever the flush did, since the close is what stops an exporter's
- thread, ships its last batch and unregisters what it put at exit. A holding handler still in
- place, because the boot died before its sink arrived, is closed too, and what it holds gets the
- stdlib's last-resort handling.
+ thread, ships its last batch and unregisters what it put at exit. The redaction processor
+ ``install_sink`` put on the sink is taken back and the closed handler is discarded, so a sink
+ object installed again carries the next configuration's processor and not two, and builds itself
+ a live handler rather than being handed back the one this close just finished with. A holding
+ handler still in place, because the boot died before its sink arrived, is closed too, and what
+ it holds gets the stdlib's last-resort handling once the redaction ``configure`` gave it has run
+ over each record.
"""
root_logger = logging.getLogger()
try:
@@ -90,6 +98,8 @@ class Log:
_finish_teardown_step(sink=sink, verb="flush", step=handler.flush)
finally:
_finish_teardown_step(sink=sink, verb="close", step=handler.close)
+ self._take_back_redaction_processor(sink=sink)
+ sink.discard_handler()
if self._holding_handler is not None:
holding, self._holding_handler = self._holding_handler, None
root_logger.removeHandler(holding)
@@ -141,19 +151,40 @@ class Log:
# every record is held, so nothing a boot says is lost or written in a shape nothing chose.
root_logger = logging.getLogger()
root_logger.setLevel(log_config.default_log_level.int_logging_level)
- self._holding_handler = HoldingLogHandler()
+ # A boot that dies before its sink arrives hands what was held to the stdlib's last resort, and
+ # those records meet the redaction there as they would have met it on the sink's handler, behind
+ # the same guard: a failed boot is the one moment the trail on stderr is read line by line.
+ last_resort_filter = None
+ if log_config.redaction.is_enabled:
+ last_resort_filter = ProcessorFilter(processors=[make_redaction_processor(config=log_config.redaction)])
+ self._holding_handler = HoldingLogHandler(last_resort_filter=last_resort_filter)
root_logger.addHandler(self._holding_handler)
self.set_levels_for_packages(package_log_levels=log_config.package_log_levels)
self.verbose("Logs configured and config set")
+ def _take_back_redaction_processor(self, *, sink: LogSink) -> None:
+ """Remove from the sink the processor ``install_sink`` put there, so a sink installed again carries the next configuration's alone.
+
+ Guarded, since a sink is free to have replaced its list; a processor that is no longer there is nothing to take back.
+ """
+ processor, self._redaction_processor = self._redaction_processor, None
+ if processor is None:
+ return
+ with contextlib.suppress(ValueError):
+ sink.processors.remove(processor)
+
def install_sink(self, sink: LogSink):
"""Put the sink's handler on the root logger and replay through it every record held since ``configure``.
The handler is built here, so a sink whose dependency is missing fails at this call, at boot,
with the extra named. Once per configuration: a second sink is refused, as a second ``configure`` is.
+ The redaction processor is put in front of the sink's own processors here rather than by each
+ sink, so every sink gets it, the built-in ones, an out-of-tree one and the console sink the
+ doctor falls back to alike, and none of them knows about it.
+
Raises:
RuntimeError: If logging is not configured, or a sink is already installed.
MissingDependencyError: If the sink's handler needs a package that is not installed.
@@ -166,7 +197,22 @@ class Log:
msg = "A log sink is already installed. You can only call log.install_sink() once per configuration."
raise RuntimeError(msg)
- handler = sink.handler
+ redaction = self._log_config_instance.redaction
+ if redaction.is_enabled:
+ # Ahead of whatever the sink appended, so a processor that renders or enriches a record
+ # works on one the secrets have already left. A processor that adds a secret of its own
+ # after the scrub is that sink's to answer for. Remembered, so ``reset`` takes it back off a
+ # sink object a caller installs again.
+ self._redaction_processor = make_redaction_processor(config=redaction)
+ sink.processors.insert(0, self._redaction_processor)
+
+ try:
+ handler = sink.handler
+ except BaseException:
+ # The sink is not recorded when its handler fails to build, so ``reset`` would never reach it:
+ # the processor comes back off here, or the same sink installed again carries two.
+ self._take_back_redaction_processor(sink=sink)
+ raise
# Ahead of every other filter, so the sink's processors never run on a record it rejects.
handler.filters.insert(0, ForwardedRecordFilter())
root_logger = logging.getLogger()
diff --git a/pipelex/tools/log/log_config.py b/pipelex/tools/log/log_config.py
index a32629f52..d42123b1b 100644
--- a/pipelex/tools/log/log_config.py
+++ b/pipelex/tools/log/log_config.py
@@ -1,5 +1,6 @@
from __future__ import annotations
+import re
from enum import StrEnum
from typing import cast
@@ -76,6 +77,43 @@ class OtlpLogSinkConfig(ConfigModel):
headers: dict[str, str]
+class LogRedactionConfig(ConfigModel):
+ """What the redaction processor removes from a record before any sink renders it.
+
+ ``is_enabled`` turns the processor off for a process that redacts downstream, or one whose records
+ must be reproduced exactly as the call made them. ``extra_patterns`` are regular expressions a
+ deployment adds to the shipped families, for the secret shapes only it knows: every match is
+ replaced by the redaction text. A pattern the ``re`` module refuses is a configuration error named
+ at load rather than a boot that dies later on a regex nobody can see, and so is one that matches the
+ empty string, which is a typo away from any quantifier and destroys every line the process writes.
+ """
+
+ is_enabled: bool
+ extra_patterns: list[str]
+
+ @field_validator("extra_patterns")
+ @classmethod
+ def validate_extra_patterns(cls, value: list[str]) -> list[str]:
+ for pattern in value:
+ try:
+ compiled = re.compile(pattern)
+ except re.error as exc:
+ msg = f"extra_patterns under [runtime.log.redaction] holds a regular expression the re module refuses: '{pattern}' ({exc})"
+ raise ValueError(msg) from exc
+ if compiled.match("") is not None:
+ # ``x*`` for ``x+`` is the whole of it: a pattern that matches nothing matches at every
+ # position, so the substitution writes the redaction text between every two characters
+ # of every message and every field value, for the life of the process. Named here, where
+ # the pattern is still in front of whoever typed it.
+ msg = (
+ f"extra_patterns under [runtime.log.redaction] holds a regular expression that matches the empty string: '{pattern}'. "
+ "It would match at every position of every log line and replace the whole of it with the redaction text. "
+ "A quantifier that admits zero repetitions is the usual cause: write '+' where you wrote '*'."
+ )
+ raise ValueError(msg)
+ return value
+
+
class LogConfig(ConfigModel):
default_log_level: LogLevel = Field(strict=False)
package_log_levels: dict[str, LogLevel]
@@ -92,6 +130,7 @@ class LogConfig(ConfigModel):
silenced_problem_ids: list[str]
+ redaction: LogRedactionConfig
rich_log: RichLogConfig
otlp: OtlpLogSinkConfig
diff --git a/pipelex/tools/log/log_dispatch.py b/pipelex/tools/log/log_dispatch.py
index 561dc11fa..805849d2a 100644
--- a/pipelex/tools/log/log_dispatch.py
+++ b/pipelex/tools/log/log_dispatch.py
@@ -19,6 +19,7 @@ from typing import TYPE_CHECKING, Any, cast
from pipelex.tools.log.log_config import CallerInfoTemplate, LogConfig
from pipelex.tools.log.log_context import get_log_context
from pipelex.tools.log.log_fields import attach_log_record_extra, build_log_record_extra
+from pipelex.tools.log.log_redaction import redact_secret_entries
from pipelex.tools.misc.json_utils import purify_json, purify_json_dict, purify_json_list
if TYPE_CHECKING:
@@ -174,10 +175,25 @@ class LogDispatch:
# given, and a sink that serializes later would read whatever the caller did to it since. The
# data is therefore the rendering re-read: a snapshot of the call, JSON-ready whatever it held.
data = json.loads(rendered)
+ if log_config is not None and log_config.redaction.is_enabled:
+ # Redacted by name before the message is settled, because the message is this rendering and
+ # the redaction processor reads it as text: an entry named like a secret whose value is an
+ # object or a number would keep its value there while ``data`` lost it. Rendered again only
+ # when an entry was replaced, so every other line keeps the helpers' own rendering.
+ redacted = redact_secret_entries(value=data)
+ if redacted != data:
+ data = redacted
+ rendered = json.dumps(redacted, indent=indent)
except (TypeError, ValueError):
# What ``json`` refuses outright, a circular reference or a mapping with a non-string key,
- # is rendered as its ``repr`` and carries no ``data``: a log call never raises.
- rendered = repr(cast("object", content))
+ # is rendered as its ``repr`` and carries no ``data``: a log call never raises. The names
+ # are redacted on this path too, and not only where the serialization worked: the ``repr``
+ # of an entry holding an object is beyond what the string families can read back out of
+ # text, so a fallback that skipped it would be the one rendering in which a secret the
+ # redaction is configured to remove reaches the sink whole.
+ is_redacting = log_config is not None and log_config.redaction.is_enabled
+ fallback = cast("object", redact_secret_entries(value=content) if is_redacting else content)
+ rendered = repr(fallback)
data = None
message = f"\n{rendered}"
if title is not None:
diff --git a/pipelex/tools/log/log_fields.py b/pipelex/tools/log/log_fields.py
index a5d288763..016df9cd1 100644
--- a/pipelex/tools/log/log_fields.py
+++ b/pipelex/tools/log/log_fields.py
@@ -46,9 +46,20 @@ FORWARDED_MARK = "_pipelex_forwarded"
# wire, and reserving it is what stops a caller steering the console through a field of that name.
VERBATIM_MARK = "markup"
+# The attribute the redaction stamps on a record it could not strip, and takes back off the moment it
+# has. It is the fail-closed half of the scrub: a record still carrying it reaches no sink, because what
+# it carries is whatever the call put there and the scrub never read. It is set before the stripping
+# rather than after the failure, so a stripping that dies partway leaves it behind rather than needing a
+# second thing to go right at the moment the first one went wrong.
+UNSCRUBBED_MARK = "_pipelex_unscrubbed"
+
# The names this package stamps on a record itself. Never a field: a caller's entry of the same name is
# prefixed on the way on, and a record carrying one does not hand it to a sink as something it carries.
-PIPELEX_OWNED_ATTRIBUTES = frozenset({FORWARDED_MARK, VERBATIM_MARK})
+# Reserving them is what makes each one safe, because each is stamped later than the entries are attached
+# and so a fresh record owns none of them: a caller's field spelling ``FORWARDED_MARK`` would be read as
+# the forwarding marker and cost the whole record its delivery, and one spelling ``UNSCRUBBED_MARK`` would
+# have a perfectly ordinary record read as one the scrub could not strip, and dropped.
+PIPELEX_OWNED_ATTRIBUTES = frozenset({FORWARDED_MARK, VERBATIM_MARK, UNSCRUBBED_MARK})
# Reserved whether or not the record carries the name yet, which is exactly what the stdlib's own refusal
# cannot cover: both sets are stamped after the entries are attached.
@@ -74,22 +85,27 @@ def build_log_record_extra(
"""The ``extra`` for one record, in precedence order: the bound context, then the call's fields, then the content.
A field overrides the context for its record, so a call site that names a request it is not running
- under can say so. Structured content owns the ``data`` name, and a field of that name is moved aside
+ under can say so. The ``data`` name is the dispatch's own, and a field spelled that way is moved aside
under the ``field_`` prefix rather than destroyed — the same discipline the record's own attributes
and every wire sink's reserved keys follow, applied until the name lands where nothing sits, so a call
passing both ``data`` and ``field_data`` beside structured content loses neither.
+
+ The move happens whether or not this call has structured content to put there. Owning the name only
+ when the content happens to be structured would leave a caller's ``data`` on the record's own ``data``
+ beside a string content — where the runtime treats it as its own rendering and hands it to a sink
+ with its control characters intact, which is exactly the forged line the escaping exists to stop.
"""
extra: dict[str, Any] = {}
if context is not None:
extra.update(context.fields)
if fields:
extra.update(fields)
+ if DATA_FIELD in extra:
+ displaced = f"{COLLIDING_FIELD_PREFIX}{DATA_FIELD}"
+ while displaced in extra:
+ displaced = f"{COLLIDING_FIELD_PREFIX}{displaced}"
+ extra[displaced] = extra.pop(DATA_FIELD)
if data is not None:
- if DATA_FIELD in extra:
- displaced = f"{COLLIDING_FIELD_PREFIX}{DATA_FIELD}"
- while displaced in extra:
- displaced = f"{COLLIDING_FIELD_PREFIX}{displaced}"
- extra[displaced] = extra[DATA_FIELD]
extra[DATA_FIELD] = data
return extra
diff --git a/pipelex/tools/log/log_holding.py b/pipelex/tools/log/log_holding.py
index 5ba8c6745..ad3924b82 100644
--- a/pipelex/tools/log/log_holding.py
+++ b/pipelex/tools/log/log_holding.py
@@ -7,7 +7,8 @@ rendered by the sink the configuration chose rather than dropped or written in a
A boot that dies before a sink arrives closes this handler, and what it still holds reaches stderr
through the stdlib's last resort — every record of it, since the root logger's level already admitted
them and that level came from the configuration, so each held line is one this process was asked to
-show. A boot that failed is when that trail is worth most.
+show. A boot that failed is when that trail is worth most, and the redaction the sink would have run
+over each of those records runs over it on that path too.
"""
from __future__ import annotations
@@ -60,12 +61,20 @@ def _deliver(*, handler: logging.Handler, record: logging.LogRecord) -> None:
class HoldingLogHandler(logging.Handler):
- """Holds every record it is handed until a sink's handler takes them over, then forwards to that handler."""
+ """Holds every record it is handed until a sink's handler takes them over, then forwards to that handler.
- def __init__(self) -> None:
+ ``last_resort_filter`` is what a held record passes through on its way to the stdlib's last resort,
+ when the handler closes with records still held: the redaction a sink's handler would have run over
+ it, behind the same guard. A record it rejects is not written. It runs there and nowhere else, since
+ a record released to a sink meets the sink's own processors, and a second pass would escape its
+ control characters twice.
+ """
+
+ def __init__(self, *, last_resort_filter: logging.Filter | None = None) -> None:
super().__init__(level=logging.NOTSET)
self._held: list[logging.LogRecord] = []
self._released_to: logging.Handler | None = None
+ self._last_resort_filter = last_resort_filter
@property
def held_count(self) -> int:
@@ -116,7 +125,9 @@ class HoldingLogHandler(logging.Handler):
records passed the root logger's level, which ``configure`` set from the configuration, so each one
is a line this process was asked to show. The only moment this runs with anything still held is a
boot that died before its sink arrived, which is exactly when the trail a verbose run was turned on
- to produce is the thing being looked for.
+ to produce is the thing being looked for. Each one passes the last-resort filter first, so a secret
+ a held line quoted is scrubbed on this path as it would have been by the sink, and a record the
+ filter rejects, one the redaction could neither scrub nor strip, is not written.
"""
self.acquire()
try:
@@ -126,5 +137,7 @@ class HoldingLogHandler(logging.Handler):
last_resort = logging.lastResort
if last_resort is not None:
for record in held:
+ if self._last_resort_filter is not None and not self._last_resort_filter.filter(record):
+ continue
last_resort.handle(record)
super().close()
diff --git a/pipelex/tools/log/log_redaction.py b/pipelex/tools/log/log_redaction.py
new file mode 100644
index 000000000..e8f6933d4
--- /dev/null
+++ b/pipelex/tools/log/log_redaction.py
@@ -0,0 +1,447 @@
+"""Secret scrubbing and injection-safe field values, in one processor that runs before any sink renders.
+
+Two distinct removals, on two distinct parts of a record.
+
+**Secrets are scrubbed** from the message, from the exception's rendered text and from every string
+a field carries. The pattern families are the ones the workspace already wrote twice: the hosted
+plane's Lambdas ran them over their own records, which is where the bearer tokens, the api-key and
+signature headers, the OAuth ``code`` parameter, the cookies, the JSON secret fields and the key
+prefixes come from. Running them here instead means every Pipelex process gets them, whichever sink
+it selected, and a record a third-party library emitted with a raw request in it is scrubbed too,
+because the processor sits on the sink's handler rather than at the call sites. A structured value is
+walked to any depth: a mapping entry named like a secret loses its value whatever it holds, since the
+mapping split the name from the value the string families read together, and so does a field whose own
+name is a secret's; a model is dumped and any other object rendered as text before the walk, exactly as
+a wire sink would have done after it, and one that refuses to render loses that value alone. A
+structured content is redacted by name before the dispatch renders it, so the message a sink writes
+beside ``data`` is the rendering of what ``data`` holds rather than a second copy of the secret.
+
+**Control characters are neutralised** in a field's string values, and only there. A field value is
+caller-supplied text, and a sink that writes a ``key=value`` run or a console line renders it as it is,
+so a newline in it forges a line and a tab forges a separator; an escape byte forges colour on a
+terminal. Each becomes its printable escape, the way ``pipelex-api`` escaped the values it flattened
+into a log line. The **message** and the **data** attribute keep their control characters, because
+they are the runtime's own rendering and not a caller's string: a titled call and a structured content
+both put a newline there deliberately, the wire sinks escape ``data`` themselves, and escaping it here
+would turn a logged prompt's newlines into text no consumer can tell from a typed backslash.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Any, cast
+
+from pydantic import BaseModel
+
+from pipelex.tools.log.log_fields import COLLIDING_FIELD_PREFIX, DATA_FIELD, UNSCRUBBED_MARK, carried_attributes
+
+if TYPE_CHECKING:
+ from collections.abc import Sequence
+
+ from pipelex.tools.log.log_config import LogRedactionConfig
+ from pipelex.tools.log.log_sink import LogRecordProcessor
+
+# What a scrubbed secret is replaced by, everywhere: the line stays readable and says what was removed.
+REDACTED_TEXT = "[REDACTED]"
+
+# What a container that contains itself is cut at: the walk ends there, and the sink meets a marker
+# rather than the raw container whose strings the scrub never reached.
+CYCLE_TEXT = "[cycle]"
+
+# What the message of a record whose scrub failed becomes, followed by the name of what was raised and
+# a closing bracket: the sink writes a line that says the scrub failed, and nothing of the call.
+QUARANTINE_PREFIX = "[REDACTION FAILED: "
+
+# What a value that refuses to render becomes, followed by the name of what was raised and a closing
+# bracket: that one value is lost, and the record and every other value it carries are handed on.
+UNRENDERABLE_PREFIX = "[UNRENDERABLE: "
+
+# What follows the format string of a record whose arguments do not fit it, in place of the arguments:
+# the stdlib's own report of that failure prints them raw, which is exactly what the scrub removes.
+ARGUMENTS_WITHHELD_TEXT = "[ARGUMENTS WITHHELD: the message could not be rendered]"
+
+# The names under which a mapping entry is a secret whatever it holds, read lowercased and with a dash
+# as an underscore, so a header name and a JSON key are both caught. ``code`` is not among them: it is
+# the runtime's own identifier for a pipe, a domain and an error, and the OAuth code has its own family.
+SECRET_KEY_NAMES = frozenset(
+ {
+ "password",
+ "pipelex_api_key",
+ "gateway_api_key",
+ "jwt_secret_key",
+ "portkey_api_key",
+ "client_secret",
+ "access_token",
+ "refresh_token",
+ "id_token",
+ "authorization",
+ "api_key",
+ "x_api_key",
+ "x_signature",
+ "x_completion_signature",
+ "cookie",
+ "set_cookie",
+ }
+)
+
+# One compiled pattern and the text that replaces what it matched, a back-reference keeping whatever
+# named the secret so a reader still sees which header or which field was carrying it.
+RedactionPattern = tuple[re.Pattern[str], str]
+
+# A quoted entry name whose value is a secret whatever it holds, and what introduces the value: the
+# names a mapping key is read against, with a dash or an underscore wherever the name has an underscore
+# and in any case, so a serialised object and a mapping key are judged by the same list.
+_SECRET_ENTRY_NAMES = "|".join(sorted(re.escape(name).replace("_", "[-_]") for name in SECRET_KEY_NAMES))
+_SECRET_ENTRY_KEY = rf"[\"'](?:{_SECRET_ENTRY_NAMES})[\"']\s*:\s*"
+
+# What a secret's value looks like once something has named it: the characters a token, a key, a hash or
+# a percent-encoded parameter is written in, and at least eight of them. The bound is what keeps these
+# families off ordinary prose, where a name followed by a colon is a sentence rather than a header; a
+# secret shorter than it is below what the shipped families read at all, in this repo as in the hosted
+# plane's scrubber they were ported from.
+_SECRET_VALUE = r"[A-Za-z0-9._\-~+/=%]{8,}"
+
+# A cookie header's value, in the grammar RFC 6265 gives it rather than as a run to the end of the line.
+# The first crumb must be ``name=value``, which is what tells a header from prose that merely says
+# "cookie:" before a sentence; the value is either double-quoted, or a run holding no quote, no comma
+# and no semicolon, which is exactly what the RFC admits, so a value holding an apostrophe is read whole
+# and one holding a double quote is read to its closing quote. The crumbs and flag attributes after the
+# first are taken with it, so the whole header goes and not only its first cookie.
+_COOKIE_VALUE = r"(?:\"[^\"\r\n]*\"|[^\s;,\"\r\n]*)"
+_COOKIE_RUN = rf"[^\s;=,\"\r\n]+={_COOKIE_VALUE}(?:\s*;\s*[^\s;=,\"\r\n]+(?:={_COOKIE_VALUE})?)*"
+
+# The shipped families, in the order they run. Ported from the hosted plane's own scrubber; a family
+# is written to name the secret's carrier in the same string as the secret, which is what a header
+# line, a query string or a serialised JSON object gives it.
+SECRET_PATTERNS: tuple[RedactionPattern, ...] = (
+ # An Authorization header, whichever scheme it carries. The schemes are named rather than read as
+ # "whatever word follows", because the header name introduces its value with whitespace as readily
+ # as with a colon, and a pattern taking any word there redacts the next word of a sentence that
+ # merely says "authorization". The scheme is kept, being what tells a reader which credential went.
+ (re.compile(rf"(?i)(authorization[\"'\s:=]+(?:bearer|basic|token|digest|negotiate|hmac)\s+)({_SECRET_VALUE})"), rf"\1{REDACTED_TEXT}"),
+ # An api-key header or entry, however it is spelled: x-api-key, api-key, api_key.
+ (re.compile(rf"(?i)([\"']?x?-?api[_-]key[\"']?\s*[:=]\s*[\"']?)({_SECRET_VALUE})"), rf"\1{REDACTED_TEXT}"),
+ # A webhook signature header: x-signature, x-completion-signature.
+ (re.compile(rf"(?i)([\"']?x-(?:completion-)?signature[\"']?\s*[:=]\s*[\"']?)({_SECRET_VALUE})"), rf"\1{REDACTED_TEXT}"),
+ # An OAuth authorization code in a query string, read to the delimiter that ends the parameter
+ # rather than through an alphabet of its own: a code is routinely percent-encoded, and a class that
+ # stops at the escape leaves the tail behind — or the whole code, when the escape falls early enough
+ # that what precedes it is shorter than the minimum length.
+ (re.compile(r"(?i)([?&]code=)([^&#\s\"'\r\n]{8,})"), rf"\1{REDACTED_TEXT}"),
+ # The serialised entries that are a secret whatever they hold, a JSON object and a Python ``repr``
+ # alike. A quoted value is read up to the same quote that opened it, whichever quoted the name, with
+ # a backslash escape honoured, so a value holding the other quote character or an escaped one is
+ # removed whole; a number or a boolean is removed as the bare token it is. A nested object or list
+ # is beyond a pattern, which is why a structured content is redacted by name before it is rendered.
+ # ``code`` is not among the names: it is the runtime's own identifier for a pipe, a domain and an
+ # error, and the OAuth code has the query-string family above. These run before the raw-header
+ # families below, so a header serialised as an entry is removed as an entry, quotes and all, and a
+ # raw-header family never reads into the JSON punctuation around it.
+ (re.compile(rf'(?i)({_SECRET_ENTRY_KEY}")((?:\\.|[^"\\])+)(")'), rf"\1{REDACTED_TEXT}\3"),
+ (re.compile(rf"(?i)({_SECRET_ENTRY_KEY}')((?:\\.|[^'\\])+)(')"), rf"\1{REDACTED_TEXT}\3"),
+ (re.compile(rf"(?i)({_SECRET_ENTRY_KEY})(-?\d[\w.+-]*|true|false)(?![\w.+-])"), rf"\1{REDACTED_TEXT}"),
+ # A raw cookie header's whole value, every crumb and every flag attribute of it. The value has to be
+ # a cookie header's own ``name=value`` grammar, which is what separates a header from prose: a
+ # sentence that merely says "cookie:" or "cookie=" before ordinary words is left alone, where a run
+ # to the end of the line destroyed the rest of it — the secret a later word carried among it.
+ (re.compile(rf"(?i)\b((?:set-)?cookie[\"']?\s*[:=]\s*[\"']?)({_COOKIE_RUN})"), rf"\1{REDACTED_TEXT}"),
+ # The same secret names again, named in the plain ``name=value`` or ``name: value`` form a query
+ # string, a form-encoded body or a header line writes them in. The entry families above read them
+ # only when something quoted the name, which is the serialised shape and not the shape a raw request
+ # reaches this processor in. The colon or the equals sign is required and the value must be at least
+ # eight characters of what a secret is written in, which is what keeps this off ordinary prose.
+ (re.compile(rf"(?i)((?:{_SECRET_ENTRY_NAMES})\s*[:=]\s*)({_SECRET_VALUE})"), rf"\1{REDACTED_TEXT}"),
+ # A key recognisable by its prefix alone, wherever it appears and whatever introduced it. The
+ # prefix is spelled with a dash as with an underscore, since that is how the keys in use are
+ # actually issued, and what follows it has to end in a long unbroken run of letters and digits: an
+ # ordinary snake_case identifier — a table, a column, a partition — is words all the way down, and
+ # a family reading the prefix alone redacted those. The prefix is kept, as every other family keeps
+ # what named the secret, so a reader still sees which kind of key was carried.
+ (re.compile(r"\b((?:plx[_-]sk|sk|pk|bl)[_-])((?:[A-Za-z0-9]{1,8}[_-]){0,2}[A-Za-z0-9]{16,})(?![A-Za-z0-9])"), rf"\1{REDACTED_TEXT}"),
+)
+
+# Every C0 and C1 control character, the DEL byte included. A newline or a tab forges a line or a field
+# separator in a text sink, and an escape byte forges colour and cursor moves on a terminal.
+CONTROL_CHARACTERS = re.compile(r"[\x00-\x1f\x7f-\x9f]")
+
+# The escapes a reader recognises, for the three control characters that have a spelling of their own.
+_NAMED_ESCAPES = {"\n": "\\n", "\r": "\\r", "\t": "\\t"}
+
+# The stdlib's own rendering of an exception, chain included, which is what ``Formatter.format`` would
+# have put in ``exc_text`` had the processor not got there first.
+_EXCEPTION_FORMATTER = logging.Formatter()
+
+
+def _escaped_control_character(match: re.Match[str]) -> str: # kw-only: ignore — ``re.sub`` calls its replacement positionally
+ """The printable spelling of one control character: its named escape, or its hexadecimal one."""
+ character = match.group()
+ return _NAMED_ESCAPES.get(character) or f"\\x{ord(character):02x}"
+
+
+def scrub_secrets(*, text: str, patterns: tuple[RedactionPattern, ...] = SECRET_PATTERNS) -> str:
+ """Run every pattern over a string. Idempotent: a string already scrubbed comes back unchanged."""
+ for pattern, replacement in patterns:
+ text = pattern.sub(replacement, text)
+ return text
+
+
+def escape_control_characters(*, text: str) -> str:
+ """The string with every control character replaced by its printable escape, and nothing else moved.
+
+ Only the control characters move: accented text, CJK and emoji are left as they are, because the
+ point is to stop a caller forging a line, not to reduce a value to ASCII.
+ """
+ return CONTROL_CHARACTERS.sub(_escaped_control_character, text)
+
+
+def make_redaction_processor(*, config: LogRedactionConfig) -> LogRecordProcessor:
+ """One processor for the sink seam, carrying the shipped families and whatever the configuration added.
+
+ The patterns are compiled once, here, rather than on every record: a processor runs on the calling
+ thread of every log call in the process.
+ """
+ patterns = SECRET_PATTERNS + tuple((re.compile(extra), REDACTED_TEXT) for extra in config.extra_patterns)
+
+ def redact(record: logging.LogRecord) -> None: # kw-only: ignore — the sink seam calls a processor positionally
+ try:
+ _redact_record(record=record, patterns=patterns)
+ except Exception as exc:
+ # Fails closed, in two steps that do not depend on each other. The mark goes on first, by
+ # assignment into the record's own dictionary, which needs no call and no frame: whatever
+ # happens next, the guard on the sink's handler has been told not to hand this record on.
+ # Then the strip, which turns the record into a notice and lifts the mark when it gets all
+ # the way through. It is the strip that can fail a second time — the failure that brings us
+ # here is routinely a stack that has run out, and a stack that cannot take ``_redact_record``
+ # cannot always take the stripping of what it left behind either.
+ record.__dict__[UNSCRUBBED_MARK] = True
+ _quarantine(record=record, exc=exc)
+ raise
+
+ return redact
+
+
+def _quarantine(*, record: logging.LogRecord, exc: Exception) -> None:
+ """Strip a record whose scrub failed down to a notice naming the failure, so nothing unscrubbed leaves with it.
+
+ The mark ``redact`` set is lifted at the end and only there, so a strip that gets partway leaves the
+ record marked and the record is dropped rather than emitted as a notice that says it was stripped
+ while still carrying what the scrub never read.
+ """
+ record.msg = f"{QUARANTINE_PREFIX}{type(exc).__name__}]"
+ record.args = ()
+ record.exc_info = None
+ record.exc_text = None
+ record.stack_info = None
+ for name in carried_attributes(record=record):
+ setattr(record, name, REDACTED_TEXT)
+ record.__dict__.pop(UNSCRUBBED_MARK, None)
+
+
+def _redact_record(*, record: logging.LogRecord, patterns: tuple[RedactionPattern, ...]) -> None:
+ """Scrub the record's message and its exception text, and scrub and neutralise every string the record carries."""
+ message = _rendered_message(record=record)
+ if message is None:
+ _withhold_arguments(record=record, patterns=patterns)
+ else:
+ scrubbed = scrub_secrets(text=message, patterns=patterns)
+ if scrubbed != message:
+ # The rendering replaces the format string and its arguments, because that is where the
+ # secret was: a handler reading ``getMessage`` afterwards gets the scrubbed text, and one
+ # reading ``msg`` gets it too rather than the template the arguments would fill back in.
+ record.msg = scrubbed
+ record.args = ()
+ _redact_exception_text(record=record, patterns=patterns)
+ for name, value in carried_attributes(record=record).items():
+ # A field whose own name is a secret's loses its value whatever it holds, exactly as a mapping
+ # entry does. ``data`` keeps its control characters for the reason the message does: it is the
+ # runtime's own rendering of the caller's object, and the wire sinks escape it themselves.
+ setattr(
+ record,
+ name,
+ REDACTED_TEXT
+ if _is_secret_field_name(name=name)
+ else _clean_value(value=value, patterns=patterns, open_containers=set(), is_escaping_control_characters=name != DATA_FIELD),
+ )
+
+
+def _is_secret_field_name(*, name: str) -> bool:
+ """Whether the name a field is carried under is a secret's, read with every collision prefix taken off first.
+
+ A field lands under a prefixed name whenever the record already owns the name the caller used, and a
+ record factory that stamps ``password`` is enough to do it — so the name reaching a sink is
+ ``field_password`` while the value under it is exactly the one the caller asked to have redacted.
+ Judging the name as it was spelled rather than as it was carried covers that, and covers a caller who
+ spelled the prefix themselves, which is the safe direction to be wrong in.
+ """
+ while name.startswith(COLLIDING_FIELD_PREFIX):
+ name = name[len(COLLIDING_FIELD_PREFIX) :]
+ return _is_secret_key(key=name)
+
+
+def _redact_exception_text(*, record: logging.LogRecord, patterns: tuple[RedactionPattern, ...]) -> None:
+ """Render the exception the stdlib way, scrubbed, into ``exc_text``, where every formatter reads it first.
+
+ ``Formatter.format`` renders ``exc_info`` into ``exc_text`` lazily and only when it is not already
+ there, and the ``json`` sink reads it the same way, so a rendering put there before any sink runs
+ is the one they all write. The exception object itself stays on the record, since a rendering can
+ be scrubbed and an exception cannot; a sink that renders from the object rather than the text, the
+ console's Rich traceback, is outside what this covers. A stack summary the call asked for rides
+ ``stack_info`` as text already and is scrubbed in place.
+ """
+ if record.exc_text:
+ record.exc_text = scrub_secrets(text=record.exc_text, patterns=patterns)
+ elif record.exc_info:
+ record.exc_text = scrub_secrets(text=_EXCEPTION_FORMATTER.formatException(record.exc_info), patterns=patterns)
+ if record.stack_info:
+ record.stack_info = scrub_secrets(text=record.stack_info, patterns=patterns)
+
+
+def _rendered_message(*, record: logging.LogRecord) -> str | None:
+ """The record's message as a handler would render it, or ``None`` when it cannot be rendered.
+
+ ``getMessage`` interpolates the call's arguments, which is where a third-party library puts the
+ value its format string names, so the secret is usually in the rendering rather than in ``msg``.
+ A record whose arguments do not match its format string raises there, and ``_withhold_arguments``
+ decides what it becomes.
+ """
+ try:
+ return record.getMessage()
+ except Exception: # ruff: ignore[blind-except]
+ return None
+
+
+def _withhold_arguments(*, record: logging.LogRecord, patterns: tuple[RedactionPattern, ...]) -> None:
+ """Replace the arguments of a record whose message cannot be rendered by a notice, after its scrubbed format string.
+
+ Left as it was, the record would fail again in the handler, and the stdlib's report of that failure
+ prints the format string and every argument to stderr as they are, the value a secret pattern would
+ have removed among them. With no arguments the stdlib renders the format string as it stands, so the
+ line still says which call it was; a format string that cannot even be read as text is dropped too.
+ """
+ try:
+ template = scrub_secrets(text=str(record.msg), patterns=patterns)
+ except Exception: # ruff: ignore[blind-except]
+ record.msg = ARGUMENTS_WITHHELD_TEXT
+ else:
+ record.msg = f"{template} {ARGUMENTS_WITHHELD_TEXT}"
+ record.args = ()
+
+
+def redact_secret_entries(*, value: Any, open_containers: set[int] | None = None) -> Any:
+ """A JSON-ready value with every mapping entry named like a secret replaced by the redaction text, at any depth.
+
+ For a structured content, before the dispatch renders it: the message it writes is that rendering,
+ and a secret nested in an object or held as a number is beyond what the string families can read
+ back out of text. What comes back is a new value wherever an entry was replaced, and the value
+ itself otherwise.
+
+ A container that contains itself is cut at the cycle, exactly as the field walk cuts one. The walk
+ has to survive a cycle because the caller that needs it most is the one rendering content ``json``
+ has just refused, and a circular reference is the commonest reason it refuses.
+ """
+ if open_containers is None:
+ open_containers = set()
+ container_id = id(value)
+ if isinstance(value, Mapping):
+ if container_id in open_containers:
+ return CYCLE_TEXT
+ mapping = cast("Mapping[Any, Any]", value)
+ open_containers.add(container_id)
+ try:
+ return {
+ key: REDACTED_TEXT if _is_secret_key(key=key) else redact_secret_entries(value=item, open_containers=open_containers)
+ for key, item in mapping.items()
+ }
+ finally:
+ open_containers.discard(container_id)
+ if isinstance(value, (list, tuple)):
+ if container_id in open_containers:
+ return CYCLE_TEXT
+ sequence = cast("Sequence[Any]", value)
+ open_containers.add(container_id)
+ try:
+ items = [redact_secret_entries(value=item, open_containers=open_containers) for item in sequence]
+ finally:
+ open_containers.discard(container_id)
+ if isinstance(value, list):
+ return items
+ # A tuple is walked as the field walk walks one, since the ``repr`` fallback writes whatever it
+ # holds. It keeps its shape there, and it is handed back as it was when nothing in it changed,
+ # so a named tuple that carried no secret keeps its name in the rendering.
+ if all(new is old for new, old in zip(items, sequence, strict=True)):
+ return sequence
+ return tuple(items)
+ return value
+
+
+def _is_secret_key(*, key: Any) -> bool:
+ """Whether a mapping key names a secret, read lowercased and with a dash as an underscore."""
+ return isinstance(key, str) and key.lower().replace("-", "_") in SECRET_KEY_NAMES
+
+
+def _clean_value(*, value: Any, patterns: tuple[RedactionPattern, ...], open_containers: set[int], is_escaping_control_characters: bool) -> Any:
+ """The value with every string it holds, at any depth, scrubbed of secrets, and its control characters escaped when asked.
+
+ A mapping and a sequence are walked and rebuilt, a tuple coming back as a list the way a JSON
+ rendering would have made it, and a mapping entry named like a secret loses its value whatever
+ the value is, since the mapping split the name from the value the string families read together.
+ A model is dumped and an object is rendered as text before the walk, exactly as the wire sinks
+ would have dumped and rendered them after it, so neither carries a secret past the scrub. A
+ number, a boolean and ``None`` come back as they are. A container that contains itself is cut at
+ the cycle with a marker: kept raw, it would hand its unscrubbed strings to a sink's fallback rendering.
+ A model whose dump raises and an object whose text raises become a marker naming what was raised,
+ and nothing of what it said, which may be the very value it failed on: one value that refuses to
+ render costs that value, not the record and every other value beside it.
+ """
+ if isinstance(value, str):
+ scrubbed = scrub_secrets(text=value, patterns=patterns)
+ return escape_control_characters(text=scrubbed) if is_escaping_control_characters else scrubbed
+ if value is None or isinstance(value, (bool, int, float)):
+ return value
+ if isinstance(value, BaseModel):
+ try:
+ value = value.model_dump(mode="json")
+ except Exception as exc: # ruff: ignore[blind-except]
+ return _unrenderable_text(exc=exc)
+ container_id = id(value)
+ if container_id in open_containers:
+ return CYCLE_TEXT
+ if isinstance(value, Mapping):
+ mapping = cast("Mapping[Any, Any]", value)
+ open_containers.add(container_id)
+ try:
+ return {
+ key: REDACTED_TEXT
+ if _is_secret_key(key=key)
+ else _clean_value(
+ value=item, patterns=patterns, open_containers=open_containers, is_escaping_control_characters=is_escaping_control_characters
+ )
+ for key, item in mapping.items()
+ }
+ finally:
+ open_containers.discard(container_id)
+ if isinstance(value, (list, tuple)):
+ sequence = cast("Sequence[Any]", value)
+ open_containers.add(container_id)
+ try:
+ return [
+ _clean_value(
+ value=item, patterns=patterns, open_containers=open_containers, is_escaping_control_characters=is_escaping_control_characters
+ )
+ for item in sequence
+ ]
+ finally:
+ open_containers.discard(container_id)
+ # What ``json_fallback`` would have written for it, scrubbed before it is written.
+ try:
+ text = str(value)
+ except Exception as exc: # ruff: ignore[blind-except]
+ return _unrenderable_text(exc=exc)
+ return _clean_value(value=text, patterns=patterns, open_containers=open_containers, is_escaping_control_characters=is_escaping_control_characters)
+
+
+def _unrenderable_text(*, exc: Exception) -> str:
+ """The marker a value that refused to render is carried as: the name of what it raised, and nothing of its text."""
+ return f"{UNRENDERABLE_PREFIX}{type(exc).__name__}]"
diff --git a/pipelex/tools/log/log_sink.py b/pipelex/tools/log/log_sink.py
index 46e38bc4a..44841cbb4 100644
--- a/pipelex/tools/log/log_sink.py
+++ b/pipelex/tools/log/log_sink.py
@@ -10,6 +10,7 @@ slot and the stream resolution, and names no sink.
from __future__ import annotations
+import contextlib
import json
import logging
import math
@@ -23,6 +24,7 @@ from pydantic import BaseModel
from typing_extensions import override
from pipelex.system.console_target import ConsoleTarget
+from pipelex.tools.log.log_fields import UNSCRUBBED_MARK
if TYPE_CHECKING:
from collections.abc import Sequence
@@ -36,8 +38,11 @@ POSITIVE_INFINITY_TEXT = "Infinity"
NEGATIVE_INFINITY_TEXT = "-Infinity"
# A processor edits a record in place before the sink renders it; redaction is the intended one. It
-# runs on the sink's own handler, once per record, so a handler another integration attached to the
-# root logger sees the record as the processors left it only if it runs after this one.
+# runs on the sink's own handler, once per record, and on the original record rather than a copy, so a
+# handler another integration attached to the root logger sees the record as the processors left it
+# when it runs after this one, and as the call made it when it runs before. In place is deliberate:
+# what the processors do is remove what must not leave the process, and a copy would hand every other
+# handler the secret the sink was spared.
LogRecordProcessor = Callable[[logging.LogRecord], None]
@@ -49,18 +54,50 @@ class LogSinkMethod(StrEnum):
OTLP = "otlp"
-class _ProcessorFilter(logging.Filter):
- """Runs the sink's processors over each record before the handler formats it, and never drops one."""
+class ProcessorFilter(logging.Filter):
+ """Runs the sink's processors over each record before the handler formats it, and drops only what one asks it to.
+
+ The stdlib runs a handler's filters outside any ``try``, so a processor that raised would raise out
+ of the ``log.<level>(...)`` call that emitted the record, against the promise that a log call never
+ raises. Each processor is therefore guarded on its own: what it raises is reported on stderr, the
+ processors after it still run, and the record is handed to the handler all the same. The report
+ names the processor and the type of what it raised, and withholds the exception's text and
+ traceback, which the handler's ``handleError`` would have printed: a processor fails on the record's
+ own values, so its exception is where they end up, the secret the redaction was removing among them.
+ The reporter is guarded too, since a closed stderr makes it raise. A processor that fails costs that
+ record its processing, never the call and never the line; a processor that must not hand on what it
+ failed to process, the redaction, strips the record itself before it raises, and where even the
+ stripping failed it leaves the mark that has this filter drop the record instead.
+ """
- def __init__(self, processors: list[LogRecordProcessor]):
+ def __init__(self, *, processors: list[LogRecordProcessor]):
super().__init__()
self._processors = processors
@override
def filter(self, record: logging.LogRecord) -> bool:
for processor in self._processors:
- processor(record)
- return True
+ try:
+ processor(record)
+ except Exception as exc: # ruff: ignore[blind-except]
+ with contextlib.suppress(Exception):
+ _report_processor_failure(processor=processor, exc=exc)
+ # A processor that must not hand on what it failed to process says so by leaving the mark on the
+ # record, and the record is dropped rather than emitted. It is read out of the record's own
+ # dictionary, so finding out costs no call and no frame: this runs where a stack that has run
+ # out is the likeliest reason a processor failed in the first place.
+ return UNSCRUBBED_MARK not in record.__dict__
+
+
+def _report_processor_failure(*, processor: LogRecordProcessor, exc: Exception) -> None:
+ """Write the stdlib's logging-error banner with the processor and the exception type, when the stdlib would have reported at all."""
+ if not logging.raiseExceptions or not sys.stderr:
+ return
+ processor_name = getattr(processor, "__qualname__", type(processor).__qualname__)
+ sys.stderr.write(
+ f"--- Logging error ---\nThe log record processor {processor_name} raised {type(exc).__name__}, and the record was handed on "
+ "without it. The exception's text is withheld, since it may carry what the processor was removing.\n"
+ )
class LogSink(ABC):
@@ -84,10 +121,27 @@ class LogSink(ABC):
"""The sink's handler, built on first read with the processors wired in front of it."""
if self._handler is None:
handler = self.make_handler()
- handler.addFilter(_ProcessorFilter(self.processors))
+ handler.addFilter(ProcessorFilter(processors=self.processors))
self._handler = handler
return self._handler
+ def discard_handler(self) -> None:
+ """Forget the handler built for an install, so a sink object installed again builds a fresh one.
+
+ A teardown closes the handler, and a close is terminal for a sink that really releases what it
+ writes to: a file sink closes its file there. Handing the same handler back at the next install
+ would install a sink that accepts every record, runs every filter and drops the lot on the floor,
+ with nothing raised to say so. The fresh handler also gets a fresh processor filter, reading
+ whatever ``processors`` holds at that install rather than the list the first one closed over.
+
+ A fresh handler is only as live as what ``make_handler`` builds it on. A sink that opens its
+ target there comes back whole; one that was handed its target built, and whose close released
+ it, cannot, and says so from ``make_handler`` rather than build a handler on the dead target:
+ the ``otlp`` sink, whose close shuts down the provider and the processor it was constructed
+ with, is that case.
+ """
+ self._handler = None
+
def redirect_to_stderr(self) -> None:
"""Point a sink that writes to a process stream at stderr; a sink that does not ignores the call."""
return
diff --git a/pipelex/tools/log/otlp_log_sink.py b/pipelex/tools/log/otlp_log_sink.py
index 1ab148a55..fd33ecf53 100644
--- a/pipelex/tools/log/otlp_log_sink.py
+++ b/pipelex/tools/log/otlp_log_sink.py
@@ -3,13 +3,14 @@
Each record becomes one OTel log record on the logger named after the emitting module: the message
is the body, the level maps onto the OTel severity scale, the record's fields, context identifiers and
``data`` ride as attributes, with a value the wire cannot carry as is written as JSON text, and an
-exception lands under the ``exception.*`` semantic-convention keys. The semantic-convention keys the
-sink writes itself — the source location and the exception — are reserved whether or not the record
-carries an exception, exactly as the ``json`` sink reserves its own keys: a field named like one is
-carried under the same ``field_`` prefix, so the same field survives a change of sink. The records the
-sink's own export path emits, the SDK's and the transport's, are rejected by a filter on the handler and
-never exported. This module imports the OpenTelemetry SDK at load, which is why the built-in plugin
-imports it inside the ``otlp`` factory and nowhere else.
+exception lands under the ``exception.*`` semantic-convention keys, the stacktrace being the record's
+rendered exception text so that what the redaction processor scrubbed is what leaves. The
+semantic-convention keys the sink writes itself — the source location and the exception — are reserved
+whether or not the record carries an exception, exactly as the ``json`` sink reserves its own keys: a
+field named like one is carried under the same ``field_`` prefix, so the same field survives a change of
+sink. The records the sink's own export path emits, the SDK's and the transport's, are rejected by a
+filter on the handler and never exported. This module imports the OpenTelemetry SDK at load, which is why
+the built-in plugin imports it inside the ``otlp`` factory and nowhere else.
"""
from __future__ import annotations
@@ -181,9 +182,14 @@ class OtlpLogHandler(logging.Handler):
exc_type, exc_value, exc_traceback = record.exc_info
if exc_type is not None:
attributes[exception_attributes.EXCEPTION_TYPE] = exc_type.__name__
- if exc_value is not None:
- attributes[exception_attributes.EXCEPTION_MESSAGE] = str(exc_value)
- if exc_traceback is not None:
+ # The type and the stacktrace, whose last line is the exception's own text, and no message
+ # attribute: ``str(exc_value)`` is the one rendering nothing before this sink can scrub,
+ # whereas ``exc_text`` is what the redaction processor rendered and scrubbed, when it ran. An
+ # exception that was never raised, or whose traceback was dropped, renders as its last line
+ # alone, which is then the only place its text is exported.
+ if record.exc_text:
+ attributes[exception_attributes.EXCEPTION_STACKTRACE] = record.exc_text
+ elif exc_value is not None:
attributes[exception_attributes.EXCEPTION_STACKTRACE] = "".join(traceback.format_exception(exc_type, exc_value, exc_traceback))
for name, value in carried_attributes(record=record).items():
key = name
@@ -194,12 +200,21 @@ class OtlpLogHandler(logging.Handler):
class OtlpLogSink(LogSink):
- """The OpenTelemetry logs signal behind one log record processor, a batching exporter in production."""
+ """The OpenTelemetry logs signal behind one log record processor, a batching exporter in production.
+
+ One install per object. The processor is handed over already built, and the handler's close shuts
+ the provider down and the processor with it, which nothing can start again: a second handler would
+ accept every record and export none. So a second handler is refused, loudly, at the install that
+ asks for it. The registered ``otlp`` factory builds a new sink at every boot, so a configure/reset
+ cycle through the registry never meets the refusal; a host that keeps a sink object and installs it
+ again does, and builds a new one instead.
+ """
def __init__(self, *, processor: OTelLogRecordProcessor, resource: Resource | None = None) -> None:
super().__init__()
self._logger_provider = LoggerProvider(resource=resource)
self._logger_provider.add_log_record_processor(processor)
+ self._has_built_handler = False
@property
def logger_provider(self) -> LoggerProvider:
@@ -207,6 +222,14 @@ class OtlpLogSink(LogSink):
@override
def make_handler(self) -> logging.Handler:
+ if self._has_built_handler:
+ msg = (
+ "This otlp sink was installed once already, and the teardown that closed its handler shut its logger provider and its "
+ "processor down, so it can export nothing again. Build a new OtlpLogSink for this install; the registered 'otlp' factory "
+ "builds one at every boot."
+ )
+ raise RuntimeError(msg)
handler = OtlpLogHandler(logger_provider=self._logger_provider)
handler.addFilter(ExportPathFilter())
+ self._has_built_handler = True
return handler
diff --git a/tests/unit/pipelex/cli/test_agent_doctor_cmd.py b/tests/unit/pipelex/cli/test_agent_doctor_cmd.py
index 5a794e691..5c9a389f4 100644
--- a/tests/unit/pipelex/cli/test_agent_doctor_cmd.py
+++ b/tests/unit/pipelex/cli/test_agent_doctor_cmd.py
@@ -63,10 +63,14 @@ class TestAgentDoctorCmd:
def test_the_doctor_releases_the_logging_it_configured_once_the_report_is_out(self, mocker: MockerFixture) -> None:
log.reset()
sink = _NullSink()
+ # The handler the install put on the root logger, captured while it is there: the release discards
+ # it, and ``sink.handler`` read afterwards builds a new one that could never be on the root.
+ installed: list[logging.Handler] = []
def report_through_a_sink(**_options: Any) -> None:
log.configure(log_config=_package_log_config())
log.install_sink(sink)
+ installed.append(sink.handler)
mocker.patch.object(agent_doctor_module, "_do_agent_doctor_cmd", side_effect=report_through_a_sink)
try:
@@ -74,7 +78,8 @@ class TestAgentDoctorCmd:
assert log.sink is None
assert not log.is_configured
- assert sink.handler not in logging.getLogger().handlers
+ (handler,) = installed
+ assert handler not in logging.getLogger().handlers
finally:
log.reset()
diff --git a/tests/unit/pipelex/cli/test_doctor_log_sink.py b/tests/unit/pipelex/cli/test_doctor_log_sink.py
index ad0080b7d..e3ab51da9 100644
--- a/tests/unit/pipelex/cli/test_doctor_log_sink.py
+++ b/tests/unit/pipelex/cli/test_doctor_log_sink.py
@@ -63,6 +63,28 @@ class _NullSink(LogSink):
return logging.NullHandler()
+class _UnrecoverableHandler(logging.Handler):
+ """Cannot render a record, and cannot say so either: the shape a closed stderr gives a handler at its ``handleError``."""
+
+ @override
+ def emit(self, record: logging.LogRecord) -> None:
+ msg = "this handler cannot render a record"
+ raise RuntimeError(msg)
+
+ @override
+ def handleError(self, record: logging.LogRecord) -> None:
+ msg = "stderr is closed"
+ raise ValueError(msg)
+
+
+class _FailsOnReplaySink(LogSink):
+ """Builds its handler, so the sink is recorded as installed, and then fails on the first record replayed through it."""
+
+ @override
+ def make_handler(self) -> logging.Handler:
+ return _UnrecoverableHandler()
+
+
def _registry() -> LogSinkRegistry:
return LogSinkRegistry(
{
@@ -85,11 +107,15 @@ class TestDoctorLogSink:
@pytest.mark.usefixtures("released_log")
def test_the_doctor_releases_the_logging_it_configured_once_the_report_is_out(self, mocker: MockerFixture) -> None:
sink = _NullSink()
+ # The handler the install put on the root logger, captured while it is there: the release discards
+ # it, and ``sink.handler`` read afterwards builds a new one that could never be on the root.
+ installed: list[logging.Handler] = []
def report_through_a_sink(**_options: Any) -> None:
log.configure(log_config=_log_config(sink=LogSinkMethod.CONSOLE))
log.install_sink(sink)
assert log.sink is sink
+ installed.append(sink.handler)
mocker.patch.object(doctor_cmd, "do_doctor_cmd", side_effect=report_through_a_sink)
@@ -97,7 +123,8 @@ class TestDoctorLogSink:
assert log.sink is None
assert not log.is_configured
- assert sink.handler not in logging.getLogger().handlers
+ (handler,) = installed
+ assert handler not in logging.getLogger().handlers
@pytest.mark.usefixtures("released_log")
def test_the_doctor_leaves_logging_an_embedder_configured_before_calling_in(self, mocker: MockerFixture) -> None:
@@ -151,6 +178,20 @@ class TestDoctorLogSink:
assert "choose stdout or stderr" in check.message
_assert_the_fallback_console_sink_is_installed_on_stderr()
+ @pytest.mark.usefixtures("released_log")
+ def test_a_sink_that_failed_after_being_recorded_is_a_row_and_the_installed_sink_is_kept(self) -> None:
+ """The failure comes out of the replay, past the point where the sink was recorded, so there is nothing for a fallback to install."""
+ log_config = _log_config(sink=LogSinkMethod.JSON)
+ log.configure(log_config=log_config)
+ log.warning("a record held until the sink arrives")
+ registry = LogSinkRegistry({LogSinkMethod.JSON: lambda _config: _FailsOnReplaySink()})
+
+ check = install_doctor_log_sink(registry=registry, log_config=log_config)
+
+ assert not check.is_healthy
+ assert "stderr is closed" in check.message
+ assert isinstance(log.sink, _FailsOnReplaySink)
+
@pytest.mark.usefixtures("released_log")
def test_a_plugin_registry_that_does_not_build_is_a_row_and_the_report_goes_on_through_stderr(self, mocker: MockerFixture) -> None:
log_config = _log_config(sink=LogSinkMethod.JSON)
diff --git a/tests/unit/pipelex/tools/test_log_holding.py b/tests/unit/pipelex/tools/test_log_holding.py
index c7220b123..6f35921a9 100644
--- a/tests/unit/pipelex/tools/test_log_holding.py
+++ b/tests/unit/pipelex/tools/test_log_holding.py
@@ -16,7 +16,7 @@ from typing_extensions import override
from pipelex.system.configuration.config_loader import ConfigLoader
from pipelex.tools.log.log import Log
from pipelex.tools.log.log_config import LogConfig
-from pipelex.tools.log.log_fields import FORWARDED_MARK
+from pipelex.tools.log.log_fields import COLLIDING_FIELD_PREFIX, FORWARDED_MARK
from pipelex.tools.log.log_holding import HOLDING_CAPACITY, ForwardedRecordFilter, HoldingLogHandler
from pipelex.tools.log.log_sink import LogSink
from pipelex.tools.misc.toml_utils import load_toml_from_path
@@ -282,6 +282,18 @@ class TestHoldingLogHandler:
assert [record.getMessage() for record in target.records] == ["after"]
+ def test_a_caller_field_named_like_the_forwarded_mark_is_prefixed_and_the_record_is_still_delivered(self, fresh_log: Log) -> None:
+ """A field is never allowed to make a record vanish: spelled as the mark, it lands prefixed and the sink still sees the line."""
+ sink = _ListSink()
+ fresh_log.install_sink(sink)
+
+ fresh_log.info("still here", fields={FORWARDED_MARK: "whatever the caller meant"})
+
+ (delivered,) = [record for record in sink.list_handler.records if record.name == __name__]
+ assert delivered.getMessage() == "still here"
+ assert getattr(delivered, f"{COLLIDING_FIELD_PREFIX}{FORWARDED_MARK}") == "whatever the caller meant"
+ assert not getattr(delivered, FORWARDED_MARK, False)
+
def test_the_holding_handler_keeps_the_newest_records_up_to_its_capacity(self) -> None:
holding = HoldingLogHandler()
for index in range(HOLDING_CAPACITY + 5):
diff --git a/tests/unit/pipelex/tools/test_log_json_sink.py b/tests/unit/pipelex/tools/test_log_json_sink.py
index 65d7dfee0..d5bbbaa6d 100644
--- a/tests/unit/pipelex/tools/test_log_json_sink.py
+++ b/tests/unit/pipelex/tools/test_log_json_sink.py
@@ -18,10 +18,11 @@ import pytest
from pydantic import BaseModel
from pipelex.system.configuration.config_loader import ConfigLoader
-from pipelex.tools.log.json_log_sink import EXCEPTION_KEY, LOGGER_KEY, MESSAGE_KEY, SEVERITY_KEY, TIME_KEY, JsonLogSink
+from pipelex.tools.log.json_log_sink import EXCEPTION_KEY, LOGGER_KEY, MESSAGE_KEY, SEVERITY_KEY, TIME_KEY, JsonLogFormatter, JsonLogSink
from pipelex.tools.log.log import Log
from pipelex.tools.log.log_config import LogConfig
from pipelex.tools.log.log_fields import COLLIDING_FIELD_PREFIX, DATA_FIELD
+from pipelex.tools.log.log_redaction import CYCLE_TEXT, REDACTED_TEXT
from pipelex.tools.misc.toml_utils import load_toml_from_path
if TYPE_CHECKING:
@@ -90,6 +91,16 @@ class TestJsonLogSink:
assert structured[DATA_FIELD] == {"key": "value", "nested": {"flag": True}}
assert structured[MESSAGE_KEY].startswith("Config:")
+ def test_a_field_value_carrying_a_newline_is_still_one_line_and_forges_nothing(self, json_log: tuple[Log, io.StringIO]) -> None:
+ """Redaction neutralises the control characters in a field value before the sink writes it, so a caller cannot forge a line or a field."""
+ fresh, buffer = json_log
+
+ fresh.info("received", fields={"detail": 'ok\nseve\x1b[31mrity="ERROR"'})
+
+ assert len([line for line in buffer.getvalue().splitlines() if "detail" in line]) == 1
+ (received,) = _own_lines(buffer)
+ assert received["detail"] == 'ok\\nseve\\x1b[31mrity="ERROR"'
+
def test_the_exception_is_a_field_and_not_part_of_the_message(self, json_log: tuple[Log, io.StringIO]) -> None:
fresh, buffer = json_log
try:
@@ -103,6 +114,19 @@ class TestJsonLogSink:
assert "Traceback (most recent call last)" in line[EXCEPTION_KEY]
assert "ValueError: boom" in line[EXCEPTION_KEY]
+ def test_a_secret_in_an_exceptions_message_is_scrubbed_from_the_exception_value(self, json_log: tuple[Log, io.StringIO]) -> None:
+ fresh, buffer = json_log
+ try:
+ msg = "refused: Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.body.sig for sk_live_0123456789abcdef"
+ raise RuntimeError(msg)
+ except RuntimeError:
+ fresh.error("call failed", include_exception=True)
+
+ (line,) = _own_lines(buffer)
+ assert "eyJhbGciOiJIUzI1NiJ9" not in line[EXCEPTION_KEY]
+ assert "sk_live_0123456789abcdef" not in line[EXCEPTION_KEY]
+ assert line[EXCEPTION_KEY].endswith(f"RuntimeError: refused: Authorization: Bearer {REDACTED_TEXT} for sk_{REDACTED_TEXT}")
+
def test_no_ansi_ever_even_for_a_warning_or_an_error(self, json_log: tuple[Log, io.StringIO]) -> None:
fresh, buffer = json_log
fresh.warning("careful")
@@ -123,7 +147,7 @@ class TestJsonLogSink:
assert line[f"{COLLIDING_FIELD_PREFIX}logger"] == "other"
def test_a_value_json_does_not_know_is_serialized_and_never_lost(self, json_log: tuple[Log, io.StringIO]) -> None:
- """A model dumps in JSON mode, a datetime becomes text, a cycle keeps the line an object."""
+ """A model dumps in JSON mode, a datetime becomes text, a cycle is cut by the redaction walk and keeps the line an object."""
class Item(BaseModel):
name: str
@@ -139,8 +163,20 @@ class TestJsonLogSink:
assert odd["item"] == {"name": "x", "when": "2020-01-02T00:00:00Z"}
assert odd["when"] == "2021-03-04 00:00:00+00:00"
assert cyclic_line[MESSAGE_KEY] == "cyclic value"
- assert isinstance(cyclic_line["loop"], str)
- assert "{...}" in cyclic_line["loop"]
+ assert cyclic_line["loop"] == {"me": CYCLE_TEXT}
+
+ def test_a_raw_cycle_reaching_the_formatter_keeps_the_line_an_object(self) -> None:
+ """The sink's own guard, for a process with redaction off: a value ``json`` refuses is written as its ``repr``, the line stays one object."""
+ cyclic: dict[str, Any] = {}
+ cyclic["me"] = cyclic
+ record = logging.LogRecord(name=__name__, level=logging.INFO, pathname="", lineno=0, msg="cyclic value", args=(), exc_info=None)
+ record.loop = cyclic
+
+ line = json.loads(JsonLogFormatter().format(record))
+
+ assert line[MESSAGE_KEY] == "cyclic value"
+ assert isinstance(line["loop"], str)
+ assert "{...}" in line["loop"]
def test_a_non_finite_float_is_written_as_text_a_strict_parser_accepts(self, json_log: tuple[Log, io.StringIO]) -> None:
"""JSON has no NaN: the bare tokens Python writes by default would cost the whole line, so they are strings."""
@@ -203,7 +239,7 @@ class TestJsonLogSink:
assert "ValueError: boom" in with_exception[EXCEPTION_KEY]
assert with_exception[f"{COLLIDING_FIELD_PREFIX}{EXCEPTION_KEY}"] == "supplied"
assert cycle[MESSAGE_KEY] == "cycle under a reserved name"
- assert "{...}" in cycle[f"{COLLIDING_FIELD_PREFIX}{EXCEPTION_KEY}"]
+ assert cycle[f"{COLLIDING_FIELD_PREFIX}{EXCEPTION_KEY}"] == {"me": CYCLE_TEXT}
def test_redirect_to_stderr_moves_the_stream(self, json_log: tuple[Log, io.StringIO], capsys: pytest.CaptureFixture[str]) -> None:
fresh, buffer = json_log
@@ -216,3 +252,26 @@ class TestJsonLogSink:
assert fresh.sink is not None
assert isinstance(fresh.sink, JsonLogSink)
assert fresh.sink.handler.stream is sys.stderr # type: ignore[attr-defined]
+
+ def test_content_the_serialization_refuses_is_redacted_by_name_before_it_falls_back_to_a_repr(self, json_log: tuple[Log, io.StringIO]) -> None:
+ """The ``repr`` of an entry holding an object is beyond what the string families read back out of text."""
+ fresh, buffer = json_log
+ cyclic: dict[str, Any] = {"password": {"value": "private_credential_12345"}}
+ cyclic["self"] = cyclic
+
+ fresh.info(cyclic)
+
+ (line,) = _own_lines(buffer)
+ assert "private_credential_12345" not in line[MESSAGE_KEY]
+ assert REDACTED_TEXT in line[MESSAGE_KEY]
+
+ def test_a_caller_field_named_like_the_content_attribute_is_carried_under_the_collision_prefix(self, json_log: tuple[Log, io.StringIO]) -> None:
+ """``data`` is the runtime's own rendering and keeps its control characters; a caller's string must not land there."""
+ fresh, buffer = json_log
+
+ fresh.info("string content", fields={DATA_FIELD: "ok\nFAKE LINE", "other": "ok\nFAKE LINE"})
+
+ (line,) = _own_lines(buffer)
+ assert DATA_FIELD not in line
+ assert line[f"{COLLIDING_FIELD_PREFIX}{DATA_FIELD}"] == "ok\\nFAKE LINE"
+ assert line["other"] == "ok\\nFAKE LINE"
diff --git a/tests/unit/pipelex/tools/test_log_otlp_sink.py b/tests/unit/pipelex/tools/test_log_otlp_sink.py
index dd974c7dc..1375928ef 100644
--- a/tests/unit/pipelex/tools/test_log_otlp_sink.py
+++ b/tests/unit/pipelex/tools/test_log_otlp_sink.py
@@ -21,6 +21,7 @@ from pipelex.system.configuration.config_loader import ConfigLoader
from pipelex.tools.log.log import Log
from pipelex.tools.log.log_config import LogConfig
from pipelex.tools.log.log_fields import COLLIDING_FIELD_PREFIX
+from pipelex.tools.log.log_redaction import REDACTED_TEXT
from pipelex.tools.log.otlp_log_sink import FLUSH_TIMEOUT_MILLIS, ExportPathFilter, OtlpLogSink
from pipelex.tools.misc.toml_utils import load_toml_from_path
@@ -31,9 +32,10 @@ if TYPE_CHECKING:
from pytest_mock import MockerFixture
-def _package_log_config() -> LogConfig:
+def _package_log_config(*, is_redaction_enabled: bool = True) -> LogConfig:
config_dict = load_toml_from_path(ConfigLoader().pipelex_root_dir / "pipelex.toml")
- return LogConfig.model_validate(config_dict["runtime"]["log"])
+ redaction = {**config_dict["runtime"]["log"]["redaction"], "is_enabled": is_redaction_enabled}
+ return LogConfig.model_validate({**config_dict["runtime"]["log"], "redaction": redaction})
def _own_logs(exporter: InMemoryLogExporter) -> list[LogData]:
@@ -105,15 +107,51 @@ class TestOtlpLogSink:
assert log_data.log_record.severity_number is SeverityNumber.ERROR
attributes = _attributes(log_data)
assert attributes[exception_attributes.EXCEPTION_TYPE] == "ValueError"
- assert attributes[exception_attributes.EXCEPTION_MESSAGE] == "boom"
+ assert exception_attributes.EXCEPTION_MESSAGE not in attributes
assert "Traceback (most recent call last)" in attributes[exception_attributes.EXCEPTION_STACKTRACE]
+ assert attributes[exception_attributes.EXCEPTION_STACKTRACE].rstrip().endswith("ValueError: boom")
+
+ def test_the_stacktrace_is_the_scrubbed_text_and_no_message_attribute_carries_the_secret(self, otlp_log: tuple[Log, InMemoryLogExporter]) -> None:
+ """The message attribute would be ``str(exc_value)``, which no sink can scrub; the type and the stacktrace's last line carry what it said."""
+ fresh, exporter = otlp_log
+ try:
+ msg = "refused for sk_live_0123456789abcdef"
+ raise RuntimeError(msg)
+ except RuntimeError:
+ fresh.error("call failed", include_exception=True)
+
+ (log_data,) = _own_logs(exporter)
+ attributes = _attributes(log_data)
+ assert exception_attributes.EXCEPTION_MESSAGE not in attributes
+ assert "sk_live_0123456789abcdef" not in attributes[exception_attributes.EXCEPTION_STACKTRACE]
+ assert attributes[exception_attributes.EXCEPTION_STACKTRACE].rstrip().endswith(f"RuntimeError: refused for sk_{REDACTED_TEXT}")
+
+ def test_an_exception_that_carries_no_traceback_still_exports_its_own_text(self, caplog: pytest.LogCaptureFixture) -> None:
+ """``exc_text`` is the processor's rendering; with redaction off there is none and the stacktrace is the only place the text goes."""
+ caplog.set_level(logging.INFO, logger=__name__)
+ exporter = InMemoryLogExporter()
+ fresh = Log()
+ fresh.configure(log_config=_package_log_config(is_redaction_enabled=False))
+ fresh.install_sink(OtlpLogSink(processor=SimpleLogRecordProcessor(exporter)))
+ try:
+ logging.getLogger(__name__).error("failed", exc_info=ValueError("upstream quota exceeded"))
+
+ (log_data,) = _own_logs(exporter)
+ attributes = _attributes(log_data)
+ assert attributes[exception_attributes.EXCEPTION_TYPE] == "ValueError"
+ assert exception_attributes.EXCEPTION_MESSAGE not in attributes
+ assert attributes[exception_attributes.EXCEPTION_STACKTRACE].rstrip() == "ValueError: upstream quota exceeded"
+ finally:
+ fresh.reset()
def test_the_semantic_convention_keys_are_reserved_with_or_without_an_exception(self, otlp_log: tuple[Log, InMemoryLogExporter]) -> None:
"""The sink writes these keys itself, so a field named like one is prefixed rather than overwritten.
Reserved whether or not the record carries an exception, exactly as the json sink reserves its own
keys on every line: a field's wire name must not depend on an exception being active, and the same
- field must not survive one sink and vanish on another.
+ field must not survive one sink and vanish on another. ``exception.message`` is reserved on the same
+ terms though the sink no longer writes it — the rendering it used to carry, ``str(exc_value)``, is
+ the one the redaction processor never sees — so a field named like it is prefixed all the same.
"""
fresh, exporter = otlp_log
supplied = {
@@ -140,7 +178,8 @@ class TestOtlpLogSink:
assert attributes[code_attributes.CODE_LINE_NUMBER] > 0
assert attributes[code_attributes.CODE_FUNCTION_NAME] == "test_the_semantic_convention_keys_are_reserved_with_or_without_an_exception"
assert _attributes(with_exception)[exception_attributes.EXCEPTION_TYPE] == "ValueError"
- assert _attributes(with_exception)[exception_attributes.EXCEPTION_MESSAGE] == "boom"
+ assert _attributes(with_exception)[exception_attributes.EXCEPTION_STACKTRACE].rstrip().endswith("ValueError: boom")
+ assert exception_attributes.EXCEPTION_MESSAGE not in _attributes(with_exception)
assert exception_attributes.EXCEPTION_TYPE not in _attributes(without)
@pytest.mark.parametrize(
@@ -251,3 +290,21 @@ class TestOtlpLogSink:
sink.handler.flush()
force_flush.assert_called_once_with(timeout_millis=FLUSH_TIMEOUT_MILLIS)
+
+ def test_the_same_sink_installed_again_after_a_reset_is_refused_rather_than_exporting_nothing(self) -> None:
+ """The teardown shuts the provider and the processor down, which nothing starts again, so a second install must say so."""
+ exporter = InMemoryLogExporter()
+ sink = OtlpLogSink(processor=SimpleLogRecordProcessor(exporter))
+ fresh = Log()
+ fresh.configure(log_config=_package_log_config())
+ fresh.install_sink(sink)
+ fresh.reset()
+ fresh.configure(log_config=_package_log_config())
+ try:
+ with pytest.raises(RuntimeError, match="installed once already"):
+ fresh.install_sink(sink)
+
+ assert fresh.sink is None
+ assert sink.processors == []
+ finally:
+ fresh.reset()
diff --git a/tests/unit/pipelex/tools/test_log_redaction.py b/tests/unit/pipelex/tools/test_log_redaction.py
new file mode 100644
index 000000000..2235dfb05
--- /dev/null
+++ b/tests/unit/pipelex/tools/test_log_redaction.py
@@ -0,0 +1,660 @@
+"""Secrets are scrubbed and field values made injection-safe once, before any sink renders the record.
+
+One test per shipped pattern family, each reading the scrubbed message and the scrubbed value of a
+field, because a secret reaches a log agent through either. Field values are additionally stripped of
+the control characters a caller could use to forge a line or a field separator; the message keeps its
+newlines, which are the runtime's own rendering and not a caller's string.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import sys
+from typing import TYPE_CHECKING, Any
+
+import pytest
+from pydantic import BaseModel, field_serializer
+from typing_extensions import override
+
+from pipelex.system.configuration.config_loader import ConfigLoader
+from pipelex.tools.log.log import Log
+from pipelex.tools.log.log_config import LogConfig, LogRedactionConfig
+from pipelex.tools.log.log_fields import COLLIDING_FIELD_PREFIX, DATA_FIELD
+from pipelex.tools.log.log_redaction import (
+ ARGUMENTS_WITHHELD_TEXT,
+ CYCLE_TEXT,
+ REDACTED_TEXT,
+ UNRENDERABLE_PREFIX,
+ make_redaction_processor,
+)
+from pipelex.tools.log.log_sink import LogSink
+from pipelex.tools.misc.toml_utils import load_toml_from_path
+
+if TYPE_CHECKING:
+ from collections.abc import Iterator
+
+ from pytest_mock import MockerFixture
+
+FIELD_NAME = "payload"
+
+
+def _package_log_config(*, is_redaction_enabled: bool = True) -> LogConfig:
+ config_dict = load_toml_from_path(ConfigLoader().pipelex_root_dir / "pipelex.toml")
+ redaction = {**config_dict["runtime"]["log"]["redaction"], "is_enabled": is_redaction_enabled}
+ return LogConfig.model_validate({**config_dict["runtime"]["log"], "redaction": redaction})
+
+
+def _record(*, text: str, value: Any = None) -> logging.LogRecord:
+ """One record whose message is ``text`` and whose single field carries ``value``, or ``text`` again."""
+ record = logging.LogRecord(name=__name__, level=logging.INFO, pathname="", lineno=0, msg=text, args=(), exc_info=None)
+ record.payload = text if value is None else value
+ return record
+
+
+def _redact(*, text: str, extra_patterns: list[str] | None = None) -> tuple[str, Any]:
+ """The message and the field value of one record, both carrying ``text``, after the processor ran."""
+ record = _record(text=text)
+ processor = make_redaction_processor(config=LogRedactionConfig(is_enabled=True, extra_patterns=extra_patterns or []))
+ processor(record)
+ return record.getMessage(), getattr(record, FIELD_NAME)
+
+
+class _ListHandler(logging.Handler):
+ def __init__(self) -> None:
+ super().__init__()
+ self.records: list[logging.LogRecord] = []
+
+ @override
+ def emit(self, record: logging.LogRecord) -> None:
+ self.records.append(record)
+
+
+class _ListSink(LogSink):
+ def __init__(self) -> None:
+ super().__init__()
+ self.list_handler = _ListHandler()
+
+ @override
+ def make_handler(self) -> logging.Handler:
+ return self.list_handler
+
+ def own_records(self) -> list[logging.LogRecord]:
+ return [record for record in self.list_handler.records if record.name == __name__]
+
+
+class _RebuildingSink(LogSink):
+ """A sink whose ``make_handler`` builds a new handler every time, the way a real one opens its target."""
+
+ def __init__(self) -> None:
+ super().__init__()
+ self.builds = 0
+
+ @override
+ def make_handler(self) -> logging.Handler:
+ self.builds += 1
+ return _ListHandler()
+
+
+class _FailingOnceSink(_ListSink):
+ def __init__(self) -> None:
+ super().__init__()
+ self.attempts = 0
+
+ @override
+ def make_handler(self) -> logging.Handler:
+ self.attempts += 1
+ if self.attempts == 1:
+ msg = "handler build failed"
+ raise RuntimeError(msg)
+ return self.list_handler
+
+
+class TestLogRedaction:
+ @pytest.fixture
+ def fresh_log(self, caplog: pytest.LogCaptureFixture) -> Iterator[Log]:
+ # pytest's ``log_level`` option restores the root logger's level at every phase boundary, undoing the
+ # level ``configure`` sets from inside a fixture; the module's own logger is enabled explicitly and
+ # ``caplog`` restores it at teardown.
+ caplog.set_level(logging.INFO, logger=__name__)
+ fresh = Log()
+ try:
+ yield fresh
+ finally:
+ fresh.reset()
+
+ def test_a_bearer_token_in_an_authorization_header_is_scrubbed(self) -> None:
+ message, value = _redact(text="calling with Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.body.signature now")
+
+ assert message == f"calling with Authorization: Bearer {REDACTED_TEXT} now"
+ assert value == f"calling with Authorization: Bearer {REDACTED_TEXT} now"
+
+ def test_an_api_key_header_value_is_scrubbed(self) -> None:
+ message, value = _redact(text="x-api-key: abcd1234efgh5678ijkl")
+
+ assert message == f"x-api-key: {REDACTED_TEXT}"
+ assert value == f"x-api-key: {REDACTED_TEXT}"
+
+ def test_a_signature_header_value_is_scrubbed(self) -> None:
+ message, value = _redact(text="x-completion-signature=0123456789abcdef0123")
+
+ assert message == f"x-completion-signature={REDACTED_TEXT}"
+ assert value == f"x-completion-signature={REDACTED_TEXT}"
+
+ def test_an_oauth_code_query_parameter_is_scrubbed(self) -> None:
+ message, value = _redact(text="redirected to /callback?code=4-0AfJohXm1n2o3p4q5&state=xyz")
+
+ assert message == f"redirected to /callback?code={REDACTED_TEXT}&state=xyz"
+ assert value == f"redirected to /callback?code={REDACTED_TEXT}&state=xyz"
+
+ def test_a_cookie_header_value_is_scrubbed(self) -> None:
+ message, value = _redact(text="Set-Cookie: session=3f9a2b7c4d1e")
+
+ assert message == f"Set-Cookie: {REDACTED_TEXT}"
+ assert value == f"Set-Cookie: {REDACTED_TEXT}"
+
+ def test_every_crumb_of_a_multi_cookie_header_is_scrubbed_and_the_next_line_survives(self) -> None:
+ message, value = _redact(text="Cookie: theme=light; session=private_session_12345\nUser ada logged in")
+
+ assert message == f"Cookie: {REDACTED_TEXT}\nUser ada logged in"
+ assert value == f"Cookie: {REDACTED_TEXT}\\nUser ada logged in"
+
+ def test_a_serialised_cookie_entry_is_scrubbed_up_to_its_closing_quote(self) -> None:
+ message, _ = _redact(text='{"cookie": "a=b; session=private_session_12345", "path": "/x"}')
+
+ assert message == f'{{"cookie": "{REDACTED_TEXT}", "path": "/x"}}'
+
+ def test_prose_that_merely_mentions_a_cookie_is_left_alone(self) -> None:
+ message, _ = _redact(text="the cookie was set and the rest of this sentence survives")
+
+ assert message == "the cookie was set and the rest of this sentence survives"
+
+ def test_a_json_secret_value_holding_the_other_quote_character_is_scrubbed_whole(self) -> None:
+ message, _ = _redact(text='{"password": "prefix\'private_suffix_12345", "next": "kept"}')
+
+ assert message == f'{{"password": "{REDACTED_TEXT}", "next": "kept"}}'
+
+ def test_a_json_secret_value_holding_an_escaped_quote_is_scrubbed_whole(self) -> None:
+ message, _ = _redact(text='{"access_token": "ab\\"cd_private_12345", "next": "kept"}')
+
+ assert message == f'{{"access_token": "{REDACTED_TEXT}", "next": "kept"}}'
+
+ def test_a_json_code_entry_is_not_a_secret(self) -> None:
+ message, value = _redact(text='{"error_type": "PipeDefinitionError", "code": "PIPE_NOT_FOUND"}')
+
+ assert message == '{"error_type": "PipeDefinitionError", "code": "PIPE_NOT_FOUND"}'
+ assert value == '{"error_type": "PipeDefinitionError", "code": "PIPE_NOT_FOUND"}'
+
+ def test_a_json_secret_field_is_scrubbed_and_keeps_its_shape(self) -> None:
+ message, value = _redact(text='{"user": "ada", "password": "hunter2hunter2", "access_token": "at-9f3c"}')
+
+ assert message == f'{{"user": "ada", "password": "{REDACTED_TEXT}", "access_token": "{REDACTED_TEXT}"}}'
+ assert value == f'{{"user": "ada", "password": "{REDACTED_TEXT}", "access_token": "{REDACTED_TEXT}"}}'
+
+ def test_an_api_key_prefix_is_scrubbed_wherever_it_appears(self) -> None:
+ text = "keys sk_live_0123456789abcdef plx_sk_0123456789abcdef pk_live_0123456789abcdef bl_0123456789abcdef seen"
+ expected = f"keys sk_{REDACTED_TEXT} plx_sk_{REDACTED_TEXT} pk_{REDACTED_TEXT} bl_{REDACTED_TEXT} seen"
+
+ message, value = _redact(text=text)
+
+ assert message == expected
+ assert value == expected
+
+ def test_a_control_character_in_a_field_value_is_neutralised_and_the_message_keeps_its_newlines(self) -> None:
+ message, value = _redact(text="ok\nstatus=200\tevent=forged\x1b[31m")
+
+ assert message == "ok\nstatus=200\tevent=forged\x1b[31m"
+ assert value == "ok\\nstatus=200\\tevent=forged\\x1b[31m"
+
+ def test_a_configured_extra_pattern_is_scrubbed_beside_the_shipped_families(self) -> None:
+ message, value = _redact(text="tenant tnt-40718 on sk_live_0123456789abcdef", extra_patterns=[r"tnt-[0-9]+"])
+
+ assert message == f"tenant {REDACTED_TEXT} on sk_{REDACTED_TEXT}"
+ assert value == f"tenant {REDACTED_TEXT} on sk_{REDACTED_TEXT}"
+
+ def test_an_extra_pattern_the_re_module_refuses_is_a_configuration_error_naming_it(self) -> None:
+ with pytest.raises(ValueError, match=r"\(unclosed"):
+ LogRedactionConfig(is_enabled=True, extra_patterns=["(unclosed"])
+
+ def test_a_secret_nested_in_a_structured_value_is_scrubbed_and_a_non_string_is_untouched(self) -> None:
+ record = logging.LogRecord(name=__name__, level=logging.INFO, pathname="", lineno=0, msg="sending", args=(), exc_info=None)
+ record.payload = {"sent": "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.body.sig", "notes": ["a\nb", "sk_live_0123456789abcdef"], "attempt": 3}
+ processor = make_redaction_processor(config=LogRedactionConfig(is_enabled=True, extra_patterns=[]))
+
+ processor(record)
+
+ assert getattr(record, FIELD_NAME) == {
+ "sent": f"Authorization: Bearer {REDACTED_TEXT}",
+ "notes": ["a\\nb", f"sk_{REDACTED_TEXT}"],
+ "attempt": 3,
+ }
+
+ def test_a_value_that_contains_itself_is_cut_at_the_cycle_rather_than_walked_forever_or_kept_raw(self) -> None:
+ """The raw container kept in the cleaned result would hand its unscrubbed strings to the sink's ``repr`` fallback."""
+ cyclic: dict[str, Any] = {"token": "sk_live_0123456789abcdef"}
+ cyclic["me"] = cyclic
+ record = _record(text="cyclic", value=cyclic)
+ processor = make_redaction_processor(config=LogRedactionConfig(is_enabled=True, extra_patterns=[]))
+
+ processor(record)
+
+ assert getattr(record, FIELD_NAME) == {"token": f"sk_{REDACTED_TEXT}", "me": CYCLE_TEXT}
+
+ def test_a_mapping_entry_named_like_a_secret_loses_its_value_whatever_it_holds(self) -> None:
+ """The families read a name and a value out of one string; a mapping splits them, so the key is what names the secret."""
+ record = _record(
+ text="sending",
+ value={"Authorization": "Bearer short", "x-api-key": "k", "password": {"nested": "p"}, "code": "PIPE_NOT_FOUND", "user": "ada"},
+ )
+ processor = make_redaction_processor(config=LogRedactionConfig(is_enabled=True, extra_patterns=[]))
+
+ processor(record)
+
+ assert getattr(record, FIELD_NAME) == {
+ "Authorization": REDACTED_TEXT,
+ "x-api-key": REDACTED_TEXT,
+ "password": REDACTED_TEXT,
+ "code": "PIPE_NOT_FOUND",
+ "user": "ada",
+ }
+
+ def test_a_model_is_dumped_and_an_object_is_rendered_before_the_walk_so_the_sink_meets_scrubbed_text(self) -> None:
+ """The sink would dump the model and render the object after the processor ran; the processor does it first so neither escapes the scrub."""
+
+ class Credentials(BaseModel):
+ api_key: str
+ note: str
+
+ class Carrier:
+ @override
+ def __str__(self) -> str:
+ return "carrying sk_live_0123456789abcdef"
+
+ record = _record(
+ text="sending", value={"model": Credentials(api_key="plx_sk_ABCDEFGHIJKLMNOPQRSTU", note="line\nforged"), "object": Carrier()}
+ )
+ processor = make_redaction_processor(config=LogRedactionConfig(is_enabled=True, extra_patterns=[]))
+
+ processor(record)
+
+ assert getattr(record, FIELD_NAME) == {"model": {"api_key": REDACTED_TEXT, "note": "line\\nforged"}, "object": f"carrying sk_{REDACTED_TEXT}"}
+
+ def test_the_data_attribute_is_scrubbed_of_secrets_but_keeps_its_control_characters(self) -> None:
+ """``data`` is the runtime's own rendering of a structured content, escaped by the wire sinks, so a logged prompt keeps its newlines."""
+ record = _record(text="prompt", value="ignored")
+ setattr(record, DATA_FIELD, {"prompt": "line one\nline two", "token": "sk_live_0123456789abcdef"})
+ processor = make_redaction_processor(config=LogRedactionConfig(is_enabled=True, extra_patterns=[]))
+
+ processor(record)
+
+ assert getattr(record, DATA_FIELD) == {"prompt": "line one\nline two", "token": f"sk_{REDACTED_TEXT}"}
+
+ def test_the_scrub_edits_the_record_every_handler_shares_rather_than_a_copy(self, fresh_log: Log) -> None:
+ """In place, not on a copy: a handler ordered after the sink is behind the scrub instead of being handed what the sink was spared."""
+ fresh_log.configure(log_config=_package_log_config())
+ sink = _ListSink()
+ fresh_log.install_sink(sink)
+ record = _record(text="token sk_live_0123456789abcdef", value="line\nforged")
+
+ sink.handler.handle(record)
+
+ (delivered,) = sink.own_records()
+ assert delivered is record
+ assert record.getMessage() == f"token sk_{REDACTED_TEXT}"
+ assert getattr(record, FIELD_NAME) == "line\\nforged"
+
+ def test_a_sink_installed_again_after_a_reset_carries_one_redaction_processor(self, fresh_log: Log) -> None:
+ """``reset`` takes back the processor ``install_sink`` put on the sink: a reused sink neither scrubs twice nor under a stale configuration."""
+ sink = _ListSink()
+ fresh_log.configure(log_config=_package_log_config())
+ fresh_log.install_sink(sink)
+ processors_after_one_install = list(sink.processors)
+
+ fresh_log.reset()
+ assert sink.processors == []
+ fresh_log.configure(log_config=_package_log_config())
+ fresh_log.install_sink(sink)
+
+ assert len(sink.processors) == len(processors_after_one_install)
+
+ def test_no_processor_is_installed_when_the_configuration_turns_redaction_off(self, fresh_log: Log) -> None:
+ fresh_log.configure(log_config=_package_log_config(is_redaction_enabled=False))
+ sink = _ListSink()
+ fresh_log.install_sink(sink)
+ record = _record(text="token sk_live_0123456789abcdef", value="line\nkept")
+
+ sink.handler.handle(record)
+
+ assert sink.processors == []
+ assert record.getMessage() == "token sk_live_0123456789abcdef"
+ assert getattr(record, FIELD_NAME) == "line\nkept"
+
+ def test_an_exceptions_text_is_rendered_and_scrubbed_before_any_sink_reads_it(self) -> None:
+ """The stdlib renders the traceback lazily into ``exc_text``; the processor renders it first, scrubbed, and every formatter reads that."""
+ try:
+ msg = "auth failed for sk_live_0123456789abcdef with Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.body.sig"
+ raise RuntimeError(msg)
+ except RuntimeError:
+ record = logging.LogRecord(name=__name__, level=logging.ERROR, pathname="", lineno=0, msg="failed", args=(), exc_info=sys.exc_info())
+ processor = make_redaction_processor(config=LogRedactionConfig(is_enabled=True, extra_patterns=[]))
+
+ processor(record)
+
+ assert record.exc_info is not None
+ assert record.exc_text is not None
+ assert "Traceback (most recent call last)" in record.exc_text
+ assert record.exc_text.endswith(f"RuntimeError: auth failed for sk_{REDACTED_TEXT} with Authorization: Bearer {REDACTED_TEXT}")
+ assert logging.Formatter().format(record).endswith(record.exc_text)
+
+ def test_an_already_rendered_exception_text_is_scrubbed_in_place(self) -> None:
+ record = _record(text="failed")
+ record.exc_text = "RuntimeError: key sk_live_0123456789abcdef refused"
+ processor = make_redaction_processor(config=LogRedactionConfig(is_enabled=True, extra_patterns=[]))
+
+ processor(record)
+
+ assert record.exc_text == f"RuntimeError: key sk_{REDACTED_TEXT} refused"
+
+ def test_a_record_whose_cleaning_fails_is_quarantined_rather_than_handed_on_raw(self, mocker: MockerFixture) -> None:
+ """Redaction fails closed: whatever the walk raised, the sink meets a record with nothing of the call left on it."""
+ mocker.patch("pipelex.tools.log.log_redaction._redact_record", side_effect=RecursionError("too deep"))
+ try:
+ msg = "key sk_live_0123456789abcdef refused"
+ raise RuntimeError(msg)
+ except RuntimeError:
+ record = logging.LogRecord(
+ name=__name__, level=logging.ERROR, pathname="", lineno=0, msg="token %s", args=("sk_live_0123456789abcdef",), exc_info=sys.exc_info()
+ )
+ record.payload = {"nested": "sk_live_0123456789abcdef"}
+ setattr(record, DATA_FIELD, ["sk_live_0123456789abcdef"])
+ processor = make_redaction_processor(config=LogRedactionConfig(is_enabled=True, extra_patterns=[]))
+
+ with pytest.raises(RecursionError):
+ processor(record)
+
+ assert record.getMessage() == "[REDACTION FAILED: RecursionError]"
+ assert record.args == ()
+ assert getattr(record, FIELD_NAME) == REDACTED_TEXT
+ assert getattr(record, DATA_FIELD) == REDACTED_TEXT
+ assert record.exc_info is None
+ assert record.exc_text is None
+ assert "sk_live" not in logging.Formatter().format(record)
+
+ def test_a_record_whose_message_cannot_be_rendered_withholds_its_arguments_and_keeps_its_scrubbed_fields(self) -> None:
+ """Left as it was, the handler would fail on it and the stdlib's report would print every argument raw to stderr."""
+ record = logging.LogRecord(
+ name=__name__,
+ level=logging.INFO,
+ pathname="",
+ lineno=0,
+ msg="%d items for sk_live_0123456789abcdef",
+ args=("plx_sk_0123456789abcdef",),
+ exc_info=None,
+ )
+ record.payload = "sk_live_0123456789abcdef"
+ processor = make_redaction_processor(config=LogRedactionConfig(is_enabled=True, extra_patterns=[]))
+
+ processor(record)
+
+ assert record.args == ()
+ assert record.getMessage() == f"%d items for sk_{REDACTED_TEXT} {ARGUMENTS_WITHHELD_TEXT}"
+ assert getattr(record, FIELD_NAME) == f"sk_{REDACTED_TEXT}"
+ assert "0123456789abcdef" not in logging.Formatter().format(record)
+
+ def test_a_field_whose_own_name_is_a_secrets_loses_its_value_whatever_it_holds(self) -> None:
+ """A mapping entry named like a secret is redacted by its key; a field is the same entry one level up, on the record itself."""
+ record = _record(text="login")
+ record.password = 12345678
+ record.Authorization = "Basic dXNlcjpwYXNz"
+ record.user = "ada"
+ processor = make_redaction_processor(config=LogRedactionConfig(is_enabled=True, extra_patterns=[]))
+
+ processor(record)
+
+ assert getattr(record, "password") == REDACTED_TEXT # ruff: ignore[get-attr-with-constant]
+ assert getattr(record, "Authorization") == REDACTED_TEXT # ruff: ignore[get-attr-with-constant]
+ assert getattr(record, "user") == "ada" # ruff: ignore[get-attr-with-constant]
+
+ def test_a_serialised_secret_entry_is_scrubbed_in_any_case_under_every_secret_name_and_whatever_scalar_it_holds(self) -> None:
+ """Text a call rendered itself, an f-string of a dict or a third-party ``%s``, is judged by the names a mapping key is."""
+ message, _ = _redact(
+ text=(
+ '{"Password": "hunter2", "authorization": "Basic dXNlcjpwYXNz", "refresh-token": "rt", "x_signature": "abc", '
+ '"CLIENT_SECRET": 42, "api_key": true, "retries": 3, "code": "PIPE_NOT_FOUND"}'
+ )
+ )
+
+ assert message == (
+ f'{{"Password": "{REDACTED_TEXT}", "authorization": "{REDACTED_TEXT}", "refresh-token": "{REDACTED_TEXT}", '
+ f'"x_signature": "{REDACTED_TEXT}", "CLIENT_SECRET": {REDACTED_TEXT}, "api_key": {REDACTED_TEXT}, '
+ '"retries": 3, "code": "PIPE_NOT_FOUND"}'
+ )
+
+ def test_a_repr_entry_whose_value_is_quoted_differently_from_its_name_is_scrubbed_whole(self) -> None:
+ message, _ = _redact(text=repr({"password": "it's hunter2", "user": "ada"}))
+
+ assert message == f"{{'password': \"{REDACTED_TEXT}\", 'user': 'ada'}}"
+
+ def test_a_structured_contents_message_is_rendered_from_the_redacted_content_so_it_agrees_with_data(self, fresh_log: Log) -> None:
+ """The message is the content's JSON rendering; a secret held as an object or a number is beyond what the families read back out of text."""
+ log_config = _package_log_config()
+ fresh_log.configure(log_config=log_config)
+ sink = _ListSink()
+ fresh_log.install_sink(sink)
+
+ fresh_log.info({"password": {"nested": "hunter2"}, "pin": {"id_token": 123456789}, "user": "ada"})
+
+ (delivered,) = sink.own_records()
+ expected = {"password": REDACTED_TEXT, "pin": {"id_token": REDACTED_TEXT}, "user": "ada"}
+ assert getattr(delivered, DATA_FIELD) == expected
+ assert delivered.getMessage().endswith(json.dumps(expected, indent=log_config.json_logs_indent))
+ assert "hunter2" not in delivered.getMessage()
+ assert "123456789" not in delivered.getMessage()
+
+ def test_a_structured_content_with_no_secret_entry_keeps_the_helpers_own_rendering(self, fresh_log: Log) -> None:
+ log_config = _package_log_config()
+ fresh_log.configure(log_config=log_config)
+ sink = _ListSink()
+ fresh_log.install_sink(sink)
+ content = {"user": "ada", "tags": ["a", "b"]}
+
+ fresh_log.info(content)
+
+ (delivered,) = sink.own_records()
+ assert getattr(delivered, DATA_FIELD) == content
+ assert delivered.getMessage().endswith(json.dumps(content, indent=log_config.json_logs_indent))
+
+ def test_a_value_that_refuses_to_render_costs_that_value_alone_and_says_nothing_of_what_it_raised(self) -> None:
+ """Quarantining the record for one value would wipe the message and every innocent field beside it."""
+
+ class Creds(BaseModel):
+ token: str
+
+ @field_serializer("token")
+ def _refuse(self, token: str) -> str:
+ msg = f"cannot serialise {token}"
+ raise ValueError(msg)
+
+ class Refusing:
+ @override
+ def __str__(self) -> str:
+ msg = "refusing to render sk_live_0123456789abcdef"
+ raise RuntimeError(msg)
+
+ record = _record(text="processing", value={"creds": Creds(token="sk_live_0123456789abcdef"), "object": Refusing(), "request": "r-1"})
+ processor = make_redaction_processor(config=LogRedactionConfig(is_enabled=True, extra_patterns=[]))
+
+ processor(record)
+
+ cleaned = getattr(record, FIELD_NAME)
+ assert record.getMessage() == "processing"
+ assert cleaned["request"] == "r-1"
+ assert cleaned["creds"].startswith(UNRENDERABLE_PREFIX)
+ assert cleaned["object"] == f"{UNRENDERABLE_PREFIX}RuntimeError]"
+ assert "sk_live" not in str(cleaned)
+
+ def test_a_sink_whose_handler_fails_to_build_is_left_without_the_redaction_processor(self, fresh_log: Log) -> None:
+ """The failed sink is not recorded, so ``reset`` never reaches it; installed again, it must not carry a second processor."""
+ fresh_log.configure(log_config=_package_log_config())
+ sink = _FailingOnceSink()
+
+ with pytest.raises(RuntimeError, match="handler build failed"):
+ fresh_log.install_sink(sink)
+ assert sink.processors == []
+ fresh_log.install_sink(sink)
+
+ assert len(sink.processors) == 1
+
+ def test_a_cookie_value_holding_a_quote_is_removed_whole_rather_than_up_to_the_quote(self) -> None:
+ """Stopping at the quote left the session cookie after it in clear, and a value may legally hold one."""
+ quoted, _ = _redact(text='Cookie: session="private_session_12345"; HttpOnly')
+ apostrophe, _ = _redact(text="Cookie: theme=O'Reilly; session=private_session_12345")
+
+ assert quoted == f"Cookie: {REDACTED_TEXT}"
+ assert apostrophe == f"Cookie: {REDACTED_TEXT}"
+
+ def test_prose_that_says_cookie_before_a_colon_or_an_equals_sign_keeps_the_rest_of_its_line(self) -> None:
+ """Running the value to the end of the line destroyed the sentence, and any secret a later word carried."""
+ sentence, _ = _redact(text="The cookie: consent banner was shown to the user alice")
+ assignment, _ = _redact(text="Reading cookie=1 and then user=alice access_token=abcdefgh12345678")
+
+ assert sentence == "The cookie: consent banner was shown to the user alice"
+ assert assignment == f"Reading cookie=1 and then user=alice access_token={REDACTED_TEXT}"
+
+ def test_a_cookie_header_inside_a_serialised_string_stops_at_the_string_it_is_in(self) -> None:
+ """A raw-header family reading through the closing quote would take the JSON punctuation with it."""
+ message, _ = _redact(text='{"headers": "Cookie: session=abc"}')
+
+ assert message == f'{{"headers": "Cookie: {REDACTED_TEXT}"}}'
+
+ def test_a_percent_encoded_oauth_code_is_scrubbed_rather_than_passed_through(self) -> None:
+ """A class stopping at the escape leaves the tail, and the whole code when the escape falls early."""
+ message, value = _redact(text="/callback?code=4%2F0AfJohXm1n2o3p4q5&state=xyz")
+
+ assert message == f"/callback?code={REDACTED_TEXT}&state=xyz"
+ assert value == f"/callback?code={REDACTED_TEXT}&state=xyz"
+
+ def test_an_authorization_header_is_scrubbed_whichever_scheme_it_carries(self) -> None:
+ """Basic credentials decode to a password in one step; requiring the word bearer left them in clear."""
+ basic, _ = _redact(text="Authorization: Basic YWxhZGRpbjpvcGVuc2VzYW1l")
+ token, _ = _redact(text="Authorization: Token abcdefgh12345678")
+
+ assert basic == f"Authorization: Basic {REDACTED_TEXT}"
+ assert token == f"Authorization: Token {REDACTED_TEXT}"
+
+ def test_a_secret_named_in_the_plain_key_value_form_is_scrubbed_as_a_quoted_entry_is(self) -> None:
+ """A query string and a form-encoded body name their secrets unquoted, which is the shape a raw request arrives in."""
+ form, _ = _redact(text="form body: client_secret=s3cr3tvaluehere&grant_type=x")
+ query, _ = _redact(text="https://example.test/x?access_token=abcdefgh12345678")
+
+ assert form == f"form body: client_secret={REDACTED_TEXT}&grant_type=x"
+ assert query == f"https://example.test/x?access_token={REDACTED_TEXT}"
+
+ def test_a_key_is_scrubbed_by_its_prefix_spelled_with_a_dash_as_with_an_underscore(self) -> None:
+ """The dash-separated spellings are the ones the providers actually issue."""
+ message, _ = _redact(text="keys sk-proj-ABCDEFGHIJKLMNOPQRST and sk-ant-api03-ABCDEFGHIJKLMNOPQRST seen")
+
+ assert message == f"keys sk-{REDACTED_TEXT} and sk-{REDACTED_TEXT} seen"
+
+ def test_an_ordinary_identifier_that_starts_like_a_key_prefix_is_left_alone(self) -> None:
+ """A table, a column and a partition are named this way, and the family redacted them whole."""
+ message, _ = _redact(text="loaded pk_customer_reference_index rows from bl_run_history_partition")
+
+ assert message == "loaded pk_customer_reference_index rows from bl_run_history_partition"
+
+ def test_a_field_carried_under_the_collision_prefix_is_redacted_by_the_name_the_caller_used(self) -> None:
+ """A record factory that stamps ``password`` renames the caller's field, and the rename escaped the name check."""
+ record = _record(text="logging in")
+ setattr(record, f"{COLLIDING_FIELD_PREFIX}password", "private_credential_12345")
+ processor = make_redaction_processor(config=LogRedactionConfig(is_enabled=True, extra_patterns=[]))
+
+ processor(record)
+
+ assert getattr(record, f"{COLLIDING_FIELD_PREFIX}password") == REDACTED_TEXT
+
+ def test_a_pattern_that_matches_the_empty_string_is_refused_at_load(self) -> None:
+ """``x*`` for ``x+`` matches at every position, which replaces every log line the process writes."""
+ with pytest.raises(ValueError, match="matches the empty string"):
+ LogRedactionConfig(is_enabled=True, extra_patterns=["x*"])
+
+ def test_a_record_whose_quarantine_also_fails_is_dropped_rather_than_handed_to_the_sink(self, mocker: MockerFixture, fresh_log: Log) -> None:
+ """The stack that could not take the scrub cannot always take the stripping of what it left behind."""
+ mocker.patch("pipelex.tools.log.log_redaction._redact_record", side_effect=RecursionError("too deep"))
+ mocker.patch("pipelex.tools.log.log_redaction.carried_attributes", side_effect=RecursionError("too deep"))
+ fresh_log.configure(log_config=_package_log_config())
+ sink = _ListSink()
+ fresh_log.install_sink(sink)
+ record = _record(text="Authorization: Bearer private_token_1234567890")
+
+ sink.handler.handle(record)
+
+ assert sink.own_records() == []
+
+ def test_a_sink_installed_again_after_a_reset_builds_a_fresh_handler(self, fresh_log: Log) -> None:
+ """A close is terminal for a sink that releases what it writes to, so the handler it closed must not be handed back."""
+ sink = _RebuildingSink()
+ fresh_log.configure(log_config=_package_log_config())
+ fresh_log.install_sink(sink)
+ first = sink.handler
+ fresh_log.reset()
+ fresh_log.configure(log_config=_package_log_config())
+ fresh_log.install_sink(sink)
+
+ assert sink.builds == 2
+ assert sink.handler is not first
+ # The forwarded-record filter is inserted at every install and taken off by none, so the filters
+ # stacked up on the cached handler for as long as the same one came back.
+ assert len(sink.handler.filters) == len(first.filters)
+
+ @pytest.fixture
+ def root_without_other_handlers(self, mocker: MockerFixture) -> None:
+ """The root logger with none of the session's handlers on it, whose own sink would scrub the shared record first."""
+ mocker.patch.object(logging.getLogger(), "handlers", [])
+
+ @pytest.mark.usefixtures("root_without_other_handlers")
+ def test_a_boot_that_dies_before_its_sink_arrives_writes_its_held_records_scrubbed(
+ self, fresh_log: Log, capsys: pytest.CaptureFixture[str]
+ ) -> None:
+ """The held records reach stderr through the stdlib's last resort, and the redaction runs over each of them first."""
+ fresh_log.configure(log_config=_package_log_config())
+ fresh_log.warning("upstream refused: Authorization: Bearer sk_live_0123456789abcdef")
+ try:
+ msg = "token=sk_live_EXC0123456789abcdef"
+ raise RuntimeError(msg)
+ except RuntimeError:
+ logging.getLogger(__name__).exception("the remote config could not be read")
+
+ fresh_log.reset()
+
+ captured = capsys.readouterr()
+ assert "upstream refused: Authorization: Bearer" in captured.err
+ assert "the remote config could not be read" in captured.err
+ assert "sk_live_0123456789abcdef" not in captured.err
+ assert "sk_live_EXC0123456789abcdef" not in captured.err
+ assert REDACTED_TEXT in captured.err
+
+ @pytest.mark.usefixtures("root_without_other_handlers")
+ def test_a_boot_that_dies_with_redaction_turned_off_writes_its_held_records_as_they_were(
+ self, fresh_log: Log, capsys: pytest.CaptureFixture[str]
+ ) -> None:
+ fresh_log.configure(log_config=_package_log_config(is_redaction_enabled=False))
+ fresh_log.warning("upstream refused: Authorization: Bearer sk_live_0123456789abcdef")
+
+ fresh_log.reset()
+
+ assert "sk_live_0123456789abcdef" in capsys.readouterr().err
+
+ def test_a_secret_entry_inside_a_tuple_is_redacted_on_the_repr_fallback(self, fresh_log: Log) -> None:
+ """A cyclic content falls back to its ``repr``, and an entry holding an object is beyond the text families there."""
+ fresh_log.configure(log_config=_package_log_config())
+ sink = _ListSink()
+ fresh_log.install_sink(sink)
+ cyclic: list[Any] = [({"password": {"nested": "hunter2-cyclic"}},)]
+ cyclic.append(cyclic)
+
+ fresh_log.info(cyclic)
+
+ (delivered,) = sink.own_records()
+ message = delivered.getMessage()
+ assert "hunter2-cyclic" not in message
+ assert f"({{'password': '{REDACTED_TEXT}'}},)" in message
diff --git a/tests/unit/pipelex/tools/test_log_reset.py b/tests/unit/pipelex/tools/test_log_reset.py
index bbd6ee645..c417c2860 100644
--- a/tests/unit/pipelex/tools/test_log_reset.py
+++ b/tests/unit/pipelex/tools/test_log_reset.py
@@ -100,11 +100,14 @@ class TestLogReset:
) -> None:
sink = _RaisingAtCloseSink(error=RuntimeError("the collector is gone"))
configured_log.install_sink(sink)
+ # Captured before the reset, which discards it: read afterwards, ``sink.handler`` builds a new one
+ # that was never on the root logger, and the assertion could not fail.
+ installed = sink.handler
configured_log.reset()
assert configured_log.sink is None
- assert sink.handler not in logging.getLogger().handlers
+ assert installed not in logging.getLogger().handlers
captured = capsys.readouterr()
assert "_RaisingAtCloseSink" in captured.err
assert "the collector is gone" in captured.err
@@ -152,6 +155,7 @@ class TestLogReset:
"""The diagnostic has one place to go; when that place is gone the teardown still finishes and the next configure is not refused."""
sink = _RaisingAtCloseSink(error=RuntimeError("the collector is gone"))
configured_log.install_sink(sink)
+ installed = sink.handler
closed_stderr = io.StringIO()
closed_stderr.close()
mocker.patch("sys.stderr", closed_stderr)
@@ -160,4 +164,4 @@ class TestLogReset:
assert configured_log.sink is None
assert not configured_log.is_configured
- assert sink.handler not in logging.getLogger().handlers
+ assert installed not in logging.getLogger().handlers
diff --git a/tests/unit/pipelex/tools/test_log_sink.py b/tests/unit/pipelex/tools/test_log_sink.py
index 2cc8e7f21..84dccbfee 100644
--- a/tests/unit/pipelex/tools/test_log_sink.py
+++ b/tests/unit/pipelex/tools/test_log_sink.py
@@ -55,6 +55,67 @@ class TestLogSink:
assert isinstance(handler, _RecordingHandler)
assert handler.seen == ["one|yes", "two|yes"]
+ def test_a_processor_that_raises_costs_that_records_processing_and_not_the_log_call(self, monkeypatch: pytest.MonkeyPatch) -> None:
+ """The stdlib runs a handler's filters outside any ``try``, so an unguarded processor would raise out of ``log.info``."""
+ sink = _RecordingSink()
+
+ def fail(_record: logging.LogRecord) -> None:
+ msg = "this processor is broken"
+ raise RuntimeError(msg)
+
+ def redact(record: logging.LogRecord) -> None:
+ record.redacted = "yes"
+
+ sink.processors.extend([fail, redact])
+ handler = sink.handler
+ reported = io.StringIO()
+ monkeypatch.setattr(sys, "stderr", reported)
+
+ handler.handle(_record(message="one"))
+
+ assert isinstance(handler, _RecordingHandler)
+ assert handler.seen == ["one|yes"]
+ assert "--- Logging error ---" in reported.getvalue()
+ assert "RuntimeError" in reported.getvalue()
+
+ def test_what_a_failed_processor_raised_is_named_by_its_type_and_never_quoted(self, monkeypatch: pytest.MonkeyPatch) -> None:
+ """A processor fails on the record's own values, so its exception is where they end up: the secret the redaction was removing among them."""
+ sink = _RecordingSink()
+
+ def fail(_record: logging.LogRecord) -> None:
+ msg = "cannot scrub sk_live_0123456789abcdef"
+ raise RuntimeError(msg)
+
+ sink.processors.append(fail)
+ handler = sink.handler
+ reported = io.StringIO()
+ monkeypatch.setattr(sys, "stderr", reported)
+
+ handler.handle(_record(message="one"))
+
+ assert "sk_live_0123456789abcdef" not in reported.getvalue()
+ assert "Traceback" not in reported.getvalue()
+ assert "fail" in reported.getvalue()
+
+ def test_a_reporter_that_raises_on_a_failed_processor_does_not_raise_out_of_the_log_call(self, monkeypatch: pytest.MonkeyPatch) -> None:
+ """The report writes to stderr, and a closed stderr makes the write raise; the guard swallows that too, and the record is still delivered."""
+ sink = _RecordingSink()
+
+ def fail(_record: logging.LogRecord) -> None:
+ msg = "this processor is broken"
+ raise RuntimeError(msg)
+
+ sink.processors.append(fail)
+ handler = sink.handler
+ closed = io.StringIO()
+ closed.close()
+ monkeypatch.setattr(sys, "stderr", closed)
+
+ handler.handle(_record(message="one"))
+
+ assert isinstance(handler, _RecordingHandler)
+ assert handler.seen == ["one|-"]
+
def test_redirect_to_stderr_is_a_no_op_on_a_sink_that_writes_to_no_stream(self) -> None:
sink = _RecordingSink()
sink.redirect_to_stderr()
diff --git a/wip/structured-logs/review-deferrals.md b/wip/structured-logs/review-deferrals.md
index dca18c8b9..1685a4536 100644
--- a/wip/structured-logs/review-deferrals.md
+++ b/wip/structured-logs/review-deferrals.md
@@ -170,3 +170,64 @@ The defect is not in dispute and never was. `_ProcessorFilter.filter` runs each
The reason it belongs there rather than here is that the cure is a contract choice and not a guard. A redaction processor that raises means the record is *unredacted*: rendering it anyway leaks exactly what the processor existed to hide, while dropping it contradicts `LogSink`'s promise that it never drops a record. Only the first registrant of a processor is in a position to take that decision, and it arrives with that member. What it owes is recorded on its item: decide the policy and say why, with fail-closed — drop the record and emit a minimal diagnostic carrying none of the unprocessed payload — as the shape the reviewers converged on; implement the guard at the processor boundary, routed to the handler's error path; and cover both the live and replay paths so they can no longer disagree.
A later round that re-raises this should be closed against this entry rather than argued again.
+
+## L-260916-4837d4, round 1 (bar open)
+
+The branch stacks on `feature/Log-sink-seam`, so the pass measured it against `dev` with a focus naming its own commits. The pass fixed everything confirmed inside them: the exception text no sink scrubbed, the structured values scrubbed string by string and never by key, the model and the object the walk returned raw, the cycle branch that handed the raw container back, the cookie family that stopped at the first crumb and ran to the end of a multi-line message, the JSON-entry family that read a value up to the other quote and counted `code` a secret, the control-character escaping that corrupted `data`, the guard that failed open and could itself raise, and the processor a reinstalled sink accumulated. What follows was raised on code this branch does not touch and stands as traced on the sink member.
+
+- **The OTLP sink overwrites a carried `code.*` or `exception.*` field** (codex:review, restating the sink member's round 3). The entry under L-260916-aa6e58, round 3 stands; this branch's commits do not reach `_attributes`.
+- **The migration's safe deletion of a silencing file, at boot** (codex:adversarial, restating the sink member's rounds 1 to 4). The entries above stand, with L-260916-5d142f and L-260916-0e1435 carrying the engine gaps.
+- **Redaction by mapping key was filed and fenced before this round** (L-260916-715f62) and is now closed by the round's own fix; the item is closed by the pull request that carries this branch. The traceback surface filed beside it (L-260916-8bcd3f) is only *advanced* by the same fix: the rendered exception text every structured sink writes is scrubbed, and the `console` sink's Rich traceback, which renders from the exception object, is not — round 2 read that in the code and corrected this entry, which had said the item was closed.
+
+## L-260916-4837d4, round 2 (bar defects)
+
+The pull request opened after round 1, so this round measured the branch against `feature/Log-sink-seam` and every finding was its own. The pass fixed the eight confirmed defects: the top-level field whose name is a secret's, the structured content's message leaking what `data` redacted, the arguments the stdlib's own error report printed raw, the processor guard's `handleError` printing the exception that carried the secret, the sink left holding the processor when its handler build failed, the one unrenderable value that quarantined the whole record, the serialised-entry family reading its names in one case only, and the OTLP export losing an exception's text when it carried no traceback. What follows was read as real and left.
+
+- **A sink's own processor runs after the redaction and can put a secret back** (*refuted as reachable*, cubic). `install_sink` inserts the redaction at index 0 so a sink's processors work on a record the secrets have already left; a processor appended afterwards that adds or restores an attribute is exported unscrubbed. No sink in this repo, in `pipelex-server`, in `pipelex-api`, in `pipelex-mistral-workflows` or in `cocode` appends a processor at all, so the path exists only for an out-of-tree sink, whose own processor is that sink's to answer for. The comment that claimed a later processor "cannot put back what the scrub removed" overstated it and was corrected in the same round. Running the redaction last instead would scrub whatever a sink's processor added, at the cost of handing that processor the raw secret; whichever way it goes, it is a contract decision for the plugin seam rather than a defect of this branch.
+- **The `console` sink's Rich traceback still renders from the exception object** (*verified*, cubic). With `is_rich_tracebacks = true`, the default, an exception whose message holds a secret reads as it was raised on a person's terminal, and its frame locals do too under the non-default `is_tracebacks_show_locals`. Deliberate and documented in `_redact_exception_text`, in `docs/tools/logging.md#redaction` and in `logging-config.md`: the processor scrubs `exc_text`, which is what the stdlib formatter and the `json` and `otlp` sinks write. L-260916-8bcd3f carries the remaining surface, and the round-1 entry above is corrected accordingly.
+- **A mapping key that is itself a secret is carried through** (*verified*, cubic). The walk redacts a value under a secret *name* and copies every key unchanged, so `fields={"cache": {"sk_live_0123456789abcdef": "hit"}}` exports the key, at the top level and at any depth, and a structured content's `data` keeps a key whose message copy the prefix family scrubbed. Reachable but unusual, a dictionary keyed by a credential; scrubbing keys needs a rule for two keys that redact to the same text, which is a design question rather than a line to change.
+- **A control character in a mapping key is not escaped** (*verified*, cubic). The escaping covers a field's string values and not its keys. `json.dumps` escapes the C0 range in a key, so the `json` sink cannot be made to forge a line that way; a C1 byte reaches the line raw in a key where it would have been escaped in a value, the `console` sink renders no fields at all, and OTLP nests keys inside JSON text. Same behaviour as the base.
+- **The OTLP sink exports no exception at all for a record rebuilt from another process** (*verified*, code-review). `_attributes` is gated on `record.exc_info`, which a record prepared by `QueueHandler` or `SocketHandler` no longer carries, although it does carry `exc_text`; the `json` sink writes `exc_text` without `exc_info`. Pre-existing, and untouched by this branch, whose own fix covers the exception that carries no traceback.
+- **A secret nested in text a call rendered itself is beyond the families** (*verified*, codex:review). A structured content is redacted by name before it is rendered, so the facade's own dictionaries are covered whatever depth the secret sits at; an f-string of a dictionary, or a third-party `%s` of one, reaches the processor as text, where the serialised-entry family reads a quoted or bare scalar and cannot see into a nested object. Documented in `logging-config.md` as the limit of that family.
+
+## L-260916-4837d4, rounds 3 and 4 (bar necessity)
+
+Round 3 reported its findings without applying them, which held round 4 at the same bar rather than letting the ladder climb over work nobody had done. Round 4 therefore carried them, and its own reviewers raised most of them again: eleven findings were confirmed by reproduction and all eleven were fixed, every one of them a secret leaving the process, log data destroyed, or a defect the previous pass's own changes introduced. What the two rounds fixed: the cookie family stopping at a quote and, in the same pattern, running to the end of a sentence that merely said "cookie:"; the field escaping the name check under the `field_` collision prefix; the OAuth code class stopping at `%`; the key-prefix family missing the dash spellings the providers issue and matching ordinary snake_case identifiers while dropping the prefix that named the secret; the secret names readable only when something had quoted them, so a query string and a form-encoded body went through; `Authorization: Basic`, a credential pair one step from plaintext; the `extra_patterns` validator accepting a pattern that matches the empty string; a caller's field named `data` landing on the attribute the runtime exempts from escaping; structured content redacted only where the serialization succeeded, so the `repr` fallback carried what it was meant to remove; the quarantine that could itself fail and hand a sink a record neither scrubbed nor stripped; and a sink installed again after a reset being handed back the handler its teardown had closed. What follows was read as real and left.
+
+- **The `console` sink's Rich traceback still renders from the exception object** (*unverified*, cubic, restating rounds 2 and 3). The round-2 entry above stands unchanged, and L-260916-8bcd3f carries the surface. Raised in every round since the branch opened; it is a documented boundary rather than a finding.
+- **A mapping key that is itself a secret, and a control character in one** (*unverified*, cubic and code-review, restating round 2). Both round-2 entries above stand, and L-260916-715f62 carries the first. code-review sharpened the control-character half: a key holding a carriage return and a newline forges a line in exactly the `key=value` text rendering the escaping exists to stop — which no shipped sink writes, the `console` sink rendering no attributes at all, so the exposure is to an out-of-tree sink written against the documented contract.
+- **A plugin that replaces `sink.processors` after the handler is built** (*unverified*, cubic). `_ProcessorFilter` closes over the list the sink held when its handler was constructed, so a sink that assigns a new list afterwards keeps running the old one, and teardown removes the redaction from whichever list the attribute now names. Round 4's `discard_handler` settles it across installs — a fresh handler reads whatever `processors` holds at that install — and leaves it within one. Nothing in this repo replaces the list; the cure is a contract sentence saying the slot is appended to and not reassigned, which belongs with the factory-context question the round-2 entry already parks.
+- **`CYCLE_TEXT` is the one marker Rich deletes** (*unverified*, code-review). Rich's markup parser reads `[` followed by a lowercase letter as a tag and renders an unknown style as nothing, so `[cycle]` disappears where `[REDACTED]`, `[UNRENDERABLE: …]`, `[REDACTION FAILED: …]` and `[ARGUMENTS WITHHELD: …]` all survive on their capital. Not reachable today: the marker only ever lands on a record attribute and the `console` sink renders no attributes. Capitalising it costs nothing and should go with the next change to the markers.
+- **`_withhold_arguments` writes the raw format string** (*unverified*, code-review). The arguments are cleared so `getMessage` never interpolates, and a `%%` stays doubled and a `%(name)s` stays literal. The docstring's claim that the line still says which call it was holds; a reader sees the template rather than the text. Cosmetic.
+- **The doctor infers the cause of a failed install from a global** (*unverified*, code-review, restating round 3). `doctor_cmd.py` reads `log.sink is not None` as proof the failure came out of the held-record replay, which is equally true when `install_sink` refused because a sink was already installed: the row then reports a replay failure whose message says a sink is already installed. Narrow — it needs something else to have installed a sink first — but the row asserts a mechanism the code cannot distinguish. Discriminating on the exception, or comparing `log.sink` with the sink just built, would be exact.
+- **A record held when the boot dies before `install_sink` meets no processor** (*unverified*, code-review). `HoldingLogHandler.close()` hands what it holds to the stdlib's last-resort handler, which writes the unscrubbed message to stderr. The dispatch-level redaction still covers structured content on that path, so only the message-text families are missed, and the window is a boot that dies between `configure` and its sink.
+- **A test that does not isolate the branch it names** (*unverified*, code-review). `test_an_exception_that_carries_no_traceback_still_exports_its_own_text` uses `caplog`, whose handler may set `record.exc_text` before the OTLP handler reads it; for a traceback-less exception both renderings are the same string, so the assertion passes either way. The behaviour it covers is real and separately exercised; the test would want a fixture that does not attach a formatter ahead of the sink.
+
+## L-260916-4837d4, round 4 again, after the dev merge (bar necessity)
+
+Round 4 fixed a critical and left the ladder at its cap, so it read stalled. The developer's call on 2026-09-25 was to review the branch once more after current `dev` had been merged into it, and this pass ran as round 4 again, measured against `feature/Log-sink-seam`. A verifier confirmed five findings by reproduction and the pass fixed them. The `otlp` sink, installed again as the same object after a reset, exported nothing while the docstring, the changelog and the plugin page named it as the case the fresh-handler fix covered, so it now refuses a second handler loudly and the prose says why. A boot that died before its sink arrived handed its held records to the stdlib's last resort unscrubbed, including the message, the exception text and every third-party record, which is broader than the round-3 and round-4 entry above recorded; the holding handler now runs the redaction over each of them first, behind the same guard. The `repr` fallback's name walk skipped tuples. Two lines of `docs/tools/logging.md` still described the `data` move as conditional. Four reset assertions had become vacuous once `discard_handler` made `sink.handler` build a new handler after a reset. What follows was read as real and left, every entry unverified.
+
+- **The key-prefix family misses real `sk-ant-api03-…` and `sk-proj-…` bodies** (*unverified*, code-review and cubic). After the prefix and at most two short segments, the pattern needs an unbroken run of sixteen letters and digits, while those bodies are base64url and carry `-` and `_` throughout, so such a key is either left whole or cut after its first run with the rest logged. The tests use alphanumeric bodies only. This is the completeness of the families, fenced as L-260920-44f6ff.
+- **The plain `name=value` family misses a quoted value** (*unverified*, code-review and cubic). `password='hunter2hunter2'` in a dataclass, attrs or keyword-argument `repr`, and `password: "…"` in YAML, come back unchanged, since only the api-key and signature families accept an opening quote after the separator. `_clean_value` renders a non-model object with `str(value)` before the scrub, so a credentials object passed in a field has exactly that shape, and so does a model inside content JSON refuses on the `repr` fallback. L-260920-44f6ff.
+- **`Authorization: Digest` loses only its first parameter** (*unverified*, cubic). The value pattern stops at the quote, so `response="…"` stays in the line while the documentation lists the scheme as covered. L-260920-44f6ff.
+- **A field or mapping key is matched against the secret names exactly, while text is matched by suffix** (*unverified*, cubic). `fields={"openai_api_key": "…"}` and `db_password` keep their value, where the same entry written as text is caught because the text families have no leading word boundary. L-260920-44f6ff, whose stated grammar should settle one rule for both paths.
+- **The empty-match guard on `extra_patterns` misses zero-width matches in context** (*unverified*, code-review and cubic). `compiled.match("")` refuses `x*` and accepts `\b`, `(?<=a)` and `\b[a-z]*`, which scatter the redaction text through every line, the very failure the validator names. A deployment's own pattern is the only way in; the grammar pass of L-260920-44f6ff is where a check for any zero-width match belongs.
+- **The `console` sink's Rich traceback** (*unverified*, codex:adversarial, restating every round). The round-2 entry stands, and L-260916-8bcd3f carries it.
+- **A mapping key that is itself a secret** (*unverified*, codex:adversarial, restating round 2). L-260916-715f62 carries it.
+- **The doctor keeps a sink whose replay failed** (*unverified*, codex:review). Where the replay failed because the handler is permanently broken, a closed stderr for one, the next doctor log line raises through the same handler and the command ends on the generic unexpected-error path rather than its report. Detaching the failed sink and installing the fallback would keep the report; the case needs a stderr already closed, and it is the same row the round-3 entry on the doctor's global reads.
+
+Rejected on their face: the blanket catch around the redactor (codex:review), which is the fail-closed boundary the owner settled on 2026-09-18 and recorded above; and the claim that the `config-docs` ack rationale understates the change (cubic), since an ack's rationale describes the trigger delta since the previous ack, which that one does.
+
+## L-260916-4837d4, round 4, the verification pass on the round-4 fixes (bar freeze)
+
+The fixes of the pass above had not been reviewed, so the ladder read stalled. The orchestrator spent one verification pass on them, on the developer's recorded call to re-review this member after the dev absorption, and the pass ran as round 4 at the `freeze` bar, which changes nothing but a critical. Its reviewers were cubic and code-review, both pointed at the round-4 fixes and above all at the holding handler now running the redaction at boot, and Codex in review and adversarial modes, which take no focus. None of them found a defect in the otlp refusal, in the redaction the holding handler now runs before the last resort, in the tuple walk, or in the corrected docs and reset assertions; what they said about those fixes is two comments that overstate what the code does. Nothing read as a critical: every leak below is a gap in the protection this branch adds rather than a hole it opens, since the base writes every record unscrubbed, and the bar's definition sends such a defect to the fix clause, which at `freeze` admits nothing. No verifier ran, and every entry is unverified.
+
+- **The holding handler's docstring gives a false reason for not redacting twice** (*unverified*, cubic). `HoldingLogHandler` in `pipelex/tools/log/log_holding.py` says a second pass over a released record "would escape its control characters twice". `escape_control_characters` turns a control character into a printable escape and never escapes a backslash, and `scrub_secrets` is idempotent by its own docstring, so a second pass would change nothing. The design, running the filter on the last-resort path alone, is right; the stated reason should become the plain one, that a released record already meets the sink's own processors.
+- **An unchanged tuple is handed back as it was only when it holds no mapping or list** (*unverified*, cubic). The identity check that 4b2bf35c1 added to `redact_secret_entries` in `pipelex/tools/log/log_redaction.py` compares each item with what the walk returned, but the mapping and list branches always build a new container, so a tuple holding a `dict` or a `list` is rebuilt as a plain tuple even when nothing in it was redacted, and a named tuple loses its field names in the `repr` fallback. The comment beside the check and the function's docstring ("the value itself otherwise") both claim more than that. Cosmetic: no value is lost. Either the mapping and list branches hand back the original when no entry changed, or both comments are corrected.
+- **A message whose rendering changes between two calls escapes the scrub** (*unverified*, codex:review). `_redact_record` renders the message once and replaces `msg` and `args` only when the scrub changed the text, so a sink that calls `getMessage` again re-renders from the original arguments. An argument whose `__str__` answers differently the second time, a mutable object another thread writes to between the processor and the handler's format for one, could put a secret in the second rendering. The window is the time between a handler's filter and its own format, on the same thread. Freezing the rendering into `msg` and clearing `args` after every successful render, not only after one that changed, closes it.
+- **The `repr` fallback's name walk can raise out of a log call** (*unverified*, codex:review). When `json` refuses a structured content, `LogDispatch._render_content` in `pipelex/tools/log/log_dispatch.py` now calls `redact_secret_entries` inside its `except` clause, and a user-defined `Mapping` whose `items()` raises makes that call raise out of `log.info(content)`, where the base's plain `repr` did not. It needs content that `json` refuses with a `TypeError` or `ValueError` while holding such a mapping. Guarding the walk on that path, with a marker in place of the content when the walk itself fails, keeps the promise that a log call never raises.
+- **A model that dumps to a scalar comes back as text** (*unverified*, codex:review). `_clean_value` in `pipelex/tools/log/log_redaction.py` checks for a number, a boolean and `None` before it dumps a model, so a `RootModel[int]`, a `RootModel[None]`, or a model whose serializer returns a scalar falls through to the `str` rendering after its dump, and a field that was `123` or `null` reaches the `json` and `otlp` sinks as `"123"` or `"None"` when redaction is on. Re-entering the cleaner with the dumped value keeps the type.
+- **The key-prefix family misses base64url key bodies, `Authorization: Digest` keeps its later parameters, and a punctuated plain value survives** (*unverified*, code-review and codex:adversarial, restating the pass above). L-260920-44f6ff.
+- **The empty-match guard on `extra_patterns` misses zero-width matches in context** (*unverified*, code-review, restating the pass above). L-260920-44f6ff.
+- **The `console` sink's Rich traceback renders from the exception object** (*unverified*, codex:adversarial, restating every round). L-260916-8bcd3f.
+- **A mapping key that is itself a secret is carried through** (*unverified*, codex:adversarial, restating round 2). L-260916-715f62.