第 10 章 监视代理

本章介绍可用来监视代理的工具，以及如何获得度量数据。本章包含以下各节：

• 监视工具简介

• 配置和使用代理日志记录

• 以交互方式显示度量

• 编写应用程序来监视代理

第 18 章，度量参考提供了有关特定度量的参考信息。

监视工具简介

Message Queue^TM 信息有三种监视接口：日志文件、交互式命令以及可获取度量的客户端 API。每一种接口都有其各自的优缺点，如下所述：

• 日志文件提供长期的度量数据记录，但不易于解析。

• 使用命令可以根据需要快速获取采样信息，但不能查看历史信息或通过编程方式操作数据。

• 使用客户端 API 可以提取和处理信息、操作数据、提供图形或发送警报。但是，要使用它，您必须编写自定义应用程序来捕获和分析数据。

表 10–1 比较了各种不同的工具。

除了表中给出的不同外，每种工具收集到的具体信息（代理生成的度量信息的一部分）也稍有不同。有关每种监视工具收集的度量数据的信息，请参见第 18 章，度量参考。

配置和使用代理日志记录

Message Queue 记录程序获取代理代码、调试器和度量生成器等生成的信息，并将这些信息写入多个输出通道：标准输出（控制台）、日志文件以及 Solaris™ 操作系统上的 syslog 守护进程。

您可以指定记录程序收集的信息类型以及写入每个输出通道的信息类型。特别是，您可以指定将度量信息写出到日志文件。

本节介绍了代理的默认日志记录配置，并说明了如何将日志信息重定向到替代的输出通道，如何更改日志文件转移条件，以及如何将度量数据发送到日志文件。

默认日志记录配置

代理自动配置为将日志输出保存到一组循环的日志文件中。这些日志文件位于由关联代理的实例名称标识的目录中（请参见附录 A， Message Queue^TM 数据在特定平台上的位置）：

…/instances/instanceName/log

对于其生命周期由应用服务器控制的代理，日志文件位于域目录（该域中启动了此代理）的子目录中：

…/appServer_domainName_dir/imq/instances/imqbroker/log

日志文件是纯文本文件。它们按如下方式命名（从最早生成到最近生成）：

log.txt
log_1.txt
log_2.txt
…log_9.txt

默认情况下，日志文件每星期转移一次；系统维护九个备份文件。

• 要更改保存日志文件的目录，请将 imq.log.file.dirpath 属性设置为所需的路径。

• 要将日志文件的根名称从 log 改为其他名称，请设置 imq.log.file.filename 属性。

代理支持三种日志级别：ERROR、WARNING 和 INFO。表 10–2 介绍了每种级别。

设置日志记录级别后，将收集所有高于和等于该级别的消息。默认的日志级别是 INFO，因此，默认情况下会记录所有 ERROR、WARNING 和 INFO 消息。

日志消息格式

记录的消息由时间戳、消息代码和消息本身构成。信息量取决于所设置的日志级别。下面是一个 INFO 消息的示例。

[13/Sep/2000:16:13:36 PDT] [B1004]: Starting the broker service using tcp 
[25374,100] with min threads 50 and max threads of 500

要更改时间戳时区，请参见有关 imq.log.timezone 属性的信息，表 14–8 中介绍了该属性。

更改记录程序配置

表 14–8 中介绍了与日志相关的属性。

更改代理的记录程序配置

1. 设置日志级别。

2. 为一个或多个日志记录类别设置输出通道（文件和/或控制台）。

3. 如果要将输出记录到文件中，请为该文件配置转移条件。

   可以通过设置记录程序属性来完成上述步骤。可以使用以下两种方法之一来设置记录程序属性：

   • 启动代理之前，在该代理的 config.properties 文件中更改或添加记录程序属性。

   • 在启动代理的 imqbrokerd 命令中指定记录程序命令行选项。也可以使用代理选项 -D 来更改记录程序属性（或任何代理属性）。

   通过命令行传递的选项将覆盖代理实例配置文件中指定的属性。以下 imqbrokerd 选项影响日志记录：

   -metrics interval

   代理度量的日志记录时间间隔（以秒为单位）

   -loglevel level

   日志记录级别（ERROR、WARNING、INFO 或 NONE）

   -silent

   无提示模式（不向控制台记录消息）

   -tty

   将所有消息记录到控制台

   下面几节介绍了如何更改默认配置以执行下列操作：

   • 更改输出通道（日志消息的目的地）

   • 更改转移条件

