Skip to end of metadata
Go to start of metadata

Topics marked with * relate to features available only in vFabric Hyperic.

Feedback is welcome. Click Add Comment at the bottom of the page.

This page documents Hyperic's RabbitMQ plugin, introduced in Hyperic 4.5.1.2.

RabbitMQ Plugin Overview

Hyperic's RabbitMQ plugin manages RabbitMQ brokers, the virtual hosts within a broker, and RabbitMQ exchanges, queues, connections, and channels. The plugin can discover and manage multiple RabbitMQ nodes on the same platform as the HQ Agent.

The indented list below illustrates the hierarchy of Hyperic resource types that map to RabbitMQ entities. Each resource type is described below in RabbitMQ Resources and the HQ Inventory Model.

RabbitMQ
     RabbitMQ Exchange
     RabbitMQ Queue
     RabbitMQ VirtualHost
     RabbitMQ Connection
     RabbitMQ Channel

Supported Versions and Requirements

The RabbitMQ plugin supports RabbitMQ v1.8.1 and later running on Linux and Windows platforms, and requires v4.5.1 of the Hyperic Agent and the Hyperic Server.

Both Agent and Server Must be version 4.5.1
Note that to monitor RabbitMQ with the 4.5.1 version of the plugin, you must run v4.5.1 of both the Hyperic Server and the Hyperic Agent.

RabbitMQ Resources and the HQ Inventory Model

The table below lists the resource types in Hyperic that map to managed RabbitMQ entities. The right column indicates the inventory level for each type in the Hyperic inventory model.

Hyperic Resource Type Description Hyperic Inventory Type
RabbitMQ A RabbitMQ broker, also referred to as a node, is an implementation of an Advanced Message Queuing Protocol (AMQP) broker. It is a configurable entity that listens for messages on a TCP/IP port.

A broker is represented in Hyperic as a "RabbitMQ" server. 
server
RabbitMQ Exchange
A RabbitMQ exchange is a resource that routes messages to queues. 

An exchange is represented in Hyperic as a "RabbitMQ Exchange" service.
service
RabbitMQ Queue A queue is a resource that stores and forwards messages to message consumers .

A queue is represented in Hyperic as a "RabbitMQ Queue" service.
service
RabbitMQ VirtualHost A virtual host serves as a name-spacing mechanism for queues and exchanges on a broker. A broker always has a default virtual host identified by a forward slash character ( /). Additional virtual hosts can be explicitly configured on a broker. The same queue (or exchange) name in two virtual hosts on denotes a different resource in each virtual host.

RabbitMQ's first level of access control is enforced at the virtual host level; if a user attempts to connect to a virtual host to which he does not have credentials, the a broker rejects the connection attempt.

A RabbitMQ virtual host is represented in HQ as a "RabbitMQ VirtualHost" service.
service
RabbitMQ Connection A physical connection e.g. using TCP/IP or SCTP. A connection is bound to a user. service
RabbitMQ Channel A logical connection that is tied to a connection.
service

Note: For more information about the managed resource hierarchy, see HQ Inventory Model.

Configuration Instructions

The RabbitMQ plugin can automatically discover and monitor one or more RabbitMQ nodes and associated Rabbit services on a platform. You must:

  • Run the HQ Agent on same platform as the RabbitMQ nodes it will manage, and
  • Run the HQ Agent under a user account that can run rabbitmqctl and read the .erlang.cookie file.

Step 1 - Remove Previous RabbitMQ Inventory Resources and Agent Installation

If you use the previous version of the RabbitMQ plugin, you must remove the existing RabbitMQ resources from from inventory and perform a fresh agent install.

If you currently use the RabbitMQ plugin released in Hyperic 4.5.0, the following requirements apply:
  1. Remove the RabbitMQ server resource runs from inventory:
    1. Use Browse > Resource > Servers > RabbitMQ to navigate to the RabbitMQ instance.
    2. Select Delete Server from the Tools menu.
      • The RabbitMQ server and service resources on the platform are removed from inventory.
  2. Stop the Hyperic Agent that runs on the RabbitMQ host.
  3. Uninstall the Hyperic Agent from the RabbitMQ host by deleting the AgentHome directory.
  4. Do a fresh install of the HQ Agent, as described in the following step.

Step 2 - Configure Hyperic Agent

If you have not already done so, install a Hyperic Agent on the RabbitMQ host. See Installing an Agent-Only Package for instructions.

As of Hyperic 4.5.1, you must specify the HQ username and password that the Hyperic Agent uses to connect the Hyperic Server in its properties file. Uncomment the following lines in agent.properties and edit the values as appropriate for your enviornment.

agent.setup.camLogin=hqadmin
agent.setup.camPword=hqadmin

Run the HQ Agent under an account that has permissions to read the Erlang cookie.

Step 3 - Import RabbitMQ Server(s) to Inventory

The HQ Agent on a platform automatically discovers each RabbitMQ node running on the platform. After the RabbitMQ node(s) are discovered, the platform appears in the Auto-Discovery portlet of the HQ Dashboard, and presents the RabbitMQ nodes as new servers.

Import the platform and the new RabbitMQ server resources.

For more information, see Discover and Import Resources to Inventory.

Step 4 - Set Event Tracking Options

The RabbitMQ plugin supports log tracking for the RabbitMQ server resource type.

By default, the plugin tails the standard RabbitMQ node log file, and logs an event for messages of level "ERR".

You can disable log tracking, set a different tracking level, or track messages based on whether they include (or exclude) a specified string. You configure log tracking options on the Monitoring section of the Configuration Properties page for the RabbitMQ server.

For more information, see Set Up Log Tracking.

Step 5 - Tailor Plugin Monitoring Defaults

You can enable and disable metrics, select indicator metrics, and change the collection interval for a resource type on its Monitoring Defaults page. 

  1. Click the Administration tab.
  2. Click Monitoring Defaults.
  3. Scroll down to the desired RabbitMQ resource type and click Edit Metric Template.

For more information, see& Configure Metric Collection for a Resource Type.

Step 6 - Configure Alert Definitions

Create alert definitions as desired for your managed RabbitMQ components. For more information, see Configure Alert Definitions.

Resource Types and Management Functions

This section describes the management functions the RabbitMQ plugin performs for Rabbit MQ components.

Auto-Discovery

The plugin auto-discovers the RabbitMQ Server instances on a platform by querying the process table, and then discovers the queues, exchanges, and the virtual hosts for each server instance.

When the plugin detects that a transient service no longer exists in RabbitMQ, the plugin removes the associated HQ resource from inventory. Note that the RabbitMQ server must be running for the plugin to detect that previously existing services no longer exist - the plugin will not remove services while the Rabbit node is down.

RabbitMQ Server Properties

Property Description
resource name The plugin forms the Hyperic name for a RabbitMQ server from serveral components. For example, this server name:

vmc-ssrc-rh82 RabbitMQ Node rabbit@vmc-ssrc-rh82

is made up of these components:
  • vmc-ssrc-rh82 — The first segment of the hosting platform's DNS name.
  • RabbitMQ Node — A string that indicates the resource type.
  • rabbit@vmc-ssrc-rh82 — The RabbitMQ node name for the node.
Description The plugin bases the Description property for a RabbitMQ server on the Rabbit nodes process ID. For example, the description:

RabbitMQ Node 853

 is name up of these components:
  • RabbitMQ Node — A string that indicates the resource type.
  • 853 — The node's process ID, which is unique per node.
Owner The HQ account under which the resource was created.
Node Path This is the auto-generated path that RabbitMQ creates for a node --- it is always under mnesia, the default data store, and is unique per node.
Node PID The RabbitMQ node's process ID.
Rabbit -boot Based on the node's PID arguments.
Node Name
The RabbitMQ Node Name for the node.

RabbitMQ Exchange Service Properties

Property Description
resource name The plugin forms the HQ name for a RabbitMQ exchange resource from serveral components. For example, this resource name:

rabbit@vmc-ssrc-rh82 exchange://amq.direct@directvirtual-host-test

is formed from these components:
  • rabbit@vmc-ssrc-rh82 — The RabbitMQ server where the exchange runs.
  • exchange — String that indicates the resource type.
  • :// — A separator string.
  • amq.direct — The RabbitMQ exchange name.  Note: If an exchange has no name, then an underscore (_) character forms the portion of the Hyperic resource name for the exchange. 
  • @ — A separator character
  • directvirtual-host-test — The RabbitMQ VirtualHost where the exchange runs.
Description The plugin forms the HQ description for a RabbitMQ exchange from several components.  For example, this description: 

exchange://amq.direct@directvirtual-host-test 

is formed from these components: 
  • exchange --- String that indicates the resource type.
  • :// --- A separator string.
  • amq.direct --- The RabbitMQ exchange name.  Note: If an exchange has no name, then an underscore character forms the portion of the Hyperic description for the exchange.
  • @ --- A separator character
  • directvirtual-host-test --- The RabbitMQ VirtualHost where the exchange runs.
