Skip to main content

Beats

Beats are StatiBeat's synthetic monitoring workspace. They let page admins check customer-facing paths proactively, capture evidence, and turn those signals into internal alerts, reviewable drafts, or automated public incident updates.

Beats can now run either as standalone monitors or as members of an optional Beat Group. Grouped Beats still own monitoring and evidence, while the Beat Group owns the customer-facing automation surface above them.

In the API, Beats use the /api/v1/admin/beats/... route family.

Useful API calls on the main path are:

  • GET /api/v1/admin/beats to list Beats for the current page
  • POST /api/v1/admin/beats to create a Beat
  • GET /api/v1/admin/beats/{id} to fetch one Beat in full
  • POST /api/v1/admin/beats/{id}/run to trigger a run immediately
  • GET /api/v1/admin/beat-groups to list Beat Groups for the current page
  • POST /api/v1/admin/beat-groups to create a Beat Group

Beat lists return a compact summary by default. Append ?view=full to the quoted URL when you want the full configuration document, for example curl "$STATIBEAT_BASE_URL/api/v1/admin/beats?view=full" -H "Authorization: Bearer $STATIBEAT_TOKEN".

tip

Beats are most useful when they are tied to the same hierarchy and communication model your customers already see on the status page.

This guide is based on:

  • application/frontend/src/pages/admin/SyntheticMonitorManagement.jsx
  • application/frontend/src/constants/presetVariables.js
  • application/frontend/src/services/api.js
  • application/backend/internal/models/synthetic_monitor_models.go
  • application/backend/docs/openapi_public.json

What the Beats workspace covers​

The current page-admin Beats area supports:

  • listing all beats for the selected page
  • creating, editing, enabling, disabling, and deleting beats
  • creating, editing, and deleting Beat Groups
  • assigning Beats into one Beat Group at a time
  • viewing current stage, recent evidence, and pending reviews
  • manually running a beat immediately
  • reviewing recent runs and generated actions
  • approving or rejecting pending public-facing actions

For shared-runtime beats, the same workspace can also initialize the shared synthetics runtime for the page when it is not already configured.

Wizard and Advanced setup modes​

When you create a new beat, the workspace now opens in Wizard mode by default.

  • Wizard is the recommended path for common setups. It starts with large monitor-type cards, then guides you through target setup, simplified alert behavior, affected scope, and a final review step.
  • Advanced keeps the full existing editor for target fields, threshold rules, notifications, screenshots, MTR capture, and message-template controls.
  • Edit flows continue to open in Advanced mode first so existing advanced or legacy-style beats remain lossless.

Use Wizard when you want the fastest path to a standard website, API, journey, or network check. Use Advanced when you need the full alert/message surface or a configuration the wizard does not model directly.

When a Beat is assigned to a Beat Group, the monitoring setup stays editable on the Beat, but the incident and messaging controls move up to the Beat Group form.

Supported beat types​

The current UI supports these beat types:

  • HTTP
  • API
  • Latency
  • Heartbeat
  • Private Beat
  • Browser Journey
  • TCP Connect
  • DNS Resolve
  • SSL / Certificate Check
  • ICMP Ping
  • Packet Loss
  • External Event
  • Generic (Advanced)

Generic remains Advanced-only in the first wizard version. Selecting it from the wizard routes you straight into the Advanced editor without changing the shared submit contract.

Shared-runtime beats run in one or more configured regions. In the current shared runtime, the UI exposes a shared Europe West 2 region for this page. Private Beat runs from your deployed agent instead, so shared regions do not apply.

Beat Groups and ownership​

Beat Groups are an optional layer above Beats. They are useful when several checks should behave like one operational surface, such as a website health bundle containing latency, HTTP status, and ping checks.

  • grouped Beats still own target setup, thresholds, evidence, and public metrics eligibility
  • Beat Groups own grouped incident lifecycle, channels, customer-facing scope, cooldowns, and message-source strategy
  • one Beat can belong to one Beat Group at a time in the current release

Basics and target configuration​

Every beat currently includes:

  • name
  • type
  • interval in seconds
  • timeout in milliseconds
  • optional description
  • region selection for shared-runtime beats
  • enabled or disabled state
  • associated hierarchy components

In Wizard mode, these fields are collected across guided steps instead of one long form:

  • Choose monitor type
  • Tell us what to check
  • Choose alert behavior
  • Attach it to this page
  • Review before creating

Target configuration depends on the beat type:

  • HTTP, API, Latency, and Heartbeat beats support URL, method, expected status codes, request headers, and optional response-body checks
  • Private Beat supports either an internal HTTP or HTTPS target URL with expected status codes, or a heartbeat-only mode with no target URL, plus a grace period before StatiBeat treats the agent as offline
  • Browser Journey beats support a start URL, ordered browser steps, and shared request headers
  • TCP, DNS, SSL, ICMP, Packet Loss, and Generic beats support protocol-specific targets such as tcp://host:port, hostnames, or TLS endpoints