更改输出通道

默认情况下，错误和警告消息除了记录到日志文件中以外，还会显示在终端上。（在 Solaris 中，错误消息还会写入到系统的 syslog 守护进程中。）

可以用以下方式更改日志消息的输出通道：

• 要在屏幕上显示所有日志类别（对于给定的级别）输出，请在 imqbrokerd 命令中使用 -tty 选项。

• 要禁止在屏幕上显示日志输出，请在 imqbrokerd 命令中使用 -silent 选项。

• 使用 imq.log.file.output 属性指定将哪些类别的日志记录信息写入到日志文件中。例如，

  imq.log.file.output=ERROR

• 使用 imq.log.console.output 属性指定将哪些类别的日志记录信息写入到控制台。例如，

  imq.log.console.output=INFO

• 在 Solaris 中，使用 imq.log.syslog.output 属性指定将哪些类别的日志记录信息写入到 Solaris syslog 中。例如，

  imq.log.syslog.output=NONE

在更改记录程序输出通道前，必须确保日志记录级别已设置为支持映射到输出通道的信息。例如，如果将日志级别设置为 ERROR，然后将 imq.log.console.output 属性设置为 WARNING，那么将不会记录任何消息，因为没有启用 WARNING 消息的日志记录。

更改日志文件转移条件

转移日志文件有两个条件：时间和大小。默认情况下使用时间条件，每七天转移一次文件。

• 要更改时间间隔，需要更改 imq.log.file.rolloversecs 属性。例如，以下属性定义将时间间隔更改为十天：

  imq.log.file.rolloversecs=864000

• 要将转移条件更改为取决于文件大小，需要设置 imq.log.file.rolloverbytes 属性。例如，以下定义将在文件达到 500,000 字节的限制时将代理定向到转移文件。

  imq.log.file.rolloverbytes=500000

如果同时设置与时间和大小相关的转移属性，则转移将由最先达到的限制触发。前面已指出，代理最多维护九个转移文件。

可以在代理运行时设置或更改日志文件转移属性。要设置这些属性，请使用 imqcmd update bkr 命令。

将度量数据发送到日志文件

本节讲述使用代理日志文件报告度量信息的过程。有关配置记录程序的一般信息，请参见配置和使用代理日志记录。

使用日志文件报告度量信息

1. 配置代理的度量生成功能：

   1. 确认 imq.metrics.enabled=true

      默认情况下，用于日志记录的度量生成功能处于启用状态。

   2. 将度量生成时间间隔设置为合适的秒数。

      imq.metrics.interval=interval

      该值可以在 config.properties 文件中设置，也可以在启动代理时使用 -metrics interval 命令行选项进行设置。

2. 确认记录程序是否收集度量信息：

   imq.log.level=INFO

   这是默认值。该值可以在 config.properties 文件中设置，也可以在启动代理时使用 -loglevel level 命令行选项进行设置。

3. 确认记录程序是否已设置为将度量信息写入日志文件：

   imq.log.file.output=INFO

   这是默认值。它可以在 config.properties 文件中设置。

4. 启动代理。

   下面显示了输出到日志文件的样例代理度量：

   [21/Jul/2004:11:21:18 PDT] Connections: 0 JVM Heap: 8323072 bytes (7226576 free) Threads: 0 (14-1010) In: 0 msgs (0bytes) 0 pkts (0 bytes) Out: 0 msgs (0bytes) 0 pkts (0 bytes) Rate In: 0 msgs/sec (0 bytes/sec) 0 pkts/sec (0 bytes/sec) Rate Out: 0 msgs/sec (0 bytes/sec) 0 pkts/sec (0 bytes/sec)

   有关度量数据的参考信息，请参见第 18 章，度量参考。

记录停用消息

可以通过对代理启用停用消息日志记录来监视物理目的地。无论是否使用停用消息队列，都可以记录停用消息。

如果启用了停用消息日志记录，代理会记录以下类型的事件：

• 物理目的地超出最大大小。

• 代理由于如下原因从物理目的地中删除消息：

  • 到达目的地大小限制。

  • 消息已过期。

  • 消息太大。

  • 代理试图处理消息时出错。

如果使用了停用消息队列，日志记录还会包括以下类型的事件：

• 代理将消息移动到停用消息队列中。

• 代理从停用消息队列中删除某条消息并将它丢弃。

下面是一个停用消息的日志格式示例：

