Agents

The optional Monitoring Agent resides on the host server being monitored. You can use the agent to gather on-host metrics based on agent checks and push them to Rackspace Monitoring where you can analyze them, use them with the Rackspace Monitoring infrastructure, and archive them.

Note

To learn about installing and configuring monitoring agents, read the Install and configure section.

The agent adheres to a few core design principals to ensure it fits easily and securely into your infrastructure:

• Size The agent uses very few resources. The design goal of the agent is to run as a single process with as few dependencies as possible. The agent consumes a nominal amount of RAM.
• Security The agent has multiple layers of security to protect your infrastructure. The agent is designed using best practices like package signing, x509 certificates, and TLS throughout the agent infrastructure.
• Simple Protocol The agent communicates with Rackspace Monitoring via a documented JSON protocol.
• Open Source The agent source code is available under the Apache 2.0 license. This gives your the ability to inspect the implementation and compile the agent on platforms where native packages are not supported. See the source repository.

Security

The agent implements several layers of security to protect your infrastructure:

• Signed Install Binaries Agent Linux binaries and repositories are signed using public key cryptography and verified using distribution native methods. See Install and configure for instructions.
• Secure Endpoint Connections Connections to the Agent Endpoint use TLS and trust only a single root CA certificate that is directly under Rackspace control.
• No Arbitrary Commands The goal of the agent is to gather metrics about your system. The agent is not designed for you to run arbitrary commands on your system. This means that even if your Rackspace API token is compromised the only thing an attacker will have access to is metric data.
• Signed Updates Agent updates are verified against a cryptographic digest which is signed by the agent root certificate authority. This signing certificate is separate from the endpoint TLS certificate and the signing is done on a single computer, off-line. This means that the security of updates is separated from that of the endpoint.

Agent IDs

Agent IDs are user specified strings that are a maximum of 255 characters and can contain letters, numbers, dashes (-) and dots (.). If you used the Setup wizard to install and configure the agent on your host server, the agent ID for your agent is the fully qualified domain name (FQDN) of the host on which the agent is installed.

Agents API operations

Use the following agents API operations to get information about agents and agent connections.

• List agents
• Get agent by ID

List agents

GET /agents

This operation lists the Agent IDs that have been connected to your account and when they were last connected. If an agent ID does not connect to the account for 30 days, the agent ID is automatically deleted from this list. Time is shown in Coordinated Universal Time (UTC) as the number of milliseconds that have elapsed since January 1, 1970.

The following table shows the possible response codes for this operation:

Request

The following table shows the header parameters for the request:

Note

This operation does not accept a request body.

Response

Example List agents: JSON response

{
"values": [
{
"id": "00-agent.example.com",
"last_connected": 1334685407
},
{
"id": "i-need-a-new-agent.example.com",
"last_connected": 1334685407
}
],
"metadata": {
"count": 2,
"limit": 50,
"marker": null,
"next_marker": null,
"next_href": null
}
}

Get agent by ID

GET /agents/{agentId}

Returns information about the agent specified by agentId.

Time is shown in UTC.

The following table shows the possible response codes for this operation:

Request

This table shows the header parameters for the request:

Note

This operation does not accept a request body.

Response

Example Get agent by ID: JSON response

{
"id": "00-agent.example.com",
"last_connected": 1334685407
}

List agent connections

GET /agents/{agentId}/connections

This operation lists the connections that are currently active for an agent. Agents are connected to three monitoring zones when operating normally.

The following table shows the possible response codes for this operation:

Request

The following table shows the header parameters for the request:

Note

This operation does not accept a request body.

Response

Example List agent connections: JSON response

{
"values": [
{
"id": "cntl4qsIbA",
"guid": "0b49b96d-24c9-45ca-c585-4040707f4880",
"agent_id": "00-agent.example.com",
"process_version": "0.1.2.16",
"bundle_version": "0.1.2.16",
"agent_ip": "10.1.2.3"
},
{
"id": "cnyHsfATLd",
"guid": "0b49b96d-24c9-45ca-c585-4040707f4880",
"agent_id": "00-agent.example.com",
"process_version": "0.1.2.16",
"bundle_version": "0.1.2.16",
"agent_ip": "10.1.2.3"
}
],
"metadata": {
"count": 2,
"limit": 50,
"marker": null,
"next_marker": null,
"next_href": null
}
}

List agent connection by ID

GET /agents/{agentId}/connections/{connId}

Get information about a specific connection for the specified agent.

The following table shows the possible response codes for this operation:

Request

The following table shows the header parameters for the request:

Note

This operation does not accept a request body.

Response

This operation does not return a response body.