Entities

What is an entity?

An entity represents anything (such as a server, container, or 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.

How do entities work?

Agent entities are monitoring agents that 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 (e.g. a webserver or a database). Sensu entities will “subscribe” to (or watch for) check requests published by the Sensu backend (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 backend).

Proxy entities are dynamically created entities that are added to the entity store if an entity does not already exist for a check result. Proxy entities allow Sensu to monitor external resources on systems where a Sensu agent cannot be installed (like a network switch or website) using the defined check ProxyEntityName to create a proxy entity for the external resource.

Usage limits

This version of Sensu has no functional limitations based on entity count. If your Sensu instance includes over 1,000 entities, contact us to learn about license-activated features designed for monitoring at scale. See Discourse for more information about our usage policy.

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

Labels are custom attributes that Sensu includes with event data, which can be accessed using filters and tokens. In contrast to annotations, you can use labels to create meaningful collections that can be selected with API filtering and sensuctl filtering. Overusing labels can impact Sensu’s internal performance, so we recommend moving complex, non-identifying metadata to annotations.

Proxy entity labels

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.

type: Entity
api_version: core/v2
metadata:
  labels:
    url: docs.sensu.io
  name: sensu-docs
  namespace: default
spec:
  deregister: false
  deregistration: {}
  entity_class: proxy
  last_seen: 0
  subscriptions: []
  system:
    network:
      interfaces: null
{
  "type": "Entity",
  "api_version": "core/v2",
  "metadata": {
    "name": "sensu-docs",
    "namespace": "default",
    "labels": {
      "url": "docs.sensu.io"
    }
  },
  "spec": {
    "deregister": false,
    "deregistration": {},
    "entity_class": "proxy",
    "last_seen": 0,
    "subscriptions": [],
    "system": {
      "network": {
        "interfaces": null
      }
    }
  }
}

Then run sensuctl create to create the entity based on the definition.

sensuctl create --file entity.json

To add a label to an existing entity, you can use sensuctl edit. For example, run sensuctl edit to add a url label to a sensu-docs entity.

sensuctl edit entity sensu-docs

And update the metadata scope to include labels.

type: Entity
api_version: core/v2
metadata:
  labels:
    url: docs.sensu.io
  name: sensu-docs
  namespace: default
spec:
  '...': '...'
{
  "type": "Entity",
  "api_version": "core/v2",
  "metadata": {
    "name": "sensu-docs",
    "namespace": "default",
    "labels": {
      "url": "docs.sensu.io"
    }
  },
  "spec": {
    "...": "..."
  }
}

Proxy entity checks

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 check with a proxy entity name to associate the check results with that proxy entity. On the first check result, if the proxy entity does not exist, Sensu will create the entity as a proxy entity.

After you create a proxy entity check, define which agents will run the check by configuring a subscription. See proxy requests for details on creating a proxy check for a proxy entity.

Agent entity labels

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.

labels:
  url: sensu.docs.io

Or using sensu-agent start configuration flags.

sensu-agent start --labels url=sensu.docs.io

Entities specification

Top-level attributes

type
description Top-level attribute specifying the sensuctl create resource type. Entities should always be of type Entity.
required 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 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
"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.
type Map of key-value pairs
example
"metadata": {
  "name": "webserver01",
  "namespace": "default",
  "labels": {
    "region": "us-west-1"
  },
  "annotations": {
    "slack-channel" : "#monitoring"
  }
}
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
"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"
    },
    "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"
    ]
  }

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.
required false
type map
example
system:
  arch: amd64
  hostname: example-hostname
  network:
    interfaces:
    - addresses:
      - 127.0.0.1/8
      - ::1/128
      name: lo
    - addresses:
      - 93.184.216.34/24
      - 2606:2800:220:1:248:1893:25c8:1946/10
      mac: 52:54:00:20:1b:3c
      name: eth0
  os: linux
  platform: ubuntu
  platform_family: debian
  platform_version: "16.04"
{
  "system": {
    "hostname": "example-hostname",
    "os": "linux",
    "platform": "ubuntu",
    "platform_family": "debian",
    "platform_version": "16.04",
    "network": {
      "interfaces": [
        {
          "name": "lo",
          "addresses": [
            "127.0.0.1/8",
            "::1/128"
          ]
        },
        {
          "name": "eth0",
          "mac": "52:54:00:20:1b:3c",
          "addresses": [
            "93.184.216.34/24",
            "2606:2800:220:1:248:1893:25c8:1946/10"
          ]
        }
      ]
    },
    "arch": "amd64"
  }
}
last_seen
description Timestamp the entity was last seen, in seconds since the Unix epoch.
required false
type integer
example
"last_seen": 1522798317 
deregister
description If the entity should be removed when it stops sending keepalive messages.
required false
type boolean
default false
example
"deregister": false 
deregistration
description A map containing a handler name, for use when an entity is deregistered. See the deregistration attributes for more information.
required false
type map
example
deregistration:
  handler: email-handler
{
  "deregistration": {
    "handler": "email-handler"
  }
}
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
redact:
- extra_secret_tokens
{
  "redact": [
    "extra_secret_tokens"
  ]
}
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
"user": "agent"

