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 ProxyEntityID 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 2.0 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

Entity Attributes

ID
description The unique ID of the entity, validated with go regex \A[\w\.\-]+\z
required true
type string
example
"ID": "example-hostname"
class
description The entity type, validated with go regex \A[\w\.\-]+\z. This value is not user configurable; it is set directly by the agent. An entity that runs an agent will be of agent, while a proxy entity will have class proxy.
required true
type string
example
"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:{ID} where ID 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 
organization
description The Sensu RBAC organization that this entity belongs to.
required false
type string
example
"organization": "default"
environment
description The Sensu RBAC environment that this entity belongs to.
required false
type string
default current environment value configured for sensuctl (ie default)
example
"environment": "default"
extended_attributes
description Custom attributes to include with the entity, which can be queried like regular attributes.
required false
type JSON object
example
{"team":"ops"}
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"
  ]
}

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

{
  "class": "agent",
  "deregister": false,
  "deregistration": {},
  "environment": "default",
  "id": "example-hostname",
  "keepalive_timeout": 60,
  "last_seen": 1523387195,
  "organization": "default",
  "redact": [
    "password",
    "passwd",
    "pass",
    "api_key",
    "api_token",
    "access_key",
    "secret_key",
    "private_key",
    "secret"
  ],
  "subscriptions": [
    "entity:example-hostname"
  ],
  "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"
  },
  "user": "agent",
  "region": "us-west-1",
  "team": "ops"
}