HP BAC Adapter Installation and Configuration Guide

vCenter Operations Manager 1.0

This document supports the version of each product listed and supports all subsequent versions until the document is replaced by a new edition. To check for more recent editions of this document, see http://www.vmware.com/support/pubs.

EN-000857-03

HP BAC Adapter Installation and Configuration Guide

You can find the most up-to-date technical documentation on the VMware Web site at: http://www.vmware.com/support/ The VMware Web site also provides the latest product updates. If you have comments about this documentation, submit your feedback to: docfeedback@vmware.com

Copyright 2013 VMware, Inc. All rights reserved. This product is protected by U.S. and international copyright and intellectual property laws. VMware products are covered by one or more patents listed at http://www.vmware.com/go/patents. VMware is a registered trademark or trademark of VMware, Inc. in the United States and/or other jurisdictions. All other marks and names mentioned herein may be trademarks of their respective companies.

VMware, Inc. 3401 Hillview Ave. Palo Alto, CA 94304 www.vmware.com

VMware, Inc.

Contents

HP BAC Adapter Installation and Configuration Guide 5 Updated Information 7

1 Introduction to the HP BAC Adapter 9

How the HP BAC Adapter Collects Data 9 How the HP BAC Adapter Defines Resource Relationships 9 Installation and Configuration Requirements 10 Security Considerations 10

2 Installing the HP BAC Adapter 11

Install the Adapter in a Standalone Installation Install the Adapter in a vApp Installation 12 HP BAC Adapter Folders and Files 13

11

3 Configuring the HP BAC Adapter 15

Overview of Configuration Steps 15 Configuring Data Collection and Relationship Tasks 15 Tuning Adapter Operation 24 Add an Adapter Instance 24

4 Troubleshooting the HP BAC Adapter 27

Troubleshooting an HP BAC Adapter Instance 27 Viewing System Log Files 27 Use Test Data to Test an Adapter Instance 28

Index 29

VMware, Inc.

HP BAC Adapter Installation and Configuration Guide

VMware, Inc.

HP BAC Adapter Installation and Configuration Guide

The HP BAC Installation and Configuration Guide describes how to install and configure the HP Business Availability Center (BAC) adapter. The BAC adapter is an embedded adapter for vCenter Operations Manager.

Intended Audience
This information is intended for anyone who wants to install or configure the BAC adapter.

VMware, Inc.

HP BAC Adapter Installation and Configuration Guide

VMware, Inc.

Updated Information

The HP BAC Adapter Installation and Configuration Guide is updated with each release of the product or when necessary. This table provides the update history of the HP BAC Adapter Installation and Configuration Guide.
Revision EN-000857-03 Description
n n

Corrected the BPMconfig.xml and SSconfig.xml file names in Defining Tasks in the BAC Adapter Properties File, on page 16. Corrected step 7 in Add an Adapter Instance, on page 24. Added Security Considerations, on page 10. Added information about log file locations to Viewing System Log Files, on page 27. Changed the product name to reflect the new licensing model for the 5.6 release. Added the open_source_license.txt file to HP BAC Adapter Folders and Files, on page 13.

EN-000857-02 EN-000857-01 EN-000857-00

n n n n

Initial release.

VMware, Inc.

HP BAC Adapter Installation and Configuration Guide

VMware, Inc.

Introduction to the HP BAC Adapter

The HP BAC adapter is an embedded adapter for vCenter Operations Manager. The adapter collects data from HP Business Availability Center (BAC). HP BAC contains components for monitoring and managing business services and applications. This chapter includes the following topics:
n n n n

How the HP BAC Adapter Collects Data, on page 9 How the HP BAC Adapter Defines Resource Relationships, on page 9 Installation and Configuration Requirements, on page 10 Security Considerations, on page 10

How the HP BAC Adapter Collects Data

The HP BAC adapter uses data collection tasks to retrieve and parse data. You define data collection tasks in the BAC adapter properties file. You must create a data collection task XML configuration file for each data collection task. When it runs a data collection task, the HP BAC adapter parses the data according to the rules in the associated data collection task XML configuration file. You can configure a data collection task to use SOAP queries to the BAC Generic Data Engine API, use SQL queries to the BAC database, or read data from a text file. You can define multiple data collection tasks for a single HP BAC adapter instance. The adapter runs multiple data collection tasks sequentially during each collection cycle.

How the HP BAC Adapter Defines Resource Relationships

