TIBCO® Operational Intelligence Hawk® RedTail Plug-in Reference Guide Version 7.1.0 August 2021 Copyright © 2011-2021. TIBCO Software Inc. All Rights Reserved. 2 | Contents Contents Contents 2 TIBCO® Operational Intelligence Hawk® RedTail Plug-in Overview 5 Writing a Custom TIBCO OI Hawk RedTail Plug-in And Registering It With The Existing Hawk Agent 5 Enterprise Message Service™ Plug-in Microagent 7 Installing and Configuring TIBCO EMS Plug-in Microagent 7 COM.TIBCO.hawk.tibjms.HawkListener Microagent 10 HawkListener:isRunning Method 11 HawkListener:getNumConnections Method 12 HawkListener:getServerinfo Method 12 HawkListener:getConnections Method 17 HawkListener:getUsers Method 18 HawkListener:getQueues Method 19 HawkListener:getRoutes Method 22 HawkListener:getTopics Method 24 HawkListener:getDurables Method 28 HawkListener:getConsumers Method 29 HawkListener:getProducers Method 30 HawkListener:getListenPorts Method 31 HawkListener:getCMLedgerInfo Method 32 HawkListener:getTransports Method 33 HawkListener:getTransport Method 34 HawkListener:getDbStores Method 35 HawkListener:getFileStores Method 36 HawkListener:getStores Method 37 HawkListener:getChannels Method 38 COM.TIBCO.hawk.tibjms.HawkController Microagent 40 TIBCO® Operational Intelligence Hawk® RedTail Plug-in Reference Guide 3 | Contents HawkController:shutdown Method 41 HawkController:purgeDurable Method 41 HawkController:purgeQueue Method 42 HawkController:purgeTopic Method 42 HawkController:rotateLog Method 43 HawkController:compact Method 43 Java Virtual Machine Plug-in Microagent 45 Installing and Configuring Java Virtual Machine Plug-in Microagent 45 COM.TIBCO.hawk.jvm.JavaVirtualMachine Microagent 46 getVirtualMachineInfo Method 47 getThreadInfo Method 49 getGarbageCollectorInfo Method 51 getMemoryPoolInfo Method 52 Universal Collector Plug-in Microagent 54 Installing and Configuring Universal Collector Plug-in Microagent 54 COM.TIBCO.hawk.microagent.HawkUniversalCollector Microagent 55 getCollectors Method 55 getForwarders Method 57 onEvent Method 58 Inventory Plug-in Microagent 59 Installing and Configuring Inventory Plug-in Microagent 59 COM.TIBCO.hawk.microagent.inventory.InventoryMicroAgent Microagent 60 getAllEnvironments Method 60 getEnvironmentDetail Method 61 getProductsInAllEnvironments Method 62 getProductsInAnEnvironment Method 63 getSpecificProductDetail Method 64 getProductFeatureDetail Method 65 Heartbeat Plug-in Microagent 67 TIBCO® Operational Intelligence Hawk® RedTail Plug-in Reference Guide 4 | Contents Installing and Configuring Heartbeat Plug-in Microagent 67 COM.TIBCO.hawk.microagent.heartbeat.HeartbeatMicroAgent Microagent 68 pingEMSServer Method 69 pingSecuredEMSServer Method 70 pingFTPServer Method 72 pingHTTPServer Method 73 pingJDBCDriver Method 74 pingSMTPServer Method 75 Hawk Prometheus Plug-in Microagent 76 COM.TIBCO.hawk.microagent.HawkPrometheus Microagent 76 scrapeMetrics Method 77 removeScrapeConfig Method 77 Proprietary Methods 78 TIBCO Documentation and Support Services 79 Legal and Third-Party Notices 81 TIBCO® Operational Intelligence Hawk® RedTail Plug-in Reference Guide 5 | TIBCO® Operational Intelligence Hawk® RedTail Plug-in Overview TIBCO® Operational Intelligence Hawk® RedTail Plug- in Overview TIBCO® OI Hawk® RedTail plug-in is a type of Hawk microagents that reside within the process space of a Hawk agent. Such plug-ins are used to communicate with third-party applications using their specific protocols and to monitor and manage them from within the TIBCO OI Hawk RedTail subsystem. TIBCO OI Hawk RedTail installation provides the following fully functional ready-to-use plug-ins: • Enterprise Message Service™ Plug-in Microagent • Java Virtual Machine Plug-in Microagent • Universal Collector Plug-in Microagent • Inventory Plug-in Microagent • Heartbeat Plug-in Microagent • Hawk Prometheus Plug-in Microagent In addition, you can also write a custom Hawk plug-in to suit specific needs, using the set of available TIBCO OI Hawk RedTail API methods. Writing a Custom TIBCO OI Hawk RedTail Plug-in And Registering It With The Existing Hawk Agent TIBCO OI Hawk RedTail is an extensible product and additional monitoring capabilities can be added by creating plug-ins to it. Every plug-in requires a .hma file, which is a HMA configuration file, and a .jar file, which contains a Java implementation for the methods you want to expose via the TIBCO OI Hawk RedTail subsystem. Use the following steps to create a plug-in: 1. Create the .hma file. See the OIHR_HOME/examples/ma_plugin/DM*.hma file for guidance. TIBCO® Operational Intelligence Hawk® RedTail Plug-in Reference Guide 6 | TIBCO® Operational Intelligence Hawk® RedTail Plug-in Overview — Most important constituent of this .hma file is the main/startup class of the plug- in implementation that is to be mentioned under the <classname> tag. For example: <classname>com.A.B.myPluginControllerClass</classname> — If required, specify some optional arguments that you would expect the users to configure externally without the need to change plug-in implementation. Give such optional arguments in the <arguments> tag. For example: <arguments><arg>-traceDir</arg><arg>C:/LogDir</arg></arguments> — You must specify the absolute path to the .jar implementation files and all the required third party libraries should be mentioned under <classpath> tag. For example: <classpath><path>C:/TPCL/libs/slf4j-api-1.6.4.jar</path></classpath> 2. Place the .hma file in the CONFIG_FOLDER/plugin folder. Make sure that all .hma files for Hawk plug-ins are present in the CONFIG_ FOLDER/plugin subfolder if you have more than one Hawk plug-ins. 3. Edit the CONFIG_FOLDER/bin/hawkagent.cfg to set or uncomment the following parameter: -hma_plugin_dir ${CONFIG_FOLDER}/plugin 4. Ensure that you have created the implementation .jar file in the same folder that is specified in the <classpath> tag in the .hma file. Refer to the OIHR_HOME/examples/ma_plugin/DM*.java for guidance. 5. Restart the Hawk agent. Your custom plug-in microagent and corresponding methods are displayed in the Hawk RedTail Console. TIBCO® Operational Intelligence Hawk® RedTail Plug-in Reference Guide 7 | Enterprise Message Service™ Plug-in Microagent Enterprise Message Service™ Plug-in Microagent This section gives details about the microagent methods that are used to administer and monitor the TIBCO Enterprise Message Service server. • Installing and Configuring TIBCO EMS Plug-in Microagent • COM.TIBCO.hawk.tibjms.HawkListener Microagent • COM.TIBCO.hawk.tibjms.HawkController Microagent Installing and Configuring TIBCO EMS Plug-in Microagent TIBCO OI Hawk RedTail installer installs Enterprise Message Service plug-in microagent in the TIBCO_HOME/hawk/<version>/plugin/ems folder. To configure the plug-in microagent, follow these steps: 1. Make sure that TIBCO Enterprise Message Service is installed and running. 2. Go to the TIBCO_HOME/hawk/<version>/plugin/ems folder and ensure that the TIBCO Enterprise Message Service installation path is set in the hawkemsadmin.hma file. 3. Copy the hawkemsadmin.hma file to CONFIG_FOLDER/plugin. 4. Edit the hawkagent.cfg file in CONFIG_FOLDER/bin and set the following option: -hma_plugin_dir CONFIG_FOLDER/plugin 5. Navigate to CONFIG_FOLDER/plugin directory, open the hawkemsadmin.hma file in a text editor, and specify the following details: In the <classname> element, specify the Hawk microagent class that must be used. — To only monitor the server, use the HawkListener class. — To monitor and manage the server, use the HawkController class. — Specify the username, password, and server URL that must be used to connect to the TIBCO Enterprise Message Service server in the appropriate <arg> elements. For description of the parameters, see Parameters. For example: TIBCO® Operational Intelligence Hawk® RedTail Plug-in Reference Guide 8 | Enterprise Message Service™ Plug-in Microagent <arguments> <arg>-user</arg> <arg>admin</arg> <arg>-password</arg> <arg>MyPassword</arg> <arg>-server</arg> <arg>tcp://server1.yourcompany.com:7222</arg> <arg>-timeout</arg> <arg>5</arg> </arguments> Note: To use an SSL connection to the TIBCO Enterprise Message Service server, set the additional SSL arguments in the hawkemsadmin.hma file. 6. Restart the Hawk agent. Parameters Parameter Description -user The microagent identifies itself with this user name and password -password when it connects to the TIBCO EMS server. When unspecified, the default user name is admin and the default password is an empty string. -user To use an encrypted password, specify this pair. As the value for - -encryptedPassword encryptedPassword, supply the output you obtain by running the tibhawkpassword Hawk utility program located in the CONFIG_ FOLDER/bin directory: tibhawkpassword -encrypt Enter your current password when prompted. For details, see TIBCO® Operational Intelligence Hawk® RedTail Installation, Configuration, and Administration. -server The microagent connects to the EMS server at this URL (host computer and port). When absent, the default is tcp://localhost:7222. TIBCO® Operational Intelligence Hawk® RedTail Plug-in Reference Guide 9 | Enterprise Message Service™ Plug-in Microagent Parameter Description -timeout Limits the time (in seconds) that the microagent waits for the TIBCO EMS server to respond to queries. Acceptable values are in the range [5, 3600]. When absent, the default is 60. -version TIBCO EMS server version -server_in_agent_ Includes the server url with the microagent name. name To monitor multiple servers on one Hawk