Keywords & Triggers

There are two types of triggers: keywords and container_events.

Keyword Types

The keywords list accepts three types, which can be mixed freely:

keyword

keywords:
  - error           # simple keyword
  - keyword: failed login   # another way to set a simple keyword

regex

keywords:
  - regex: 'download.*failed'
  - regex: 'process (?P<pid>\d+) crashed'  # named capture group → available in templates

all_of

# these only trigger when all members of the all_of group match in the same log entry
keywords:
  - all_of:
      - error
      - timeout
      - keyword: database
  - all_of:
      - keyword: authentication
      - regex: 'failed.*attempt'

INFO

• keywords are case-insensitive
• regexes are case-sensitive by default (controlled by regex_case_sensitive in defaults:)
• named capturing groups ((?P<name>...)) can be used to extract values that become available as template variables in title_template and message_template. See Customize Noticications and Extract from Regex.

---

Container Events

Monitor Docker container lifecycle events instead of (or in addition to) log content.

containers:
  rules:
    - container_name: my-app
      container_events:
        - event: crash
        - event: oom

Supported Events

Event	Triggered when...
start	Container is started
stop	Container is stopped via a stop request (not on crashes or forced exits)
die	Container exits, regardless of reason (stop, crash, or kill)
crash	Container exits with a non-zero exit code
destroy	Container is removed
healthy	Container health status changes to healthy
unhealthy	Container health status changes to unhealthy
starting	Container health status changes to starting
oom	Container is killed by the OOM killer
kill	Container is killed by a signal
create	Container is created
restart	Container is restarted

---

How triggers are merged across levels

Keywords and container events can be configured at the following levels:

• Global level (global.keywords): applied to every matched target across all sources.
• Source level (containers.keywords, containers.container_events): applied to every target of that source (containers or swarm) that is matched by any rule.
• Rule level (rules[*].keywords, rules[*].container_events): applied only to containers matched by that specific rule.

Triggers from all levels are combined. Source-level triggers come first, followed by rule-level triggers.
If the same container event type appears at multiple levels, the most specific level's settings are used.

INFO

There will most likely be more log sources in the future. This is why there is no global.container_events section since that is specific to containers and swarm.

Example

global:
  keywords:
    - "critical" # applied to every matched target across all sources (containers and swarm)

containers:
  keywords:
    - keyword: "panic" # applied to every container matched by any rule

  container_events:
    - event: crash # applied to every container matched by any rule

  rules:
    - container_name: my-app
      keywords:
        - keyword: "error" # applied only to containers matched by this rule
      container_events:
        - event: start # applied only to containers matched by this rule

swarm:
  rules:
    - service_name: my-service
      keywords:
        - keyword: "timeout" # applied only to services matched by this rule

Threshold-Based Triggering with trigger_on

Instead of triggering on every match, trigger_on delays a trigger until the keyword has matched a minimum number of times within a sliding time window. This is useful for noisy signals where a single occurrence is not actionable, but repeated occurrences indicate a real problem.

trigger_on works on keyword:, regex:, and all_of: items, as well as on container_events items.

keyword

keywords:
  - keyword: "connection timeout"
    trigger_on:
      count: 5
      timeframe: 60
    title_template: "{{ container_name }}: {{ trigger_on_count }} timeouts in {{ trigger_on_timeframe }}s"

container_event

container_events:
  - event: crash
    trigger_on:
      count: 5
      timeframe: 60
    title_template: "{{ container_name }} crashed {{ trigger_on_count }} times in {{ trigger_on_timeframe }}s"

Behavior:

• Each match is recorded in an in-memory sliding window.
• When the match count reaches count within timeframe seconds, the trigger fires and the counter resets to zero.
• trigger_cooldown still applies as a gate before a match is evaluated against trigger_on.
• count must be ≥ 2. timeframe must be ≥ 1 second.

Template variables available when trigger_on is set:

• {{ trigger_on_count }}: the configured count threshold
• {{ trigger_on_timeframe }}: the configured timeframe in seconds

Actions

You can configure container_action and olivetin_actions on keywords and container events.
See Actions for more details.

Per-Keyword defaults Settings

Any field from global.defaults: can be set on an individual trigger (keyword or container event). These override the inherited value for that specific trigger only.

Per Trigger Settings Example

global:
  defaults:
    ntfy_priority: 1
    attach_logfile: false

containers:
  rules:
    - container_name: my-app
      keywords:
        - keyword: error
          ntfy_priority: 5          # override priority for this keyword only
          attach_logfile: true
          trigger_cooldown: 60
          title_template: "Error in my-app"

        - regex: 'panic.*goroutine'
          ntfy_topic: "critical-alerts"
          container_action: restart  # see Actions guide

      container_events:
        - event: crash
          ntfy_priority: 5
          attach_logfile: true
          title_template: "Container {{ container_name }} crashed"

Additional explanation on some of the settings from global.defaults:

merge_matches

Controls what happens when multiple keywords match in the same log line.

• merge_matches: false (default): each matching keyword fires its own independent notification with its own configuration. One log line can produce multiple notifications.
• merge_matches: true: all keywords matching the same log line that have merge_matches: true set (whether inherited or set on the keyword itself) are merged into one notification. Keywords that have merge_matches: false fire their own independent notification.

global:
  defaults:
    merge_matches: true

containers:
  rules:
    - container_name: my-app
      keywords:
        - keyword: "error"
          merge_matches: false # this keyword will not be merged with other keywords

merge_matches can be set at defaults:, source-level defaults:, rule level, or per-keyword. Setting it on individual keywords makes those keywords opt-in or opt-out of merging while others remain independent.

Buffering triggers

Sometimes a keyword is found but you may want LoggiFly to wait and collect subsequent log lines for a specified number of seconds. This can be done with the buffer setting.

INFO

the buffer setting explicitly opts you out of merge_matches: true if you have that configured.

containers:
  rules:
    - container_name: my-app
      keywords:
        - keyword: error
          buffer:
            seconds: 10
            mode: matching # optional, defaults to 'matching'
            max_lines: # optional
global:
  defaults:
    # it is recommended to configure buffers explicitly for specific triggers 
    # but if you want it to apply to all triggers you can set it here as well (or under containers or a rule)
    buffer:
      seconds: 10

Buffer option	Description
seconds	Required. Number of seconds to buffer subsequent log lines before triggering and sending the notification.
mode	One of matching or all. matching collects only subsequent log lines that match the same keyword. all collects all subsequent log lines. Default is matching.
max_lines	Optional. Maximum number of buffered lines to capture, including the first matching line. When this limit is reached, the buffer is flushed and the notification is sent immediately.

INFO

You can also set buffer.seconds for container_events, but mode is always treated as matching and max_lines does not apply. Event buffering counts repeated occurrences of the same configured container event during the specified number of seconds and exposes that count in the notification title and the buffer_match_count template field.

TIP

You can find the supported template fields for this feature here.

ignore_keywords

Keywords or regex patterns that suppress a trigger when found in the same log line.

Can be set at multiple levels

global:
  defaults:
    ignore_keywords:
      - regex: "debug.*message"
containers:
  rules:
    - container_name: my-app
      ignore_keywords:
        - keyword: "ignoreforthisrule"
      keywords:
        - keyword: "error"
          ignore_keywords:
            - regex: "ignoreforthiskeyword"

ignore_keywords are merged across all levels.

disable_trigger_notifications

Suppresses the notification when a trigger fires, while still executing any configured actions (container actions, OliveTin actions). Useful when you only want to trigger automation without notification noise.

keywords:
  - keyword: "unhealthy"
    disable_trigger_notifications: true
    container_action: restart