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/Console-package-prefix · L-261010-e63a19 (#1410)

Louis Choquel0a42ac09d62f
diff --git a/.drift/acks/config-docs.toml b/.drift/acks/config-docs.toml
index bf24b0109..395da7216 100644
--- a/.drift/acks/config-docs.toml
+++ b/.drift/acks/config-docs.toml
@@ -1,8 +1,8 @@
contract = "config-docs"
-digest = "sha256:55894578aae3a9fbcaaaa2276dd54cb643a13f9face3709649e903b0f7dde02e"
+digest = "sha256:51d1fd8be2b31fb9319489713a54973482d907d85bcdb7a0fbb4d978134a499b"
reviewed_by = "Claude (Opus 5.5)"
-reviewed_at = "2026-10-10T14:00:11Z"
-rationale = "clean-pass: after merging origin/dev, the triggers changed since dev's ack are this branch's four files. ScanConfig.excluded_dirs is a lax frozenset[str] with no before-validator, so a string or a number is refused, and library-config.md names the key and the refusal; LogConfig.package_log_levels is dict[str, LaxEnum[LogLevel]], whose entries logging-config.md describes unchanged; DryRunConfig.validate_image_urls keeps its name and its non-empty rule as an after-validator raising ValueError, as dry-run-config.md says and as this contract's list of live sites names it, and dev's removal of gateway_test from config_cogt.py merged beside it untouched; ConfigModel lost its transform helpers and gained LaxEnum, documented in the kit standards rule. check-migration-schemas passes on all three surfaces after the merge, pipelex-config@8 included, so the annotation changes moved no fingerprint; the narrowings refuse only values that never meant what they said, so no ledger entry is owed."
+reviewed_at = "2026-10-10T16:14:48Z"
+rationale = "real-catch: RichLogConfig gained package_prefix (PackagePrefix libraries|all|none, strict=False) with its default libraries and a prose comment in pipelex/pipelex.toml. Grepping docs/configuration for rich_log found logging-config.md the only page naming the console settings, both in its Display Options excerpt and its full example; both now carry package_prefix, with the three values and the root-logger exception documented under Display Options, and the section intro's claim that the fields and layouts have no setting still holds. configs.py and config_cogt.py are untouched since RichLogConfig lives in log_config.py. The key is additive, so the defaults layer supplies it and no ledger entry is owed: make umig regenerated the pipelex-config@8 golden and check-migration-schemas passes on all three surfaces."
[trigger_files]
"pipelex/cogt/config_cogt.py" = "blob:293ef22ae123266e6a1886d4ffb07f455e5be9e3"
@@ -10,7 +10,7 @@ rationale = "clean-pass: after merging origin/dev, the triggers changed since de
"pipelex/graph/graph_config.py" = "blob:dc0939a6d2730c0a10b88aa1a6e0b2dd583462a6"
"pipelex/language/mthds_config.py" = "blob:353009ad8c59dc5266bdd9dfa42b1ad18b67dca7"
"pipelex/methods/methods_config.py" = "blob:76ca9a0e64f8c10ef6a355aafd0d79d36b09f06a"
-"pipelex/pipelex.toml" = "blob:cd7090d669438aef7364babbee6c11a34f1e1227"
+"pipelex/pipelex.toml" = "blob:0de0caa573498250eb7a7331fa4969cafcbb7946"
"pipelex/system/configuration/__init__.py" = "blob:8b137891791fe96927ad78e64b0aad7bded08bdc"
"pipelex/system/configuration/config_check.py" = "blob:2d5de29aba3d2ce205d3d82b4623f37b53108332"
"pipelex/system/configuration/config_loader.py" = "blob:2850f6b39df6ad2afafefc4d431672cb6ee91ced"
@@ -21,7 +21,7 @@ rationale = "clean-pass: after merging origin/dev, the triggers changed since de
"pipelex/system/configuration/pipe_func_config.py" = "blob:dc8890e914fbcdb611147e42eaa0cd87b32288a5"
"pipelex/system/telemetry/telemetry_config.py" = "blob:068a785d97a2d52ee43e82e723cd944b8b6601bc"
"pipelex/tools/aws/aws_config.py" = "blob:0a7c9dbf276e61355b1fa79b9db8caf252450a39"
-"pipelex/tools/log/log_config.py" = "blob:c7ffacbd2b8fcd85b990fc09755cd3279a23932c"
+"pipelex/tools/log/log_config.py" = "blob:0a893b9e62737b7954a924eaed577ba5c8ef9eaf"
"pipelex/tools/log/log_levels.py" = "blob:12b94e4d4793a70156ac547ee20c9d483910ecae"
"pipelex/tools/network/network_config.py" = "blob:e12d1d0e4a40d04859f10a77addeaf8fe2b00414"
"pipelex/tools/secrets/secrets_config.py" = "blob:cf30aaec1c76c9cabc0531a5b9fe681e153d7024"
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e374986db..9a2ad1e88 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,7 @@
- **`Rating` carries the label of its level**: the `Rating` native has an optional `label`, which the MTHDS standard's native set pinned at `5.0.0` defines as the name of the selected level when the scale declares labels, held in `RatingContent.label` and stated by the input-form descriptor, the I/O contracts and the generated Python and TypeScript types. A `PipeJudge` declares no labelled levels yet, so a `Rating` it produces carries no label, while a `PipeLLM` whose output is `Rating`, or any other producer, may fill it like any optional member; either way a `Rating` renders in a prompt as its label when it has one and as its level otherwise, so `$severity` reads `Workaround available` for a rating carrying that label and `1` for one carrying none, and its JSON rendering carries the label only when present. Since a crate materializes the pinned definition, a crate whose methods use `Rating` gets a new normalized fingerprint, and types generated before this release gain the field when `pipelex codegen types` regenerates them.
- **A log line's advice in `user_action`**: a log call puts what its reader should do in a `user_action` field, one imperative sentence, and the `console` sink prints it whole on a line of its own under the record, after `→ `, in cyan, while every other sink writes it as a field like any other. Pipelex's own warnings carry their advice there, such as `Run pipelex migrate to update it` on a stale configuration file, so their message says only what happened.
+- **`package_prefix` chooses which console lines name their package**: a setting under `[runtime.log.rich_log]` decides which lines the `console` sink starts with their logger's top-level package name, dimmed. `libraries`, the default, keeps the rule that names another library's package and leaves a line from `pipelex` or a `pipelex_` package bare; `all` names every line's package, so `pipelex: `, `pipelex_api: ` and a plugin's name tell apart which component spoke; `none` names none. A line logged on the root logger never carries one.
### Changed
diff --git a/docs/configuration/config-practical/logging-config.md b/docs/configuration/config-practical/logging-config.md
index e14564048..ac9a42c59 100644
--- a/docs/configuration/config-practical/logging-config.md
+++ b/docs/configuration/config-practical/logging-config.md
@@ -160,12 +160,22 @@ is_show_time = false
is_show_level = true
is_show_path = false
is_link_path_enabled = true
+package_prefix = "libraries" # or "all", or "none"
```
- `is_show_time`: Show timestamp in logs
- `is_show_level`: Show log level
- `is_show_path`: Show the source file and line that logged each record, in a column at the right of the line. It is off by default: the column takes about 25 characters of every line and makes a long one wrap
- `is_link_path_enabled`: Make that path clickable, where the terminal supports links
+- `package_prefix`: Choose which lines start with their logger's top-level package name, dimmed, such as `httpx: ` (see [Another library's lines](../../tools/logging.md#another-librarys-lines))
+
+`package_prefix` takes one of three values:
+
+- `libraries`, the default: a line another library logged starts with its package name, and a line from `pipelex` or from a package whose name starts with `pipelex_`, the API server's `pipelex_api` or a plugin named that way, has none. A plugin whose package is named otherwise counts as another library
+- `all`: every line starts with its package name, Pipelex's own included, so `pipelex: `, `pipelex_api: ` and a plugin's name tell the runtime, the API server and the plugin apart
+- `none`: no line has one
+
+A line logged on the root logger names no package, so it never starts with one, whatever the value.
### Syntax Highlighting
@@ -311,6 +321,7 @@ is_tracebacks_word_wrap = true
is_tracebacks_show_locals = false
tracebacks_suppress = []
keywords_to_hilight = ["error", "warning", "failed"]
+package_prefix = "libraries"
[runtime.log.otlp]
headers = {}
diff --git a/docs/tools/logging.md b/docs/tools/logging.md
index 6506b4e46..5a3644101 100644
--- a/docs/tools/logging.md
+++ b/docs/tools/logging.md
@@ -268,13 +268,15 @@ Every other sink writes `user_action` as the field it is, so a log store can cou
### Another library's lines
-A line has no prefix when its logger's top-level package is `pipelex` or starts with `pipelex_`, which covers the runtime, the API server's `pipelex_api` and a plugin whose package is named that way, and none when it was logged on the root logger. A line another library logged, an HTTP client's or a provider SDK's, starts with the top-level package of its logger, dimmed, so the reader still sees which library spoke:
+By default, a line has no prefix when its logger's top-level package is `pipelex` or starts with `pipelex_`, which covers the runtime, the API server's `pipelex_api` and a plugin whose package is named that way, and none when it was logged on the root logger. A line another library logged, an HTTP client's or a provider SDK's, starts with the top-level package of its logger, dimmed, so the reader still sees which library spoke:
```text
INFO httpx: HTTP Request: POST https://api.example.com/v1/chat/completions "HTTP/1.1 200 OK"
```
-Your own application's lines, logged through `log` from a module of `myapp`, start with `myapp: ` the same way. The package name is styled text the console adds, never part of the message, so no other sink writes it: they carry the logger's full name as the record's own.
+Your own application's lines, logged through `log` from a module of `myapp`, start with `myapp: ` the same way, and so does a plugin whose package is not named `pipelex_…`. The package name is styled text the console adds, never part of the message, so no other sink writes it: they carry the logger's full name as the record's own.
+
+The console setting `package_prefix` under `[runtime.log.rich_log]` changes which lines carry the prefix. The default, `libraries`, is the rule above; `all` puts it on every line, Pipelex's own included, where `pipelex: `, `pipelex_api: ` and a plugin's name tell apart which component spoke; `none` puts it on no line. A line logged on the root logger never carries one (see [Display options](../configuration/config-practical/logging-config.md#display-options)).
### The style map
diff --git a/docs/under-the-hood/log-sink-plugins.md b/docs/under-the-hood/log-sink-plugins.md
index 3c9d207a1..baf4a430e 100644
--- a/docs/under-the-hood/log-sink-plugins.md
+++ b/docs/under-the-hood/log-sink-plugins.md
@@ -130,7 +130,7 @@ class LogSinkPlugin:
| Sink | What it does | Where it reads its settings |
|------|--------------|-----------------------------|
| `json` | One JSON object per line on the configured stream: `time`, `severity`, `logger`, `message`, `exception` when there is one, `trace_id`, `span_id` and `trace_flags` in hex when OpenTelemetry's current span names a trace, under the keys OpenTelemetry specifies for trace context in a JSON log that is not OTLP, `pipelex.trace_id` and `pipelex.span_id` in hex when a Pipelex span is active, then the fields, the context identifiers and `data` flat beside them, a field named like one of those keys under a `field_` prefix on every line, a non-finite float as the string `"NaN"`, `"Infinity"` or `"-Infinity"`. The key names are the ones the CloudWatch agent, the Google Cloud Logging agent and any OTLP collector ingest without a parser, and no ANSI ever. What the hosted plane's runner and worker select. | `console_log_target` |
-| `console` | The Rich handler with every `[runtime.log.rich_log]` setting, which reads no message as markup, shows a record's fields after its message, coloured by name, starts a line another library logged with that library's top-level package name, dimmed, and renders the layouts a call names (see [Console rendering](../tools/logging.md#console-rendering)). The column naming each record's source file is off unless `is_show_path` turns it on. Rich, the `cli` extra, is imported when the handler is built, and a process that selects another sink never loads it through this path. | `console_log_target`, `[runtime.log.rich_log]` |
+| `console` | The Rich handler with every `[runtime.log.rich_log]` setting, which reads no message as markup, shows a record's fields after its message, coloured by name, starts a line another library logged with that library's top-level package name, dimmed, and renders the layouts a call names (see [Console rendering](../tools/logging.md#console-rendering)). The column naming each record's source file is off unless `is_show_path` turns it on, and `package_prefix` chooses which lines carry the package name: another library's by default, every line's, or none. Rich, the `cli` extra, is imported when the handler is built, and a process that selects another sink never loads it through this path. | `console_log_target`, `[runtime.log.rich_log]` |
| `otlp` | The OpenTelemetry logs signal: a `LoggerProvider` carrying the same service identity as the tracer, a `BatchLogRecordProcessor` and the OTLP HTTP log exporter. The message is the body, the level maps onto the OTel severity scale, the fields, identifiers and `data` ride as attributes (a mapping as JSON text), an exception lands under the `exception.*` semantic-convention keys, each record is filed under OpenTelemetry's current span, with the active Pipelex span as the `pipelex.trace_id` and `pipelex.span_id` attributes, and a collector receives the logs beside the spans the runtime already exports. The keys the sink writes itself, the `code.*` source location, the two `pipelex.*` keys and the `exception.*` set, are reserved on every record whether or not it carries an exception, so a field named like one of them rides under a `field_` prefix rather than being overwritten. A filter on the handler rejects the records of the sink's own export path, the SDK's by logger name and the transport's by the context value the SDK sets around an export, before the handler's lock is taken, so an export failure never re-enters the pipeline and a shutdown never waits on itself. | `[runtime.log.otlp]` |
| `gcp` | Google Cloud Logging through the `google-cloud-logging` client library, behind the `gcp-logging` extra. Each record becomes one struct entry: the level maps onto the Cloud Logging severity scale (which has nothing below `DEBUG`, so `VERBOSE` lands there), the message, the logger, the exception and the fields become the JSON payload, the run-scoped identifiers become the entry's labels, which is what Cloud Logging indexes, the entry's `trace`, `spanId` and `traceSampled` name OpenTelemetry's current span, the trace project-qualified, and the active Pipelex span rides in the payload as `pipelex.trace_id` and `pipelex.span_id`. The entries leave through the client library's background-thread transport, which batches them off the calling thread. The factory refreshes the credentials once before that transport starts, so credentials Google refuses stop the boot with `GcpLogSinkCredentialsError` rather than losing every record in silence. **Most processes on Google Cloud want `json` instead**: a platform whose logging agent reads the container's stdout, Cloud Run and GKE among them, ingests what that sink writes and needs no client at all; `gcp` is for a process with no such agent in front of it, or one writing to a log or a project that is not the ambient one. | `[runtime.log.gcp]` |
diff --git a/pipelex/migration/goldens/pipelex-config/[email protected] b/pipelex/migration/goldens/pipelex-config/[email protected]
index cd7090d66..0de0caa57 100644
--- a/pipelex/migration/goldens/pipelex-config/[email protected]
+++ b/pipelex/migration/goldens/pipelex-config/[email protected]
@@ -97,7 +97,10 @@ pipelex = "INFO"
# The settings of the "console" sink. is_show_path adds a column at the right of every line naming the
# source file and line that logged it, which makes a long line wrap; is_link_path_enabled makes that
-# path clickable where the terminal supports links.
+# path clickable where the terminal supports links. package_prefix chooses which lines start with their
+# logger's top-level package name, dimmed: "libraries" names another library's package and leaves a
+# line from pipelex or a pipelex_ package bare, "all" names every line's package, Pipelex's own
+# included, and "none" names none. A line logged on the root logger never carries one.
[runtime.log.rich_log]
is_show_time = false
is_show_level = true
@@ -109,6 +112,7 @@ is_tracebacks_word_wrap = true
is_tracebacks_show_locals = false
tracebacks_suppress = []
keywords_to_hilight = []
+package_prefix = "libraries"
# The settings of the "otlp" sink. An endpoint key, when set, names the collector's logs URL
# (for instance "http://localhost:4318/v1/logs"); left unset, the exporter follows the OpenTelemetry
diff --git a/pipelex/migration/goldens/pipelex-config/[email protected] b/pipelex/migration/goldens/pipelex-config/[email protected]
index 0765458c6..307a95ea1 100644
--- a/pipelex/migration/goldens/pipelex-config/[email protected]
+++ b/pipelex/migration/goldens/pipelex-config/[email protected]
@@ -1228,6 +1228,17 @@
"default": [],
"open_node": false
},
+ "runtime.log.rich_log.package_prefix": {
+ "value_type": "enum",
+ "required": true,
+ "enum_members": [
+ "all",
+ "libraries",
+ "none"
+ ],
+ "default": "libraries",
+ "open_node": false
+ },
"runtime.log.rich_log.tracebacks_suppress": {
"value_type": "list[str]",
"required": true,
diff --git a/pipelex/pipelex.toml b/pipelex/pipelex.toml
index cd7090d66..0de0caa57 100644
--- a/pipelex/pipelex.toml
+++ b/pipelex/pipelex.toml
@@ -97,7 +97,10 @@ pipelex = "INFO"
# The settings of the "console" sink. is_show_path adds a column at the right of every line naming the
# source file and line that logged it, which makes a long line wrap; is_link_path_enabled makes that
-# path clickable where the terminal supports links.
+# path clickable where the terminal supports links. package_prefix chooses which lines start with their
+# logger's top-level package name, dimmed: "libraries" names another library's package and leaves a
+# line from pipelex or a pipelex_ package bare, "all" names every line's package, Pipelex's own
+# included, and "none" names none. A line logged on the root logger never carries one.
[runtime.log.rich_log]
is_show_time = false
is_show_level = true
@@ -109,6 +112,7 @@ is_tracebacks_word_wrap = true
is_tracebacks_show_locals = false
tracebacks_suppress = []
keywords_to_hilight = []
+package_prefix = "libraries"
# The settings of the "otlp" sink. An endpoint key, when set, names the collector's logs URL
# (for instance "http://localhost:4318/v1/logs"); left unset, the exporter follows the OpenTelemetry
diff --git a/pipelex/tools/log/console_log_sink.py b/pipelex/tools/log/console_log_sink.py
index 9cae4e3d3..26d2e7c13 100644
--- a/pipelex/tools/log/console_log_sink.py
+++ b/pipelex/tools/log/console_log_sink.py
@@ -4,9 +4,10 @@ The handler reads no message as Rich markup: a message is the caller's text, mad
and prints as written, ``list[int]`` and ``[red]`` included. The colour is the sink's own: it renders a
record's fields after its message as a styled ``key=value`` suffix, a record's advice on a line of its own
under it, and a record that names a layout through that layout's template; what is shown and how it is
-coloured is in ``console_fields`` and ``console_layouts``. A line from another library than Pipelex starts
-with that library's package name, dimmed, as ``console_prefix`` decides; a Pipelex line has no prefix. A
-traceback printed as text, with Rich tracebacks off, goes under the line, after the suffix and the advice.
+coloured is in ``console_fields`` and ``console_layouts``. A line starts with its logger's package name,
+dimmed, when the ``package_prefix`` setting asks for it, as ``console_prefix`` decides: by default a line from
+another library than Pipelex does and a Pipelex line does not. A traceback printed as text, with Rich
+tracebacks off, goes under the line, after the suffix and the advice.
Rich is the ``cli`` extra. It is imported when the handler is built and nowhere else in this module, so
this module asks for Rich only where this sink is the one selected; a process that selects another sink
@@ -28,7 +29,7 @@ from typing_extensions import override
from pipelex.tools.log.console_fields import advice_segments, attached_fields, field_suffix_segments
from pipelex.tools.log.console_layouts import console_layout
-from pipelex.tools.log.console_prefix import foreign_package_name
+from pipelex.tools.log.console_prefix import prefixed_package_name
from pipelex.tools.log.log_config import HighlighterName
from pipelex.tools.log.log_fields import LAYOUT_MARK
from pipelex.tools.log.log_sink import LogSink, LogSinkMethod, stream_for_target
@@ -47,7 +48,7 @@ CONSOLE_SINK_MISSING_MESSAGE = (
f"or select the '{LogSinkMethod.JSON}' sink in [runtime.log] for a process with no terminal."
)
-#: What follows another library's package name before its message, and the style the two are printed in.
+#: What follows a line's package name before its message, and the style the two are printed in.
PACKAGE_PREFIX_SEPARATOR = ": "
PACKAGE_PREFIX_STYLE = "dim"
@@ -69,6 +70,8 @@ class ConsoleLogSink(LogSink):
from rich.logging import RichHandler
from rich.text import Text
+ config = self._rich_log_config
+
# Declared here because ``RichHandler`` is imported here, which is what keeps Rich off the import
# path of a process that selected another sink. ``RichHandler`` overrides ``emit`` and does not
# restore the ``try``/``handleError`` the stdlib's own handlers put around theirs, so anything
@@ -89,7 +92,7 @@ class ConsoleLogSink(LogSink):
def render_message(self, record: logging.LogRecord, message: str) -> ConsoleRenderable:
"""The message, or the layout the call named, then the fields as a styled ``key=value`` suffix, then any advice and traceback text.
- A line from another library than Pipelex starts with that library's package name, dimmed. The message
+ A line starts with its logger's package name, dimmed, when ``package_prefix`` asks for it. The message
is plain text, read as no markup, and the prefix, the suffix and the advice are assembled as ``Text``
from styled segments around it after the highlighter has run on the message, so the highlighter never
reads a field's value. The advice, a ``user_action`` field, prints on a line of its own under the line.
@@ -127,7 +130,7 @@ class ConsoleLogSink(LogSink):
if message_text is None:
message_text = super().render_message(record, message_line)
if isinstance(message_text, Text):
- package_name = foreign_package_name(logger_name=record.name)
+ package_name = prefixed_package_name(logger_name=record.name, package_prefix=config.package_prefix)
if package_name is not None:
message_text = Text.assemble((f"{package_name}{PACKAGE_PREFIX_SEPARATOR}", PACKAGE_PREFIX_STYLE), message_text)
segments = field_suffix_segments(fields=fields, presented_fields=presented_fields)
@@ -142,7 +145,6 @@ class ConsoleLogSink(LogSink):
message_text.append_text(Text(appended_text))
return message_text
- config = self._rich_log_config
highlighter: Highlighter
match config.highlighter_name:
case HighlighterName.JSON:
diff --git a/pipelex/tools/log/console_prefix.py b/pipelex/tools/log/console_prefix.py
index 27c5818fe..4f2a48c5d 100644
--- a/pipelex/tools/log/console_prefix.py
+++ b/pipelex/tools/log/console_prefix.py
@@ -1,10 +1,14 @@
-"""What the console puts before a record's message: nothing on a Pipelex line, the package name of any other library.
+"""What the console puts before a record's message: its logger's top-level package name, on the lines the setting chooses.
-Nearly every line on a Pipelex console is Pipelex's own, so a prefix naming Pipelex says nothing and costs columns. A
-line from another library, an HTTP client's or a provider SDK's, starts with its logger's top-level package name, which
-the sink prints dimmed, so the reader still sees which library spoke. The root logger's lines carry no prefix either.
+Nearly every line on a Pipelex console is Pipelex's own, so by default a prefix naming Pipelex says nothing and costs
+columns: the ``package_prefix`` setting's ``libraries`` value leaves a Pipelex line bare and starts a line from another
+library, an HTTP client's or a provider SDK's, with its logger's top-level package name, which the sink prints dimmed,
+so the reader still sees which library spoke. ``all`` names the package on every line, where it tells the runtime, the
+API server and a plugin apart, and ``none`` names it on none. The root logger's lines carry no prefix under any value.
"""
+from pipelex.tools.log.log_config import PackagePrefix
+
#: The logger of a record logged on the root logger, which names no library.
ROOT_LOGGER_NAME = "root"
@@ -12,19 +16,25 @@ ROOT_LOGGER_NAME = "root"
PIPELEX_PACKAGE = "pipelex"
#: What starts the top-level package of a Pipelex distribution beside the runtime, ``pipelex_api`` or a plugin's named that
-#: way. A plugin whose package is named otherwise gets its prefix like any other library.
+#: way. A plugin whose package is named otherwise counts as another library.
PIPELEX_PACKAGE_PREFIX = f"{PIPELEX_PACKAGE}_"
-def foreign_package_name(*, logger_name: str) -> str | None:
- """The top-level package of a logger that is not Pipelex's, which the console prints before the message; else ``None``.
+def prefixed_package_name(*, logger_name: str, package_prefix: PackagePrefix) -> str | None:
+ """The top-level package of the logger, which the console prints before the message, or ``None`` for no prefix.
- A logger under ``pipelex`` or a ``pipelex_`` package, the runtime's, the API server's or a plugin's named that way,
- and the root logger have none.
+ Under ``libraries``, a logger under ``pipelex`` or a ``pipelex_`` package, the runtime's, the API server's or a
+ plugin's named that way, has none. The root logger has none under any value.
"""
if logger_name == ROOT_LOGGER_NAME:
return None
package = logger_name.split(".", 1)[0]
- if package == PIPELEX_PACKAGE or package.startswith(PIPELEX_PACKAGE_PREFIX):
- return None
- return package
+ match package_prefix:
+ case PackagePrefix.LIBRARIES:
+ if package == PIPELEX_PACKAGE or package.startswith(PIPELEX_PACKAGE_PREFIX):
+ return None
+ return package
+ case PackagePrefix.ALL:
+ return package
+ case PackagePrefix.NONE:
+ return None
diff --git a/pipelex/tools/log/log_config.py b/pipelex/tools/log/log_config.py
index c7ffacbd2..0a893b9e6 100644
--- a/pipelex/tools/log/log_config.py
+++ b/pipelex/tools/log/log_config.py
@@ -48,6 +48,19 @@ class CallerInfoTemplate(StrEnum):
return "{func} {module} {line}"
+class PackagePrefix(StrEnum):
+ """Which lines the ``console`` sink starts with their logger's top-level package name.
+
+ ``LIBRARIES`` names another library's package and leaves a line from ``pipelex`` or a ``pipelex_`` package bare,
+ ``ALL`` names the package of every line logged under a named logger, and ``NONE`` names none. A line logged on the
+ root logger names no package under any value.
+ """
+
+ LIBRARIES = "libraries"
+ ALL = "all"
+ NONE = "none"
+
+
class RichLogConfig(ConfigModel):
"""The settings of the ``console`` sink's Rich handler. Read by the sink; this module imports no Rich."""
@@ -61,6 +74,7 @@ class RichLogConfig(ConfigModel):
is_tracebacks_show_locals: bool
tracebacks_suppress: list[str]
keywords_to_hilight: list[str]
+ package_prefix: PackagePrefix = Field(strict=False)
class OtlpLogSinkConfig(ConfigModel):
diff --git a/tests/helpers/console_log_rendering.py b/tests/helpers/console_log_rendering.py
index 7ea214b9b..e49c6932b 100644
--- a/tests/helpers/console_log_rendering.py
+++ b/tests/helpers/console_log_rendering.py
@@ -41,8 +41,9 @@ def package_log_config() -> LogConfig:
return LogConfig.model_validate(config_dict["runtime"]["log"])
-def console_handler() -> RichHandler:
- handler = ConsoleLogSink(rich_log_config=package_log_config().rich_log, target=ConsoleTarget.STDERR).handler
+def console_handler(*, rich_log_config: RichLogConfig | None = None) -> RichHandler:
+ """The console sink's handler, with the package's console settings unless others are given."""
+ handler = ConsoleLogSink(rich_log_config=rich_log_config or package_log_config().rich_log, target=ConsoleTarget.STDERR).handler
assert isinstance(handler, RichHandler)
return handler
@@ -60,9 +61,12 @@ def record_with_fields(
return record
-def rendered_text(*, record: logging.LogRecord) -> Text:
- """The ``Text`` the console sink's handler renders for the record's message line, styles and all."""
- handler = console_handler()
+def rendered_text(*, record: logging.LogRecord, rich_log_config: RichLogConfig | None = None) -> Text:
+ """The ``Text`` the console sink's handler renders for the record's message line, styles and all.
+
+ The handler takes the package's console settings unless others are given.
+ """
+ handler = console_handler(rich_log_config=rich_log_config)
record.message = record.getMessage()
assert handler.formatter is not None
rendered = handler.render_message(record, handler.formatter.formatMessage(record))
diff --git a/tests/unit/pipelex/tools/test_log_console_prefix.py b/tests/unit/pipelex/tools/test_log_console_prefix.py
new file mode 100644
index 000000000..90865a722
--- /dev/null
+++ b/tests/unit/pipelex/tools/test_log_console_prefix.py
@@ -0,0 +1,48 @@
+"""Which package name the console prints before a line's message, under each value of the ``package_prefix`` setting.
+
+``libraries`` names another library's package and leaves a Pipelex line bare, ``all`` names every named logger's
+package, Pipelex's own included, and ``none`` names nothing. A line on the root logger names no package under any value.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from pipelex.tools.log.console_prefix import prefixed_package_name
+from pipelex.tools.log.log_config import PackagePrefix
+from tests.helpers.console_log_rendering import package_log_config
+
+LOGGER_NAMES = [
+ "pipelex.cogt.inference",
+ "pipelex_api.security",
+ "pipelex_temporal.worker",
+ "manifold_client.manifold_native_client",
+ "httpx._client",
+ "root",
+]
+LOGGER_IDS = ["the runtime", "the API server", "a pipelex_ plugin", "a plugin named otherwise", "another library", "the root logger"]
+
+
+class TestPrefixedPackageName:
+ @pytest.mark.parametrize(
+ ("logger_name", "expected"),
+ list(zip(LOGGER_NAMES, [None, None, None, "manifold_client", "httpx", None], strict=True)),
+ ids=LOGGER_IDS,
+ )
+ def test_libraries_names_the_package_of_a_logger_outside_pipelex_only(self, logger_name: str, expected: str | None) -> None:
+ assert prefixed_package_name(logger_name=logger_name, package_prefix=PackagePrefix.LIBRARIES) == expected
+
+ @pytest.mark.parametrize(
+ ("logger_name", "expected"),
+ list(zip(LOGGER_NAMES, ["pipelex", "pipelex_api", "pipelex_temporal", "manifold_client", "httpx", None], strict=True)),
+ ids=LOGGER_IDS,
+ )
+ def test_all_names_the_package_of_every_named_logger(self, logger_name: str, expected: str | None) -> None:
+ assert prefixed_package_name(logger_name=logger_name, package_prefix=PackagePrefix.ALL) == expected
+
+ @pytest.mark.parametrize("logger_name", LOGGER_NAMES, ids=LOGGER_IDS)
+ def test_none_names_no_package(self, logger_name: str) -> None:
+ assert prefixed_package_name(logger_name=logger_name, package_prefix=PackagePrefix.NONE) is None
+
+ def test_the_shipped_default_is_libraries(self) -> None:
+ assert package_log_config().rich_log.package_prefix == PackagePrefix.LIBRARIES
diff --git a/tests/unit/pipelex/tools/test_log_console_sink.py b/tests/unit/pipelex/tools/test_log_console_sink.py
index 1d28d35a0..db9e18c7e 100644
--- a/tests/unit/pipelex/tools/test_log_console_sink.py
+++ b/tests/unit/pipelex/tools/test_log_console_sink.py
@@ -23,7 +23,7 @@ from pipelex.system.console_target import ConsoleTarget
from pipelex.tools.log.console_fields import ADVICE_STYLE, one_line_text
from pipelex.tools.log.console_layouts import LogLayout
from pipelex.tools.log.console_log_sink import ConsoleLogSink
-from pipelex.tools.log.log_config import HighlighterName, LogConfig, RichLogConfig
+from pipelex.tools.log.log_config import HighlighterName, LogConfig, PackagePrefix, RichLogConfig
from pipelex.tools.log.log_fields import RICH_MARKUP_ATTRIBUTE, USER_ACTION_FIELD, attach_log_record_extra
from pipelex.tools.log.log_redaction import CYCLE_TEXT
from pipelex.tools.misc.toml_utils import load_toml_from_path
@@ -203,6 +203,30 @@ class TestConsoleLogSink:
assert text.plain == "httpx: HTTP Request: POST attempt=2"
assert "dim" in styles_of(text=text, fragment="httpx: ")
+ def test_with_package_prefix_all_a_pipelex_line_starts_with_its_package_name_dimmed(self) -> None:
+ config = _package_rich_log_config().model_copy(update={"package_prefix": PackagePrefix.ALL})
+ record = record_with_fields(message="Model resolved", logger_name="pipelex.cogt.inference", extra={"attempt": 2})
+
+ text = rendered_text(record=record, rich_log_config=config)
+
+ assert text.plain == "pipelex: Model resolved attempt=2"
+ assert "dim" in styles_of(text=text, fragment="pipelex: ")
+
+ def test_with_package_prefix_all_a_root_line_still_carries_no_prefix(self) -> None:
+ config = _package_rich_log_config().model_copy(update={"package_prefix": PackagePrefix.ALL})
+
+ text = rendered_text(record=record_with_fields(message="Loaded the library", logger_name="root"), rich_log_config=config)
+
+ assert text.plain == "Loaded the library"
+
+ def test_with_package_prefix_none_a_line_from_another_library_carries_no_prefix(self) -> None:
+ config = _package_rich_log_config().model_copy(update={"package_prefix": PackagePrefix.NONE})
+ record = record_with_fields(message="HTTP Request: POST", logger_name="httpx._client", extra={"attempt": 2})
+
+ text = rendered_text(record=record, rich_log_config=config)
+
+ assert text.plain == "HTTP Request: POST attempt=2"
+
@pytest.mark.parametrize("is_show_path", [False, True], ids=["the default", "is_show_path"])
def test_the_source_path_column_shows_only_when_the_setting_asks_for_it(self, is_show_path: bool) -> None:
config = _package_rich_log_config().model_copy(update={"is_show_path": is_show_path, "is_link_path_enabled": False})
diff --git a/tests/unit/pipelex/tools/test_log_console_sink_without_rich.py b/tests/unit/pipelex/tools/test_log_console_sink_without_rich.py
index 9b38dd21c..bf548b37a 100644
--- a/tests/unit/pipelex/tools/test_log_console_sink_without_rich.py
+++ b/tests/unit/pipelex/tools/test_log_console_sink_without_rich.py
@@ -27,7 +27,7 @@ _GUARD_SCRIPT = textwrap.dedent(
from pipelex.system.console_target import ConsoleTarget
from pipelex.system.exceptions import MissingDependencyError
from pipelex.tools.log.console_log_sink import ConsoleLogSink
- from pipelex.tools.log.log_config import HighlighterName, RichLogConfig
+ from pipelex.tools.log.log_config import HighlighterName, PackagePrefix, RichLogConfig
from pipelex.tools.misc.rich_extra import RICH_EXTRA_NAME
sink = ConsoleLogSink(
@@ -42,6 +42,7 @@ _GUARD_SCRIPT = textwrap.dedent(
is_tracebacks_show_locals=False,
tracebacks_suppress=[],
keywords_to_hilight=[],
+ package_prefix=PackagePrefix.LIBRARIES,
),
target=ConsoleTarget.STDERR,
)