<commit_before>---
title: "Client"
description: "Reference documentation for Sensu Clients."
version: 0.26
weight: 2
---

# Sensu Client

## Reference documentation

- [What is a Sensu client?](#what-is-a-sensu-client)
- [Client keepalives](#client-keepalives)
  - [What is a client keepalive?](#what-is-a-client-keepalive)
  - [Client registration & the client registry](#registration-and-registry)
    - [Registration events](#registration-events)
    - [Proxy clients](#proxy-clients)
  - [How are keepalive events created?](#keepalive-events)
  - [Client keepalive configuration](#client-keepalive-configuration)
- [Client subscriptions](#client-subscriptions)
  - [What is a client subscription?](#what-is-a-sensu-subscription)
  - [Round-robin client subscriptions](#round-robin-client-subscriptions)
  - [Client subscription configuration](#client-subscription-configuration)
- [Client socket input](#client-socket-input)
  - [What is the Sensu client socket](#what-is-the-sensu-client-socket)
  - [Example client socket usage](#example-client-socket-usage)
  - [Client socket configuration](#client-socket-configuration)
- [Standalone check execution scheduler](#standalone-check-execution-scheduler)
- [Client configuration](#client-configuration)
  - [Example client definition](#example-client-definition)
  - [Client definition specification](#client-definition-specification)
    - [`client` attributes](#client-attributes)
    - [`socket` attributes](#socket-attributes)
    - [`keepalive` attributes](#keepalive-attributes)
    - [`thresholds` attributes](#thresholds-attributes)
    - [`registration` attributes](#registration-attributes)
    - [`deregistration` attributes](#deregistration-attributes)
    - [`ec2` attributes](#ec2-attributes)
    - [`chef` attributes](#chef-attributes)
    - [`puppet` attributes](#puppet-attributes)
    - [`servicenow` attributes](#servicenow-attributes)
    - [Custom attributes](#custom-attributes)

## What is a Sensu client?

Sensu clients are [monitoring agents][1], which are installed and run on every
system (e.g. server, container, etc) that needs to be monitored. The client is
responsible for registering the system with Sensu, sending client [keepalive][2]
messages (the Sensu heartbeat mechanism), and executing monitoring checks. Each
client is a member of one or more [subscriptions][3] &ndash; a list of roles
and/or responsibilities assigned to the system (e.g. a webserver, database,
etc). Sensu clients will "subscribe" to (or watch for) [check requests][4]
published by the [Sensu server][5] (via the [Sensu Transport][6]), execute the
corresponding requests locally, and publish the results of the check back to the
transport (to be processed by a Sensu server).

## Client keepalives

### What is a client keepalive?

Sensu Client `keepalives` are the heartbeat mechanism used by Sensu to ensure
that all registered Sensu clients are still operational and able to reach the
[Sensu Transport][6]. Sensu clients publish keepalive messages containing client
configuration data to the Sensu transport every 20 seconds. If a Sensu client
fails to send keepalive messages over a period of 120 seconds (by default), the
Sensu server (or Sensu Enterprise) will create a keepalive [event][7].
Keepalives can be used to identify unhealthy systems and network partitions
(among other things), and keepalive events can trigger email notifications and
other useful actions.

### Client registration & the client registry {#registration-and-registry}

In practice, client registrations happens when a Sensu server processes a client
`keepalive` message for a client that is not already registered in the Sensu
client registry (based on the configured client `name` or `source` attribute).
This client registry is stored in the Sensu [data store][8], and is accessible
via the Sensu [Clients API][9].

All Sensu client data provided in client keepalive messages gets stored in the
client registry, which data is used to add context to Sensu [Events][7] and
to detect Sensu clients in an unhealthy state.

#### Registration events

If a [Sensu event handler][30] named `registration` is configured, or if a Sensu
client definition includes a [registration attribute][31], the [Sensu server][5]
will create and process a [Sensu event][7] for the client registration, applying
any configured [filters][26] and [mutators][32] before executing the configured
[handler(s)][30].

Registration events are useful for executing one-time handlers for new Sensu
clients. For example, registration event handlers can be used to update external
[Configuration Management Databases (CMDBs)][34] such as [ServiceNow][35], etc.

To configure a registration event handler, please refer to the [Sensu event
handler documentation][30] for instructions on creating a handler named
`registration`. Alternatively, please see [Client definition `registration`
attributes][31], below.

_WARNING: registration events are not stored in the event registry (in the Sensu
[data store][8]), so they are not accessible via the Sensu API; however, all
registration events are logged in the [Sensu server][5] log._

#### Proxy clients

Sensu proxy clients (formerly known as "Just-in-time" or "JIT" clients) are
dynamically created clients, added to the client registry if a client does not
already exist for a _check result_.

Proxy client registration differs from keepalive-based registration
because the registration event happens while processing a check result (not a
keepalive message). If a check result includes a `source` attribute, a proxy
client will be created for the `source`, and the check result will be stored
under the newly created client. Sensu proxy clients allow Sensu to monitor
external resources (e.g. on systems and/or devices where a `sensu-client` cannot
be installed, such a network switches), using the defined check `source` to
create a proxy clients for the external resource. Once created, proxy clients
work much in the same way as any other Sensu client; e.g. they are used to store
check execution history and provide context within event data.

_NOTE: `keepalive` monitoring is not supported for proxy clients, as they are
inherently unable to run a `sensu-client`._

##### Proxy client example

Proxy clients are created when a check result includes a `source` attribute, as
follows:

~~~ json
{
  "check": {
    "status": 0,
    "command": "check-http.rb -u https://sensuapp.org",
    "subscribers": [
      "demo"
    ],
    "interval": 60,
    "name": "sensu-website",
    "source": "sensuapp.org",
    "issued": 1458934742,
    "executed": 1458934742,
    "duration": 0.637,
    "output": "CheckHttp OK: 200, 78572 bytes\n"
  },
  "client": "sensu-docs"
}
~~~

_NOTE: this `source` attribute can be provided in a [check definition][14], or
included in a check result published to the Sensu [client input socket][36]._

By default, proxy client data includes a minimal number of attributes. The
following is an example of proxy client data that is added to the registry.

~~~ json
{
  "name": "switch-x",
  "address": "unknown",
  "subscriptions": [],
  "keepalives": false
}
~~~

The Sensu API can be used to update proxy client data in the client registry. To
update proxy client data, please refer to the [Client API reference
documentation][9].

### How are keepalive events created? {#keepalive-events}

Sensu servers (including Sensu Enterprise) monitor the Sensu client registry for
stale client data, detecting clients that have failed to send [client keepalive
messages][10] for more than 120 seconds (by default). When a Sensu server
detects that a client hasn't sent a keepalive message within the configured
`threshold`, _the Sensu server (or Sensu Enterprise)_ will create an event (this
is different from how events are created for monitoring checks; see ["How are
Sensu events created?"][11]).

### Client keepalive configuration

For more information on configuring client keepalives, please see the [client
keepalive attribute reference documentation][12] (below).

Sensu client keepalives are published to the Sensu transport every 20 seconds.
Client keepalive behavior can be configured per Sensu client, allowing each
Sensu client to set its own alert thresholds and keepalive event handlers. By
default, client data is considered stale if a keepalive hasn't be received in
`120` seconds (WARNING). By default, keepalive events will be sent to the Sensu
handler named `keepalive` if defined, or the `default` handler will be used.

To configure the keepalive check for a Sensu client, please refer to [the client
`keepalive` attributes reference documentation][12].
<commit_msg>Add a proxy client example that uses the client socket, based on discussion in sensu/sensu#1499<commit_after>---
title: "Client"
description: "Reference documentation for Sensu Clients."
version: 0.26
weight: 2
---

# Sensu Client

## Reference documentation

- [What is a Sensu client?](#what-is-a-sensu-client)
- [Client keepalives](#client-keepalives)
  - [What is a client keepalive?](#what-is-a-client-keepalive)
  - [Client registration & the client registry](#registration-and-registry)
    - [Registration events](#registration-events)
    - [Proxy clients](#proxy-clients)
  - [How are keepalive events created?](#keepalive-events)
  - [Client keepalive configuration](#client-keepalive-configuration)
- [Client subscriptions](#client-subscriptions)
  - [What is a client subscription?](#what-is-a-sensu-subscription)
  - [Round-robin client subscriptions](#round-robin-client-subscriptions)
  - [Client subscription configuration](#client-subscription-configuration)
- [Client socket input](#client-socket-input)
  - [What is the Sensu client socket](#what-is-the-sensu-client-socket)
  - [Example client socket usage](#example-client-socket-usage)
  - [Client socket configuration](#client-socket-configuration)
- [Standalone check execution scheduler](#standalone-check-execution-scheduler)
- [Client configuration](#client-configuration)
  - [Example client definition](#example-client-definition)
  - [Client definition specification](#client-definition-specification)
    - [`client` attributes](#client-attributes)
    - [`socket` attributes](#socket-attributes)
    - [`keepalive` attributes](#keepalive-attributes)
    - [`thresholds` attributes](#thresholds-attributes)
    - [`registration` attributes](#registration-attributes)
    - [`deregistration` attributes](#deregistration-attributes)
    - [`ec2` attributes](#ec2-attributes)
    - [`chef` attributes](#chef-attributes)
    - [`puppet` attributes](#puppet-attributes)
    - [`servicenow` attributes](#servicenow-attributes)
    - [Custom attributes](#custom-attributes)

## What is a Sensu client?

Sensu clients are [monitoring agents][1], which are installed and run on every
system (e.g. server, container, etc) that needs to be monitored. The client is
responsible for registering the system with Sensu, sending client [keepalive][2]
messages (the Sensu heartbeat mechanism), and executing monitoring checks. Each
client is a member of one or more [subscriptions][3] &ndash; a list of roles
and/or responsibilities assigned to the system (e.g. a webserver, database,
etc). Sensu clients will "subscribe" to (or watch for) [check requests][4]
published by the [Sensu server][5] (via the [Sensu Transport][6]), execute the
corresponding requests locally, and publish the results of the check back to the
transport (to be processed by a Sensu server).

## Client keepalives

### What is a client keepalive?

Sensu Client `keepalives` are the heartbeat mechanism used by Sensu to ensure
that all registered Sensu clients are still operational and able to reach the
[Sensu Transport][6]. Sensu clients publish keepalive messages containing client
configuration data to the Sensu transport every 20 seconds. If a Sensu client
fails to send keepalive messages over a period of 120 seconds (by default), the
Sensu server (or Sensu Enterprise) will create a keepalive [event][7].
Keepalives can be used to identify unhealthy systems and network partitions
(among other things), and keepalive events can trigger email notifications and
other useful actions.

### Client registration & the client registry {#registration-and-registry}

In practice, client registrations happens when a Sensu server processes a client
`keepalive` message for a client that is not already registered in the Sensu
client registry (based on the configured client `name` or `source` attribute).
This client registry is stored in the Sensu [data store][8], and is accessible
via the Sensu [Clients API][9].

All Sensu client data provided in client keepalive messages gets stored in the
client registry, which data is used to add context to Sensu [Events][7] and
to detect Sensu clients in an unhealthy state.

#### Registration events

If a [Sensu event handler][30] named `registration` is configured, or if a Sensu
client definition includes a [registration attribute][31], the [Sensu server][5]
will create and process a [Sensu event][7] for the client registration, applying
any configured [filters][26] and [mutators][32] before executing the configured
[handler(s)][30].

Registration events are useful for executing one-time handlers for new Sensu
clients. For example, registration event handlers can be used to update external
[Configuration Management Databases (CMDBs)][34] such as [ServiceNow][35], etc.

To configure a registration event handler, please refer to the [Sensu event
handler documentation][30] for instructions on creating a handler named
`registration`. Alternatively, please see [Client definition `registration`
attributes][31], below.

_WARNING: registration events are not stored in the event registry (in the Sensu
[data store][8]), so they are not accessible via the Sensu API; however, all
registration events are logged in the [Sensu server][5] log._

#### Proxy clients

Sensu proxy clients (formerly known as "Just-in-time" or "JIT" clients) are
dynamically created clients, added to the client registry if a client does not
already exist for a _check result_.

Proxy client registration differs from keepalive-based registration
because the registration event happens while processing a check result (not a
keepalive message). If a check result includes a `source` attribute, a proxy
client will be created for the `source`, and the check result will be stored
under the newly created client. Sensu proxy clients allow Sensu to monitor
external resources (e.g. on systems and/or devices where a `sensu-client` cannot
be installed, such a network switches), using the defined check `source` to
create a proxy clients for the external resource. Once created, proxy clients
work much in the same way as any other Sensu client; e.g. they are used to store
check execution history and provide context within event data.

_NOTE: `keepalive` monitoring is not supported for proxy clients, as they are
inherently unable to run a `sensu-client`._

##### Proxy client example

Proxy clients are created when a check result includes a `source` attribute, as
follows:

~~~ json
{
  "check": {
    "status": 0,
    "command": "check-http.rb -u https://sensuapp.org",
    "subscribers": [
      "demo"
    ],
    "interval": 60,
    "name": "sensu-website",
    "source": "sensuapp.org",
    "issued": 1458934742,
    "executed": 1458934742,
    "duration": 0.637,
    "output": "CheckHttp OK: 200, 78572 bytes\n"
  },
  "client": "sensu-docs"
}
~~~

_NOTE: this `source` attribute can be provided in a [check definition][14], or
included in a check result published to the Sensu [client input socket][36]._

By default, proxy client data includes a minimal number of attributes. The
following is an example of proxy client data that is added to the registry.

~~~ json
{
  "name": "switch-x",
  "address": "unknown",
  "subscriptions": [],
  "keepalives": false
}
~~~

The Sensu API can be used to update proxy client data in the client registry. To
update proxy client data, please refer to the [Client API reference
documentation][9].

##### Proxy client via the client socket example

The following is an example of how to sent a proxy client payload via the [Client socket input](#client-socket-input):

~~~ shell
echo '{"source": "mysql01", "name": "app_01", "output": "could not connect to mysql", "status": 1}' | nc localhost 3030
~~~

### How are keepalive events created? {#keepalive-events}

Sensu servers (including Sensu Enterprise) monitor the Sensu client registry for
stale client data, detecting clients that have failed to send [client keepalive
messages][10] for more than 120 seconds (by default). When a Sensu server
detects that a client hasn't sent a keepalive message within the configured
`threshold`, _the Sensu server (or Sensu Enterprise)_ will create an event (this
is different from how events are created for monitoring checks; see ["How are
Sensu events created?"][11]).

### Client keepalive configuration

For more information on configuring client keepalives, please see the [client
keepalive attribute reference documentation][12] (below).

Sensu client keepalives are published to the Sensu transport every 20 seconds.
Client keepalive behavior can be configured per Sensu client, allowing each
Sensu client to set its own alert thresholds and keepalive event handlers. By
default, client data is considered stale if a keepalive hasn't be received in
`120` seconds (WARNING). By default, keepalive events will be sent to the Sensu
handler named `keepalive` if defined, or the `default` handler will be used.

To configure the keepalive check for a Sensu client, please refer to [the client
`keepalive` attributes reference documentation][12].

{'fraction_non_alphanumeric': 0.08961119575644716, 'fraction_numerical': 0.01201963771796174, 'mean_word_length': 4.960982172889337, 'pattern_counts': {'":': 36, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4307560', 'n_tokens_mistral': 5021, 'n_tokens_neox': 4692, 'n_words': 2174}