14.3 Tools for ActiveMQ administration

14.3 ActiveMQ的管理工具

A wide range of tools exist for monitoring and administering ActiveMQ. Which ones you’ll be using depends primarily on the environment you’re using, your setup, and also on your preferences. We’ll start this section with an explanation of command-line tools. Next we’ll see how we can use the JMS API to issue commands to ActiveMQ using the command agent (and how you can use it to access your broker using chat clients).

已有大量的监控和管理ActiveMQ的工具.使用何种工具主要取决于你的应用环境,设置和个人喜好. 本节中,我们将从解释命令工具开始.接下来,我们将看到如何使用JMS API运行命令代理发送命令 给ActiveMQ(以及如何使用命令代理运用chat客户端与代理交互).

The general-purpose management console for Java platform named JConsole and  how it  can be  used with  ActiveMQ is  our next  topic. Finally,  we’ll cover  the ActiveMQ web console, integrated with  ActiveMQ, which provides you with  a nice user interface for  inspecting ActiveMQ resources.  Most of these  tools use the JMX API  to communicate  with the  broker, so  be sure  to enable JMX support as explained earlier in  the chapter. So  let’s see what  more can we  do from the command line besides starting a broker.

Java平台的通用管理控制台工具成为JConsole,我们的下一个话题就是讨论如何使用JConsole管理 ActiveMQ.最后,我们将讨论ActiveMQ的Web控制台,该控制台与ActiveMQ集成在一起,提供友好用户 界面以便管理和监控ActiveMQ资源.上述工具大部分使用JMX API与代理交互,因此确保启动代理时 按照前面章节所解释的那样启用了JMX支持.下面让我们看看通过命令行代码除了能够启动代理之外 还能做些什么.

14.3.1 Command-line tools

14.3.1 命令行工具

You already know how to use the bin/activemq script to start the broker. In addition to this script, the bin/activemq-admin script can be used to monitor the broker state from the command line. The activemq-admin script provides the following functionality:
? Start and stop the broker
? List available brokers
? Query the broker for certain state information
? Browse broker destinations

你已经知道如何使用bin/activemq脚本来启动代理了.除了这个脚本,bin/activemq-admin脚本可用于通过 命令行来监控代理状态.activemq-admin脚本提供了下面的功能:
(1)启动和停止代理
(2)列出所有可用代理
(3)查询代理指定的状态信息
(4)浏览代理消息目的地

In the following sections, we’ll explore this functionality and the commands used to expose it through the use of examples. For the complete reference and explanation of all available command options, please refer to the Command-Line Tools page on the ActiveMQ website (http://mng.bz/lj9a).

在接下来的章节中,我们将探索上述功能以及示例中用于实现那些功能而使用的命令.至于命令行 所有可用命令的完整内容和说明请参阅ActiveMQ站点的Command-Line Tools页面 (http://mng.bz/lj9a).

$ cd apache-activemq-5.4.1
$ ./bin/activemq

$ ./bin/activemq-admin start

$ ./bin/activemq-admin stop

The bin/activemq-admin  script is  a nice  alternative for  stopping the broker. It’ll attempt to use the JMX API to  do this, so be sure to enable JMX  support if  you  plan to  use  this script.  Please  note that  the  bin/activemq script connects to the default ActiveMQ JMX URL  to send commands, so if you made  some modifications to the JMX URL (as we did for the earlier JMX examples) or the JMX domain, be sure to  provide the correct JMX  URL and domain to  the script using the appropriate parameters. For example,  to stop the previously defined  broker that starts the JMX  connector on port 2011  and uses the my-broker  domain, the following command should be used:

使用bin/activemq-admin 脚本是停止代理的一种很好的替代方式.该脚本尝试使用JMX API来 停止代理,因此如果你打算使用这个脚本,请确保代理开启了JMX支持.请注意,bin/activemq-admin 脚本使用默认的JMX URL然后发送命令,因而,如果你修改了JMX的URL(比如前面章节JMX例子做的修改) 或者JMX的域名,请确保提供了正确的JMXURL和域名给这个脚本作为合适的参数.例如,为了停止前面 配置的在2011端口启动的JMX连接器并使用my-broker作为域名的代理,需要使用下面的命令:

$ ./bin/activemq-admin stop ^
--jmxurl service:jmx:rmi:///jndi/rmi://localhost:2011/jmxrmi ^
--jmxdomain my-broker

In some situations, multiple brokers may be running in the same JMX context. Using the bin/activemq script you can use the list command to list all the available brokers as shown next.
Listing 14.8 The activemq-admin list command

有些情况下,同一个JMX上下文中可能存在多个代理.使用bin/activemq-admin脚本的list命令可以列出 所有可用代理,命令如下所示:
代码清单14.8 activemq-admin的list命令

$ ./bin/activemq-admin list

Java Runtime: Apple Inc. 1.5.0_16
/System/Library/Frameworks/JavaVM.framework/Versions/1.5.0/Home
Heap sizes: current=1984k free=1709k max=65088k
JVM args: -Dactivemq.classpath=/tmp/apache-activemq-5.4.1/conf;
-Dactivemq.home=/tmp/apache-activemq-5.4.1
-Dactivemq.base=/tmp/apache-activemq-5.4.1
ACTIVEMQ_HOME: /tmp/apache-activemq-5.4.1
ACTIVEMQ_BASE: /tmp/apache-activemq-5.4.1
Connecting to pid: 99591
BrokerName = localhost

As you can see in listing 14.8, we have only one broker in the given context and its name is localhost.

如你所见,在清单14.8中,我们看到只有一个代理其名称为localhost.

Starting, stopping, and listing all available brokers are useful features, but what you’ll probably want to do more often is query various broker parameters. Let’s take a look at demonstrating the query command being used to grab information about destinations.
Listing 14.9 The activemq-admin query command

启动,停止代理,列出所有可用代理都是有用的功能,但是你更常见的需求是查询代理的各种参数. 然后买来看下如何使用查询命令来获取消息目的地方面的信息.
代码清单14.9 activemq-admin query命令

$ ./bin/activemq-admin query -QQueue=*
Java Runtime: Apple Inc. 1.5.0_16
/System/Library/Frameworks/JavaVM.framework/Versions/1.5.0/Home
Heap sizes: current=1984k free=1709k max=65088k
JVM args: -Dactivemq.classpath=/tmp/apache-activemq-5.4.1/conf;
-Dactivemq.home=/tmp/apache-activemq-5.4.1
-Dactivemq.base=/tmp/apache-activemq-5.4.1
ACTIVEMQ_HOME: /tmp/apache-activemq-5.4.1
ACTIVEMQ_BASE: /tmp/apache-activemq-5.4.1
Connecting to pid: 99591
DequeueCount = 0
Name = TEST.FOO
MinEnqueueTime = 0
CursorMemoryUsage = 0
MaxAuditDepth = 2048
Destination = TEST.FOO
AverageEnqueueTime = 0.0
InFlightCount = 0
MemoryLimit = 1048576
Type = Queue
EnqueueCount = 0
MaxEnqueueTime = 0
MemoryUsagePortion = 0.0
ProducerCount = 0
UseCache = true
MaxProducersToAudit = 32
CursorFull = false
BrokerName = localhost
ConsumerCount = 0
ProducerFlowControl = true
Subscriptions = []
QueueSize = 0
MaxPageSize = 200
CursorPercentUsage = 0
MemoryPercentUsage = 0
DispatchCount = 0
ExpiredCount = 0
DequeueCount = 0
Name = example.A
MinEnqueueTime = 0
CursorMemoryUsage = 0
MaxAuditDepth = 2048
Destination = example.A
AverageEnqueueTime = 0.0
InFlightCount = 0
MemoryLimit = 1048576
Type = Queue
EnqueueCount = 0
MaxEnqueueTime = 0
MemoryUsagePortion = 0.0
ProducerCount = 0
UseCache = true
MaxProducersToAudit = 32
CursorFull = false
BrokerName = localhost
ConsumerCount = 1
ProducerFlowControl = true
Subscriptions = [org.apache.activemq:BrokerName=localhost,
Type=Subscription,persistentMode=Non-Durable,
destinationType=Queue,destinationName=example.A,
clientId=ID_mongoose.local-59784-1255450207356-3_0,
consumerId=ID_mongoose.local-59784-1255450207356-2_0_1_1]
QueueSize = 0
MaxPageSize = 200
CursorPercentUsage = 0
MemoryPercentUsage = 0
DispatchCount = 0
ExpiredCount = 0

In listing 14.9, the bin/activemq-admin script was used with the query command and a query of -QQueue=*. This query will print all the state information about all the queues in the broker instance. In the case of a broker using a default configuration, the only queue that exists is one named example.A (from the Camel configuration example in the conf/activemq.xml file) and these are its properties.

在代码清单14.9中,使用了bin/activemq-admin脚本的query命令和查询字符串-QQueue=*.该查询将 打印代理 实例中所有队列的状态信息.使用默认配置的代理只有唯一的队列,该队列名称为example.A (来自Camel示例配置文件conf/activemq.xml),上面打印出来的信息是这个队列的相关属性.

The command-line tools reference page contains the full description of all available query options. If you call the query command without any additional parameters, it’ll print all available broker properties, which can you can use to get a quick snapshot of a broker’s state.

命令行工具手册页面包含了所有查询选项的完整说明.如果你使用不带任何额外参数的query命令,则该命令 将打印出所有可用代理的属性,通过这些属性信息你可以快速了解代理状态信息.

Browsing destinations in the broker is another fundamental administrative task. This functionality is also exposed in the bin/activemq-admin script. The following is an example of browsing one of the queues we’re using in our job queue example.
Listing 14.10 The activemq-admin browse command

浏览代理的消息目的地信息也是代理管理的一项基本工作.该功能依然可以通过使用bin/activemq-admin 脚本来完成.下面是一个示例,该例子将浏览我们在job queue例子中用到的一个队列信息.
代码清单14.10 activemq-admin脚本的browse命令

${ACTIVEMQ_HOME}/bin/activemq-admin browse --amqurl tcp://localhost:61616 JOBS.delete
 
ACTIVEMQ_HOME: /workspace/apache-activemq-5.2.0
ACTIVEMQ_BASE: /workspace/apache-activemq-5.2.0
JMS_HEADER_FIELD:JMSDestination = JOBS.delete
JMS_HEADER_FIELD:JMSDeliveryMode = persistent
JMS_HEADER_FIELD:JMSMessageID =
ID:dejan-bosanacs-macbook-pro.local-64257-1234789436483-0:0:1:1:2
JMS_BODY_FIELD:JMSObjectClass = java.lang.Integer
JMS_BODY_FIELD:JMSObjectString = 1000001
JMS_HEADER_FIELD:JMSExpiration = 0
JMS_HEADER_FIELD:JMSPriority = 4
JMS_HEADER_FIELD:JMSRedelivered = false
JMS_HEADER_FIELD:JMSTimestamp = 1234789436702
JMS_HEADER_FIELD:JMSDestination = JOBS.delete
JMS_HEADER_FIELD:JMSDeliveryMode = persistent
JMS_HEADER_FIELD:JMSMessageID =
ID:dejan-bosanacs-macbook-pro.local-64257-1234789436483-0:0:1:1:3
JMS_BODY_FIELD:JMSObjectClass = java.lang.Integer
JMS_BODY_FIELD:JMSObjectString = 1000002
JMS_HEADER_FIELD:JMSExpiration = 0
JMS_HEADER_FIELD:JMSPriority = 4
JMS_HEADER_FIELD:JMSRedelivered = false
JMS_HEADER_FIELD:JMSTimestamp = 1234789436706
JMS_HEADER_FIELD:JMSDestination = JOBS.delete
JMS_HEADER_FIELD:JMSDeliveryMode = persistent
JMS_HEADER_FIELD:JMSMessageID =
ID:dejan-bosanacs-macbook-pro.local-64257-1234789436483-0:0:1:1:4
JMS_BODY_FIELD:JMSObjectClass = java.lang.Integer
JMS_BODY_FIELD:JMSObjectString = 1000003
JMS_HEADER_FIELD:JMSExpiration = 0
JMS_HEADER_FIELD:JMSPriority = 4
JMS_HEADER_FIELD:JMSRedelivered = false
JMS_HEADER_FIELD:JMSTimestamp = 1234789436708
...

The browse command is different from the previous commands, as it doesn’t use JMX, but browses queues using the QueueBrowser from the JMS API. For that reason, you need to provide it with the broker URL using the -amqurl switch. The final parameter provided to this command is the name of the queue to be browsed.

browse命令与之前的命令不同,因为该命令不使用JMX,而是在浏览队列信息时使用了JMS API中的 QueueBrowser.为此,你需要在命令中使用-amqurl 开关提供代理的URL.提供给该命令的最后一个 参数是打算浏览的队列的名称.

As you can see, a fair number of monitoring and administration operations can be achieved from the command line. This functionality can help you to easily check the broker’s state and can be helpful for diagnosing possible problems. But this isn’t the end of the administrative tools for ActiveMQ. There are still a few more advanced administrative tools; they’re explained in following sections.

你已经看到,通过命令行就可以进行很多监控和管理代理的操作.该功能可以帮你很容易的检查代理 状态在诊断代理问题时很有用.但这并不是ActiveMQ唯一的管理工具.还有很多高级管理工具,下面的 章节将做介绍.

14.3.2 Command agent

14.3.2 管理代理

Sometimes issuing administration  commands to the  broker from the  command line isn’t easily achievable, mostly in situations when you don’t have shell access to  the machines  hosting your  brokers. In  these situations  you’ll want  to administer your broker using some  of the existing administrative channels.  The command agent allows  you to issue  administration commands to  the broker using plain old JMS messages. When the command agent is enabled, it’ll listen to  the ActiveMQ.Agent topic  for messages.  All commands  such as  help, list and query submitted in form of  JMS text messages will  be processed by the  agent and the result will be posted to the same topic.

有时候,从命令行发送管理命令到代理不太容易实现,大部分情况下是因为你不能在运行代理 的机器上执行shell.这种情况下,你需要借用一些已有的管理代理来管理你的代理.命令行代理 允许你使用老的JMS消息啦发送管理命令给代理.当启用命令代理时,它将监听ActiveMQ.Agent 主题的消息.所有的命令,比如help,list和query都以JMS文本消息的格式提交,然后被代理处理, 处理的结果也会发送到相同的主题.

In this section we’ll  demonstrate how to configure  and use the command  agent with the ActiveMQ broker. We’ll also go one step further and introduce the XMPP transport connector, and see how  you can use practically any  instant messaging client to communicate with the command agent.

本节中,我们将说明如何配置和使用ActiveMQ代理的命令代理.我们还将进一步介绍XMPP传输 连接器,同时还会介绍如何使用任何即时的消息客户端来与命令代理通信.

...
<broker xmlns="http://activemq.apache.org/schema/core"
brokerName="localhost"
dataDirectory="${activemq.base}/data">
<transportConnectors>
<transportConnector name="openwire" uri="tcp://localhost:61616"/>
<transportConnector name="xmpp" uri="xmpp://localhost:61222"/>
</transportConnectors>
</broker>
 
<commandAgent xmlns="http://activemq.apache.org/schema/core"
brokerUrl="vm://localhost"/>
...

Two details are important in  this configuration fragment. First we’ve  started the XMPP transport connector on port  61222 to expose the broker to  clients via XMPP (the  Extensible Messaging  and Presence  Protocol). This  was achieved  by using the appropriate URI scheme, like  we do for all supported protocols.  XMPP is an open XML-based protocol mainly used for instant messaging and developed by the Jabber project (http:// jabber.org/). Since it’s open and widespread, a lot of chat clients already support this protocol, and you can use these clients  to communicate with ActiveMQ.

在上述配置代码片段中有两个细节很重要.首先,我们在61222端口的启动了XMPP传输连机器,以便通过XMPP(扩展消息和展示协议)协议将代理暴露给客户端.可以通过合适的URI主题来配置该传输连接器,就想我们配置其他所有已支持的协议一样.XMPP是一种开发的基于XML的 协议,主要用于即时的发送消息,由Jabber项目开发(http:// jabber.org/).因为XMPP是开发且应用广泛的,有许多chat客户端都支持该协议,因此你可以使用这些客户端与ActiveMQ通信.

For the purposes  of this book,  we chose to  use the Adium  (http://www.adiumx.com/) instant messaging  client. This client  runs on Mac  OS X and  speaks manydifferent protocols, including XMPP. Any XMPP client can be used here. The firststep  is always  to provide  the XMPP  client with  the details  to connect  toActiveMQ, such as server host, port, username, and password, as shown in  figure14.7. Of course, you should connect  to your broker on port 61222  since that’swhere the  XMPP transport  connector is  running, and  you can  use any user andpassword.

本书中,我们选用Adium(http://www.adiumx.com)即时消息客户端.该客户端在Mac OS X上运行,支持多种一些,包括XMPP.任何XMPP客户端都可以使用.首先,需要提供让XMPP客户端连接到ActiveMQ的一些信息,比如服务器主机名,端口,用户名和密码如图14.7所示.当然,你应当从端口61222连接到代理,因为我们在61222端口上配置了XMPP传输连接器.

After successfully connecting  to the broker,  you have to  join the appropriatechat room, which basically  means that you’ll subscribe  to the topic with  thesame name. In this example we’ll  subscribe to the ActiveMQ.Agent topic, so  wecan use the command agent.

Typing a message in the chat room sends a message to the topic, so you can  typeyour commands directly into the messaging client. An example of the response forthe help command is shown in figure 14.8. More complex commands are supported aswell. Figure 14.9  shows how you  can query the  topic named TEST.FOO  using thequery -QTopic=TEST.FOO command.

The example  shown in  this section  introduced the  use of  XMPP protocol. Thisallows you to use instant  messaging applications to interact with  the ActiveMQcommand agent  to administer  the broker  via standard  JMS messages. Now let’sreturn to some classic administration tools such as JConsole.

14.3.3 JConsole

As we said earlier,  the JMX API is  the standardized API used  by developers tomanage and monitor  Java applications. But  the API isn’t  so useful without  aclient tool. That’s why the Java SE comes with a tool named JConsole, the  Javamonitoring and management console. JConsole is a client application that  allowsyou to browse and call methods of exposed MBeans. Because ActiveMQ requires  theJava SE to run, JConsole should  be available, and is handy for  quickly viewingbroker state. In this  section, we’ll cover some  of its basic operations  withActiveMQ.

The  first thing  you should  do after  starting JConsole  (using the  jconsolecommand on the  command line) is  choose or locate  the application you  want tomonitor (see figure 14.10). In this figure, we see a local Java process running.This is the case when ActiveMQ and JConsole are started on the same machine.  Tomonitor ActiveMQ on a remote machine, be sure to start a JMX connector from  theActiveMQ  configuration  file  (via  the  createConnector  attribute  from   the<managementContext> element). Then you can enter host and port information (suchas localhost and 1099 in case of a local broker) in the Remote tab, or the  fullURL  (such  as  service:jmx:rmi:///  jndi/rmi://localhost:1099/jmxrmi)  in   theAdvanced tab.

Upon  successfully  connecting  to  the  local  ActiveMQ  broker,  figure  14.11demonstrates  some of  what you  are able  to see.  This figure  shows that  theActiveMQ  broker  exposes  information  about  all  of  its  important   objects(connectors, destinations, subscriptions, and so on) via JMX. In this particularexample, all  the attributes  for queue://example.A  can be  easily viewed. Suchinformation  as  queue size  and  number of  producers  and consumers  can  be avaluable debugging aid for your applications or the broker itself.

Besides peaking at the broker state, you can also use JConsole (and the JMX API)to execute MBean methods.  If you go to  the Operations tab for  the destinationnamed  queue://example.A,  you’ll  see   all  available  operations  for   thatparticular  queue  as  shown  in  figure  14.12.  This  figure  shows  that  thesendTextMessage button allows you  to send a simple  message to the queue.  Thiscan be a simple test tool to produce messages without writing any code.

Now let’s look at another similar tool that’s distributed with ActiveMQ.

14.3.4 Web console

In chapter  9, we  saw how  an internal  web server  is used  to expose ActiveMQresources via REST and Ajax  APIs. The same web server  is used to host the  webconsole,  which provides  basic management  functions via  a web  browser. Uponstarting   ActiveMQ   using   the   default   configuration,   you   can   visithttp://localhost:8161/admin/ to view the web console.

The web console is far more modest in capabilities compared to JConsole, but  itallows you to do some of the most basic management tasks using an user interfaceadapted  to ActiveMQ  management. Figure  14.13 shows  a screenshot  of the  webconsole viewing a list of queues with some basic information.

For every destination, you can  also execute certain management operations.  Forexample, you  can browse,  purge, and  delete queues,  or send,  copy, and  movemessages to  various destinations.  Figure 14.14  shows the  page that  displaysbasic message properties.

The ActiveMQ web console provides some additional pages for viewing destinationsand sending messages. As stated earlier, this functionality is fairly basic  andis meant to be used for development environments, not production environments.