The HP BAC adapter uses relationship tasks to define parent and child resource relationships based on the data that the adapter collects during a collection cycle. You define relationship tasks in the BAC adapter properties file. You must create a relationship task XML configuration file for each relationship task. When it runs a relationship task, the HP BAC adapter converts the data to parent and child mappings according to the rules in the associated relationship task XML configuration file. You can configure a relationship task to use SOAP queries to the BAC Generic Data Engine API, use SQL queries to the BAC database, or read data from a text file. You can define multiple relationship tasks for a single HP BAC adapter instance. The adapter runs multiple relationship tasks sequentially during each collection cycle.

VMware, Inc.

HP BAC Adapter Installation and Configuration Guide

Because the HP BAC adapter uses a SET flag to report parent and child relationships to the Collector, only specific children can be in a parent and child relationship for a specific parent. For example, if a relationship exists between Parent1 and (Child1, Child2), and the adapter reports a relationship between Parent 1 and (Child1, Child3) during the next collection cycle, the adapter removes Child2 and adds Child3 to the relationship with Parent1. NOTE Resource relationship management is supported only in HP BAC adapter versions 2.6 and later.

Installation and Configuration Requirements

The HP BAC adapter has certain installation and configuration requirements.

Compatible HP BAC Versions

The HP BAC adapter supports HP BAC versions 6, 7, 8, and 9. The adapter can read data from all HP Real User Monitor (RUM), HP Business Process Monitor (BPM), and HP SiteScope versions that can write into these HP BAC versions.

Connection and Credential Requirements

If you define a task to use SOAP queries to the BAC Generic Data Engine API, you must specify the URL of the BAC Web Service. If you configure a task to use SQL queries to the BAC database, you must provide a JDBC URL and user credentials to connect to the database.

Security Considerations
The Collector service must have access to all of the configuration files in the HP BAC adapter's conf and work folders and the files should be secured. The Collector service must have read access rights to the folder that contains the HP BAC adapter properties file. You specify the location of the HP BAC adapter properties file when you configure an HP BAC adapter instance. For more information about HP BAC adapter folders and files, see HP BAC Adapter Folders and Files, on page 13. For information about BAC adapter log files, see Viewing System Log Files, on page 27.

10

VMware, Inc.

Installing the HP BAC Adapter

How you install the HP BAC adapter depends on whether you have a vCenter Operations Manager Standalone or vApp installation. This chapter includes the following topics:
n n n

Install the Adapter in a Standalone Installation, on page 11 Install the Adapter in a vApp Installation, on page 12 HP BAC Adapter Folders and Files, on page 13

Install the Adapter in a Standalone Installation

If you have a standalone installation, you install the HP BAC adapter by extracting installation files from a TGZ file and running an installation utility. Prerequisites
n n

Download the adapter installation TGZ file anonymously from ftp://ftp.integrien.com/. Make a note of the build number in the TGZ file name. The build number appears after the adapter name, for example, adaptername-buildnumber.tgz. Read the release notes that are included with the TGZ file.

Procedure 1 2 3 4 5 Open the TGZ file and extract the TAR file to a temporary folder on your vCenter Operations Manager server. In the temporary folder, open the TAR file and extract and run the installer for your operating system platform. Log in to the Custom user interface as an administrator. Select Admin > Support. On the Info tab, find the Adapters Info pane and click the Describe icon ( ). The Describe icon is located at the top right of the Adapters Info pane. 6 Click Yes to start the describe process and click OK. The Custom user interface finds the adapter files, gathers information about the abilities of the adapter, and updates the user interface with information about the adapter. If you have remote collectors, it installs the adapter on the remote collectors. The describe process might take several minutes. When the describe process is finished, the adapter appears in the Adapters Info pane. The build number is in the Adapter Version column.

VMware, Inc.

11

HP BAC Adapter Installation and Configuration Guide

Verify that the build number in the Adapter Version column for the adapter matches the build number in the TGZ file that you downloaded.

The installer creates the bac_adapter3 folder and bac_adapter3.jar file in the vcenterops\user\plugins\inbound folder.

Install the Adapter in a vApp Installation

If you have a vApp installation, you install the HP BAC adapter from a PAK file. Prerequisites
n n

Download the adapter installation PAK file anonymously from ftp://ftp.integrien.com. Make a note of the build number in the PAK file name. The build number appears after the adapter name, for example, adaptername-buildnumber.pak. Read the release notes that are included with the PAK file.