[29/Mar/2006:15:35:39 PST] [B1147]: Message 8-129.145.180.87(e7:6b:dd:5d:98:aa)-
35251-1143675279400 from destination Q:q0 has been placed on the DMQ because 
[B0053]: Message on destination Q:q0 Expired: expiration time 1143675279402, 
arrival time 1143675279401, JMSTimestamp 1143675279400

默认情况下将禁用停用消息日志记录。要启用它，请设置代理属性 imq.destination.logDeadMsgs。

以交互方式显示度量

Message Queue 代理可以报告以下类型的度量：

• Java 虚拟机 (Java Virtual Machine, JVM) 度量。有关 JVM 堆大小的信息。

• 代理范围内的度量。有关代理中存储的消息、流入或流出代理的消息以及内存使用的信息。按消息数和字节数跟踪消息。

• 连接服务度量。有关连接和连接线程资源的信息，以及有关特定连接服务的消息流的信息。

• 目的地度量。有关流入和流出特定物理目的地的消息的信息、有关物理目的地的使用方的消息以及有关内存和磁盘空间使用情况的信息。

imqcmd 命令可以获取整个代理、单个连接服务以及单个物理目的地的度量信息。要获取度量数据，通常应该使用 imqcmd 的 metrics 子命令。度量数据将按照您指定的时间间隔或次数写到控制台屏幕上。

也可以使用 query 子命令查看也包含配置信息的类似数据。有关详细信息，请参见 imqcmd query。

imqcmd metrics

imqcmd metrics 的语法和选项分别如表 10–3 和表 10–4 所示。

metrics bkr
   [-b hostName:portNumber]
   [-m metricType]
   [-int interval]
   [-msp numSamples]

metrics svc -n serviceName
   [-b hostName:portNumber]
   [-m metricType]
   [-int interval]
   [-msp numSamples]

metrics dst -t destType
   -n destName
   [-b hostName:portNumber]
   [-m metricType]
   [-int interval]
   [-msp numSamples]

-b hostName: portNumber

-int interval

-m metricType

-msp numSamples

-n destName

-n serviceName

-t destType

使用 metrics 子命令显示度量数据

本节介绍使用 metrics 子命令报告度量信息的过程。

使用 metrics 子命令

1. 启动需要度量信息的代理。

   请参见启动代理。

2. 使用正确的 imqcmd metrics 子命令和选项，如表 10–3 和表 10–4 中所示。

度量输出：imqcmd metrics

本节包含 imqcmd metrics 子命令的输出示例。这些示例显示了代理范围、连接服务和物理目的地度量。

代理范围内的度量

要获取在 10 秒的时间间隔内流入和流出代理的消息和包的速率，请使用 metrics bkr 子命令：

imqcmd metrics bkr -m rts -int 10 -u admin

此命令产生类似如下内容的输出（请参见表 18–2 中的数据说明）：

--------------------------------------------------------
 Msgs/sec   Msg Bytes/sec   Pkts/sec    Pkt Bytes/sec   
 In   Out     In      Out     In   Out     In      Out  
--------------------------------------------------------
 0     0      27      56      0     0      38      66   
 10    0     7365     56      10    10    7457    1132  
 0     0      27      56      0     0      38      73   
 0     10     27     7402     10    20    1400    8459  
 0     0      27      56      0     0      38      73   

连接服务度量

要获取 jms 连接服务所处理的消息和包的累计总数，请使用 metrics svc 子命令：

imqcmd metrics svc -n jms -m ttl -u admin

此命令产生类似如下内容的输出（请参见表 18–3 中的数据说明）：

-------------------------------------------------
  Msgs      Msg Bytes      Pkts      Pkt Bytes     
In   Out    In     Out   In   Out    In     Out  
-------------------------------------------------
164  100  120704  73600  282  383  135967  102127
657  100  483552  73600  775  876  498815  149948

物理目的地度量

要获取有关物理目的地的度量信息，请使用 metrics dst 子命令：

imqcmd metrics dst -t q -n XQueue -m ttl -u admin

此命令产生类似如下内容的输出（请参见表 18–4 中的数据说明）：

-----------------------------------------------------------------------------
  Msgs      Msg Bytes         Msg Count         Total Msg Bytes (k)     Largest
In   Out    In     Out    Current  Peak  Avg  Current  Peak     Avg    Msg (k)
-----------------------------------------------------------------------------
200  200  147200  147200     0     200    0      0      143      71        0  
300  200  220800  147200    100    200   10     71      143      64        0  
300  300  220800  220800     0     200    0      0      143      59        0  

