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 
api_version: core/v2
{
  "api_version": "core/v2"
}
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 
metadata:
  name: webserver01
  namespace: default
  created_by: admin
  labels:
    region: us-west-1
  annotations:
    slack-channel: "#monitoring"
{
  "metadata": {
    "name": "webserver01",
    "namespace": "default",
    "created_by": "admin",
    "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
    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.30897618146109257
  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
{
  "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.30897618146109257
        }
      ]
    },
    "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"
    ]
  }
}
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 
type: Entity
{
  "type": "Entity"
}

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 webhookURL: "https://my-webhook.com" in agent.yml or backend.yml, it will be listed as webhookurl: "https://my-webhook.com" in entity definitions.

Key cases are not modified for annotations you define with a command line flag or an environment variable.
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
{
  "annotations": {
    "managed-by": "ops",
    "playbook": "www.example.url"
  }
}
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 
created_by: admin
{
  "created_by": "admin"
}
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 proxyType: "website" in agent.yml or backend.yml, it will be listed as proxytype: "website" in entity definitions.

Key cases are not modified for labels you define with a command line flag or an environment variable.
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 
labels:
  environment: development
  region: us-west-2
{
  "labels": {
    "environment": "development",
    "region": "us-west-2"
  }
}
name
description Unique name of the entity, validated with Go regex \A[\w\.\-]+\z.
required true
type String
example 
name: example-hostname
{
  "name": "example-hostname"
}
namespace
description Sensu RBAC namespace that this entity belongs to.
required false
type String
default default
example 
namespace: production
{
  "namespace": "production"
}

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 
deregister: false
{
  "deregister": false
}
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 
deregistration:
  handler: email-handler
{
  "deregistration": {
    "handler": "email-handler"
  }
}
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 
entity_class: agent
{
  "entity_class": "agent"
}
last_seen
description Time at which the entity was last seen. In seconds since the Unix epoch.
required false
type Integer
example 
last_seen: 1522798317
{
  "last_seen": 1522798317
}
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"
  ]
}
sensu_agent_version
description Sensu Semantic Versioning (SemVer) version of the agent entity.
required true
type String
example 
sensu_agent_version: 1.0.0
{
  "sensu_agent_version": "1.0.0"
}
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 
subscriptions:
- web
- prod
- entity:example-entity
{
  "subscriptions": [
    "web",
    "prod",
    "entity:example-entity"
  ]
}
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 processes attributes. Instead, the field will be empty: "processes": null.
required false
type Map
example 
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: 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",
    "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
      }
    ]
  }
}
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
{
  "user": "agent"
}

Deregistration attributes

handler
description Name of the handler to call when an agent entity is deregistered.
required false
type String
example 
handler: email-handler
{
  "handler": "email-handler"
}

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 
arch: amd64
{
  "arch": "amd64"
}
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 
arm_version: 7
{
  "arm_version": 7
}
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 
"cloud_provider": ""
{
  "cloud_provider": ""
}
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 
float_type: hardfloat
{
  "float_type": "hardfloat"
}
hostname
description Hostname of the entity.
required false
type String
example 
hostname: example-hostname
{
  "hostname": "example-hostname"
}
libc_type
description Entity’s libc type.
required false
type String
example 
libc_type: glibc
{
  "libc_type": "glibc"
}
network
description Entity’s network interface list. Read 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"
        ]
      }
    ]
  }
}
os
description Entity’s operating system.
required false
type String
example 
os: linux
{
  "os": "linux"
}
platform
description Entity’s operating system distribution.
required false
type String
example 
platform: ubuntu
{
  "platform": "ubuntu"
}
platform_family
description Entity’s operating system family.
required false
type String
example 
platform_family: debian
{
  "platform_family": "debian"
}
platform_version
description Entity’s operating system version.
required false
type String
example 
platform_version: 16.04
{
  "platform_version": "16.04"
}
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 processes attributes. Instead, the field will be empty: "processes": null.
required false
type Map
example 
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
{
  "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
    }
  ]
}
vm_role
description Entity’s virtual machine role. Automatically populated upon agent startup.
required false
type String
example 
vm_role: host
{
  "vm_role": "host"
}
vm_system
description Entity’s virtual machine system. Automatically populated upon agent startup.
required false
type String
example 
vm_system: kvm
{
  "vm_system": "kvm"
}

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

Interfaces attributes

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

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 
background: true
{
  "background": true
}
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 cpu_percent attribute is supported on Linux and macOS. It is not supported on Windows.
required false
type float
example 
cpu_percent: 0.12639
{
  "cpu_percent": 0.12639
}
created
description Time at which the process was created. In seconds since the Unix epoch.
required false
type Integer
example 
created: 1586138786
{
  "created": 1586138786
}
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 memory_percent attribute is supported on Linux and macOS. It is not supported on Windows.
required false
type float
example 
memory_percent: 0.19932
{
  "memory_percent": 0.19932
}
name
description Name of the process.
required false
type String
example 
name: Slack
{
  "name": "Slack"
}
pid
description Process ID of the process.
required false
type Integer
example 
pid: 1349
{
  "pid": 1349
}
ppid
description Parent process ID of the process.
required false
type Integer
example 
ppid: 0
{
  "ppid": 0
}
running
description If true, the process is running. Otherwise, false.
required false
type Boolean
example 
running: true
{
  "running": true
}
status
description Status of the process. Read the Linux top manual page for examples.
required false
type String
example 
status: Ss
{
  "status": "Ss"
}