Owner The HQ user account under which the resource was created.
Exchange Type Values include:
  • fanout
  • direct 
  • topic
  • headers
Durable Whether or not the exchange (and the routing data it contains) will survive a server restart.
Auto-Delete Whether or not the exchange is removed when all queues have stopped using it.

RabbitMQ Queue Service Properties

Property Description
resource name The plugin forms the Hyperic name for a RabbitMQ queue from serveral components. For example, this resource name:

rabbit@vmc-ssrc-rh82 queue://queue.test@/

is formed from these components:
  • rabbit@vmc-ssrc-rh82 — The node name of the RabbitMQ server where the queue runs.
  • queue — A string that indicates the resource type.
  • :// — A separator string.
  • queue.test — The RabbitMQ name for the queue. 
  • @ — A separator character.
  • / — The Rabbit MQ Virtual Host where the queue runs.
Description The plugin bases the Hyperic Description for a queue on its RabbitMQ name and the VirtualHost where it runs.
For example, this description: 

queue://queue.test@/ 

is formed from these components:
  • queue --- A string that indicates the resource type.
  • :// --- A separator string.
  • queue.test --- The RabbitMQ name for the queue.
  • @ --- A separator character.
  • / --- The Rabbit MQ Virtual Host where the queue runs.
Owner The HQ account under which the resource was created.
Name The RabbitMQ name for the resource.
Process ID ID of the Erlang process associated with the queue.
Durable Whether or not the queue and the messages it contains will survive server restarts.

RabbitMQ VirtualHost Service Properties

Property Description
resource name The plugin forms the Hyperic name for a RabbitMQ VirtualHost from serveral components. For example, this resource name:

rabbit@vmc-ssrc-rh82 VirtualHost rabbit@vmc-ssrc-rh82virtual-host-test

is formed from these components:
  • rabbit@vmc-ssrc-rh82 — The node name of the RabbitMQ server where the VirtualHost runs.
  • VirtualHost — A string that indicates the resource type.
  • rabbit@vmc-ssrc-rh82 - The node name of the RabbitMQ server where the VirtualHost runs.
  • virtual-host-test — The RabbitMQ name for the VirtualHost.
Description The plugin forms the HQ description for a RabbitMQ VirtualHost from several components. For example, this description: 

VirtualHost rabbit@vmc-ssrc-rh82virtual-host-test 

is formed from these components: 
  • VirtualHost — String that indicates the resource type.
  • rabbit@vmc-ssrc-rh82 — The node name of the RabbitMQ server where the VirtualHost runs.
  • virtual-host-test --- The RabbitMQ name for the VirtualHost.
Owner The HQ user account under which the resource was created.
Virtual Host The RabbitMQ name for the VirtualHost.
Node The Node Name of the RabbitMQ Node where the VirtualHost runs.

RabbitMQ Connection Service Properties

Property Description
resource name The plugin forms the Hyperic name for a RabbitMQ Connection resource from two components. For example, this resource name:

rabbit@vmc-ssrc-rh82 amqp://guest@10.16.16.106:1899/

is formed from these components:
  • rabbit@vmc-ssrc-rh82 — The node name of the RabbitMQ server where the VirtualHost runs.
  • amqp://guest@10.16.16.106:1899/ - The AMQP connection URL.
Description The plugin uses an AMQP connection's URL the Description for a connection.  For example: 

amqp://guest@10.16.16.106:1899/ 
Owner The Hyperic account under which the resource was created.
Username RabbitMQ user account associated with the connection.
Peer Node Peer address and port.
Frame Max Maximum frame size used by the connection.
vHost VirtualHost associated with the connection
State Connection state — starting, tuning, opening, running, closing, or closed.
Self Node Server address and port.
PID ID of the Erlang process associated with the connection.

RabbitMQ Channel Service Properties

Property Description
resource name The plugin forms the Hyperic name for a RabbitMQ Connection resource from serveral components. For example, this resource name:

rabbit@vmc-ssrc-rh82 channel://guest@rabbit@vmc-ssrc-rh82.7651.27/

is formed from these components:

  • rabbit@vmc-ssrc-rh82 — The node name of the RabbitMQ server where the channel runs.
  • channel — A string that indicates the resource type.
  • :// — A separator.
  • guest — The RabbitMQ user account that associated with the channel.
  • rabbit@vmc-ssrc-rh82.7651.27/ — ID of the Erlang process associated with the connection to which the channel belongs.
