Skip to main content

Documentation Index

Fetch the complete documentation index at: https://doc.heex.io/llms.txt

Use this file to discover all available pages before exploring further.

Observability lets you connect Heex to your existing monitoring stack so that fleet metrics, dashboards, and alerts live where your team already looks.
Observability is currently in private beta. Contact Heex support to request access.

​
What you get

  • Always-on edge telemetry: the Heex Agent samples CPU, memory, network, and disk usage every 10 seconds and forwards them to your OpenTelemetry collector, even when no trigger is active.
  • Embedded Grafana dashboards: predefined dashboards ship with the platform; you can also add and manage your own custom dashboards directly from the Observability page.
  • No vendor lock-in: your data flows to your OpenTelemetry collector and your Grafana instance. Heex only forwards.
Observability streams continuous telemetry to an external stack independently of triggers. If you instead want Heex events to fire on system-health thresholds (and capture recordings around them), use the Observability Package, which is trigger-driven and complementary to this page.

​
Configuration

​
Prerequisites

  • Workspace administrator role (the same role that can manage workspace settings)
  • Heex Agent version 2026.04.2 or later on every system that should report telemetry; older agents will ignore the settings until they are updated over the air

​
Settings page

The Observability settings live at Settings → Observability. Two deployment modes are available:
  • None: telemetry forwarding is disabled. The Heex Agent still runs normally; only the export to your collector is off.
  • Self-Hosted: telemetry is forwarded to a collector and visualizer that you operate.

​
Self-Hosted setup

The Self-Hosted form has two independent sections, one per service:
  • OpenTelemetry collector: endpoint URL and authentication token. Used by the agent to push metrics.
  • Grafana visualizer: base URL and access token. Used by the Heex UI to embed dashboards.
Each section has its own Test connection button. You can save a partial configuration, for example with only the collector filled in. In that case the agent will start exporting metrics while Grafana embedding remains disabled, and the Observability page displays a warning so the gap is explicit.

​
Edge telemetry

Once the collector is configured, the agent exports the following metrics every 10 seconds:
  • CPU usage (per-core and aggregate)
  • Memory usage and pressure
  • Network throughput (in/out, per interface)
  • Disk usage and I/O
Each metric is tagged with system metadata (system ID, workspace) so you can group and filter on the receiving side. If the collector becomes unreachable, the agent retries with an exponential backoff and buffers up to 1000 metrics in memory. The agent never crashes on collector outage; once the collector returns, buffered metrics are flushed. There is no on-disk persistence: if the agent restarts, buffered metrics are lost.

​
Dashboards

The Observability page in the main navigation hosts the dashboards. You can:
  • Switch between predefined dashboards (provided by Heex) and custom dashboards (added by your team) via a dropdown selector.
  • Add a custom dashboard: click the add button, give it a name and a Grafana URL. The dashboard is embedded as an iframe.
  • Edit a custom dashboard: click the pen icon next to the selector to update the name or URL.
  • Remove a custom dashboard: click the trash icon and confirm. Predefined dashboards cannot be removed.
Dashboard definitions are stored on the workspace, so every member of the workspace sees the same list.

​
Limitations

  • Only Self-Hosted mode is currently offered; a managed mode is on the roadmap.
  • Telemetry buffering is in-memory only and capped at 1000 metrics; sustained collector outages will drop the oldest queued samples.