Procedure 1 2 Save the PAK file in a temporary folder. Log in to the Admin user interface as the admin user. For example: https://ipaddress/admin/ 3 4 On the Update tab, click Browse to locate the temporary folder and select the PAK file. Click Update and click OK to confirm the update. The Admin user interface uploads the PAK file. The upload might take several minutes. 5 6 Read and accept the EULA and click OK. Click OK to confirm and start the update process. The update might take several minutes. Status information appears on the Update tab when the update is finished. 7 Log in to the Custom user interface as an administrator. For example: https://ipaddress/vcops-custom/ 8 9 Select Admin > Support. On the Info tab, find the Adapters Info pane and click the Describe icon ( ). The Describe icon is located at the top right of the Adapters Info pane. 10 Click Yes to start the describe process and click OK. The Custom user interface finds the adapter files, gathers information about the abilities of the adapter, and updates the user interface with information about the adapter. The describe process might take several minutes. When the describe process is finished, the adapter appears in the Adapters Info pane. The build number is in the Adapter Version column. 11 Verify that the build number in the Adapter Version column for the adapter matches the build number in the PAK file that you uploaded.

The installer creates the bac_adapter3 folder and bac_adapter3.jar file in the vcenterops\user\plugins\inbound folder.

12

VMware, Inc.

Chapter 2 Installing the HP BAC Adapter

HP BAC Adapter Folders and Files

The installer places the HP BAC adapter files in the bac_adapter3 folder. The bac_adapter3 folder contains several folders, subfolders, and files. Table 2-1. HP BAC Adapter Folders, Subfolders, and Files
Folder conf File bac.properties open_source_license.txt examples describe.xml history.txt version.txt lib commons-dbcp-1.2.1.jar commons-pool-1.2.jar mysql.jar ojdbc14.jar pg73jdbc3.jar postgresql-8.3dev-600.jdbc3.jar sqljdbc4.jar Subfolder Description BAC adapter properties file. Open source license file. Contains sample files. Describes the adapter. Contains the history of the adapter changes. Contains version information. JAR files that contain classes and resources used to implement queries.

work

You must save your task XML configuration files in this folder.

VMware, Inc.

13

HP BAC Adapter Installation and Configuration Guide

14

VMware, Inc.

Configuring the HP BAC Adapter

To configure the HP BAC adapter, you must configure data collection and relationship tasks and add an adapter instance. You can optionally modify properties in the BAC adapter properties file to tune adapter operation. This chapter includes the following topics:
n n n n

Overview of Configuration Steps, on page 15 Configuring Data Collection and Relationship Tasks, on page 15 Tuning Adapter Operation, on page 24 Add an Adapter Instance, on page 24

Overview of Configuration Steps

You must perform the HP BAC adapter configuration steps in a particular order. 1 2 3 Configure data collection and relationship tasks. See Configuring Data Collection and Relationship Tasks, on page 15. (Optional) Modify properties in the BAC adapter properties file to tune adapter operation. See Tuning Adapter Operation, on page 24. Add an adapter instance and start data collection. See Add an Adapter Instance, on page 24

Configuring Data Collection and Relationship Tasks

You define data collection and relationship tasks in the bac.properties file in the conf folder. You must create a data collection XML configuration file for each data collection task and a relationship XML configuration file for each relationship task. NOTE In a vApp installation, you modify the bac.properties file on the Analytics virtual machine.

VMware, Inc.

15

HP BAC Adapter Installation and Configuration Guide

Defining Tasks in the BAC Adapter Properties File

The bac.properties file contains task properties that you use to define data collection and relationship tasks. You can configure multiple tasks for a single adapter instance. The adapter runs tasks sequentially. Table 3-1. bac.properties File Task Properties
Property TASK_COUNT TASKn_CONFIG TASKn_START Description Number of tasks to run. For example: TASK_COUNT=1 Name of the XML configuration file for task n. For example: TASK1_CONFIG=/work/Config.xml (Optional) Time to start task n in the format MM/DD/YYYY. For example: TASK1_START=02/25/2012

The following example defines three tasks.

TASK_COUNT=3 TASK1_CONFIG=BPMconfig.xml TASK2_CONFIG=SSconfig.xml TASK3_CONFIG=RUMconfig.xml

You can also modify properties in the bac.properties file to tune adapter operation. See Tuning Adapter Operation, on page 24.

Creating a Data Collection Task XML Configuration File