Description ID of the Erlang process associated with the connection to which the channel belongs.
Owner The HQ user account under which the resource was created.
Process ID ID of the Erlang process associated with the connection.
Number The number of the channel, which uniquely identifies it within a connection.
Connection ID of the Erlang process associated with the connection to which the channel belongs
Transactional True if the channel is in transactional mode, false otherwise.
User The RabbitMQ username associated with the channel.

Metric Collection

The following sections define the metrics for each RabbitMQ resource type.

RabbitMQ Metrics

Name Alias Units Category Default On Default Interval
Availability Availability percentage AVAILABILITY true 5 min
Process Virtual Memory Size ProcessVirtualMemorySize B UTILIZATION false 5 min
Process Resident Memory Size ProcessResidentMemorySize B UTILIZATION true 5 min
Process Page Faults ProcessPageFaults none UTILIZATION false 10 min
Process Page Faults per Minute ProcessPageFaults1m none UTILIZATION false 10 min
Process Cpu System Time ProcessCpuSystemTime ms UTILIZATION false 10 min
Process Cpu System Time per Minute ProcessCpuSystemTime1m ms UTILIZATION false 10 min
Process Cpu User Time ProcessCpuUserTime ms UTILIZATION false 10 min
Process Cpu User Time per Minute ProcessCpuUserTime1m ms UTILIZATION false 10 min
Process Cpu Total Time ProcessCpuTotalTime ms UTILIZATION false 10 min
Process Cpu Total Time per Minute ProcessCpuTotalTime1m ms UTILIZATION false 10 min
Process Cpu Usage ProcessCpuUsage percentage UTILIZATION true 5 min
Process Start Time ProcessStartTime epoch-millis AVAILABILITY false 5 min
Process Open File Descriptors ProcessOpenFileDescriptors none UTILIZATION false 5 min
Process Threads ProcessThreads none UTILIZATION false 5 min

RabbitMQ Exchange Metrics

Name Alias Units Category Default On Default Interval
Availability Availability percentage AVAILABILITY true 10 min

RabbitMQ Queue Metrics

Name Alias Definition Units Category Default On Default Interval
Messages messages Sum of ready and unacknowledged messages (queue depth). none THROUGHPUT true 5 min
Consumers consumers Number of consumers. none UTILIZATION true 5 min
Transactions transactions   none THROUGHPUT true 5 min
Acks Uncommitted acksUncommitted   none THROUGHPUT true 5 min
Messages Ready messagesReady Number of messages ready to be delivered to clients. none THROUGHPUT true 5 min
Messages Unacknowledged messagesUnacknowledged Number of messages delivered to clients but not yet acknowledged. none THROUGHPUT true 5 min
Messages Uncommitted messagesUncommitted   none THROUGHPUT true 5 min
Availability Availability   percentage AVAILABILITY true 10 min
Memory memory Bytes of memory consumed by the Erlang process associated with the queue, including stack, heap and internal structures. b UTILIZATION true 5 min

RabbitMQ VirtualHost Metrics

Name Alias Definition Units Category Default On Default Interval
Availability Availability   percentage AVAILABILITY true 10 min
Connections connectionCount   none UTILIZATION true 5 min
Exchanges exchangeCount   none UTILIZATION true 5 min
Queues queueCount   none UTILIZATION true 5 min
Total Channels channelCount   none UTILIZATION true 5 min
Total Consumers consumerCount   none UTILIZATION true 5 min

RabbitMQ Connection Metrics

Name Alias Units Category Default On Default Interval
Octets Received octetsReceived B THROUGHPUT true 5 min
Octets Sent octetsSent B THROUGHPUT true 5 min
Network Packets Received packetsReceived B THROUGHPUT true 5 min
Network Packets Sent packetsSent B THROUGHPUT true 5 min
Channels channelCount none UTILIZATION true 5 min
Pending Sends pendingSends none UTILIZATION true 5 min
Availability Availability percentage AVAILABILITY true 10 min

RabbitMQ Channel Metrics

Name Alias Description Units Category Default On Default Interval
Consumers consumerCount Number of logical AMQP consumers retrieving messages via the channel. none UTILIZATION true 5 min
Prefetch Count prefetchCount QoS prefetch count limit in force, 0 if unlimited. B THROUGHPUT true 5 min
Acks Uncommitted acksUncommitted Number of acknowledgements received in an as yet uncommitted transaction. B THROUGHPUT true 5 min
Messages Unacknowledged messagesUnacknowledged Number of messages delivered via this channel but not yet acknowledged. B THROUGHPUT true 5 min
Availability Availability   percentage AVAILABILITY true 10 min
Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.