Install and configure the agent¶
This section provides instructions for installing and configuring the Rackspace Monitoring Agent. Instructions are also provided in the How-To article Install and configure the Rackspace Monitoring Agent.
Install the agent¶
Use of the Rackspace Monitoring Agent is optional. If you choose to use the agent, you must install it on each server that you want to monitor.
Package Manager installation is supported for the following operating systems:
Ubuntu and Debian
Red Hat, Fedora, and CentOS
Windows
For more information about the agent, see How the monitoring agent works. For information about the agent endpoints, including attributes and code samples, see the Agent API operations section. The Rackspace Monitoring agent is distributed under the Apache license.
For information about installing the agent from source, see
https://github.com/racker/virgo
.
This section offers information about the methods available to install monitoring agent:
The meta packages method. Use the meta packages procedure for the simplest, and recommended, method.
The copy-and-paste agent installation method. This method provides simple commands, per environment, that you can use to quickly install the monitoring agent. This method is fine if you are doing a small deployment and don’t need to use scripts to install the agent multiple times.
The granular step procedure method. Use the step procedure if you want to understand, and possibly customize, each step of the agent installation. This method is also valuable if you will be automating the agent installation process over several or many servers.
Note
Another option for agent installation is to use the The Cloud Intelligence control panel This control panel provides easy monitoring configuration and set up as well as graphs for visualizing Rackspace Monitoring. For details, see :how-to:`Logging in to the Rackspace Intelligence dashboard <logging-in-to-the-rackspace-intelligence-dashboard>.
Install the agent using meta packages¶
The recommended method for installing the monitoring agent is the meta packages method. It’s recommended because it is the simplest. The meta packages installation obviates the need to install the certificate or create a repository manually. That’s all done as part of the meta package.
To install the monitoring agent with the meta package method:
Log into the server that you want to monitor.
Open a browser to the Rackspace Monitoring Meta Packages.
Find your operating system and enter the commands provided.
Install the agent with copy and paste¶
Find your operating system and follow those instructions.
Ubuntu¶
To install the agent on Ubuntu with copy and paste:
For all supported releases of Ubuntu, run the following WHOLE COMMAND, without line breaks, to add the monitoring agent package repository to APT:
sudo sh -c "echo 'deb http://stable.packages.cloudmonitoring.rackspace.com/ubuntu-$(lsb_release -rs)-x86_64 cloudmonitoring main' > /etc/apt/sources.list.d/rackspace-monitoring-agent.list"
Download the signing key for the agent repository and add it to APT:
curl https://monitoring.api.rackspacecloud.com/pki/agent/linux.asc | sudo apt-key add -
Run an APT update to get package information for the new repository:
sudo apt-get update
Install the agent.
sudo apt-get install rackspace-monitoring-agent
Debian¶
To install the agent on Debian with copy and paste:
Find your Linux distribution and version and run the WHOLE COMMAND listed, without line breaks, to add the monitoring agent package repository to APT.
Debian Buster:
sudo sh -c 'echo "deb http://stable.packages.cloudmonitoring.rackspace.com/debian-buster-x86_64 cloudmonitoring main" > /etc/apt/sources.list.d/rackspace-monitoring-agent.list'
Debian Jessie:
sudo sh -c 'echo "deb http://stable.packages.cloudmonitoring.rackspace.com/debian-jessie-x86_64 cloudmonitoring main" > /etc/apt/sources.list.d/rackspace-monitoring-agent.list'
Debian Stretch:
sudo sh -c 'echo "deb http://stable.packages.cloudmonitoring.rackspace.com/debian-stretch-x86_64 cloudmonitoring main" > /etc/apt/sources.list.d/rackspace-monitoring-agent.list'
Download the signing key for the agent repository and add it to APT.
curl https://monitoring.api.rackspacecloud.com/pki/agent/linux.asc | sudo apt-key add -
Run an APT update to get package information for the new repository.
sudo apt-get update
Install the agent.
sudo apt-get install rackspace-monitoring-agent
Red Hat¶
To install the agent on Red Hat with copy and paste:
Run the listed command to install the package signing key. Please run the WHOLE COMMAND.
Red Hat 6:
curl https://monitoring.api.rackspacecloud.com/pki/agent/redhat-6.asc > /tmp/signing-key.asc sudo rpm --import /tmp/signing-key.asc
Red Hat 7:
curl https://monitoring.api.rackspacecloud.com/pki/agent/redhat-7.asc > /tmp/signing-key.asc sudo rpm --import /tmp/signing-key.asc
Create and edit a text file at /etc/yum.repos.d/rackspace-cloud-monitoring.repo with your favorite text editor (like nano or vi). Find your Linux distribution and version in the following table, then add the listed configuration block to the
rackspace-cloud-monitoring.repo
file to add the agent repository to yum (Please add the WHOLE BLOCK):Red Hat 6:
[rackspace] name=Rackspace Monitoring baseurl=http://stable.packages.cloudmonitoring.rackspace.com/redhat-6-x86_64 enabled=1
Red Hat 7:
[rackspace] name=Rackspace Monitoring baseurl=http://stable.packages.cloudmonitoring.rackspace.com/redhat-7-x86_64 enabled=1
Install the agent.
sudo yum install rackspace-monitoring-agent
Next, run the agent setup program.
Fedora¶
To install the agent on Fedora with copy and paste:
Run the listed command to install the package signing key. Please run the WHOLE COMMAND.
Fedora 22:
curl https://monitoring.api.rackspacecloud.com/pki/agent/fedora-22.asc > /tmp/signing-key.asc sudo rpm --import /tmp/signing-key.asc
Fedora 23:
curl https://monitoring.api.rackspacecloud.com/pki/agent/fedora-23.asc > /tmp/signing-key.asc sudo rpm --import /tmp/signing-key.asc
Fedora 24:
curl https://monitoring.api.rackspacecloud.com/pki/agent/fedora-24.asc > /tmp/signing-key.asc sudo rpm --import /tmp/signing-key.asc
Fedora 25:
curl https://monitoring.api.rackspacecloud.com/pki/agent/fedora-25.asc > /tmp/signing-key.asc sudo rpm --import /tmp/signing-key.asc
Fedora 26:
curl https://monitoring.api.rackspacecloud.com/pki/agent/fedora-26.asc > /tmp/signing-key.asc sudo rpm --import /tmp/signing-key.asc
Fedora 27:
curl https://monitoring.api.rackspacecloud.com/pki/agent/fedora-27.asc > /tmp/signing-key.asc sudo rpm --import /tmp/signing-key.asc
Fedora 28:
curl https://monitoring.api.rackspacecloud.com/pki/agent/fedora-28.asc > /tmp/signing-key.asc sudo rpm --import /tmp/signing-key.asc
Fedora 29:
curl https://monitoring.api.rackspacecloud.com/pki/agent/fedora-29.asc > /tmp/signing-key.asc sudo rpm --import /tmp/signing-key.asc
Fedora 30:
curl https://monitoring.api.rackspacecloud.com/pki/agent/fedora-30.asc > /tmp/signing-key.asc sudo rpm --import /tmp/signing-key.asc
Create and edit a text file at /etc/yum.repos.d/rackspace-cloud-monitoring.repo with your favorite text editor (like nano or vi). Find your Linux distribution and version in the following table, then add the listed configuration block to the rackspace-cloud-monitoring.repo file to add the agent repository to yum (Please add the WHOLE BLOCK).
Fedora 22:
[rackspace] name=Rackspace Monitoring baseurl=http://stable.packages.cloudmonitoring.rackspace.com/fedora-22-x86_64 enabled=1
Fedora 23:
[rackspace] name=Rackspace Monitoring baseurl=http://stable.packages.cloudmonitoring.rackspace.com/fedora-23-x86_64 enabled=1
Fedora 24:
[rackspace] name=Rackspace Monitoring baseurl=http://stable.packages.cloudmonitoring.rackspace.com/fedora-24-x86_64 enabled=1
Fedora 25:
[rackspace] name=Rackspace Monitoring baseurl=http://stable.packages.cloudmonitoring.rackspace.com/fedora-25-x86_64 enabled=1
Fedora 26:
[rackspace] name=Rackspace Monitoring baseurl=http://stable.packages.cloudmonitoring.rackspace.com/fedora-26-x86_64 enabled=1
Fedora 27:
[rackspace] name=Rackspace Monitoring baseurl=http://stable.packages.cloudmonitoring.rackspace.com/fedora-27-x86_64 enabled=1
Fedora 28:
[rackspace] name=Rackspace Monitoring baseurl=http://stable.packages.cloudmonitoring.rackspace.com/fedora-28-x86_64 enabled=1
Fedora 29:
[rackspace] name=Rackspace Monitoring baseurl=http://stable.packages.cloudmonitoring.rackspace.com/fedora-29-x86_64 enabled=1
Fedora 30:
[rackspace] name=Rackspace Monitoring baseurl=http://stable.packages.cloudmonitoring.rackspace.com/fedora-30-x86_64 enabled=1
Install the agent.
sudo yum install rackspace-monitoring-agent
CentOS¶
To install the agent on CentOS with copy and paste:
Run the listed command to install the package signing key. Please run the WHOLE COMMAND.
CentOS 6:
curl https://monitoring.api.rackspacecloud.com/pki/agent/centos-6.asc > /tmp/signing-key.asc sudo rpm --import /tmp/signing-key.asc
CentOS 7:
curl https://monitoring.api.rackspacecloud.com/pki/agent/centos-7.asc > /tmp/signing-key.asc sudo rpm --import /tmp/signing-key.asc
Create and edit a text file at /etc/yum.repos.d/rackspace-cloud-monitoring.repo with your favorite text editor (like nano or vi). Find your Linux distribution and version in the following table, then add the listed configuration block to the rackspace-cloud-monitoring.repo file to add the agent repository to yum (Please add the WHOLE BLOCK).
CentOS 6:
[rackspace] name=Rackspace Monitoring baseurl=http://stable.packages.cloudmonitoring.rackspace.com/centos-6-x86_64 enabled=1
CentOS 7:
[rackspace] name=Rackspace Monitoring baseurl=http://stable.packages.cloudmonitoring.rackspace.com/centos-7-x86_64 enabled=1
Install the agent.
sudo yum install rackspace-monitoring-agent
Install the agent step-by-step¶
This section provides granular details about each step of the agent installation process.
Ubuntu or Debian¶
This section explains how to install the agent on a server that is running an Ubuntu or Debian OS.
These steps have been tested on Ubuntu Lucid 10.04 but should work on most recent versions of Ubuntu or Debian.
To install the agent on Ubuntu or Debian step by step:
Add a repository for the agent by creating a text file named
rackspace-monitoring-agent.list
in the/etc/apt/sources.list.d
directory.Add the following content to the
rackspace-monitoring-agent.list
file:deb <repo-name> cloudmonitoring main
repo-name
is replaced with the following link with the appropriate package inserted:For Ubuntu:
http://stable.packages.cloudmonitoring.rackspace.com/ubuntu-[Release Number, such as 14.04]-x86_64
For Debian:
http://stable.packages.cloudmonitoring.rackspace.com/debian-[Code name, such as squeeze]-x86_64
For example, to install Ubuntu, version 14.04, your file would contain this content:
deb http://stable.packages.cloudmonitoring.rackspace.com/ubuntu-14.04-x86_64 cloudmonitoring main
Add a signing key for the apt repository.
$ curl https://monitoring.api.rackspacecloud.com/pki/agent/linux.asc | sudo apt-key add -
Update your apt-get program to recognize the new repository.
$ sudo apt-get update
Install the agent.
$ sudo apt-get install rackspace-monitoring-agent
Red Hat, Fedora, or CentOS¶
This section explains how to install the agent on a server that is running a Red Hat, Fedora, or CentOS operating system.
To install the agent on Red Hat, Fedora, or CentOS step by step:
Enable the signing key.
$ curl https://monitoring.api.rackspacecloud.com/pki/agent/<signing-key> > /tmp/signing-key.asc
$ sudo rpm --import /tmp/signing-key.asc
<signing-key>
is the correct signing key for your OS:OS
Signing Key
Red Hat Enterprise Linux 6, x86-64
redhat-6.asc
Red Hat Enterprise Linux 7, x86-64
redhat-7.asc
Fedora 22, x86-64
fedora-22.asc
Fedora 23, x86-64
fedora-23.asc
Fedora 24, x86-64
fedora-24.asc
Fedora 25, x86-64
fedora-25.asc
Fedora 26, x86-64
fedora-26.asc
Fedora 27, x86-64
fedora-27.asc
Fedora 28, x86-64
fedora-28.asc
Fedora 29, x86-64
fedora-29.asc
Fedora 30, x86-64
fedora-30.asc
CentOS 6, x86-64
centos-6.asc
CentOS 7, x86-64
centos-7.asc
For example, on Red Hat version 5, you enter:
$ curl https://monitoring.api.rackspacecloud.com/pki/agent/redhat-5.asc > /tmp/signing-key.asc
$ sudo rpm --import /tmp/signing-key.asc
Set up the yum repository by creating a text file named
rackspace-cloud-monitoring.repo
in the/etc/yum.repos.d
directory.Add the following content to the
rackspace-cloud-monitoring
file:[rackspace] name=Rackspace Monitoring baseurl=<repo-name> enabled=1
where
<repo-name>
is one of the following available packages:http://stable.packages.cloudmonitoring.rackspace.com/redhat-6-x86_64
http://stable.packages.cloudmonitoring.rackspace.com/redhat-7-x86_64
http://stable.packages.cloudmonitoring.rackspace.com/fedora-22-x86_64
http://stable.packages.cloudmonitoring.rackspace.com/fedora-23-x86_64
http://stable.packages.cloudmonitoring.rackspace.com/fedora-24-x86_64
http://stable.packages.cloudmonitoring.rackspace.com/fedora-25-x86_64
http://stable.packages.cloudmonitoring.rackspace.com/fedora-26-x86_64
http://stable.packages.cloudmonitoring.rackspace.com/fedora-27-x86_64
http://stable.packages.cloudmonitoring.rackspace.com/fedora-28-x86_64
http://stable.packages.cloudmonitoring.rackspace.com/fedora-29-x86_64
http://stable.packages.cloudmonitoring.rackspace.com/fedora-30-x86_64
http://stable.packages.cloudmonitoring.rackspace.com/centos-6-x86_64
http://stable.packages.cloudmonitoring.rackspace.com/centos-7-x86_64
For example, to install Red Hat version 6, your file would contain the following content:
[rackspace] name=Rackspace Monitoring baseurl=http://stable.packages.cloudmonitoring.rackspace.com/redhat-6-x86_64/ enabled=1
Install the agent packages.
$ sudo yum update
$ sudo yum install rackspace-monitoring-agent
Install the agent on Windows¶
You install the monitoring agent on a Windows system just like you install other software: download the installation package and run the installer.
To install the agent on Windows
Download the latest stable agent installer.
64-bit systems: Windows 2008 and Windows 2012: http://stable.packages.cloudmonitoring.rackspace.com/rackspace-monitoring-agent-x64.msi
32-bit legacy systems: Windows 2008: http://stable.packages.cloudmonitoring.rackspace.com/rackspace-monitoring-agent.msi
Run the installer. The installer automatically exits when it is complete.
Next, run the agent setup program to generate a configuration file. Without a configuration file, the agent closes and is restarted by the Windows Service Manager. To prevent this continuous restarting, run the setup program immediately after installing the agent.
Configure the agent¶
When you configure a monitoring agent using the automated setup program, the
configuration process automatically creates a configuration file,
rackspace-monitoring-agent.cfg
and deploys it to one of the
following directories on the customer’s server.
On Linux systems, navigate to the
/etc directory
.On Windows systems, navigate to
C:\ProgramData\Rackspace Monitoring\config\
.
You can also create or edit the configuration file manually to specify or update the following attributes:
Option
Type
Description
monitoring_token
string
Required. This token is a string that is either provided by the API or created during the –setup process. This token gives the agent access to the monitoring services for an account.
monitoring_id
string
Optional. Specifies a user-provided id string that identifies this agent to the monitoring services.
monitoring_snet_region
string
Optional. This option tells the agent to connect to the agent endpoints over the Rackspace ServiceNet (instead of over the public Internet). Valid regions are dfw, ord, lon, syd, hkg, and iad. (Use lower case.) If the option is set, the value must match the region of the agent and the service it is running on.
monitoring_endpoints
comma-delimited sets of
ip:port
valuesOptional. Provides a series of endpoint IP addresses for the agent to connect to instead of the default endpoint addresses.
monitoring_query_endpoints
comma-delimited sets of
ip:port
valuesOptional. Provides a series of API IP addresses for the agent to connect to instead of the default API addresses.
monitoring_proxy_url
string
Optional. Provides a URL string to a HTTP Proxy service that supports the CONNECT command. This configuration must support CONNECT on port 443. Additionally,
HTTP_PROXY
andHTTPS_PROXY
are supported. |
You can use any of the following options to specify the configuration attributes for the monitoring agent:
For the simplest, fastest set up use the agent Setup program, which automates the configuration process and simplifies the process.
To step through each task in the configuration process at your own pace, complete the manual set up process
To create a re-usable YAML file for each check you want the agent to perform, complete the YAML file agent configuration process.
Configuring the agent with the Setup program¶
The agent Setup program provides the easiest way to get started with the agent. Setup completes the following configuration tasks for you:
Configures an agent token that the agent uses to authenticate with Rackspace Monitoring.
Creates an agent configuration file,
rackspace-monitoring-agent.cfg
.On Linux systems this file is located in the
/etc
directoryOn Windows systems, you can find it in
C:\ProgramData\Rackspace Monitoring\config\
.Verifies connectivity to the Rackspace data centers.
Associates the agent with a monitoring entity.
You can also manually edit the agent configuration file. See Configure the agent manually for details.
Note
The Setup program supports the HTTP proxy environment variable.
Run the agent setup program¶
You need your Rackspace user name and API key to run the setup program. If you don’t have them, follow the process to get your credentials.
To run the program, complete the following steps:
Log in as the root user on the server where you installed the agent package.
On Linux: Enter the following command to run the Setup program:
$ rackspace-monitoring-agent --setup
Use this command to run Setup with the HTTP proxy variable:
$ HTTP_PROXY=<ip_address:port> rackspace-monitoring-agent --setup
Alternately, you can use an FQDN:
$ HTTP_PROXY=<FQDN> rackspace-monitoring-agent --setup
On Windows, the agent location depends on the version of the agent installed and the architecture of the operating system.
Note
If you are using PowerShell, precede the path with an ampersand (&).
For a 64-bit system with the 64-bit agent installed, enter the following command:
$"C:\Program Files\Rackspace Monitoring\rackspace-monitoring-agent.exe" -o --setup
For a 64-bit system with the 32-bit agent installed, enter the following command:
$"C:\Program Files (x86)\Rackspace Monitoring\rackspace-monitoring-agent.exe" -o --setup
For a 32-bit system with the 32-bit agent installed, enter the following command:
$"C:\Program Files\Rackspace Monitoring\rackspace-monitoring-agent.exe" -o --setup
A list of Setup settings appears, which includes the agent ID. The agent ID matches the hostname of the server.
When prompted, enter your Rackspace Cloud user name.
When prompted, enter either your API key or your Cloud Control Panel password.
Note that this entry is displayed in clear text while it is typed; therefore, using your API key instead of your password is recommended. Neither value is stored in clear text, it is used only for this initial authentication.
The Rackspace Monitoring service creates an agent token and syncs it with the entity representing the resource that you are monitoring.
You should see the message
Agent successfully connected!
The agent should automatically start.
The next prompt displays a list of Rackspace Monitoring entities.
Note
A Rackspace Monitoring entity is created automatically for every Rackspace cloud server on your account. But if you install the agent on a dedicated server, or on a server not hosted with Rackspace, including a server in a Rackspace private cloud, entities are not automatically created. Instead, you will have to manually create an entity and agent token.
After you have an agent token, associate it with the resource entity by choosing the entity ID created for your resource, or select the option to create a new entity. If you create a new monitoring entity on your server, it won’t be visible in the Cloud Control Panel, but you can see see and configure it using the Cloud Intelligence dashboard You need the entity ID when you create checks to monitor the health of your server; see First steps with the agent
To learn more, see the article Monitoring: Differences Between Rackspace Server Users and Non-Rackspace Server Users.
Configuring the agent manually¶
Note
Using the Setup program is the preferred way to set up the agent. This section is provided as an alternate method of setting up the agent. If you used the Setup program to complete the agent configuration, skip this section.
To manually set up the agent
If you have not installed
raxmon
yet, install it on your local workstation. See Install and configure raxmon.If you prefer to use the API, instead of the raxmon CLI, see the entities API and Create an agent token.
Create an entity in the monitoring service, as follows:
$ raxmon-entities-create --label=<entityLabel>
<entityLabel>
is a name for the new entity. This entity represents the server where you’re installing the agent. For example, if the server is named employee-news, you might use that hostname as the<entityLabel>
.This command returns an entity ID for the new entity, for example,
ent12345
. You need to supply this entity ID for<entityId>
in the next several steps.Assign an ID to your agent and associate it with the server entity that you just created. Rackspace Monitoring uses this ID for two-way communication between the agent and the Rackspace Monitoring endpoint.
$ raxmon-entities-update --id=<entityId> --agent-id=<agentId>
The placeholders in the command are defined as follows:
<entityId>
The entity ID returned in the previous step.
<agentId>
The ID, or name, that you want to assign to the agent installed on the server. For the ID value, use any label that makes sense for the system that you plan to monitor. For example, you can use the server hostname, although the ID does not need to match or contain any part of the entity label or the entity ID.
Create an agent token.
The agent uses an agent token to authenticate with the Cloud Monitoring endpoint. The token ensures that no one masquerades as your server.
$ raxmon-agent-tokens-create --label="<agent-token-label>"
<agent-token-label>
is the name for your agent token. You can use any name.Enter the following command to see a list of tokens, including the one you just created.
$ raxmon-agent-tokens-list
Note the agent token value to use in the next few steps.
Log in as the root user on the server where you installed the agent.
Use
vi
or your favorite text editor to edit the rackspace-monitoring-agent.cfg file, or create it if it does not exist.$ sudo vi /etc/rackspace-monitoring-agent.cfg
Add the following content to the
rackspace-monitoring-agent.cfg
file:monitoring_id <agentId> monitoring_token <agentToken>
The placeholders in the command are defined as follows:
<agentId>
The agent ID you assigned to the agent in Step 3.
<agentToken>
The token value returned for your agent token by the raxmon-agent-tokens-list command.
To set the HTTP proxy variable, add the following entry to the configuration file, where
ip_address:port
stands for IP address for the resource on which you’re installing the agent:$ HTTP_PROXY=<ip_address:port> rackspace-monitoring-agent --setup
You can optionally configure the agent to use a reverse proxy to look up custom SRV records by having it proxy to lon, dfw, and ord as shown in the following example:
monitoring_query_endpoints _monitoringagent._tcp.dfw1.prod.monitoring.api.rackspacecloud.com, _monitoringagent._tcp.ord1.prod.monitoring.api.rackspacecloud.com, _monitoringagent._tcp.lon3.prod.monitoring.api.rackspacecloud.com
To optionally force a connection to a particular IP address and port, add the following to your agent configuration file:
monitoring_endpoints 192.168.95.178:50051, 192.168.95.178:50052, 192.168.95.178:50053
You can also set the HTTP proxy variable to use an FQDN. To do so, add the following entry to the configuration file where
FQDN
stands for the fully-qualified domain name for the resource on which you’re installing the agent:
$ HTTP_PROXY=<FQDN> rackspace-monitoring-agent --setup
To disable automatic updates for your monitoring agent, add the following:
monitoring_update disabled
You’re now ready to start the agent. See Start the agent.
For more information about the agent configuration file, see Agent configuration file.
Configuring the agent with YAML files¶
The server-side monitoring configuration is a new method that enables you to easily configure Rackspace Monitoring on the server that you want to monitor. It is especially useful in conjunction with automation tools or when dealing with duplicate servers. Automation tools like Chef, Puppet, and Ansible can maintain a repository of configuration files to automatically create monitoring checks and alarms for a given server or servers. Server-side monitoring configuration helps you set up monitoring more quickly.
Note
You must update your agent to take advantage of this new feature. The required agent version is 1.0.0-68 or later.
Server-side monitoring configuration files are written in YAML (YAML
Ain’t Markup Language), a text file with a
column-based syntax. You can name YAML files as you like, but they must end in
.yaml
. Each YAML configuration file can contain
configurations for one check and its associated alarms. You create a
series of YAML files, one for each check that you want. A single file
can be used repeatedly on many servers to configure the same check and
associated alarms for those servers. The YAML configuration files are
read every time you start the agent.
Note
For Windows, the files should have the name of the network interface for
the Windows network, and C:\
or D:\
for the Windows disk.
The top-level fields in the YAML file represent the check’s parameters.
The alarms are configured under a top-level field named alarms
. Each
alarm must be given a unique “handle” under the alarms
field;
“handle” is a new term referring to a unique name. The system uses the
alarm “handle” to uniquely identify that alarm within the file. The
system uses the file name to uniquely identify checks and their alarms.
Note
The handle is not the same as the alarm label in the API (or alarm name,
in the Cloud Control Panel) or the alarmId
. Rather, it is a name
that, along with the YAML file name, uniquely identifies that alarm. It
is important that the alarm handles and file names be unique because the
system uses them to identify server-side configured checks and alarms.
After an alarm or check has been created with server-side configuration
from a YAML file, the system uses the YAML file name and the alarm
handle, or just the YAML file name for a check, to detect changes to
those alarms or that check (for example, an updated YAML file). When you
use the API to list checks or alarms, you can look at the confd_name
field to determine if that check or alarm was created by server-side
configuration; if the field is non-null, the object was created by
server-side configuration.
The configuration fields used within the YAML files are identical to the
configuration fields used by the API for checks and alarms. The API will
show two configuration fields for every check and alarm that are updated
as part of server-side configuration, confd_name
and confd_hash
.
Both are generated from the YAML file, but confd_hash
is generated
each time the YAML file is updated and uploaded to the agent endpoint,
whereas confd_name
is generated at the time of the initial YAML file
deployment. API write requests (PUT or POST) to the confd_name
and
confd_hash
fields are ignored. When using the API, you can tell if a
change was made to a server-side configuration object without using
server-side configuration, if the confd_name
field is non-null and
the confd_hash
field is 0 (zero).
After authentication, the agent reads the YAML configuration files and sends them to the monitoring server. The monitoring service parses the files and creates, updates, or deletes, the checks and alarms according to the content of the files. Deleting a YAML configuration file deletes that check and associated alarms from the monitoring service.
Example server-side configuration YAML files¶
This section provides two examples of YAML configuration. More examples are provided in the Server-Side agent configuration YAML file examples.
File system check¶
The following example shows a server-side configuration file that sets
up an agent check for a file system at the target “/”. The file name is
my_fs.yaml
. It configures one check to alert on disk usage that
exceeds 90 percent of free space, two alarms, and other agent check
configuration options. The alarms have been given the handles of
techs
and its
. These handles uniquely identify these alarms
within the context of this check in the same manner that the file name
uniquely identifies this check among other server-side created checks
for this entity.
Note
You can find existing notification_plan_id
values and criteria
values through the API or the Cloud Control Panel.
Example 4.1. File system check YAML file example
type : agent.filesystem
label : Check for Main Disk
disabled : false
period : 60
timeout : 30
details :
target : /
alarms :
techs :
label : disk used alarm
notification_plan_id : npTechnicalContactsEmail
criteria : |
if (percentage(metric['used'], metric['total']) > 90) {
return new AlarmStatus(CRITICAL, 'Less than 10% free space left.');
}
if (percentage(metric['used'], metric['total']) > 80) {
return new AlarmStatus(WARNING, 'Less than 20% free space left.');
}
its :
label : disk used alarm
notification_plan_id : npInformationTechEmail
criteria : |
if (percentage(metric['used'], metric['total']) > 95) {
return new AlarmStatus(CRITICAL, 'Less than 5% free space left.');
}
if (percentage(metric['used'], metric['total']) > 90) {
return new AlarmStatus(WARNING, 'Less than 10% free space left.');
}
HTTP check¶
This example agent configuration file sets up an agent check for HTTP
traffic at the target “/”. The file name is my_http.yaml
, it
configures one check to alert on a non-responsive web server, one alarm,
and other agent configuration options. The alarm has the handle of
alarm1
.
Example 4.2. HTTP check YAML file example
type : remote.http
label : Website check 1
timeout : 30
period : 90
target_alias : default
details :
url : http://www.foo.com
method : GET
monitoring_zones_poll:
- mzord
alarms :
alarm1 :
label : http connect alarm
notification_plan_id : npTechnicalContactsEmail
For additional server-side agent configuration file examples, see “Server-Side Agent Configuration YAML File Examples”.
Use a server-side configuration YAML file¶
This section describes how to create, update, and delete, a server-side YAML configuration file.
To create a server-side configuration YAML file, complete the following steps:
Using any text editor, create a YAML file, specifying the extension as
.yaml
. YAML files are column-based, and you create the columns with whitespace left-side indentation. Use spaces to add the indentation; tabs are ignored. The number of spaces that you use to create the indentation is unimportant as long as parallel elements have the same left justification.Save the YAML file in the
rackspace-monitoring-agent.conf.d
subdirectory under theconfig
directory:(UNIX)
/etc/rackspace-monitoring-agent.conf.d
.(Windows)
C:\ProgramData\Rackspace Monitoring\config\rackspace-monitoring-agent.conf.d
.
When you start the agent, it creates the checks and alarms.
Note
Ensure that your agent has been set up via the agent setup
program, or has a valid
monitoring_token in the /etc/rackspace-monitoring-agent.cfg
file as
described in the Manual Agent Configuration
section.
Update a server-side configuration file and its checks and alarms¶
If you change parameters within the configuration files, the agent updates the corresponding check and alarms after you start, or restart, the agent and it reads the newly saved file. For information about starting the agent, see Start the agent.
Delete a server-side configuration file and its checks and alarms¶
If a server-side YAML configuration file is removed from a server, the agent deletes the check and corresponding alarms configured in the file when the server next reads the file. The YAML files are read every time you start the agent. For information about starting the agent, see Start the agent.
Troubleshoot agent configuration with YAML files¶
Q: How do I know if my server-side configuration was successful on a particular server or on a group of servers?
A: On a single server, you can look at the agent log file for success or error messages:
Wed Apr 23 03:47:49 2014 INF: Confd -> config_file post overall success
Wed Apr 23 03:47:49 2014 INF: Confd -> config_file post operation result: success for file handle: mem.yaml at parsing
Wed Apr 23 03:47:49 2014 INF: Confd -> config_file post operation result: success for file handle: main_disk.yaml at parsing
Wed Apr 23 03:47:49 2014 INF: Confd -> config_file post operation result: success for check handle: {"check":"default","filename":"mem.yaml"} at unchanged
Wed Apr 23 03:47:49 2014 INF: Confd -> config_file post operation result: success for check handle: {"check":"default","filename":"main_disk.yaml"} at unchanged
Wed Apr 23 03:47:49 2014 INF: Confd -> config_file post operation result: success for alarm handle: {"alarm":"alarm1","filename":"mem.yaml"} at unchanged
Wed Apr 23 03:47:49 2014 INF: Confd -> config_file post operation result: success for alarm handle: {"alarm":"alarm1","filename":"main_disk.yaml"} at unchanged
For a group of servers, or even one server, you can use the API endpoint
to verify that the agent created a check, or use the list alarms API
endpoint to verify that the agent created an alarm. Look for the
confd_name
field to have a string value and the confd_hash
to be
a valid SHA1 hash.
{
"id": "chlLIGmg4X",
"label": "Check for Main Disk",
"type": "agent.filesystem",
"details": {
"target": "/"
},
"monitoring_zones_poll": null,
"timeout": 30,
"period": 60,
"target_alias": null,
"target_hostname": null,
"target_resolver": null,
"disabled": false,
"metadata": null,
"confd_name": "{\"check\":\"default\",\"filename\":\"my_fs2.yaml\"}",
"confd_hash": "cf4174eef962cc27f7f9a410a39d83e82049803a",
"created_at": 1398217064602,
"updated_at": 1398217064602
}
Q: Can I deploy server-side configuration to an existing server or only to newly created servers?
A: You can use server-side configuration on any server, inside or outside of Rackspace, newly created or existing. The YAML configuration files are read every time you start the agent. The agent is commonly started at server boot or you can manually restart it.
Q: What happens if I use the API or Control Panel to make a change to a server that was configured with server-side configuration? Which takes precedence, the API or the configuration file?
A: The change from API or Control Panel takes effect immediately,
but the YAML file is the source of authority. If the API modifies a
check or alarm that was created by server-side configuration, the
object’s confd_hash
value is invalidated with a 0 (zero) value. When
you next start the agent, the object is updated or re-created to match
the values in the server-side configuration YAML file. Note that if a
check or alarm is created through the API or Control Panel, you cannot
modify it through server-side monitoring configuration.
Start the agent¶
After you perform the configuration and set-up tasks, you’re ready to start the agent.
On Linux:
Enter the following command:
$ sudo service rackspace-monitoring-agent start
On Windows:
Open the Service Manager by clicking Start > Control Panel > Administrative Tools > Service.
Locate the Rackspace Monitoring Agent service, right-click it, and then select Start.
If you just configured the agent, but the service appears to be already running, you must restart it before the agent will connect.
The rackspace-monitoring-agent
command lets you manage the agent.
Enter the following command to see the available options:
$ rackspace-monitoring-agent --help
First steps with the agent¶
After you start the agent, you create an entity to monitor and schedule some agent checks.
To create an entity and agent checks
If you have not installed
raxmon
yet, do that now. See Install and configure raxmon. If you prefer to use the API instead of theraxmon
CLI, see the API operations reference for the entity and checks resources.Create some monitoring checks for the agent to run.
For example, the following commands create three monitoring checks. The type values agent.memory, agent.cpu, and agent.filesystem, are agent check types, which means that the checks will run local to the system being monitored. And entityId is the ID for the entity that you associated with the agent.
$ raxmon-checks-create --entity-id=<entityId> --type=agent.memory --period=30 --label=mem
$ raxmon-checks-create --entity-id=<entityId> --type=agent.cpu --period=30 --label=cpu
$ raxmon-checks-create --entity-id=<entityId> --type=agent.filesystem --period=30 --label=root --details="target=/"