A data collection task XML configuration file contains elements and attributes that define how to retrieve and parse data for a data collection task. You must save your data collection task XML configuration files in the work folder.

<Format> Element
The entire content of an data collection task XML configuration file is contained within the <Format> and </Format> tags. The <Format> element contains the <Row> and <Property> elements.

<Row Element>
The <Row> element is a child element of the <Format> element. It contains elements that identify the resource and describe how to parse a row of data. The following example is of a <Row> element:
<Row> <ResourceName index="0"></ResourceName> <ResourceKind name="RUM"></ResourceKind> <Timestamp index="4"></Timestamp> <Metric name="Hits" val_index="2"></Metric> <Metric name="Server Time" val_index="3"></Metric> </Row>

<ResourceName> Element
The <ResourceName> element is a child element of the <Row> element. It contains attributes that specify the name of the resource.

16

VMware, Inc.

Chapter 3 Configuring the HP BAC Adapter

Table 3-2. <ResourceName> Attributes

Attribute name index Value String value that specifies the name of the resource. Index value that specifies the column in the row that contains the resource name.

<ResourceKind> Element
The <ResourceKind> element is a child element of the <Row> element. It contains attributes that specify the name of the resource kind. Table 3-3. <ResourceKind> Attributes
Attribute name index Value String value that specifies the name of the resource kind. Index value that specifies the column in the row that contains the resource kind name.

<Timestamp> Element
The <Timestamp> element is a child element of the <Row> element. It contains the index attribute, which specifies the column in the row that contains the timestamp. The timestamp must be in epoch time.

<Metric> Element
The <Metric> element is a child element of the <Row> element. It contains attributes that describe metrics. Table 3-4. <Metric> Attributes
Attribute name index group_name group_index instance_index Value String value that specifies the name of the metric. Index value that specifies the column in the row that contains the metric name. String value that specifies the name of the parent group for the metric. Index value that specifies the column in the row that contains the name of the parent group for the metric. Index value that specifies the column in the row that contains the instance name of the metric. For this value to take effect, you must specify the parent group by name or index. Index value that specifies the column in the row that contains the metric value. Boolean value that specifies whether to validate the instance name against the resource name map. If true, the adapter forwards the metric that has instance_index instance name to vCenter Operations Manager if the metric contains the original resource name or any of the mapped names. If false, the default value, validation is disabled. (Optional) Regular expression to use for instance name validation. If specified, the adapter forwards to vCenter Operations Manager only metrics that have instance names that match the regular expression. (Optional) Regular expression to use for instance name validation. If specified, the adapter forwards to vCenter Operations Manager only metrics that have instance names that do not match the regular expression. NOTE exclude_instance takes precedence over valid_instance. (Optional) Comma-delimited list of group names that should not have instances. Names are not case sensitive.

val_index filter_instance

valid_instance

exclude_instance

hide_instance_for_groups

VMware, Inc.

17

HP BAC Adapter Installation and Configuration Guide

<ResourceMap> Element
The <ResourceMap> element is a child element of the <Row> element. It contains a name attribute, which specifies a resource name, and one or more <Value> elements. Each <Value> element specifies a single resource to map to the resource specified in the name attribute. The following example is of a <ResourceMap> element:
<ResourceMap name="exServer"> <Value>10.1.15.22</Value> <Value>exserver.test.com</Value> <Value>exserv22.test.com</Value> </ResourceMap>

<ColumnMap> Element
The <ColumnMap> element is a child element of the <Row> element. It contains attributes that map a source column to a destination column. Table 3-5. <ColumnMap> Attributes
Attribute dest_index src_index delimiter Value Index value that specifies the destination column in the row. The destination column contains the values of the source column separated by the delimiter specified in delimiter. Index value that specifies the source column in the row. If you specify a plus sign (+) after the index value, the adapter merges all of the columns starting from the index value. String that specifies the delimiter to use to separate entries in the destination column. The default delimter is a comma (,). If you specify an empty string (""), the adapter concatenates all of the values.

The following example is of a <ColumnMap> element:

<ColumnMap dest_index="3" src_index="3,+" delimiter=""></ColumnMap>

In this example, if the source column contains 0,1,2,3,4,5,6, the destination column contains 0,1,2,3456. The adapter merges and concatenates the values 3,4,5,6 because the mapping is set to merge columns starting from index 3 (src_index="3,+") and the delimiter is set to an empty string (delimiter="").

