Entities

or click any element in the pipeline to jump to it.

An entity represents anything that needs to be observed or 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 (from server hardware to serverless functions). Sensu calls parts of an infrastructure “entities.”

An entity provides the context for observation data in events — what and where the event is from. The check and entity names associated with an event determine the event’s uniqueness. Entities can also contain system information like the hostname, operating system, platform, and version.

There are four types of Sensu entities: agent, proxy, service, and backend entities.

Agent entities

Agent entities are monitoring agents that are installed and run on every system that needs to be observed or monitored. The agent entity registers the system with the Sensu backend service, sends keepalive messages (the Sensu heartbeat mechanism), and executes observability checks.

Each entity is a member of one or more subscriptions: a list of roles and responsibilities assigned to the agent entity (for example, a webserver or a database). Sensu entities “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).

This example shows an agent entity resource definition:

---
type: Entity
api_version: core/v2
metadata:
  name: i-424242
spec:
  deregister: false
  deregistration: {}
  entity_class: agent
  last_seen: 0
  sensu_agent_version: 1.0.0
  subscriptions:
  - web
  system:
    cloud_provider: ""
    libc_type: ""
    network:
      interfaces: null
    processes: null
    vm_role: ""
    vm_system: ""
{
  "type": "Entity",
  "api_version": "core/v2",
  "metadata": {
    "name": "i-424242"
  },
  "spec": {
    "deregister": false,
    "deregistration": {
    },
    "entity_class": "agent",
    "last_seen": 0,
    "sensu_agent_version": "1.0.0",
    "subscriptions": [
      "web"
    ],
    "system": {
      "cloud_provider": "",
      "libc_type": "",
      "network": {
        "interfaces": null
      },
      "processes": null,
      "vm_role": "",
      "vm_system": ""
    }
  }
}

Proxy entities

Proxy entities [formerly known as proxy clients or just-in-time (JIT) clients] allow Sensu to monitor external resources on systems where you cannot install a Sensu agent, like a network switch or website.

Proxy entities are dynamically created when an entity does not already exist for a check result. In this case, Sensu uses the proxy_entity_name defined in the check to create proxy entities for external resources.

This example shows a proxy entity resource definition:

---
type: Entity
api_version: core/v2
metadata:
  labels:
    proxy_type: website
    sensu.io/managed_by: sensuctl
    url: https://docs.sensu.io
  name: sensu-docs
  namespace: default
spec:
  deregister: false
  deregistration: {}
  entity_class: proxy
  last_seen: 0
  sensu_agent_version: ""
  subscriptions: null
  system:
    cloud_provider: ""
    libc_type: ""
    network:
      interfaces: null
    processes: null
    vm_role: ""
    vm_system: ""
{
  "type": "Entity",
  "api_version": "core/v2",
  "metadata": {
    "labels": {
      "proxy_type": "website",
      "sensu.io/managed_by": "sensuctl",
      "url": "https://docs.sensu.io"
    },
    "name": "sensu-docs",
    "namespace": "default"
  },
  "spec": {
    "deregister": false,
    "deregistration": {
    },
    "entity_class": "proxy",
    "last_seen": 0,
    "sensu_agent_version": "",
    "subscriptions": null,
    "system": {
      "cloud_provider": "",
      "libc_type": "",
      "network": {
        "interfaces": null
      },
      "processes": null,
      "vm_role": "",
      "vm_system": ""
    }
  }
}

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.

A service entity represents a business service in business service monitoring (BSM). Sensu processes service entity events just like events generated for agent and proxy entities. You can also use service entities for proxy check requests and events.

This example shows a service entity resource definition:

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

A backend entity represents a Sensu backend. Sensu automatically creates a backend entity for each backend when it is started and populates the entity with the backend’s system information. Users cannot manually create backend entities.

Backends use their own entities to generate events due to error conditions like unavailable components and services.

This example shows a backend entity resource definition:

---
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": ""
    }
  }
}

Usage limits

Sensu’s usage limits are based on entities.

The free 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. Read the announcement on our blog for more information about our usage policy.

Commercial licenses may include an entity limit and entity class limits:

  • Entity limit: the maximum number of entities of all classes your license includes. Agent, proxy, and service entities count toward the overall entity limit.
  • Entity class limits: the maximum number of a specific class of entities (agent, proxy, or service) that your license includes.

For example, if your license has an entity limit of 10,000 and an agent entity class limit of 3,000, you cannot run more than 10,000 entities (agent and proxy) total. At the same time, you cannot run more than 3,000 agents. If you use only 1,500 agent entities, you can have 8,500 proxy entities before you reach the overall entity limit of 10,000.

If you have permission to create or update licenses, you will see messages in sensuctl and the web UI when you approach your licensed entity or entity class limit, as well as when you exceed these limits. You can also use sensuctl or the /license API to view your overall entity count and limit.