The chain-routing docs cover the PSR-3 logger path (mode flag/auto, channels[], chain: TRUE) well, but they do not document how AuditTrailInterface::event() selects its chain - a separate path with different rules. The result is real operator confusion: rows land in the default chain even though it has an empty channels list and mode: flag.

The behaviour

  • AuditTrail::event() resolves its chain as: a chain whose id equals the channel, else a chain that lists the channel in channels[], else the default chain (see AuditTrail::resolveChain()). It then records the row unconditionally - the chain's mode does NOT gate event(); mode only gates the PSR-3 logger path.
  • So the default chain is the universal catch-all for every event() write (and every chain: TRUE logger call) whose channel no chain claims - regardless of the default chain's mode or channels.

What the docs get wrong / omit

  • consumers.md - "Orchestrator path: event()", step 1 only says "Resolves the active chain for the channel". It omits the resolution order and the records-regardless-of-mode rule.
  • configuration.md - the channels[] section says unmapped-channel entries flow through to whatever chain claims that channel next, or to plain dblog if none does. For event() (and chain: TRUE logger calls) that is incorrect: they land in default, not dblog.
  • The default chain's role as the catch-all is not stated on the configuration page or the chain edit form, so an operator reasonably expects an empty-channels / flag-mode chain to receive nothing.

Proposed changes

  • consumers.md: document the event() chain-resolution order (channel-as-id, then channels[], then default fallback) and that event() records regardless of mode.
  • configuration.md: correct the dblog wording to state that unmapped event() / chain: TRUE writes fall back to the default chain, and describe default as the catch-all.
  • Chain edit form: add a one-line note that the default chain catches unmapped channels regardless of mode.
Command icon Show commands

Start within a Git clone of the project using the version control instructions.

Or, if you do not have SSH keys set up on git.drupalcode.org:

Comments

mably created an issue. See original summary.

mably’s picture

Status: Active » Needs review

Opened MR !18: documents the AuditTrail::event() chain resolution order (id -> channels[] -> default) and that event() always records regardless of mode, scopes the configuration.md mode wording to the generic logger path, and notes the default chain is the catch-all for unclaimed channels. Docs plus one form #description line; no behaviour change.

  • mably committed baddcfe7 on 1.x
    task: #3593057 Document AuditTrail::event() chain resolution and the...
mably’s picture

Status: Needs review » Fixed

Now that this issue is closed, review the contribution record.

As a contributor, attribute any organization that helped you, or if you volunteered your own time.

Maintainers, credit people who helped resolve this issue.

mably’s picture

Merged into 1.x.

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.