Mapped components are optional for internal-only beats.

  • use component_ids or component_refs when the beat should affect tracked hierarchy items on the status page
  • use affected_items_freetext when the beat covers an untracked dependency such as a vendor API, queue worker, or partner system
  • use both when you want tracked hierarchy impact plus extra freeform scope

Customer-facing beat actions still need explicit scope through mapped components, component_refs, free text, or a combination of them. Public metrics still require a mapped leaf component.

Maintenance suppression remains structured in v1: page-wide maintenance still suppresses every beat on the page, and component-scoped maintenance only suppresses beats through mapped hierarchy overlap. affected_items_freetext does not participate in maintenance matching.

In the API, prefer component_refs with external_id or slug for tracked hierarchy attachment so automation does not need numeric component lookups first.

For grouped Beats, customer-facing scope comes from the Beat Group rather than the member Beat. The Beat still keeps its local fields so detaching it later does not destroy its previous standalone configuration.

Private Beat MVP​

Private Beat is the outbound-agent path for targets that StatiBeat's shared runtime cannot reach directly.

The current MVP flow is:

  1. create a Private Beat in the admin UI
  2. choose either Internal HTTP health check or Basic heartbeat only
  3. configure the internal URL and expected status codes for HTTP mode, or skip the target URL entirely for heartbeat-only mode
  4. set the interval, timeout, and grace period
  5. choose the installer OS in the Beat detail view
  6. either generate a public install command with a one-time setup code, or download the generated installer bundle
  7. run the install flow on a host that can reach the internal target, if configured, and can always reach StatiBeat over outbound HTTPS
  8. let the agent report health check results back to StatiBeat

The current bundle includes:

  • generated config.yaml
  • the platform-specific statibeat-private-beat agent binary
  • a Linux systemd unit file or Windows PowerShell installer scripts, depending on the selected OS
  • bundle metadata about token rotation overlap

The current public installer path supports Linux and Windows:

  • generate a one-time setup code from the Beat detail view
  • run the generated install command on the target host
  • let the installer download the public statibeat-private-beat binary, redeem the setup code, write config.yaml, and register the platform-appropriate service or Scheduled Task

The setup code is intentionally separate from the long-lived heartbeat token:

  • generating the setup code does not rotate the active heartbeat token yet
  • redeeming the setup code creates the new heartbeat token and starts the normal 24h overlap window
  • setup codes are one-time and short-lived

The current token rotation model is intentionally rollout-friendly:

  • downloading a new bundle rotates the token
  • the previous token remains valid for 24h
  • admins can immediately invalidate previous overlap tokens from the Beat detail view

Private Beat is intentionally narrow in the first release:

  • installer exports for Linux x64, Linux ARM64, and Windows x64
  • one execution mode per bundle: either a simple HTTP GET check or a heartbeat-only liveness packet
  • no custom headers
  • no request body
  • no screenshots
  • no response-body upload

Private Beat also distinguishes between two different problems:

  • the health check itself failed
  • the agent stopped reporting before interval + grace

Use Basic heartbeat only when the signal you care about is "is this host or deployed agent still alive at all?" Use Internal HTTP health check when you also want the agent to verify an internal endpoint such as http://127.0.0.1/health or http://service.internal/ready.

When the agent stops reporting in time, StatiBeat synthesizes a heartbeat_missing failure so operators can tell the difference between an unhealthy service and an offline deployment.

External Beat Triggers​

External Event Beats receive state from external events instead of scheduled probes. They are managed through Beats -> External Beat Triggers, where admins can create a generic ingest endpoint, inspect a redacted event inbox, click payload fields, build trigger rules, and preview those rules against older events before enabling them.

Use this path when an external system already owns the detection logic, such as GCP Cloud Monitoring, Datadog, Elastic, AWS, Azure, or an internal deployment pipeline.

External trigger rules still feed the same Beat and Beat Group automation system:

  • standalone external-event Beats can create internal alerts, reviewable public drafts, or auto-posts
  • grouped external-event Beats can delegate public incident ownership to the Beat Group
  • Slack review prompts show ingest endpoint, matched rule, fingerprint, and redacted evidence
  • Terraform export includes endpoint metadata and trigger rules, but not existing ingest secrets

See External Beat Triggers for ingest setup, provider examples, preview behavior, and Terraform usage.

Public metrics on service pages​

Beats can now act as the data source for a public Metrics tab on a leaf service page.

In the current admin UI, a beat can be opted into public metrics with:

  • Expose this beat on the public status page
  • a customer-facing Public Label
  • a single Primary Public Component
  • a Max Public Range

The first version is intentionally narrow:

  • the primary public component must be a leaf service
  • only one beat can own public metrics for a given component
  • the public page only shows the tab when that component has a configured public beat

