Klaxon

Klaxon turns "somebody should have noticed that" into something the site says
out loud. An alert is one question worth asking — how many orders were placed in
the last half hour, has anything been sitting in this state since yesterday, did
that queue stop draining — and a place to say the answer: Slack, Telegram,
Discord, email, or any URL that accepts a webhook.

Contrib has plenty of modules that hard-wire one source to one channel, and
two frameworks either side of the target: Monitoring exposes sensors for an
external monitoring product to scrape, ECA automates a site through a graphical
modeller. Neither lets someone say "email me the daily sales total" or "tell the
ops channel when nothing has sold for half an hour" without a developer writing
a cron hook. Klaxon is that missing middle: the person who wants the alert can
build it, in a form, in about a minute.

It is not a monitoring system and does not try to be. Monitoring watches the
machine. Klaxon watches the business running on it, and the two rarely fail at
the same time.

Features

An alert is one thing worth knowing about. You pick what kind it is, and the
form then asks only what that kind needs:

• When a count or total crosses a line. On a schedule, count
  things, add up a field, or list them — inside a time window — and fire when the
  number crosses a threshold.
• When content changes. Fire the moment something is created,
  updated or deleted, optionally only when a field takes a particular value. This
  is how you say "an order was cancelled".
• When code fires it. Nothing evaluates it automatically; a
  developer calls the dispatcher and Klaxon does the templating, channels,
  severity and repeat-suppression around whatever they hand it.

Delivery goes to channels, which hold the credentials once and
are referenced by every alert that uses them. Six transports ship in the module,
and none of them needs a library — Slack, Telegram and Discord are a JSON POST
that core's HTTP client already does:

• Slack — an incoming webhook, with severity as the colour
  stripe
• Telegram — a bot token and a chat, group or channel
• Discord — a channel webhook, with severity as the embed
  colour
• Email — one mail per recipient, so a bad address cannot
  take the rest of the list down with it
• Webhook — a documented, stable JSON shape to any URL, with
  your own headers for authentication and optional HMAC-SHA256 request signing
• Log — the right channel to add while you are still deciding
  whether an alert fires too often

The parts that stop an alert becoming noise:

• The dead man's switch. Fire when a query that should return
  something returns nothing. "No orders in the last half hour" is usually the most
  valuable alert a site can have, and the one nobody writes, because the logic
  reads backwards.
• Say it once. Choose between once when it starts, once when
  it starts and again when it clears, or every time it is still true — with a
  cooldown for a value sitting right on the threshold.
• Report each match once, ever. The alert remembers what it
  has already mentioned, so "this ends within the hour" announces each one once
  rather than on every check for the rest of that hour.
• Queued delivery. Cron and entity saves hand the message to
  a queue, so a customer's order never fails to save because Slack is having a bad
  afternoon. Retries back off, rate limits are honoured, and a fallback channel
  can be told when delivery is lost for good.

Two submodules turn the module from a form into a list of things worth
knowing, ready to switch on:

• Klaxon Commerce — the takings over a period, nothing sold
  for N minutes, orders stuck in a state, carts left behind. Order states are read
  from the workflows on your site, so a shop with a dozen custom states works the
  same as a stock one.
• Klaxon System — cron falling behind, errors piling up in
  the log, queues that stopped draining.

Writing your own alert type is a class with an attribute and a
read() method; extending the scheduled base brings the schedule and
the threshold with it. Transports are the same shape.

Post-Installation

Everything lives at Configuration › System › Klaxon. There is
no new content type and nothing to add to a text format.

1. Add a channel first, at
   /admin/config/system/klaxon/channels. An alert with nowhere to go still
   runs and still records its state — it just says nothing. The Log channel needs
   no credentials and is a good first one.
2. Add an alert, at /admin/config/system/klaxon/alerts.
   Pick what kind it is from a grouped list, answer what it asks, and choose the
   channels it delivers to.
3. Press Run now on the alert row. It evaluates immediately
   and tells you whether it fired, which is the fastest way to find out that a time
   window is wrong or a threshold never trips.

Scheduled alerts are evaluated on cron, so the site needs cron running for
them to fire on their own. Alerts that watch content changes fire on the save
itself and do not wait for cron.

Two permissions, deliberately separate: Administer Klaxon alerts for
the people writing them, and Administer Klaxon channels, restricted,
because a channel holds credentials.

Speaking of which: channel credentials live in configuration and are exported
with it. To keep a Slack URL or a bot token out of an exported site, override it
in settings.php, which config entities honour like anything else:

$config['klaxon.channel.ops_slack']['transport']['webhook_url'] = getenv('SLACK_WEBHOOK');

If you have Drush, five commands answer the question cron cannot:
klaxon:list shows every alert and whether it is currently firing,
klaxon:run evaluates one and says what it decided,
klaxon:due runs everything due without the rest of cron,
klaxon:test sends a throwaway message down one channel to prove the
credentials work, and klaxon:deliver empties the delivery queue by
hand. If alerts ever stop arriving, look at that queue first — a backlog there
silences every alert on the site while every alert still looks perfectly well
configured.

Additional Requirements

• Drupal 11.4 or later.
• dragonmantank/cron-expression, installed automatically with
  Composer. It is only needed for cron-expression schedules such as
  0 7 * * *; plain intervals work without it.
• No other Drupal modules. Slack, Telegram, Discord and the
  generic webhook all go through core's HTTP client, so there is no SDK to install
  and nothing to keep up to date.

Submodules add their own: Klaxon Commerce needs Drupal
Commerce (commerce_order), and the log alert in Klaxon
System needs core's Database Logging — without it that one alert takes
itself off the list rather than offering a query that cannot run.

Recommended modules/libraries

• Drush — not required, but the five commands above are the
  difference between diagnosing an alert in a terminal and guessing from the
  log.
• Drupal Commerce — enables the Klaxon Commerce submodule.
• Database Logging (core) — enables the "errors in the log"
  alert in Klaxon System.

Similar projects

• Monitoring exposes sensors for an external monitoring
  product to read. It is built to be scraped; Klaxon is built to speak, and needs
  nothing outside the site.
• ECA and Rules are general automation
  frameworks. Either can be made to send an alert, but you are modelling a
  workflow to get there. Klaxon does one thing, so the form asks three questions
  instead of presenting a canvas — and it brings thresholds, time windows,
  cooldowns, repeat-suppression and retrying delivery, which a general modeller
  leaves you to build.
• Message with Message Notify models
  notifications as entities. Powerful, and more plumbing than "tell me when
  nothing has sold for half an hour" deserves.
• Slack, Telegram and similar single-service
  modules give you one destination and no scheduling, thresholds or
  deduplication. Klaxon treats a destination as a plugin and spends its effort on
  deciding whether there is anything worth saying.

Supporting this Module

Issues and patches are welcome in the issue queue. There is no funding link.

Community Documentation

The README in the module covers the concepts and the extension points, and each
submodule has one describing its alerts and the traps they encode. No video
walkthrough yet — if you record one, open an issue and it will be linked here.