<Property> Element
The <Property> element is a child element of the <Format> element. It contains attributes that define the connection type. Each attribute consists of a name and value pair, for example:
<Property name="request_type" value="soap"></Property>

Table 3-6. <Property> Attributes

Name request_type Value (Optional) Type of connection. The following connection types are supported: n soap (the default value) n db n file Request file name. n For a SOAP connection, specify the file that contains the SOAP message. The SQL query specified inside the query tag must have the following where clause: where time_stamp BETWEEN %s AND %s
n n

request_file

For a database connection, specify the file that contains the database connection properties and query specification. For a file connection, specify the file that contains the source data.

18

VMware, Inc.

Chapter 3 Configuring the HP BAC Adapter

Table 3-6. <Property> Attributes (Continued)

Name soap_request_file web_service_url discovery_file wait_for_expr_data wait_for_metric_data query_time_shift collection_interval autodiscovery_enabled Value Deprecated. Same as request_file. URL of the BAC Web Service from which to retrieve data. Valid only for SOAP connections. Discovery request configuration file. Valid only for SOAP connections. Time to wait for metric data before calculating expression values. Time to wait for metric data before adding a 0 value. (Optional) Time shift to apply to the query window to avoid fluctuation. Default is 0 (no effect). Time interval to collect data from the data source. This adapter uses this value as the monitoring interval for all resources that have the specified resource kind. Boolean value that specifies whether to enable auto-discovery. When autodiscovery is enabled, resources are created for you in vCenter Operations Manager when the data collection process discovers new resources. If you set this value to false, you must manually discover resources. The default is false. NOTE Auto-discovery is supported only in HP BAC adapter versions 2.6 and later. discovery_lookback_time Defines the length of the manual discovery query time window as follows: (current_time - discovery_lookback_time, current_time) The default is one hour.

Data Collection Task XML Configuration File Example

The following example is of a data collection task XML configuration file.
<?xml version="1.0" encoding="UTF-8"?> <Format> <Row> <ResourceName name="%1$s"></ResourceName> <ResourceKind name="BPM"></ResourceKind> <Timestamp index="12"></Timestamp> <Metric name="Summary Connection Time" val_index="1"></Metric> <Metric name="Summary DNS Time" val_index="2"></Metric> <Metric name="Summary Download Time" val_index="3"></Metric> <Metric name="Sum First Buf Time" val_index="4"></Metric> <Metric name="Sum Net Time" val_index="5"></Metric> <Metric name="Sum Retry Time" val_index="6"></Metric> <Metric name="Sum Server Time" val_index="7"></Metric> <Metric name="Sum SSL Time" val_index="8"></Metric> <Metric name="Response Time" val_index="9"></Metric> <Metric name="Size" val_index="10"></Metric> <Metric name="Component Error Count" val_index="11"></Metric> </Row> <Property name="web_service_url" value="http://10.118.48.137:80/topaz/gdeopenapi/services/GdeWsOpenAPI"></Property> <Property name="soap_request_file" value="soaprequestBPM.xml"></Property> <Property name="discovery_file" value="BPMdiscover.xml"></Property> </Format>

VMware, Inc.

19

HP BAC Adapter Installation and Configuration Guide

Creating a Relationship Task XML Configuration File

A relationship task XML configuration file contains elements and attributes that define a parent and child resource relationship. You must save relationship task XML configuration files in the work folder.

<Format> Element
The entire content of a relationship task XML configuration file is contained within the <Format> and </Format> tags. The <Format> element contains the <Relationship> and <Property> elements.

<Relationship> Element
The <Relationship> element contains elements that define a single parent and child resource relationship. The following example is of the <Relationship> element.
<Relationship> <ParentResourceName index="1"></ParentResourceName> <ParentResourceKind name="BPM Location"></ParentResourceKind> <ChildResourceName name="%1$s_%2$s"></ChildResourceName> <ChildResourceKind name="BPM"></ChildResourceKind> </Relationship>

<ParentResoureName> Element
The <ParentResourceName> element is a child element of the <Relationship> element. It contains attributes that specify the name of the parent resource. Table 3-7. <ParentResourceName> Attributes
Attribute name index Value String value that specifies the name of the parent resource. Index value that specifies the column that contains the parent resource name.

<ParentResourceKind> Element
The <ParentResourceKind> element is a child element of the <Relationship> element. It contains attributes that specify the name of the parent resource kind. Table 3-8. <ParentResourceKind> Attributes
Attribute name index Value String value that specifies the name of the parent resource kind. Index value that specifies the column that contains the parent resource kind name.

