Skip to main content

HONEYCOMB EXTENSIONS

Every Swamp extension that covers Honeycomb, as published in the registry. Install any of them with swamp extension pull.

Extensions

Extension Version License Contents
@hivemq/honeycomb 2026.10.01.1790870399 - 2 behavior types

@hivemq/honeycomb

swamp extension pull @hivemq/honeycomb

Behavior type @hivemq/honeycomb

Global arguments, set with --global-arg on swamp behavior create:

Name Type Required Description
configKey string yes Honeycomb v1 Configuration Key (used as X-Honeycomb-Team header)
region "us" | "eu" no Honeycomb region (us or eu)
datasetSlug string yes Dataset slug the SLO belongs to. Use 'all' for multi-dataset SLOs.

Methods, run with swamp behavior run:

Method Description Arguments
sync Fetch current SLO state from Honeycomb by SLO ID sloId
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). sloId, name (optional), description (optional), targetPercent (optional), timePeriodDays (optional), sliAlias (optional)
createSlo Create a new SLO in Honeycomb. Returns the assigned SLO ID. name, sliAlias, targetPercent, timePeriodDays, description (optional), datasetSlugs (optional)
createDerivedColumn Create a new derived column (SLI calculated field) in the target dataset. alias, expression (optional), expressionFile (optional), description (optional), datasetSlug (optional)
updateSliExpression Update the SLI derived column expression. This is a separate API call from the SLO itself. alias, expression (optional), expressionFile (optional), description (optional), sliDatasetSlug (optional)
createBurnAlert Create a burn rate alert for an SLO. Fires when the error budget is being consumed at a rate that would exhaust it within exhaustion_minutes. Also sends a recovery notification when the burn rate drops back to normal. sloId, exhaustionMinutes, recipients
deleteBurnAlert Delete a burn rate alert. Reads the stored alert ID from the burnAlert resource written by createBurnAlert. sloId, exhaustionMinutes
createBudgetRateBurnAlert Create a budget-rate burn alert for an SLO. Fires when the error budget decreases by more than the threshold (in parts per million) within a sliding window. Use this instead of exhaustion-time alerts when you want to detect active regression rate rather than projected time to exhaustion. sloId, budgetRateWindowMinutes, budgetRateDecreaseThresholdPerMillion, recipients
syncBudgetRateBurnAlert Reconcile the SLO's single budget-rate burn alert to match the supplied args. Zero alerts on the SLO → POST. Exactly one → PUT in place, preserving the alert id and its PagerDuty/Slack routing. More than one → refuse; an operator must decide which to keep. Recipients aren't returned by GET, so PUT always re-sends them; the call is a no-op on Honeycomb when nothing changed. sloId, budgetRateWindowMinutes, budgetRateDecreaseThresholdPerMillion, recipients
deleteBudgetRateBurnAlert Delete a budget-rate burn alert. Looks up the stored alert ID from the burnAlert resource written by createBudgetRateBurnAlert. sloId, budgetRateWindowMinutes, budgetRateDecreaseThresholdPerMillion
createQuery Create a Honeycomb query and store its id. Queries are immutable — there is no update/delete API. The returned id can be passed to createTrigger. NOTE: not idempotent. Calling twice with the same spec creates two queries with different ids — Honeycomb has no dedupe and the Swamp resource is keyed by API-assigned id. This is acceptable because queries are cheap reference handles, not user-facing entities. spec, datasetSlug (optional)
createQueryAnnotation Create a query annotation: bind a human-readable name and description to an existing query id. NOTE: not idempotent. Calling twice with the same args creates two annotations with different ids because the Swamp resource is keyed by API-assigned id (no stable user-supplied secondary key like createTrigger has). Manage duplicates with deleteQueryAnnotation. queryId, name, description (optional), datasetSlug (optional)
syncQueryAnnotation Refresh the local state of a query annotation from Honeycomb. id, datasetSlug (optional)
updateQueryAnnotation Update a query annotation's name, description, or query binding. Only provided fields are changed (read-modify-write merge). id, name (optional), description (optional), queryId (optional), datasetSlug (optional)
deleteQueryAnnotation Delete a query annotation. Idempotent on 404/410 — local state is tombstoned even if Honeycomb has already removed the record. id, datasetSlug (optional)
createTrigger Create a Honeycomb trigger. The query referenced by queryId must already exist (use createQuery first). Idempotency-guarded by ${datasetSlug}:${name} — if a non-tombstoned trigger already exists in local state with the same name in the same dataset, this throws. With no local state, a live Honeycomb trigger of that name is adopted and updated in place, so a fresh datastore converges instead of creating a duplicate. name, description (optional), queryId (optional), query (optional), frequency, threshold, alertType (optional), disabled (optional), autoInvestigate (optional), baselineDetails (optional), recipients, datasetSlug (optional)
syncTrigger Refresh the local state of a trigger from Honeycomb. Reads the id from the stored resource, or looks the trigger up in Honeycomb by name when local state has none. name, datasetSlug (optional)
updateTrigger Update a trigger. Read-modify-write — fetches current state from Honeycomb (including recipients) and PUTs the merged record. Only provided fields are changed. Without local state, the trigger is found in Honeycomb by name. name, description (optional), queryId (optional), query (optional), frequency (optional), threshold (optional), alertType (optional), disabled (optional), autoInvestigate (optional), baselineDetails (optional), clearBaseline (optional), recipients (optional), datasetSlug (optional)
deleteTrigger Delete a trigger. Idempotent on 404/410 — local state is tombstoned even if Honeycomb has already removed it. Without local state, the trigger is found in Honeycomb by name. name, datasetSlug (optional)

Data written:

Resource Description
slo A Honeycomb SLO
derivedColumn A Honeycomb derived column (used as SLI)
burnAlert A Honeycomb SLO burn rate alert
query A Honeycomb query (immutable spec referenced by triggers and boards)
queryAnnotation A Honeycomb query annotation (a named/described query, what the UI calls a 'saved query')
trigger A Honeycomb trigger (alert when a query crosses a threshold)

Behavior type @hivemq/honeycomb/datasets

Global arguments, set with --global-arg on swamp behavior create:

Name Type Required Description
configKey string yes Honeycomb v1 Configuration Key (used as X-Honeycomb-Team header)
region "us" | "eu" no Honeycomb region (us or eu)

Methods, run with swamp behavior run:

Method Description Arguments
deleteStaleDatasets Find and optionally delete datasets with no writes in the last N days. Honeycomb's default retention is 60 days, so stale datasets past that window hold no events — deletion clears the empty schema shell. Both modes read /1/datasets. Mode 'preview' stops there and only reports the candidate list; 'apply' additionally unprotects then deletes each candidate ENVIRONMENT-WIDE — no confirmation step. Use slugPrefix to scope the run when a narrower blast radius is required (safe UAT, per-operator scoping). A 404 on either the unprotect PUT or the DELETE is treated as idempotent success (already gone); other non-2xx responses record a per-slug failure entry rather than aborting the run. olderThanDays (optional), mode (optional), slugPrefix (optional)
deleteSpammyDatasets Find and optionally delete datasets whose names match pentester probe patterns (e.g. containing 'jndi', 'oastify', '{', '..'). Both modes read /1/datasets. Mode 'preview' stops there and only reports the candidate list; 'apply' additionally unprotects then deletes each candidate — 'apply' requires slugPrefix so a short substring hit on a legitimate name cannot delete an unrelated dataset. mode (optional), slugPrefix (optional)

Data written:

Resource Description
datasetCleanupRun One dataset cleanup invocation. Records the filter used, the candidate list, and (for apply mode) which slugs were deleted or failed.