Monitor external resources with proxy requests and entities
Proxy entities allow Sensu to monitor external resources on systems and devices where a Sensu agent cannot be installed, like a network switch or a website.
You can create proxy entities with sensuctl, the Sensu API, and the proxy_entity_name
check attribute.
When executing checks that include a proxy_entity_name
or proxy_requests
attributes, Sensu agents report the resulting event under the proxy entity instead of the agent entity.
NOTE: This guide requires a running Sensu backend, a running Sensu agent, and a sensuctl instance configured to connect to the backend as a user with get, list, and create permissions for entities, checks, and events.
Use a proxy entity to monitor a website
In this section, you’ll monitor the status of sensu.io by configuring a check with a proxy entity name so that Sensu creates an entity that represents the site and reports the status of the site under this entity.
Register dynamic runtime assets
To power the check, you’ll use the Sensu Plugins HTTP dynamic runtime asset.
The Sensu Plugins HTTP asset includes check-http.rb
, which your check will rely on.
The Sensu assets packaged from Sensu Plugins HTTP are built against the Sensu Ruby runtime environment, so you also need to add the Sensu Ruby Runtime dynamic runtime asset.
Sensu Ruby Runtime delivers the Ruby executable and supporting libraries the check will need to run the check-http.rb
plugin.
Use sensuctl asset add
to register the Sensu Plugins HTTP dynamic runtime asset, sensu-plugins/sensu-plugins-http:5.1.1
:
sensuctl asset add sensu-plugins/sensu-plugins-http:5.1.1 -r sensu-plugins-http
The response will indicate that the asset was added:
fetching bonsai asset: sensu-plugins/sensu-plugins-http:5.1.1
added asset: sensu-plugins/sensu-plugins-http:5.1.1
You have successfully added the Sensu asset resource, but the asset will not get downloaded until
it's invoked by another Sensu resource (ex. check). To add this runtime asset to the appropriate
resource, populate the "runtime_assets" field with ["sensu-plugins-http"].
This example uses the -r
(rename) flag to specify a shorter name for the dynamic runtime asset: sensu-plugins-http
.
You can also download the dynamic runtime asset definition for Debian or Alpine from Bonsai and register the asset with sensuctl create --file filename.yml
or sensuctl create --file filename.json
.
Then, use the following sensuctl example to register the Sensu Ruby Runtime dynamic runtime asset, sensu/sensu-ruby-runtime:0.0.10
:
sensuctl asset add sensu/sensu-ruby-runtime:0.0.10 -r sensu-ruby-runtime
The response will indicate that the asset was added:
fetching bonsai asset: sensu/sensu-ruby-runtime:0.0.10
added asset: sensu/sensu-ruby-runtime:0.0.10
You have successfully added the Sensu asset resource, but the asset will not get downloaded until
it's invoked by another Sensu resource (ex. check). To add this runtime asset to the appropriate
resource, populate the "runtime_assets" field with ["sensu-ruby-runtime"].
You can also download the dynamic runtime asset definition from Bonsai and register the asset using sensuctl create --file filename.yml
or sensuctl create --file filename.json
.
Use sensuctl to confirm that both dynamic runtime assets are ready to use:
sensuctl asset list
The response should list the sensu-plugins-http
and sensu-ruby-runtime
dynamic runtime assets:
Name URL Hash
────────────────────────── ─────────────────────────────────────────────────────────────────────────── ─────────
sensu-plugins-http //assets.bonsai.sensu.io/.../sensu-plugins-http_5.1.1_centos_linux_amd64.tar.gz 31023af
sensu-ruby-runtime //assets.bonsai.sensu.io/.../sensu-ruby-runtime_0.0.10_ruby-2.4.4_centos_linux_amd64.tar.gz 338b88b
NOTE: Sensu does not download and install dynamic runtime asset builds onto the system until they are needed for command execution. Read the asset reference for more information about dynamic runtime asset builds.
Create the check
Now that the dynamic runtime assets are registered, you can create a check named check-sensu-site
to run the command check-http.rb -u https://sensu.io
with the sensu-plugins-http
and sensu-ruby-runtime
dynamic runtime assets, at an interval of 60 seconds, for all agents subscribed to the proxy
subscription, using the sensu-site
proxy entity name.
To avoid duplicate events, add the round_robin
attribute to distribute the check execution across all agents subscribed to the proxy
subscription.
Create a file named check.yml
or check.json
in your Sensu installation to store the check definition.
Copy this this check definition into the check.yml
or check.json
file and save it:
---
type: CheckConfig
api_version: core/v2
metadata:
name: check-sensu-site
namespace: default
spec:
command: check-http.rb -u https://sensu.io
interval: 60
proxy_entity_name: sensu-site
publish: true
round_robin: true
runtime_assets:
- sensu-plugins-http
- sensu-ruby-runtime
subscriptions:
- proxy
{
"type": "CheckConfig",
"api_version": "core/v2",
"metadata": {
"name": "check-sensu-site",
"namespace": "default"
},
"spec": {
"command": "check-http.rb -u https://sensu.io",
"runtime_assets": [
"sensu-plugins-http",
"sensu-ruby-runtime"
],
"interval": 60,
"proxy_entity_name": "sensu-site",
"publish": true,
"round_robin": true,
"subscriptions": [
"proxy"
]
}
}
Use sensuctl to add check-sensu-site
to Sensu directly from the check.yml
or check.json
file:
sensuctl create --file check.yml
sensuctl create --file check.json
Use sensuctl to confirm that Sensu added the check:
sensuctl check list
The response should list check-sensu-site
:
Name Command Interval Cron Timeout TTL Subscriptions Handlers Assets Hooks Publish? Stdin?
────────────────── ────────────────────────────────── ────────── ────── ───────── ───── ─────────────── ────────── ─────────────────────────────────────── ─────── ────────── ────────
check-sensu-site check-http.rb -u https://sensu.io 60 0 0 proxy sensu-plugins-http,sensu-ruby-runtime true false
Add the subscription
To run the check, you’ll need a Sensu agent with the subscription proxy
.
After you install an agent, use sensuctl to add the proxy
subscription to the entity the Sensu agent is observing.
In the following command, replace ENTITY_NAME
with the name of the entity on your system.
Then, run:
sensuctl entity update ENTITY_NAME
- For
Entity Class
, press enter. - For
Subscriptions
, typeproxy
and press enter.
Validate the check
Use sensuctl to confirm that Sensu created sensu-site
.
It might take a few moments for Sensu to execute the check and create the proxy entity.
sensuctl entity list
The response should list the sensu-site
proxy entity:
ID Class OS Subscriptions Last Seen
────────────── ─────── ─────── ─────────────────────────── ───────────────────────────────
sensu-centos agent linux proxy,entity:sensu-centos 2019-01-16 21:50:03 +0000 UTC
sensu-site proxy entity:sensu-site N/A
Then, use sensuctl to confirm that Sensu is monitoring sensu-site
with the check-sensu-site
check:
sensuctl event info sensu-site check-sensu-site
The response should list check-sensu-site
status and history data for the sensu-site
proxy entity:
=== sensu-site - check-sensu-site
Entity: sensu-site
Check: check-sensu-site
Output:
Status: 0
History: 0,0
Silenced: false
Timestamp: 2019-01-16 21:51:53 +0000 UTC
You can also see the new proxy entity in your Sensu web UI.
Use proxy requests to monitor a group of websites
Suppose that instead of monitoring just sensu.io, you want to monitor multiple sites, like docs.sensu.io, packagecloud.io, and github.com.
In this section, you’ll use the proxy_requests
check attribute along with entity labels and token substitution to monitor three sites with the same check.
Before you start, register the sensu-plugins-http
and sensu-ruby-runtime
dynamic runtime assets if you haven’t already.
Create proxy entities
Instead of creating a proxy entity using the proxy_entity_name
check attribute, use sensuctl to create proxy entities to represent the three sites you want to monitor.
Your proxy entities need the entity_class
attribute set to proxy
to mark them as proxy entities as well as a few custom labels
to identify them as a group and pass in individual URLs.
Create a file named entities.yml
or entities.json
in your Sensu installation and add the following entity definitions:
---
type: Entity
api_version: core/v2
metadata:
name: sensu-docs
namespace: default
labels:
proxy_type: website
url: https://docs.sensu.io
spec:
entity_class: proxy
{
"type": "Entity",
"api_version": "core/v2",
"metadata": {
"name": "sensu-docs",
"namespace": "default",
"labels": {
"proxy_type": "website",
"url": "https://docs.sensu.io"
}
},
"spec": {
"entity_class": "proxy"
}
}
---
type: Entity
api_version: core/v2
metadata:
name: packagecloud-site
namespace: default
labels:
proxy_type: website
url: https://packagecloud.io
spec:
entity_class: proxy
{
"type": "Entity",
"api_version": "core/v2",
"metadata": {
"name": "packagecloud-site",
"namespace": "default",
"labels": {
"proxy_type": "website",
"url": "https://packagecloud.io"
}
},
"spec": {
"entity_class": "proxy"
}
}
---
type: Entity
api_version: core/v2
metadata:
name: github-site
namespace: default
labels:
proxy_type: website
url: https://github.com
spec:
entity_class: proxy
{
"type": "Entity",
"api_version": "core/v2",
"metadata": {
"name": "github-site",
"namespace": "default",
"labels": {
"proxy_type": "website",
"url": "https://github.com"
}
},
"spec": {
"entity_class": "proxy"
}
}
PRO TIP: When you create proxy entities, you can add any custom labels that make sense for your environment.
For example, when monitoring a group of routers, you may want to add ip_address
labels.
Now you can use sensuctl to add these proxy entities to Sensu directly from the entities.yml
or entities.json
file:
sensuctl create --file entities.yml
sensuctl create --file entities.json
Use sensuctl to confirm that the entities were added:
sensuctl entity list
The response should list the new sensu-docs
, packagecloud-site
, and github-site
proxy entities:
ID Class OS Subscriptions Last Seen
─────────────────── ─────── ─────── ─────────────────────────── ───────────────────────────────
github-site proxy N/A
packagecloud-site proxy N/A
sensu-centos agent linux proxy,entity:sensu-centos 2019-01-16 23:05:03 +0000 UTC
sensu-docs proxy N/A
Create a reusable HTTP check
Now that you have three proxy entities set up, each with a proxy_type
and url
label, you can use proxy requests and token substitution to create a single check that monitors all three sites.
Create a file called check-http.yml
or check-http.json
in your Sensu installation and add the following check definition:
---
type: CheckConfig
api_version: core/v2
metadata:
name: check-http
namespace: default
spec:
command: check-http.rb -u {{ .labels.url }}
interval: 60
proxy_requests:
entity_attributes:
- entity.entity_class == 'proxy'
- entity.labels.proxy_type == 'website'
publish: true
runtime_assets:
- sensu-plugins-http
- sensu-ruby-runtime
subscriptions:
- proxy
{
"type": "CheckConfig",
"api_version": "core/v2",
"metadata": {
"name": "check-http",
"namespace": "default"
},
"spec": {
"command": "check-http.rb -u {{ .labels.url }}",
"runtime_assets": [
"sensu-plugins-http",
"sensu-ruby-runtime"
],
"interval": 60,
"subscriptions": [
"proxy"
],
"publish": true,
"proxy_requests": {
"entity_attributes": [
"entity.entity_class == 'proxy'",
"entity.labels.proxy_type == 'website'"
]
}
}
}
Your check-http
check uses the proxy_requests
attribute to specify the applicable entities.
In this case, you want to run the check-http
check on all entities of entity class proxy
and proxy type website
.
Because you’re using this check to monitor multiple sites, you can use token substitution to apply the correct url
in the check command
.
Use sensuctl to add the check-http
check to Sensu directly from the check-http.yml
or check-http.json
file:
sensuctl create --file check-http.yml
sensuctl create --file check-http.json
Use sensuctl to confirm that Sensu created the check:
sensuctl check list
The response should include the check-http
check:
Name Command Interval Cron Timeout TTL Subscriptions Handlers Assets Hooks Publish? Stdin?
───────────────── ─────────────────────────────────── ────────── ────── ───────── ───── ─────────────── ────────── ─────────────────────────────────────── ─────── ────────── ────────
check-http check-http.rb -u {{ .labels.url }} 60 0 0 proxy sensu-plugins-http,sensu-ruby-runtime true false
PRO TIP: To distribute check executions across multiple agents, set the round-robin
check attribute to true
.
For more information about round robin checks, see the check reference.
Validate the check
Before you validate the check, make sure that you’ve registered the sensu-plugins-http
and sensu-ruby-runtime
dynamic runtime assets and added the proxy
subscription to a Sensu agent.
Use sensuctl to confirm that Sensu is monitoring docs.sensu.io, packagecloud.io, and github.com with the check-http
, returning a status of 0
(OK):
sensuctl event list
The response should list check status data for the sensu-docs
, packagecloud-site
, and github-site
proxy entities:
Entity Check Output Status Silenced Timestamp
─────────────────── ───────────────────── ──────── ──────── ────────── ───────────────────────────────
github-site check-http 0 false 2019-01-17 17:10:31 +0000 UTC
packagecloud-site check-http 0 false 2019-01-17 17:10:34 +0000 UTC
sensu-centos keepalive ... 0 false 2019-01-17 17:10:34 +0000 UTC
sensu-docs check-http 0 false 2019-01-17 17:06:59 +0000 UTC
Next steps
The files you created with check and entity definitions can become part of your monitoring as code repository. Storing your Sensu configurations the same way you would store code means they are portable and repeatable. Monitoring as code makes it possible to move to a more robust deployment without losing what you’ve started here and reproduce one environment’s configuration in another.
Now that you know how to run a proxy check to verify the status of a website and use proxy requests to run a check on two different proxy entities based on label evaluation, read these recommended resources: