Entities reference
An entity represents anything that needs to be monitored, such as a server, container, or network switch, including the full range of infrastructure, runtime, and application types that compose a complete monitoring environment. Sensu uses agent entities, proxy entities, and service entities.
Sensu’s free entity limit is 100 entities. All commercial features are available for free in the packaged Sensu Go distribution for up to 100 entities. If your Sensu instance includes more than 100 entities, contact us to learn how to upgrade your installation and increase your limit.
Learn more about entity limits in the license reference. Read the announcement on our blog for more information about our usage policy.
Create and manage agent entities
When an agent connects to a backend, the agent entity definition is created from the information in the agent.yml
configuration file.
The default agent.yml
file location depends on your operating system.
Agent entity example
This example shows the resource definition for an agent entity:
---
type: Entity
api_version: core/v2
metadata:
name: webserver01
spec:
deregister: false
deregistration: {}
entity_class: agent
last_seen: 1542667231
redact:
- password
- passwd
- pass
- api_key
- api_token
- access_key
- secret_key
- private_key
- secret
subscriptions:
- entity:webserver01
system:
arch: amd64
libc_type: glibc
vm_system: kvm
vm_role: host
cloud_provider: null
processes:
- name: Slack
pid: 1349
ppid: 0
status: Ss
background: true
running: true
created: 1582137786
memory_percent: 1.09932518
cpu_percent: 0.3263987595984941
- name: Slack Helper
pid: 1360
ppid: 1349
status: Ss
background: true
running: true
created: 1582137786
memory_percent: 0.146866455
cpu_percent: 0.30897618146109257
hostname: sensu2-centos
network:
interfaces:
- addresses:
- 127.0.0.1/8
- ::1/128
name: lo
- addresses:
- 10.0.2.15/24
- fe80::26a5:54ec:cf0d:9704/64
mac: 08:00:27:11:ad:d2
name: enp0s3
- addresses:
- 172.28.128.3/24
- fe80::a00:27ff:febc:be60/64
mac: 08:00:27:bc:be:60
name: enp0s8
os: linux
platform: centos
platform_family: rhel
platform_version: 7.4.1708
sensu_agent_version: 1.0.0
user: agent
{
"type": "Entity",
"api_version": "core/v2",
"metadata": {
"name": "webserver01"
},
"spec": {
"entity_class": "agent",
"system": {
"hostname": "sensu2-centos",
"os": "linux",
"platform": "centos",
"platform_family": "rhel",
"platform_version": "7.4.1708",
"network": {
"interfaces": [
{
"name": "lo",
"addresses": [
"127.0.0.1/8",
"::1/128"
]
},
{
"name": "enp0s3",
"mac": "08:00:27:11:ad:d2",
"addresses": [
"10.0.2.15/24",
"fe80::26a5:54ec:cf0d:9704/64"
]
},
{
"name": "enp0s8",
"mac": "08:00:27:bc:be:60",
"addresses": [
"172.28.128.3/24",
"fe80::a00:27ff:febc:be60/64"
]
}
]
},
"arch": "amd64",
"libc_type": "glibc",
"vm_system": "kvm",
"vm_role": "host",
"cloud_provider": "",
"processes": [
{
"name": "Slack",
"pid": 1349,
"ppid": 0,
"status": "Ss",
"background": true,
"running": true,
"created": 1582137786,
"memory_percent": 1.09932518,
"cpu_percent": 0.3263987595984941
},
{
"name": "Slack Helper",
"pid": 1360,
"ppid": 1349,
"status": "Ss",
"background": true,
"running": true,
"created": 1582137786,
"memory_percent": 0.146866455,
"cpu_percent": 0.308976181461092553
}
]
},
"sensu_agent_version": "1.0.0",
"subscriptions": [
"entity:webserver01"
],
"last_seen": 1542667231,
"deregister": false,
"deregistration": {},
"user": "agent",
"redact": [
"password",
"passwd",
"pass",
"api_key",
"api_token",
"access_key",
"secret_key",
"private_key",
"secret"
]
}
}
Manage agent entities via the backend
You can manage agent entities via the backend with sensuctl, the core/v2/entities API endpoints, and the web UI, just like any other Sensu resource.
This means you do not need to update the agent.yml
configuration file to add, update, or delete agent entity attributes like subscriptions and labels.
Management via the backend is the default configuration for agent entities.
NOTE: If you manage an agent entity via the backend, you cannot modify the agent entity with the agent.yml
configuration file unless you delete the entity.
In this case, the entity attributes in agent.yml
are used only for initial entity creation unless you delete the entity.
If you delete an agent entity that you modified with sensuctl, the core/v2/entities API endpoints, or the web UI, it will revert to the original configuration from agent.yml
.
If you change an agent entity’s class to proxy
, the backend will revert the change to agent
.
Manage agent entities via the agent
If you prefer, you can manage agent entities via the agent rather than the backend.
To do this, add the agent-managed-entity
configuration option when you start the Sensu agent or set agent-managed-entity: true
in your agent.yml
file.
When you start an agent with the agent-managed-entity
configuration option set to true
, the agent becomes responsible for managing its entity configuration.
An entity managed by this agent will include the label sensu.io/managed_by: sensu-agent
.
You cannot update these agent-managed entities via the Sensu backend REST API.
To change an agent’s configuration, restart the agent.
You can also maintain agent entities based on agent.yml
by creating ephemeral agent entities with the deregister attribute set to true
.
With this setting, the agent entity will deregister every time the agent process stops and its keepalive expires.
When it restarts, it will revert to the original configuration from agent.yml
You must set deregister: true
in agent.yml
before the agent entity is created.
Create and manage proxy entities
Proxy entities allow Sensu to monitor external resources on systems where you cannot install a Sensu agent, like a network switch or website.
You can create proxy entities the same way you would create agent entities, but Sensu can also dynamically create them when an entity does not already exist for a check result and add them to the entity store.
In this case, Sensu will use the proxy_entity_name
defined in the check to register proxy entities for your external resources.
Proxy entity registration differs from keepalive-based registration because the registration event happens while processing a check result instead of a keepalive message.
Modify proxy entities as needed via the backend with sensuctl, the core/v2/entities API endpoints, and the web UI.
NOTE: If you start an agent with the same name as an existing proxy entity, Sensu will change the proxy entity’s class to agent
and update its system
field with information from the agent configuration.
Proxy entity example
This example shows the resource definition for a proxy entity:
---
type: Entity
api_version: core/v2
metadata:
name: sensu-docs
spec:
deregister: false
deregistration: {}
entity_class: proxy
last_seen: 0
sensu_agent_version: 1.0.0
subscriptions: null
system:
cloud_provider: ""
libc_type: ""
network:
interfaces: null
processes: null
vm_role: ""
vm_system: ""
{
"type": "Entity",
"api_version": "core/v2",
"metadata": {
"name": "sensu-docs"
},
"spec": {
"deregister": false,
"deregistration": {
},
"entity_class": "proxy",
"last_seen": 0,
"sensu_agent_version": "1.0.0",
"subscriptions": null,
"system": {
"cloud_provider": "",
"libc_type": "",
"network": {
"interfaces": null
},
"processes": null,
"vm_role": "",
"vm_system": ""
}
}
}
Checks for proxy entities
Proxy entities allow Sensu to monitor external resources on systems or devices where a Sensu agent cannot be installed, like a network switch, website, or API endpoint.
You can configure a proxy check that includes a proxy_entity_name
to associate the check results with a specific proxy entity.
On the first check result, if the named proxy entity does not exist, Sensu will create it.
You can also use proxy checks to monitor multiple proxy entities based on entity attributes specified in the check definition’s proxy_requests
attribute.
When you create a proxy check, make sure the check definition includes a subscription that matches the subscription of at least one agent entity to define which agents will run the check. Proxy entities do not use subscriptions.
Read Monitor external resources with proxy entities for details about creating proxy checks for one or more proxy entities.
Proxy entities and round robin scheduling
Proxy entities make round robin check scheduling more useful because they allow you to combine all round robin events into a single event. Instead of having a separate event for each agent entity, you have a single event for the entire round robin.
If you don’t use a proxy entity for round robin scheduling, you could have several failures in a row, but each event will only be aware of one of the failures.
If you use a proxy entity without round robin scheduling, and several agents share the same subscription, they will all execute the check for the proxy entity and you’ll get duplicate results. When you enable round robin, you’ll get one agent per interval executing the proxy check, but the event will always be listed under the proxy entity.
Use proxy entity filters to establish a many-to-many relationship between agent entities and proxy entities if you want even more power over the grouping.
Create and manage service entities
COMMERCIAL FEATURE: Access business service monitoring (BSM), including service entities, in the packaged Sensu Go distribution. For more information, read Get started with commercial features.
NOTE: Business service monitoring (BSM) is in public preview and is subject to change.
Service entities are dynamically created entities that Sensu adds to the entity store when a service component generates an event. Service entities allow Sensu to monitor business services.
Create and modify service entities via the backend with sensuctl, the core/v2/entities API endpoints, and the web UI.
Service entity example
This example shows the resource definition for a service entity:
---
type: Entity
api_version: core/v2
metadata:
name: postgresql
spec:
entity_class: service
{
"type": "Entity",
"api_version": "core/v2",
"metadata": {
"name": "postgresql"
},
"spec": {
"entity_class": "service"
}
}
Backend entities
When a backend starts up, Sensu automatically creates the sensu-system
namespace and a new entity with entity_class: backend
.
Sensu populates the backend entity with the backend’s system information.
The backend uses its own entity to report cluster state errors. Backend entities can generate events due to error conditions like unavailable secrets providers or secrets. Events generated by a sensu-agent running on the backend host are also associated with the backend entity.
To prevent overloading the event bus with backend events, Sensu generates backend events no more than every 30 seconds, unless the status changes. Sensu does not generate keepalive events for backend entities.
Backend entity example
Here is an example definition for a backend entity:
---
type: Entity
api_version: core/v2
metadata:
name: 6b6264feda40
namespace: sensu-system
spec:
deregister: false
deregistration: {}
entity_class: backend
last_seen: 0
sensu_agent_version: ''
subscriptions: null
system:
arch: amd64
cloud_provider: ''
hostname: 6b6264feda40
libc_type: glibc
network:
interfaces:
- addresses:
- 127.0.0.1/8
name: lo
- addresses: null
name: tunl0
- addresses: null
name: ip6tnl0
- addresses:
- 172.18.0.4/16
mac: 02:42:ac:12:00:04
name: eth0
os: linux
platform: redhat
platform_family: rhel
platform_version: '7.9'
processes: null
vm_role: guest
vm_system: ''
{
"type": "Entity",
"api_version": "core/v2",
"metadata": {
"name": "6b6264feda40",
"namespace": "sensu-system"
},
"spec": {
"deregister": false,
"deregistration": {
},
"entity_class": "backend",
"last_seen": 0,
"sensu_agent_version": "",
"subscriptions": null,
"system": {
"arch": "amd64",
"cloud_provider": "",
"hostname": "6b6264feda40",
"libc_type": "glibc",
"network": {
"interfaces": [
{
"addresses": [
"127.0.0.1/8"
],
"name": "lo"
},
{
"addresses": null,
"name": "tunl0"
},
{
"addresses": null,
"name": "ip6tnl0"
},
{
"addresses": [
"172.18.0.4/16"
],
"mac": "02:42:ac:12:00:04",
"name": "eth0"
}
]
},
"os": "linux",
"platform": "redhat",
"platform_family": "rhel",
"platform_version": "7.9",
"processes": null,
"vm_role": "guest",
"vm_system": ""
}
}
}
Access backend entities
Only cluster admins have access to the sensu-system
namespace and the backend entities it contains.
If you have cluster admin permissions, you can use sensuctl and the web UI to access backend entities like other entities.
Cluster admins who have write permissions for the sensu-system
namespace can edit only labels and subscriptions for backend entities.
Backend entities and agent information
Sensu uses the same algorithm to determine backend entity names as the agent uses to determine entity names.
If a backend and an agent try to create the same entity, the entity class will default to backend
.
The information provided by the backend takes precedence over the information provided by the agent.
The backend should update backend entities to use information from the backend instead of from the agent.
Delete a backend entity
Cluster admins can manually delete backend entities with sensuctl or the web UI.
Manage entity labels
Labels are custom attributes that Sensu includes with observation event data that you can use for response and web UI view searches. In contrast to annotations, you can use labels to filter API responses, sensuctl responses, and web UI search views.
Limit labels to metadata you need to use for response filtering and searches. For complex, non-identifying metadata that you will not need to use in response filtering and searches, use annotations rather than labels.
Agent entity labels
For new 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
:
labels:
url: sensu.docs.io
Or, use sensu-agent start
configuration flags:
sensu-agent start --labels url=sensu.docs.io
NOTE: The entity attributes in agent.yml
are used only for initial entity creation.
Modify existing agent entities via the backend with sensuctl, the core/v2/entities API endpoints, and the web UI.
Proxy entity labels
For entities with class proxy
, you can create and manage labels with sensuctl.
For example, suppose you have a proxy entity like this one:
---
type: Entity
api_version: core/v2
metadata:
labels:
url: docs.sensu.io
name: sensu-docs
spec:
deregister: false
entity_class: proxy
sensu_agent_version: 1.0.0
{
"type": "Entity",
"api_version": "core/v2",
"metadata": {
"labels": {
"url": "docs.sensu.io"
},
"name": "sensu-docs"
},
"spec": {
"deregister": false,
"entity_class": "proxy",
"sensu_agent_version": "1.0.0"
}
}
To add a proxy_type
label to this existing entity, run the following command to open the entity definition:
sensuctl edit entity sensu-docs
Then, update the metadata scope in the entity definition to add the proxy_type
label as shown below:
---
type: Entity
api_version: core/v2
metadata:
labels:
url: docs.sensu.io
proxy_type: website
name: sensu-docs
spec:
'...': '...'
{
"type": "Entity",
"api_version": "core/v2",
"metadata": {
"labels": {
"url": "docs.sensu.io",
"proxy_type": "website"
},
"name": "sensu-docs"
},
"spec": {
"...": "..."
}
}
Save your changes to update the proxy entity definition with the proxy_type
label.
Service entity labels
For entities with class service
, you can create and manage labels with sensuctl.
To create a service entity with a service_type
label using sensuctl create
, create a file called service-entity.json
with an entity definition that includes labels
:
---
type: Entity
api_version: core/v2
metadata:
name: postgresql
labels:
service_type: datastore
spec:
entity_class: service
{
"type": "Entity",
"api_version": "core/v2",
"metadata": {
"name": "postgresql",
"labels": {
"service_type": "datastore"
}
},
"spec": {
"entity_class": "service"
}
}
Then run sensuctl create to create the entity based on the definition:
sensuctl create --file service-entity.yml
sensuctl create --file service-entity.json
To add a label to an existing service entity, use sensuctl edit.
For example, to add a region
label to a postgresql
entity:
sensuctl edit entity postgresql
And update the metadata scope to include the region
label:
---
type: Entity
api_version: core/v2
metadata:
labels:
service_type: datastore
region: us-west-1
name: postgresql
spec:
'...': '...'
{
"type": "Entity",
"api_version": "core/v2",
"metadata": {
"labels": {
"service_type": "datastore",
"region": "us-west-1"
},
"name": "postgresql"
},
"spec": {
"...": "..."
}
}
Entities specification
Top-level attributes
api_version | |
---|---|
description | Top-level attribute that specifies the Sensu API group and version. For entities in this version of Sensu, 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 |
|
metadata | |
---|---|
description | Top-level collection of metadata about the entity, including name , namespace , and created_by 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. Read metadata attributes for details. |
required | Required for entity definitions in wrapped-json or yaml format for use with sensuctl create . |
type | Map of key-value pairs |
example |
|
spec | |
---|---|
description | Top-level map that includes the entity spec attributes. |
required | Required for entity definitions in wrapped-json or yaml format for use with sensuctl create . |
type | Map of key-value pairs |
example |
|
type | |
---|---|
description | Top-level attribute that specifies the sensuctl create resource type. Entities should always be type Entity . |
required | Required for entity definitions in wrapped-json or yaml format for use with sensuctl create . |
type | String |
example |
|
Metadata attributes
annotations | |
---|---|
description | Non-identifying metadata to include with observation event data that you can access with event filters. You can use annotations to add data that’s meaningful to people or external tools that interact with Sensu. In contrast to labels, you cannot use annotations in API response filtering, sensuctl response filtering, or web UI views. NOTE: For annotations defined in agent.yml or backend.yml, the keys are automatically modified to use all lower-case letters. For example, if you define the annotation |
required | false |
type | Map of key-value pairs. Keys and values can be any valid UTF-8 string. |
default | null |
example |
|
created_by | |
---|---|
description | Username of the Sensu user who created the entity or last updated the entity. Sensu automatically populates the created_by field when the entity is created or updated. |
required | false |
type | String |
example |
|
labels | |
---|---|
description | Custom attributes to include with observation event data that you can use for response and web UI view filtering. If you include labels in your event data, you can filter API responses, sensuctl responses, and web UI views based on them. In other words, labels allow you to create meaningful groupings for your data. Limit labels to metadata you need to use for response filtering. For complex, non-identifying metadata that you will not need to use in response filtering, use annotations rather than labels. NOTE: For labels that you define in agent.yml or backend.yml, the keys are automatically modified to use all lower-case letters. For example, if you define the label |
required | false |
type | Map of key-value pairs. Keys can contain only letters, numbers, and underscores and must start with a letter. Values can be any valid UTF-8 string. |
default | null |
example |
|
name | |
---|---|
description | Unique name of the entity, validated with Go regex \A[\w\.\-]+\z . |
required | true |
type | String |
example |
|
namespace | |
---|---|
description | Sensu RBAC namespace that this entity belongs to. |
required | false |
type | String |
default | default |
example |
|
Spec attributes
deregister | |
---|---|
description | If the entity should be removed when it stops sending keepalive messages, true . Otherwise, false . |
required | false |
type | Boolean |
default | false |
example |
|
deregistration | |
---|---|
description | Map that contains a handler name to use when an agent entity is deregistered. Read deregistration attributes for more information. |
required | false |
type | Map |
example |
|
entity_class | |
---|---|
description | Entity type, validated with Go regex \A[\w\.\-]+\z . Class names have special meaning. An entity that runs an agent is class agent and is reserved. Setting the value of entity_class to proxy creates a proxy entity. An entity that represents a business service is class service . 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 |
|
last_seen | |
---|---|
description | Time at which the entity was last seen. In seconds since the Unix epoch. |
required | false |
type | Integer |
example |
|
redact | |
---|---|
description | List of items to redact from log messages. If a value is provided, it overwrites the default list of items to be redacted. |
required | false |
type | Array |
default | [“password”, “passwd”, “pass”, “api_key”, “api_token”, “access_key”, “secret_key”, “private_key”, “secret”] |
example |
|
sensu_agent_version | |
---|---|
description | Sensu Semantic Versioning (SemVer) version of the agent entity. |
required | true |
type | String |
example |
|
subscriptions | |
---|---|
description | 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 |
|
system | |
---|---|
description | System information about the entity, such as operating system and platform. Read system attributes for more information.
NOTE: Process discovery is disabled in this version of Sensu. New events will not include data in the |
required | false |
type | Map |
example |
|
user | |
---|---|
description | Sensu RBAC username used by the entity. Agent entities require get, list, create, update, and delete permissions for events across all namespaces. |
type | String |
default | agent |
example |
|
Deregistration attributes
handler | |
---|---|
description | Name of the handler to call when an agent entity is deregistered. |
required | false |
type | String |
example |
|
System attributes
arch | |
---|---|
description | Entity’s system architecture. This value is determined by the Go binary architecture as a function of runtime.GOARCH. An amd system running a 386 binary will report the arch as 386 . |
required | false |
type | String |
example |
|
arm_version | |
---|---|
description | Entity’s ARM version. Automatically populated upon agent startup for entities with ARM system architecture. For entities that do not use ARM system architecture, the arm_version attribute is omitted from the entity definition. |
required | false |
type | Integer |
example |
|
cloud_provider | |
---|---|
description | Entity’s cloud provider environment. Automatically populated upon agent startup if the detect-cloud-provider configuration option is set. Returned empty unless the agent runs on Amazon Elastic Compute Cloud (EC2), Google Cloud Platform (GCP), or Microsoft Azure.
NOTE: This feature can result in several HTTP requests or DNS lookups being performed, so it may not be appropriate for all environments. |
required | false |
type | String |
example |
|
float_type | |
---|---|
description | Type of float the entity’s system architecture uses: hardfloat or softfloat . Automatically populated upon agent startup for entities with MIPS, MIPS LE, MIPS 64, or MIPS 64 LE system architecture. For entities that do not use a MIPS system architecture, the float_type attribute is omitted from the entity definition. |
required | false |
type | String |
example |
|
hostname | |
---|---|
description | Hostname of the entity. |
required | false |
type | String |
example |
|
libc_type | |
---|---|
description | Entity’s libc type. |
required | false |
type | String |
example |
|
network | |
---|---|
description | Entity’s network interface list. Read network attributes for more information. |
required | false |
type | Map |
example |
|
os | |
---|---|
description | Entity’s operating system. |
required | false |
type | String |
example |
|
platform | |
---|---|
description | Entity’s operating system distribution. |
required | false |
type | String |
example |
|
platform_family | |
---|---|
description | Entity’s operating system family. |
required | false |
type | String |
example |
|
platform_version | |
---|---|
description | Entity’s operating system version. |
required | false |
type | String |
example |
|
processes | |
---|---|
description | List of processes on the local agent. Read processes attributes for more information.
NOTE: Process discovery is disabled in this version of Sensu. New events will not include data in the |
required | false |
type | Map |
example |
|
vm_role | |
---|---|
description | Entity’s virtual machine role. Automatically populated upon agent startup. |
required | false |
type | String |
example |
|
vm_system | |
---|---|
description | Entity’s virtual machine system. Automatically populated upon agent startup. |
required | false |
type | String |
example |
|
Network attributes
interfaces | |
---|---|
description | List of network interfaces available on the entity, with their associated MAC and IP addresses. Read interfaces attributes for more information. |
required | false |
type | Array |
example |
|
Interfaces attributes
addresses | |
---|---|
description | List of IP addresses for the network interface. |
required | false |
type | Array |
example |
|
mac | |
---|---|
description | Network interface’s MAC address. |
required | false |
type | string |
example |
|
name | |
---|---|
description | Network interface name. |
required | false |
type | String |
example |
|
Processes attributes
COMMERCIAL FEATURE: Access processes attributes with the discover-processes
configuration option in the packaged Sensu Go distribution.
For more information, read Get started with commercial features.
NOTE: Process discovery is disabled in this version of Sensu.
New events will not include data in the processes
attributes.
Instead, the field will be empty: "processes": null
.
background | |
---|---|
description | If true , the process is a background process. Otherwise, false . |
required | false |
type | Boolean |
example |
|
cpu_percent | |
---|---|
description | Percent of CPU the process is using. The value is returned as a floating-point number where 0.0 = 0% and 1.0 = 100%. For example, the cpu_percent value 0.12639 equals 12.639%.
NOTE: The |
required | false |
type | float |
example |
|
created | |
---|---|
description | Time at which the process was created. In seconds since the Unix epoch. |
required | false |
type | Integer |
example |
|
memory_percent | |
---|---|
description | Percent of memory the process is using. The value is returned as a floating-point number where 0.0 = 0% and 1.0 = 100%. For example, the memory_percent value 0.19932 equals 19.932%.
NOTE: The |
required | false |
type | float |
example |
|
name | |
---|---|
description | Name of the process. |
required | false |
type | String |
example |
|
pid | |
---|---|
description | Process ID of the process. |
required | false |
type | Integer |
example |
|
ppid | |
---|---|
description | Parent process ID of the process. |
required | false |
type | Integer |
example |
|
running | |
---|---|
description | If true , the process is running. Otherwise, false . |
required | false |
type | Boolean |
example |
|
status | |
---|---|
description | Status of the process. Read the Linux top manual page for examples. |
required | false |
type | String |
example |
|