要获取有关物理目的地的使用方的信息，请使用下面的 metrics dst 子命令：

imqcmd metrics dst -t q -n SimpleQueue -m con -u admin

此命令产生类似如下内容的输出（请参见表 18–4 中的数据说明）：

------------------------------------------------------------------
  Active Consumers         Backup Consumers         Msg Count
Current  Peak  Avg      Current  Peak    Avg    Current  Peak  Avg
------------------------------------------------------------------
   1       1      0        0       0      0       944    1000  525

imqcmd query

表 10–5 中显示了 imqcmd query 的语法和选项以及该命令所提供的度量数据的说明。

query bkr
   [-b hostName: portNumber]

query svc -n serviceName
  [-b  hostName:portNumber]

query dst -t destType
  -n destName
  [-b hostName:portNumber]

由于 imqcmd query 提供的度量数据有限，第 18 章，度量参考的表中未提到此工具。

编写应用程序来监视代理

Message Queue 提供度量监视功能，通过该功能，代理可以将度量数据写入 JMS 消息，然后根据消息中包含的度量信息类型将它们发送到众多度量主题目的地中的一个。

您可以通过编写具有下列功能的客户端应用程序来访问这些度量信息：订阅度量主题目的地、使用这些目的地中的消息以及处理消息中包含的度量信息。

共有五个度量主题目的地，它们的名称以及传送到各个目的地的度量消息的类型显示在表 10–6 中。

设置基于消息的监视

本节讲述使用基于消息的监视功能来收集度量信息的过程。此过程包括客户端开发和管理任务这两方面。

设置基于消息的监视

1. 编写度量监视客户端。

   有关以编程方式编写订阅度量主题目的地、使用度量消息并从这些消息中提取度量数据的客户端的说明，请参见 Message Queue Developer's Guide for Java Clients。

2. 通过在 config.properties 文件中设置代理属性值来配置代理的度量消息生成方：

   1. 启用度量消息生成。

      设置 imq.metrics.topic.enabled=true。

      默认值为 true。

   2. 设置生成度量消息的时间间隔（以秒为单位）。

      设置 imq.metrics.topic.interval=interval。

      默认值为 60 秒。

   3. 指定是否需要让度量消息成为持久性消息（即，当代理发生故障时它们是否能保留下来）。

      设置 imq.metrics.topic.persist。

      默认为 false。

   4. 指定在删除度量消息之前它们能在各自的目的地中保留的时间。

      设置 imq.metrics.topic.timetolive。

      默认值为 300 秒。

3. 设置需要对度量主题目的地设置的任何访问控制。

   请参见下面安全性和访问注意事项中的讨论。

4. 启动度量监视客户端。

   当使用方订阅度量主题时，系统会自动创建度量主题目的地。创建度量主题后，代理的度量消息生成方就会开始向度量主题发送度量消息。

安全性和访问注意事项

出于以下两个原因，需要限制对度量主题目的地的访问：

• 度量数据可能包含有关代理及其资源的敏感信息。

• 对度量主题目的地的过多订阅可能会增大代理开销，从而给性能带来负面影响。

出于这些方面的考虑，建议限制对度量主题目的地的访问。

用于监视目的的客户端的验证和授权控制与其他任何客户端都相同。只有用户信息保留在 Message Queue 用户系统信息库中的用户才能连接到代理。

您可以通过访问控制属性文件来限制对特定度量主题目的地的访问，从而提供更多保护，如用户授权：访问控制属性文件中所述。

例如，accesscontrol.properties 文件中的下列条目将拒绝除 user1 和 user2 之外的其他任何用户访问 mq.metrics.broker 度量主题。

topic.mq.metrics.broker.consume.deny.user=*
topic.mq.metrics.broker.consume.allow.user=user1,user2

下列条目仅允许用户 user3 监视主题 t1。

topic.mq.metrics.destination.topic.t1.consume.deny.user=*
topic.mq.metrics.destination.topic.t1.consume.allow.user=user3

根据度量数据的敏感度不同，您也可以使用加密连接将度量监视客户端连接至代理。有关使用加密连接的信息，请参见消息加密。

度量输出：度量消息

使用基于消息的监视 API 获得的度量数据输出是您编写的度量监视客户端的一个功能。您只会受到代理中度量生成器提供的数据的限制。有关这些数据的完整列表，请参见第 18 章，度量参考。