Skip to content

Entities and Signals

An Entity is the fundamental unit in Hexcovery — a single "piece" of your system: a service you run, a database you depend on, a cron job, a host. Every Entity exists in its own right, with a stable identity and its own dedicated screen where you can observe it alone, independent of any grouping.

An Entity is identity + its signals

The definition is deliberately simple:

Entity = identity + the set of signals it currently has.

The signals are the kinds of telemetry that piece emits:

Signal What it is Typically from
Traces Distributed request spans Your code, instrumented with OpenTelemetry
Metrics OTLP metrics (an entity's own numeric telemetry) OTel SDKs or infrastructure receivers
Logs Structured / unstructured log lines Apps, the agent, container & host logs
Crons Scheduled-job heartbeats (start / success / fail) Cron heartbeat pings
Host metrics CPU, memory, disk, network of a machine The Hexcovery agent

An Entity is not defined by one privileged signal. It is the identity plus whatever signals it happens to have right now.

The signal set grows; the Entity stays the same

This is the key idea, and the one that makes the model resilient over time:

The signal set an Entity carries changes. The Entity does not.

A concrete example:

  1. A PostgreSQL database first appears only because one of your services calls it — you see it purely through that service's traces, as a dependency edge.
  2. Later you attach an OpenTelemetry receiver and it starts shipping its own metrics.
  3. It is the same Entity the whole time. It didn't get replaced or duplicated — it gained a signal.

Why this matters

You never have to "set up the entity first." Entities materialize from telemetry as it arrives, and they accrete signals as you instrument more. The identity is the anchor; signals come and go around it.

The per-entity detail view

Because an Entity is "identity + signals," its detail view is composed of one section per signal that is present. Sections for absent signals simply collapse — you only see what the piece actually emits.

When multiple signals are present, the sections appear in a fixed order:

traces  →  metrics  →  logs  →  cron

A few things follow from this:

  • Traces ≈ "instrumented by us" and metrics ≈ "the entity's own telemetry" tend to be near-mutually-exclusive (your own code emits traces; an external database emits metrics). When both happen to be present, traces come first.
  • The same component renders either as a panel in context (inside a Project, for a piece that lives only there) or as a standalone page (for a shared or cross-referenced piece). Same model, two presentations.
  • Traces and Logs additionally each have their own global lens — people often want to look at all traces or all logs on their own, across every entity.

Where to go next