<ChildResourceName> Element
The <ChildResourceName> element is a child element of the <Relationship>. It contains attributes that specify the name of the child resource. Table 3-9. <ChildResourceName> Attributes
Attribute name index Value String value that specifies the name of the child resource. Index value that specifies the column that contains the child resource name.

20

VMware, Inc.

Chapter 3 Configuring the HP BAC Adapter

<ChildResourceKind> Element
The <ChildResourceKind> element is a child element of the <Relationship> element. It contains attributes that specify the name of the child resource kind. Table 3-10. <ChildResourceKind> Attributes
Attribute name index Value String value that specifies the name of the child resource kind. Index value that specifies the column that contains the child resource kind name.

<Property> Element
The <Property> element is a child element of the <Format> element. It contains attributes that define the connection type. Each attribute consists of a name and value pair, for example:
<Property name="request_type" value="soap"></Property>

Table 3-11. <Property> Attributes

Name request_type Value (Optional) Type of connection. The following connection types are supported: n soap (the default value) n db n file Request file name. n For a SOAP connection, specify the file that contains the SOAP message. The SQL query specified inside the query tag must have the following where clause: where time_stamp BETWEEN %s AND %s
n n

request_file

For a database connection, specify the file that contains the database connection properties and query specification. For a file connection, specify the file that contains the source data.

soap_request_file web_service_url discovery_file wait_for_expr_data wait_for_metric_data query_time_shift collection_interval autodiscovery_enabled

Deprecated. Same as request_file. URL of the BAC Web Service from which to retrieve data. Valid only for SOAP connections. Discovery request configuration file. Valid only for SOAP connections. Time to wait for metric data before calculating expression values. Time to wait for metric data before adding a 0 value. (Optional) Time shift to apply to the query window to avoid fluctuation. Default is 0 (no effect). Time interval to collect data from the data source. This adapter uses this value as the monitoring interval for all resources that have the specified resource kind. Boolean value that specifies whether to enable auto-discovery. When autodiscovery is enabled, resources are created for you in vCenter Operations Manager when the data collection process discovers new resources. If you set this value to false, you must manually discover resources. The default is false. NOTE Auto-discovery is supported only in HP BAC adapter versions 2.6 and later. Defines the length of the manual discovery query time window as follows: (current_time - discovery_lookback_time, current_time) The default is one hour.

discovery_lookback_time

VMware, Inc.

21

HP BAC Adapter Installation and Configuration Guide

Relationship Task XML Configuration File Example

The following example is of a relationship task XML configuration file.
<?xml version="1.0" encoding="UTF-8"?> <Format> <Relationship> <ParentResourceName index="1"></ParentResourceName> <ParentResourceKind name="BPM Location"></ParentResourceKind> <ChildResourceName name="%1$s_%2$s"></ChildResourceName> <ChildResourceKind name="BPM"></ChildResourceKind> </Relationship> <Property name="web_service_url" value="http://BACServer: 80/topaz/gdeopenapi/services/GdeWsOpenAPI"></Property> <Property name="soap_request_file" value="/conf/soaprequest-sitescope.xml"></Property> <Property name="collection_interval" value="10"></Property> </Format>

SOAP Connection Configuration Example

This example shows a SOAP connection configuration.

Property Attributes
The following example shows the <Property> element attributes in a task XML configuration file for a SOAP connection.
<Property name="web_service_url" value="http://10.118.48.137:80/topaz/gdeopenapi/services/GdeWsOpenAPI"></Property> <Property name="request_file" value="soaprequestBPM.xml"></Property> <Property name="discovery_file" value="BPMdiscover.xml"></Property>

SOAP Request File

The following example is of a SOAP request file. You use the <Property> element request_file attribute to specify the location of this file.
<?xml version="1.0" encoding="UTF-8"?> <soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:gdew="http://qalab-137.qa1int.com/topaz/gdeopenapi/services/GdeWsOpenAPI"> <soapenv:Header/> <soapenv:Body> <gdew:getDataWebService soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"> <user xsi:type="soapenc:string" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">admin</user> <password xsi:type="soapenc:string" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">admin</password> <query xsi:type="soapenc:string" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">select szTransactionName, u_iSumConnectionTime, u_iSumDnsTime,u_iSumDownloadTime, u_iSumFirstBufTime, u_iSumNetTime, u_iSumRetryTime, u_iSumServerTime, u_iSumSSLTime, dResponseTime, u_iSize, iComponentErrorCount, time_stamp from trans_t where time_stamp BETWEEN %s AND %s order by 13 asc </query> </gdew:getDataWebService> </soapenv:Body> </soapenv:Envelope>