Metadata attributes

name
description The unique name of the entity, validated with Go regex \A[\w\.\-]+\z.
required true
type String
example
"name": "example-hostname"
namespace
description The Sensu RBAC namespace that this entity belongs to.
required false
type String
default default
example
"namespace": "production"
labels
description Custom attributes to include with event data, which can be accessed using filters and tokens.

In contrast to annotations, you can use labels to create meaningful collections that can be selected with API filtering and sensuctl filtering. Overusing labels can impact Sensu’s internal performance, so we recommend moving complex, non-identifying metadata to annotations.
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 Non-identifying metadata to include with event data, which can be accessed using filters and tokens. You can use annotations to add data that’s meaningful to people or external tools interacting with Sensu.

In contrast to labels, annotations cannot be used in API filtering or sensuctl filtering and do not impact Sensu’s internal performance.
required false
type Map of key-value pairs. Keys and values can be any valid UTF-8 string.
default null
example
 "annotations": {
  "managed-by": "ops",
  "playbook": "www.example.url"
}

System attributes

hostname
description The hostname of the entity.
required false
type string
example
"hostname": "example-hostname" 
os
description The entity’s operating system.
required false
type string
example
"os": "linux" 
platform
description The entity’s operating system distribution.
required false
type string
example
"platform": "ubuntu" 
platform_family
description The entity’s operating system family.
required false
type string
example
"platform_family": "debian" 
platform_version
description The entity’s operating system version.
required false
type string
example
"platform_version": "16.04" 
network
description The entity’s network interface list. See the network attributes for more information.
required false
type map
example
network:
  interfaces:
  - addresses:
    - 127.0.0.1/8
    - ::1/128
    name: lo
  - addresses:
    - 93.184.216.34/24
    - 2606:2800:220:1:248:1893:25c8:1946/10
    mac: 52:54:00:20:1b:3c
    name: eth0
{
  "network": {
    "interfaces": [
      {
        "name": "lo",
        "addresses": [
          "127.0.0.1/8",
          "::1/128"
        ]
      },
      {
        "name": "eth0",
        "mac": "52:54:00:20:1b:3c",
        "addresses": [
          "93.184.216.34/24",
          "2606:2800:220:1:248:1893:25c8:1946/10"
        ]
      }
    ]
  }
}
arch
description The 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
"arch": "amd64" 

Network attributes

network_interface
description The list of network interfaces available on the entity, with their associated MAC and IP addresses.
required false
type array NetworkInterface
example
interfaces:
- addresses:
  - 127.0.0.1/8
  - ::1/128
  name: lo
- addresses:
  - 93.184.216.34/24
  - 2606:2800:220:1:248:1893:25c8:1946/10
  mac: 52:54:00:20:1b:3c
  name: eth0
{
  "interfaces": [
    {
      "name": "lo",
      "addresses": [
        "127.0.0.1/8",
        "::1/128"
      ]
    },
    {
      "name": "eth0",
      "mac": "52:54:00:20:1b:3c",
      "addresses": [
        "93.184.216.34/24",
        "2606:2800:220:1:248:1893:25c8:1946/10"
      ]
    }
  ]
}

NetworkInterface attributes

name
description The network interface name.
required false
type string
example
"name": "eth0"
mac
description The network interface’s MAC address.
required false
type string
example
"mac": "52:54:00:20:1b:3c"
addresses
description The list of IP addresses for the interface.
required false
type array
example
 "addresses": ["93.184.216.34/24", "2606:2800:220:1:248:1893:25c8:1946/10"]

Deregistration attributes

handler
description The name of the handler to be called when an entity is deregistered.
required false
type string
example
"handler": "email-handler"

Examples

Entity definition

type: Entity
api_version: core/v2
metadata:
  annotations: null
  labels: null
  name: webserver01
  namespace: default
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
    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
  user: agent
{
  "type": "Entity",
  "api_version": "core/v2",
  "metadata": {
    "name": "webserver01",
    "namespace": "default",
    "labels": null,
    "annotations": null
  },
  "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"
    },
    "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"
    ]
  }
}