ALERT ON A HONEYCOMB QUERY WITH A TRIGGER

This guide shows you how to create a Honeycomb trigger from a Swamp behavior. The trigger emails an on-call address when checkout server errors cross a threshold. The guide also shows how to refresh the trigger's local state and change its threshold without recreating it.

Prerequisites

• swamp auth login completed in an initialised repository
• A Honeycomb Configuration Key stored in a vault named honeycomb under config-key (see Storing Secrets)
• A dataset whose events have an http.status_code field

Set up the behavior

Pull the extension:

swamp extension pull @hivemq/honeycomb

INF extension·pull: Pulling "@hivemq/honeycomb"@"2026.10.01.1790870399"
INF extension·pull: Identity verified: "@hivemq/honeycomb"@"2026.10.01.1790870399"
INF extension·pull: Pulled "@hivemq/honeycomb"@"2026.10.01.1790870399"
INF extension·pull: Extracted 16 files:

If you do not have the vault yet, create it and store the key in it:

swamp vault create local_encryption honeycomb

INF vault·create: Created vault: "honeycomb" ("Local Encryption")

swamp vault put honeycomb config-key hcxik_replace_with_your_configuration_key

This command encrypts the Configuration Key and stores it in the honeycomb vault under config-key.

Create a behavior for the dataset you want to alert on. Change datasetSlug and region to match your team:

swamp behavior create @hivemq/honeycomb checkout-alerts \
    --global-arg "configKey=${{ vault.get('honeycomb', 'config-key') }}" \
    --global-arg region=us \
    --global-arg datasetSlug=checkout

You will see output like:

Created: checkout-slo (@hivemq/honeycomb)
Path: /tmp/.../models/@hivemq/honeycomb/checkout-slo.yaml
Version: 2026.10.01.1

Global Arguments:
  configKey (string) *required
  region (string) [us, eu]
  datasetSlug (string) *required

Methods:
  sync - Fetch current SLO state from Honeycomb by SLO ID
    Inputs:
      sloId (string) *required
  updateSlo - Update SLO metadata (target, description, period, SLI). All fields are optional — only provided fields are changed. Pass `sliAlias` to repoint the SLO at a different derived column (the column must already exist; create it first via createDerivedColumn).
    Inputs:
      sloId (string) *required
      name (string)
      description (string)
      targetPercent (number)
      timePeriodDays (integer)
      sliAlias (string)
  createSlo - Create a new SLO in Honeycomb. Returns the assigned SLO ID.
    Inputs:
      name (string) *required
      sliAlias (string) *required
      targetPercent (number) *required
      timePeriodDays (integer) *required
      description (string)
      datasetSlugs (array)
  createDerivedColumn - Create a new derived column (SLI calculated field) in the target dataset.
...

Create the trigger

This example passes the query inline. The query counts responses with a status of 500 or higher over 15 minutes. Honeycomb checks it every 900 seconds, and the trigger fires when the count goes above 50:

swamp behavior run checkout-alerts createTrigger \
    --input 'name=Checkout 5xx spike' \
    --input 'description=More than 50 server errors in 15 minutes' \
    --input 'query:json={"calculations":[{"op":"COUNT"}],"filters":[{"column":"http.status_code","op":">=","value":500}],"time_range":900}' \
    --input 'frequency:json=900' \
    --input 'threshold:json={"op":">","value":50}' \
    --input alertType=on_change \
    --input 'recipients:json=[{"type":"email","target":"oncall@example.com"}]'

This command creates the trigger in Honeycomb and writes a trigger resource. The method checks the dataset slug and trigger name first, so if a trigger with that name already exists in the dataset, running the command again does not create a duplicate.

To reuse a query that already exists, pass --input queryId=<id> in place of query. You can get a query ID from the createQuery method. For notifications to Slack, PagerDuty, a webhook or Microsoft Teams, change the type in each recipient object. For a fixed alert interval, set alertType to on_true.

Refresh the trigger from Honeycomb

If someone edits the trigger in the Honeycomb UI, refresh the stored resource:

swamp behavior run checkout-alerts syncTrigger --input 'name=Checkout 5xx spike'

This command reads the trigger from Honeycomb and updates the stored trigger resource. It uses the ID from local state, or looks the trigger up by name when there is no local state.

Change the threshold

To raise the threshold to 100 without changing anything else:

swamp behavior run checkout-alerts updateTrigger \
    --input 'name=Checkout 5xx spike' \
    --input 'threshold:json={"op":">","value":100}'

This command fetches the current trigger from Honeycomb, including its recipients. It merges in only the fields you pass, saves the merged trigger and updates the trigger resource. Other fields work the same way. For example, pass --input 'disabled:json=true' to mute the trigger, or --input 'clearBaseline:json=true' to remove baseline details.

Confirm the change

swamp data query --limit 10

This command lists the most recent data records, including the trigger resource for Checkout 5xx spike, which should now show the new threshold.

To remove the trigger, run deleteTrigger with the same name. See the Honeycomb extension reference for every trigger input.