22

VMware, Inc.

Chapter 3 Configuring the HP BAC Adapter

SOAP Discovery File

The following example is of a SOAP discovery file. You use the <Property> element discovery_file attribute to specify the location of this file.
<?xml version="1.0" encoding="UTF-8"?> <soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:gdew="http://qalab-137.qa1int.com/topaz/gdeopenapi/services/GdeWsOpenAPI"> <soapenv:Header/> <soapenv:Body> <gdew:getDataWebService soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"> <user xsi:type="soapenc:string" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">admin</user> <password xsi:type="soapenc:string" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">admin</password> <query xsi:type="soapenc:string" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">select distinct szTransactionName as ResourceName from trans_t</query> </gdew:getDataWebService> </soapenv:Body> </soapenv:Envelope>

Database Connection Configuration Example

This example shows a database connection configuration.

Property Attributes
The following example shows the <Property> element attributes in a task XML configuration file for a database connection.
<Property name="request_type" value="db"></Property> <Property name="request_file" value="db1.properties"></Property>

Database Connection Properties File

The following example is of a database connection properties file. You use the <Property> element
request_file attribute to specify the location of this file. driverClassName=org.postgresql.Driver url=jdbc:postgresql://192.168.1.12:9432/hqdb username=hqadmin password=hqadmin defaultAutoCommit=true maxActive=20 initialSize=5 minIdle=1 maxIdle=20 poolPreparedStatements=false maxWait=3000 maxOpenPreparedStatements=0 sqlQuery=select timestamp, measurement_id, value from hq_metric_data where timestamp between ? and ?

VMware, Inc.

23

HP BAC Adapter Installation and Configuration Guide

File Connection Configuration Example

The following example shows the <Property> element attributes in a task XML configuration file for a file connection.
<Property name="request_type" value="file"></Property> <Property name="request_file" value="data.txt"></Property>

In the example, data.txt is the source file for the data.

Tuning Adapter Operation

The bac.properties file in the conf folder contains properties that you can modify to tune adapter operation. NOTE In a vApp installation, you modify the bac.properties file on the Analytics virtual machine. Table 3-12. bac.properties Properties for Adapter Tuning
Property maxSendChunkInterval Description For historical collection mode, the maximum interval, in milleseconds, to buffer data before sending it to vCenter Operations Manager. Maximum trailing time from the current to query, in minutes. Minimum trailing time from the current time to query, in minutes. Together with maxQueryWindow, this property specifies the length of the collection window. If TASK_START time is not specified for TASK_CONFIG, the amount of time, in milliseconds, to go back from the current time to start data collection. When this property is set to true, historical collection mode is enabled. In historical collection mode, the BAC adapter begins sending data from the specified TASK_START time and splits data into chunks according to the maxSendChunkInterval length. When it reaches the current time, the flag resets. Time zone replacement placeholder. Replacement value for the time zone shift. This value repalces the placeholder in SOAP and database queries. Default 3600000

maxQueryWindow minQueryWindow

15 1

goBacktime

historicLoadEnabled

false

timeZoneShiftPlaceholder timeZoneShift

%TZ 0

For information about configuring task properties in the bac.properties file, see Defining Tasks in the BAC Adapter Properties File, on page 16.

Add an Adapter Instance

You must create an adapter instance for the HP BAC adapter. The adapter instance defines the adapter type and specifies the location of the BAC adapter properties file. Prerequisites Install the HP BAC adapter. See Chapter 2, Installing the HP BAC Adapter, on page 11. Procedure 1 2 Log in to the Custom user interface as an administrator. Select Environment > Configuration > Adapter Instances.

24

VMware, Inc.

Chapter 3 Configuring the HP BAC Adapter

Select the collector to use from the Collector drop-down menu. Unless you added additional collectors, the only available collector is vCenter Operations Server. You can change the name of this collector when you install the standalone version.

4 5 6 7 8 9

Select BAC from the Adapter Kind drop-down menu. Click the Add New Adapter Instance icon. Type a name for the adapter in the Adapter Instance Name text box. Type the name of the BAC adapter properties file in the Property File text box. Click Test to test the availability of the BAC adapter properties file. Click OK to save your configuration.

