How do entities work?

Agent entities are monitoring agents, which are installed and run on every system that needs to be monitored. The entity is responsible for registering the system with the Sensu backend service, sending keepalive messages (the Sensu heartbeat mechanism), and executing monitoring checks. Each entity is a member of one or more subscriptions – a list of roles and/or responsibilities assigned to the agent entity (ex: a webserver or a database). Sensu entities will “subscribe” to (or watch for) check requests published by the Sensu server (via the Sensu Transport), execute the corresponding requests locally, and publish the results of the check back to the transport (to be processed by a Sensu server).

An entity represents anything (ex: server, container, network switch) that needs to be monitored, including the full range of infrastructure, runtime and application types that compose a complete monitoring environment (from server hardware to serverless functions).
We call these monitored parts of an infrastructure “entities”.
An entity not only provides context to event data (what/where the event is from) but an event’s uniqueness is determined by the check name and the name of the entity upon which the check ran.
In addition, an entity can contain system information such as the hostname, OS, platform, and version.

Proxy entities

Proxy entities (formerly known as proxy clients, “Just-in-time” or “JIT” clients) are dynamically created entities, added to the entity store if an entity does not already exist for a check result. Proxy entity registration differs from keepalive-based registration because the registration event happens while processing a check result (not a keepalive message). Sensu proxy entities allow Sensu to monitor external resources on systems and/or devices where a sensu-agent cannot be installed (such a network switch) using the defined check ProxyEntityName to create a proxy entity for the external resource.

Managing entity labels

Custom labels let you organize entities into meaningful collections that can be selected using filters and tokens.

Proxy entities

For entities with class proxy, you can create and manage labels using sensuctl.
For example, to create a proxy entity with a url label using sensuctl create, create a file called example.json with an entity definition that includes labels.

Agent entities

For entities with class agent, you can define entity attributes in the /etc/sensu/agent.yml configuration file.
For example, to add a url label, open /etc/sensu/agent.yml and add configuration for labels.

Entities specification

Top-level attributes

Required for entity definitions in wrapped-json or yaml format for use with sensuctl create.

type

String

example

"type": "Entity"

api_version

description

Top-level attribute specifying the Sensu API group and version. For entities in Sensu backend version 5.2, this attribute should always be core/v2.

required

Required for entity definitions in wrapped-json or yaml format for use with sensuctl create.

type

String

example

"api_version": "core/v2"

metadata

description

Top-level collection of metadata about the entity, including the name and namespace as well as custom labels and annotations. The metadata map is always at the top level of the entity definition. This means that in wrapped-json and yaml formats, the metadata scope occurs outside the spec scope. See the metadata attributes reference for details.

required

Required for entity definitions in wrapped-json or yaml format for use with sensuctl create.

Spec attributes

entity_class

description

The entity type, validated with go regex \A[\w\.\-]+\z. Class names have special meaning. An entity that runs an agent is of class agent and is reserved. Setting the value of entity_class to proxy creates a proxy entity. For other types of entities, the entity_class attribute isn’t required, and you can use it to indicate an arbitrary type of entity (like lambda or switch).

required

true

type

string

example

"entity_class": "agent"

subscriptions

description

A list of subscription names for the entity. The entity by default has an entity-specific subscription, in the format of entity:{name} where name is the entity’s hostname.

required

false

type

array

default

The entity-specific subscription.

example

"subscriptions": ["web", "prod", "entity:example-entity"]

system

description

System information about the entity, such as operating system and platform. See the system attributes for more information.

Custom attributes to include with event data, which can be queried like regular attributes. You can use labels to organize entities into meaningful collections that can be selected using filters and tokens.

required

false

type

Map of key-value pairs. Keys can contain only letters, numbers, and underscores, but must start with a letter. Values can be any valid UTF-8 string.

default

null

example

"labels": {"environment": "development",
"region": "us-west-2"}

annotations

description

Arbitrary, non-identifying metadata to include with event data. In contrast to labels, annotations are not used internally by Sensu and cannot be used to identify entities. You can use annotations to add data that helps people or external tools interacting with Sensu.

required

false

type

Map of key-value pairs. Keys and values can be any valid UTF-8 string.

About Sensu

The Sensu monitoring event pipeline empowers businesses to automate their monitoring workflows and gain deep visibility into their multi-cloud infrastructure, from Kubernetes to bare metal. Companies like Sony, Box.com, and Activision rely on Sensu to help deliver value faster, at scale.