Entities

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).

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. Once created, proxy entities work much in the same way as any other Sensu entity.

New and improved entities

An entity, formally known as a client in Sensu 1.x, represents anything (ex: server, container, network switch) that needs to be monitored. Sensu Go uses an updated data model that allows for it to acknowledge the full range of infrastructure, runtime and application types that compose a complete monitoring environment (from server hardware to “serverless” functions). Sensu no longer focuses on the object doing the monitoring and instead focuses on the object it monitors. 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 ID of the entity upon which the check ran. In addition, an entity can contain system information such as the hostname, OS, platform, and version.

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 Sensu backend version 5.0, 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 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.
required false
type System
example
{
  "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 epoch time.
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.
required false
type Deregistration
example
{
  "deregistration": {
    "handler": "email-handler"
  }
}
keepalive_timeout
description The time in seconds until an entity keepalive is considered stale.
required false
type integer
default 120
example
"keepalive_timeout": 120 
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"
  ]
}

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 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 and 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.
default null
example
 "annotations": {
  "managed-by": "ops",
  "slack-channel": "#monitoring",
  "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.
required false
type Network
example
{
  "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": [
    {
      "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": {
    "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"
    ]
  }
}