What to do next Start data collection. If you enabled auto-discovery for a task, resources are created when the data collection process discovers new resources. If you did not enable auto-discovery, you must use manual discovery to create resources. For information about starting data collection and discovering resources, see the administration guide for your vCenter Operations Manager version.

VMware, Inc.

25

HP BAC Adapter Installation and Configuration Guide

26

VMware, Inc.

Troubleshooting the HP BAC Adapter

Known troubleshooting information can help you diagnose and correct problems with the HP BAC adapter. Log files contain valuable information about adapter instance operation. This chapter includes the following topics:
n n n

Troubleshooting an HP BAC Adapter Instance, on page 27 Viewing System Log Files, on page 27 Use Test Data to Test an Adapter Instance, on page 28

Troubleshooting an HP BAC Adapter Instance

Perform these general troubleshooting steps to diagnose and correct problems with an HP BAC adapter instance. 1 2 View the collection status and collection state for the adapter instance resource on the Environment Overview page in the Custom user interface. Check the adapter and collector log files for errors. See Viewing System Log Files, on page 27.

Viewing System Log Files

You can view HP BAC adapter errors in the adapter and collector log files. You can view log files in the Custom user interface or in an external log viewer. HP BAC adapter log files are in the vcenter-ops/user/log/adapters/BACAdapter folder and collector log files are in the vcenter-ops/user/log folder, where vcenter-ops represents your installation folder. In a vApp installation, log files are on the Analytics virtual machine. The logging level is set to ERROR by default. To troubleshoot issues, set the logging level to INFO. To view detailed messages, including micro steps, queries, and returned results, set the logging level to DEBUG. NOTE If you set the logging level to DEBUG, log files can become large very quickly. Set the logging level to DEBUG only for short periods of time. For information about viewing log files and modifying logging levels, see the online help.

VMware, Inc.

27

HP BAC Adapter Installation and Configuration Guide

HP BAC Adapter Classes

The HP BAC adapter uses certain adapter classes. Table 4-1. HP BAC Adapter Classes
Class com.integrien.adapter3.bac.BACAdapter com.integrien.adapter3.bac.XMLConfigReader com.integrien.adapter3.bac.DataReader com.integrien.adapter3.bac.BACAdapterUtils Description Main entry class. XML configuration file reader. Main collection logic. Utility class.

Use Test Data to Test an Adapter Instance

If you do not have access to an HP BAC installation, you can test your HP BAC adapter instance by configuring tasks that read data from text files generated by a script or application. Procedure 1 2 Create a data collection task XML configuration file and name it Data.xml. In Data.xml, set the request type to file and set the request file name to data.txt. For example:
<Property name="request_type" value="file"></Property> <Property name="request_file="data.txt"></Property>

3 4

Create a relationship task XML configuration file and name it Relationships.xml. In Relationships.xml, set the request type to file and set the request file name to relationships.txt. For example:
<Property name="request_type" value="file"></Property> <Property name="request_file="relationships.txt"></Property>

In the BAC adapter properties file, define a data collection task that uses Data.xml and a relationship task that uses Relationships.xml. For example:
TASK_COUNT=2 TASK1_CONFIG=Data.xml TASK2_CONFIG=Relationships.xml

6 7

Add an adapter instance and configure the instance to read the BAC adapter properties file. Run a script or application that writes lines in the appropriate format to the data.txt and relationships.txt files. You can purge the content of the files after each data collection cycle.

8 9

Start data collection for the adapter instance resource. If you did not enable auto-discovery, use manual discovery to discover resources.

You should see metrics and relationships in the Custom user interface.

28

VMware, Inc.

Index

A
adapter classes 28 adapter instances 24 audience information 5

B
bac_adapter3 folder 13 bac.properties file 24

C
configuration steps 15

D
data collection methods 9 data collection task XML files, syntax 16 data collection tasks 15 database connection 23

F
file connection 24

I
installing the adapter 11, 12 introduction 9

L
log files 27

R
relationship task XML configuration file 20 requirements 10 resource relationships 9

S
security considerations 10 SOAP connections 22

T
TASK properties 16 testing an adapter instance 28 troubleshooting steps 27

U
updated information 7

VMware, Inc.

29

HP BAC Adapter Installation and Configuration Guide

30

VMware, Inc.