The public page does not expose raw beat events directly. Instead, it renders sanitized chart cards from a bounded public read model.

Current public ranges are fixed:

  • Day -> last 24h
  • Week -> last 7d
  • Month -> last 30d

Bucket size is system-controlled in v1:

  • Day -> 5m
  • Week -> 1h
  • Month -> 6h

There is no admin-controlled data points every setting in the first release. That keeps the public contract predictable and avoids forcing rollup infrastructure too early.

The current public cards are intended for service-page readability, not operator forensics:

  • Availability
  • Response Time or Latency for most HTTP and network-style beats
  • Packet Loss for packet-loss beats

Multi-region beats currently render as one aggregate public series rather than separate region lines.

note

Raw evidence such as response-body previews, screenshots, MTR reports, and other detailed payload data remains admin-only.

note

Long-range public history beyond Day / Week / Month, such as 90d or 1y, is still follow-up work. The current implementation reads bounded recent raw events and leaves longer-term rollups for a later change.

Threshold stages and automation​

Beats use three operational stages:

  • warning
  • critical
  • recovery

The available trigger types depend on the beat type, but the current UI supports rules such as:

  • response time threshold
  • failures in a row
  • failures in a recent rolling window
  • failure duration
  • certificate expiry for SSL beats
  • packet loss for packet-loss beats
  • successes in a row for recovery

For each stage, the current action policy system can send or create:

  • Slack notifications
  • email notifications
  • admin-banner signals
  • public incident drafts or auto-posts
  • automatic critical escalations and recovery resolutions

Where supported, a stage can also attach:

  • browser screenshots
  • MTR network path reports

The wizard intentionally narrows this surface to a few common presets:

  • Internal only
  • Draft incident on critical
  • Auto-post on critical
  • Auto-post and auto-resolve

Those presets still save through the same synthetic monitor payload and can be adjusted later in Advanced.

Ownership depends on whether the Beat is standalone or grouped:

  • standalone Beats keep the original Beat-owned action flow
  • grouped Beats still enter warning, critical, and healthy states individually
  • grouped incidents, banners, and notifications are emitted from the Beat Group instead of the member Beat

Messages and variables​

Beats use the same preset-message system as incidents and maintenance, but with synthetic-specific categories:

  • synthetic_warning
  • synthetic_critical
  • synthetic_recovery

The current message system supports stage-specific templates for:

  • warning notifications
  • critical open messages
  • critical follow-up messages
  • recovery messages

Beat Groups add two message-source modes:

  • group_templates: the Beat Group owns warning, critical, and recovery copy directly
  • primary_beat_templates: the Beat Group still owns automation and scope, but borrows customer-facing title/body text from the current primary Beat

Beat actions can render variables such as:

  • {{Monitor-Name}}
  • {{Monitor-Stage}}
  • {{Evidence-Summary}}
  • {{Latest-Latency-Ms}}
  • {{Latest-Status-Code}}
  • {{Latest-Region}}
  • {{Target-Url}}

Grouped actions also support group-aware context. The most common starter variable is {{Group-Name}}, which is useful for generic group-owned copy such as We are aware of issues with {{Group-Name}}, and are investigating.

The current automation UI also lets admins set:

  • predefined customer impact text
  • customer-facing incident status for automated opens
  • whether a public action stays draft-only or posts automatically

Review, evidence, and operator controls​

The current workspace includes three important operational loops:

  1. pending public actions
  2. recent runs and evidence
  3. pause or mute controls

Pending public actions can be reviewed with a title, message, and decision note before approval or rejection.

Recent run evidence can include:

  • observed region
  • stage and summary
  • latency and status code
  • browser journey steps
  • captured screenshots
  • MTR reports
  • TLS certificate details

Operators can also:

  • pause automation with a reason
  • mute notifications until a chosen time
  • resume automation later
  • run a beat immediately without waiting for the next interval

Grouped Beats keep the same evidence and run-now workflows. The difference is only ownership of the customer-facing automation path.

Migrating existing Beats into groups​

The safest rollout pattern is:

  1. create the Beat Group first with its own scope, channels, and message-source mode
  2. move only the Beats that should share one customer-facing incident into that group
  3. verify the member Beats still collect evidence and change stage normally
  4. confirm the Beat Group, not the member Beat, is creating grouped drafts or public updates

Detaching is intentionally safe:

  • removing beat_group_id returns the Beat to standalone ownership without deleting local Beat configuration
  • deleting a Beat Group requires detaching all member Beats first, so grouped automation never disappears silently

Plan and limit behavior​

The Beats screen is feature-gated in the current product.

  • Beats are available on eligible plans
  • monitor-count limits depend on workspace entitlements
  • the nav can show Beats as locked when the feature is unavailable

That means a workspace might still see the idea of Beats in navigation, while the actual management surface remains gated until the plan includes synthetic monitoring.