Pattern event policy

This page documents the ready-to-use pattern event policy API.

Pattern event policy is the built-in implementation of the event policy contract.

It belongs to the logging-width layer:

LogEventMeta -> policy decision -> accepted / rejected

The policy receives event metadata, checks it against ordered pattern rules, and returns whether the event is enabled.

It does not inspect payload data, does not normalize payload values, does not create LogEvent, and does not deliver anything to a sink.

Public API

The pattern event policy API contains four public objects:

PatternLogEventPolicyAction
PatternLogEventPolicyRuleConfig
PatternLogEventPolicyConfig
PatternLogEventPolicy

PatternLogEventPolicyAction defines the rule decision.

PatternLogEventPolicyRuleConfig describes one ordered rule.

PatternLogEventPolicyConfig describes the complete policy configuration.

PatternLogEventPolicy applies the configuration to LogEventMeta.

enum mvx.common.logger.PatternLogEventPolicyAction(value)

Action returned by a matching pattern event policy rule.

Member Type:: str

Valid values are as follows:

ALLOW = <PatternLogEventPolicyAction.ALLOW: 'allow'>: Allow the matching event

DENY = <PatternLogEventPolicyAction.DENY: 'deny'>: Deny the matching event

class mvx.common.logger.PatternLogEventPolicyRuleConfig(action, events=<factory>, event_namespaces=<factory>, event_names=<factory>, entity_ids=<factory>, source_paths=<factory>, source_funcs=<factory>)

Configuration of one ordered pattern event policy rule.

A rule contains an action and optional pattern groups used to match LogEventMeta fields.

Pattern groups inside one rule are combined as logical and: every non-empty group must match the event metadata. Patterns inside one group are alternatives: at least one pattern in that group must match.

Empty pattern groups do not restrict the rule. A rule without any pattern groups matches every event.

Rules are evaluated by PatternLogEventPolicy in configuration order. The first matching rule decides whether the event is enabled.

Parameters:

action (PatternLogEventPolicyAction) – action returned when the rule matches.
events (tuple[str, ...]) – shell-style patterns matched against the composed event key.
event_namespaces (tuple[str, ...]) – shell-style patterns matched against event namespace.
event_names (tuple[str, ...]) – shell-style patterns matched against event name.
entity_ids (tuple[str, ...]) – shell-style patterns matched against entity id.
source_paths (tuple[str, ...]) – shell-style patterns matched against source path.
source_funcs (tuple[str, ...]) – shell-style patterns matched against source function.

classmethod from_mapping(data)

Build rule configuration from a mapping.

The mapping must contain the action field with value "allow" or "deny". Pattern fields are optional. Missing pattern fields and fields explicitly set to None are treated as empty pattern groups.

Supported pattern fields are:

events;
event_namespaces;
event_names;
entity_ids;
source_paths;
source_funcs.

Pattern fields must be sequences of non-empty strings. String values are stripped before they are stored in the resulting configuration.

Parameters:

data (Mapping[str, Any]) – mapping containing rule configuration.

Return type:

PatternLogEventPolicyRuleConfig

Returns:

parsed rule configuration.

Raises:

TypeError – if a field has an invalid type.
ValueError – if action is empty, unknown, or a pattern field contains an empty string.

class mvx.common.logger.PatternLogEventPolicyConfig(default_enabled=True, rules=<factory>)

Configuration of PatternLogEventPolicy.

The configuration defines a fallback decision and an ordered rule list.

default_enabled is returned when no rule matches. rules are checked from first to last. The first matching rule wins.

The configuration is immutable and can be safely shared as read-only policy configuration.

Parameters:

default_enabled (bool) – fallback decision used when no rule matches.
rules (tuple[PatternLogEventPolicyRuleConfig, ...]) – ordered sequence of pattern policy rules.

classmethod from_mapping(data)

Build pattern policy configuration from a mapping.

The mapping may contain:

default_enabled: boolean fallback decision, defaults to True;
rules: sequence of rule mappings, defaults to an empty sequence.

Rule mappings are parsed by PatternLogEventPolicyRuleConfig.from_mapping.

Parameters:

data (Mapping[str, Any]) – mapping containing policy configuration.

Return type:

PatternLogEventPolicyConfig

Returns:

parsed policy configuration.

Raises:

TypeError – if a field has an invalid type.
ValueError – if a nested rule contains an invalid value.

class mvx.common.logger.PatternLogEventPolicy(config)

Ready-to-use event policy based on ordered metadata pattern rules.

The policy implements the event policy contract used by LogContext. It receives LogEventMeta and returns whether the event is enabled.

Matching is based only on event metadata. The policy does not inspect payload, normalized payload, logging level, event type, timestamp, sink, or destination.

Rules are evaluated in the order defined by PatternLogEventPolicyConfig.rules. The first matching rule decides the result. If no rule matches, PatternLogEventPolicyConfig.default_enabled is returned.

Initialize pattern event policy.

Parameters:: config (PatternLogEventPolicyConfig) – immutable pattern policy configuration.
Raises:: TypeError – if config is not a PatternLogEventPolicyConfig instance.

is_event_enabled(event)

Return whether the event is enabled by this policy.

The method checks configured rules in order. The first matching rule returns its action as a boolean decision. If no rule matches, the configured default decision is returned.

Parameters:: event (LogEventMeta) – event metadata to check.
Return type:: bool
Returns:: True if the event is enabled, False otherwise.

Rule model

A pattern policy is an ordered decision table.

Each rule has:

action
pattern groups

The action is returned when the rule matches.

The pattern groups select which metadata values the rule applies to.

Inside one rule, non-empty pattern groups are combined as logical and.

Inside one pattern group, patterns are alternatives.

rules
    checked in order

fields inside one rule
    AND

patterns inside one field
    OR

The first matching rule decides the result.

If no rule matches, PatternLogEventPolicyConfig.default_enabled is returned.

Pattern fields

A rule may match:

events
event_namespaces
event_names
entity_ids
source_paths
source_funcs

events matches the composed event key built from event namespace and event name.

The other fields match the corresponding LogEventMeta fields.

Pattern matching uses shell-style patterns.

Mapping configuration

Both configuration dataclasses support mapping-based construction:

PatternLogEventPolicyRuleConfig.from_mapping()
PatternLogEventPolicyConfig.from_mapping()

This is intended for configuration loaded from dictionaries, files, environment-specific settings, or another configuration layer.

Mapping data is validated and converted into typed immutable configuration objects before runtime event matching starts.

Minimal object-form example

from mvx.common.logger import (
    PatternLogEventPolicy,
    PatternLogEventPolicyAction,
    PatternLogEventPolicyConfig,
    PatternLogEventPolicyRuleConfig,
)

policy = PatternLogEventPolicy(
    PatternLogEventPolicyConfig(
        default_enabled=False,
        rules=(
            PatternLogEventPolicyRuleConfig(
                action=PatternLogEventPolicyAction.ALLOW,
                event_namespaces=("my_app.worker",),
            ),
        ),
    )
)

Minimal mapping-form example

from mvx.common.logger import (
    PatternLogEventPolicy,
    PatternLogEventPolicyConfig,
)

config = PatternLogEventPolicyConfig.from_mapping(
    {
        "default_enabled": False,
        "rules": [
            {
                "action": "allow",
                "event_namespaces": ["my_app.worker"],
            },
        ],
    }
)

policy = PatternLogEventPolicy(config)