Download Relationships Adapter Installation and Configuration

Relationships 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-000923-06
Relationships 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:
[email protected]
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
2
VMware, Inc.
Contents
Relationships Adapter Installation and Configuration Guide
5
Updated Information 7
1 Introduction to the Relationships Adapter 9
How the Relationships Adapter Updates Resource Relationships
Instance Generated Metrics 9
Installation and Configuration Requirements 10
2 Installing the Relationships Adapter 11
Install the Adapter in a Standalone Installation
Install the Adapter in a vApp Installation 12
Relationships Adapter Folder and Files 13
9
11
3 Configuring the Relationships Adapter 15
Overview of Configuration Steps 15
Creating the Source Relationships Table 16
Creating a Relationships SQL File 19
Add an Adapter Instance 19
Modifying Database Connection Properties 22
Modifying Adapter Properties 23
Validate the Relationships in vCenter Operations Manager Enterprise
24
4 Troubleshooting the Relationships Adapter 27
Troubleshooting a Relationships Adapter Instance 27
View Collection Information 27
Viewing System Log Files 29
Adapter Cannot Connect to the Source Relationships Table
Adapter Does Not Update Relationships 30
30
Index 33
VMware, Inc.
3
Relationships Adapter Installation and Configuration Guide
4
VMware, Inc.
Relationships Adapter Installation and
Configuration Guide
The Relationships Adapter Installation and Configuration Guide explains how to install and configure the
Relationships adapter for vCenter Operations Manager.
Intended Audience
This information is intended for anyone who needs to install and configure the Relationships adapter.
VMware, Inc.
5
Relationships Adapter Installation and Configuration Guide
6
VMware, Inc.
Updated Information
The Relationships Adapter Installation and Configuration Guide is updated with each release of the product or
when necessary.
This table provides the update history of the Relationships Adapter Installation and Configuration Guide.
Revision
Description
EN-000923-06
n
Added the Use Identifiers option to “Add an Adapter Instance,” on page 19.
n
Added the MULTIPLE_RELATIONSHIPS_ENABLED and CACHE_UPDATE_INTERVAL properties to
“Modifying Adapter Properties,” on page 23.
n
Removed the com.integrien.adapter3.relationship.exceptions.SystemException class
from “Relationships Adapter Classes,” on page 30.
EN-000923-05
Updated the library files listed in “Relationships Adapter Folder and Files,” on page 13.
EN-000923-04
Updated the document for the 5.6 release.
n Added information about instance-generated and adapter-specific metrics. See “Instance Generated
Metrics,” on page 9.
n
Added descriptions of the relationships.properties, collect_status_messages.properties,
allParents_resourceId.txt, and open_source_license.txt files to “Relationships Adapter
Folder and Files,” on page 13.
n
Added descriptions of the properties in the relationships.properties file. See “Modifying
Adapter Properties,” on page 23.
Added information about viewing messages about collection states and collection status values. See
“View Collection Information,” on page 27.
n
EN-000923-03
Removed information about Sybase database support.
EN-000923-02
Added the Child Adapter Kinds To Clear option to “Add an Adapter Instance,” on page 19.
EN-000923-01
Added information about resource identification to “Columns in the Source Relationships Table,” on
page 16.
EN-000923-00
The Relationships Adapter Technical Note is now the Relationships Adapter Installation and Configuration
Guide.
The Relationships Adapter Technical Note is the initial release of this document.
VMware, Inc.
7
Relationships Adapter Installation and Configuration Guide
8
VMware, Inc.
Introduction to the Relationships
Adapter
1
The Relationships adapter is an embedded adapter for vCenter Operations Manager. The adapter updates
relationships between resources in the vCenter Operations Manager database.
This chapter includes the following topics:
n
“How the Relationships Adapter Updates Resource Relationships,” on page 9
n
“Instance Generated Metrics,” on page 9
n
“Installation and Configuration Requirements,” on page 10
How the Relationships Adapter Updates Resource Relationships
With the Relationships adapter, you can define relationships between resources that different types of
adapters create. The Relationships adapter does not collect data.
The Relationships adapter updates relationships between resources in the vCenter Operations Manager
database based on parent-child relationships that you define in a table in an external database. The adapter
can also create new container resources to use in resource relationships.
During each collection cycle, the Relationships adapter reads the source relationships table in the external
database and updates the relationships in vCenter Operations Manager.
The Relationships adapter uses a SELECT statement in an SQL file to read the source relationships table. The
RELATIONSHIPS.sql file in the conf folder contains a query that you can use as a template to create your own
relationships SQL files.
When you create an adapter instance for the Relationships adapter, you identify the external database that
contains the source relationships table and specify the name of the relationships SQL file to use to read the
source relationships table.
Instance Generated Metrics
In vCenter Operations Manager 5.x and later releases, all adapter instances, including Relationships adapter
instances, collect certain adapter-specific metrics under Instance Generated. These metrics include the
elapsed time to collect data, the new metrics and resources in each collect call, the number of down
resources, and the total number of metrics and resources collected.
In vCenter Operations Manager 5.6 and later releases, metrics specific to each adapter kind appear under
Instance Generated in Adapter Specific. Adapter-specific metrics provide additional information about
adapter instance operation. For the Relationships adapter kind, the Query Execution Time metric shows the
amount of time taken to run the query to retrieve relationships.
VMware, Inc.
9
Relationships Adapter Installation and Configuration Guide
Installation and Configuration Requirements
You must make sure that your system meets certain requirements before you install the Relationships
adapter.
Supported Database Types
The external database that contains the source relationships table must be one of the following database
types:
n
SQL Server
n
Oracle
n
PostgreSQL
n
MySql
Connection Requirements
The Relationships adapter uses a JDBC connection to access the database that contains the source
relationships table. The format of the JDBC connection URL depends on the database type.
Table 1‑1. JDBC Connection URL Formats
Database Type
URL Format
PostgreSQL
jdbc:postgresql://host:port/dbname
SQL Server
jdbc:sqlserver://host:port;DatabaseName=dbname
MySQL
jdbc:mysql://host:port/dbname
Oracle
jdbc:oracle:thin:@host:port:dbname
Credential Requirements
The Relationships adapter requires the user name and password of a user account that can read the database
that contains the source relationships table. You use this user name and password when you create a
credential for a Relationships adapter instance.
vCenter Adapter Requirements
You must install and configure the vCenter adapter before you install the Relationships adapter. See the
VMware vCenter Adapter Installation and Configuration Guide.
NOTE If you have a vCenter Operations Manager vApp installation, the vCenter adapter is installed by
default.
10
VMware, Inc.
Installing the Relationships Adapter
2
How you install the Relationships adapter depends on whether you have a vCenter Operations Manager
Standalone or vApp installation.
This chapter includes the following topics:
n
“Install the Adapter in a Standalone Installation,” on page 11
n
“Install the Adapter in a vApp Installation,” on page 12
n
“Relationships Adapter Folder and Files,” on page 13
Install the Adapter in a Standalone Installation
If you have a standalone installation, you install the Relationships adapter by extracting the adapter
installation files from a TGZ file and running an installation utility.
Prerequisites
n
Download the adapter installation TGZ file anonymously from ftp://ftp.integrien.com/.
n
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.
n
Read the release notes that are included with the TGZ file.
Procedure
1
Open the TGZ file and extract the TAR file to a temporary folder on your vCenter Operations Manager
server.
2
In the temporary folder, open the TAR file and extract and run the installer for your operating system
platform.
3
Log in to the Custom user interface as an administrator.
4
Select Admin > Support.
5
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
Relationships Adapter Installation and Configuration Guide
7
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 installation utility creates the relationships_adapter3 folder and relationship_adapter3.jar file under
the vcenter-ops/user/plugins/inbound folder.
Install the Adapter in a vApp Installation
If you have a vApp installation, you install the Relationships adapter from a PAK file.
Prerequisites
n
Download the adapter installation PAK file anonymously from ftp://ftp.integrien.com.
n
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.
n
Read the release notes that are included with the PAK file.
Procedure
1
Save the PAK file in a temporary folder.
2
Log in to the Admin user interface as the admin user.
For example: https://ipaddress/admin/
3
On the Update tab, click Browse to locate the temporary folder and select the PAK file.
4
Click Update and click OK to confirm the update.
The Admin user interface uploads the PAK file. The upload might take several minutes.
5
Read and accept the EULA and click OK.
6
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
Select Admin > Support.
9
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 installation process creates the relationships_adapter3 folder and relationship_adapter3.jar file in
the vcenter-ops/user/plugins/inbound folder.
12
VMware, Inc.
Chapter 2 Installing the Relationships Adapter
Relationships Adapter Folder and Files
The installer places the Relationships adapter files in the vcenterops/user/plugins/inbound/relationships_adapter3 folder.
The relationships_adapter3 folder contains several subfolders and files.
Table 2‑1. Relationships Adapter Folders and Files
Folder
File
Description
conf
db.properties
Contains database properties.
relationships.properties
(vCenter Operations Manager 5.6 and later
only) Contains adapter properties.
describe.xml
Includes the supported databases for the
source relationships table.
history.txt
Contains information about the changes
implemented in the adapter versions.
version.txt
Contains information about the adapter
version.
collect_status_messages.properties
(vCenter Operations Manager 5.6 and later
only) Contains properties that define the
messages that appear in the Custom user
interface when you point to the collection
status of an adapter instance on the
Environment Overview page.
RELATIONSHIPS.sql
Sample relationships SQL file. Use the
query in this file as a template to create
your own relationships SQL file.
open_source_license.txt
Open source license file.
allParents_resourceId.txt
Keeps track of all parent resources that
have relationships that an adapter instance
creates.
If all records for a parent are deleted from
the source relationships table, the adapter
uses the parent resource cached in this file
to delete the related relationships from the
vCenter Operations Manager database.
work
NOTE The adapter creates the work folder
after it begins collecting data. The installer
does not create the work folder.
lib
OSS library files:
n
n
n
n
commons-dbcp-1.2.1.jar
commons-pool-1.2.jar
postgresql-8.3.dev-600.jdbc3.jar
jtds.jar
Database drivers and other commonly
used files.
mysql-connector-java-3.1.8.jar
Non-OSS library files:
n
n
n
VMware, Inc.
sqljdbc4.jar
ojdbc14.jar
13
Relationships Adapter Installation and Configuration Guide
14
VMware, Inc.
Configuring the Relationships
Adapter
3
Configuring the Relationships adapter involves several steps. You create and populate a source
relationships table in an external database, create a relationships SQL file to read the source relationships
table, and configure an adapter instance. You can optionally tune adapter operation by modifying
configuration properties.
This chapter includes the following topics:
n
“Overview of Configuration Steps,” on page 15
n
“Creating the Source Relationships Table,” on page 16
n
“Creating a Relationships SQL File,” on page 19
n
“Add an Adapter Instance,” on page 19
n
“Modifying Database Connection Properties,” on page 22
n
“Modifying Adapter Properties,” on page 23
n
“Validate the Relationships in vCenter Operations Manager Enterprise,” on page 24
Overview of Configuration Steps
You must perform the configuration steps in a particular order.
1
If your resource topology is not already described in a database, create and populate a source
relationships table in an external database. See “Creating the Source Relationships Table,” on page 16.
2
Create a relationships SQL file to read the source relationships table. See “Creating a Relationships SQL
File,” on page 19.
3
Create one or more adapter instances for the Relationships adapter. See “Add an Adapter Instance,” on
page 19.
4
(Optional) Modify database connection properties for the Relationships adapter. See “Modifying
Database Connection Properties,” on page 22.
5
(Optional) In vCenter Operations Manager 5.6 and later releases, modify adapter properties for the
Relationships adapter. See “Modifying Adapter Properties,” on page 23.
6
Validate the resource relationships in the user interface. See “Validate the Relationships in vCenter
Operations Manager Enterprise,” on page 24.
VMware, Inc.
15
Relationships Adapter Installation and Configuration Guide
Creating the Source Relationships Table
The Relationships adapter updates relationships between resources in the vCenter Operations Manager
database based on parent-child relationships that you define in a table in an external database. If you do not
already have relationships data stored in an external database, you must create and populate the source
relationships table.
NOTE The Relationships adapter only reads the source relationships table. It does not update the data in the
source relationships table.
Columns in the Source Relationships Table
Each column of the source relationships table defines a field. All of the columns are required. You can
rearrange the order of the columns.
Field Names
Each column in the source relationships table is a field name. Each field has a maximum length. All of the
fields are text fields, except for parentIsContainer.
Table 3‑1. Field Names in the Source Relationships Table
Column Field Name
Maximum
Length
Description
parentAdapterKind
50
Adapter kind of the parent object.
parentResKind
50
Resource type of the parent object.
parentResName
1000
Name of the parent resource
parentResIdentifiers
Key 50
Value 1000
Resource identifier for the parent object. The adapter uses this field only for
parent resources that require unique identification.
childAdapterKind
50
Adapter kind of the child resource.
childResKind
Resource kind of the child resource.
childRes
1000
Name of the child resource.
childResIdentifiers
Key 50
Value 1000
Resource identifiers for the child object. The adapter uses this field only for
child resources that require unique identification.
parentIsContainer
Use 1 in this field to force the parent resource to be a container resource,
otherwise use 0.
Resource Identification
When you specify an identifier for a resource, include only the identifiers that are part of the uniqueness of
the resource.
Not all identifiers uniquely identify a resource. For example, a virtual machine has the identifiers
VMEntityObjectID, VMEntityVCID, and VMEntityName, but only VMEntityObjectID and VMEntityVCID
uniquely identify the virtual machine. When you specify a resource identifier for a virtual machine, you do
not include VMEntityName, for example:
VMEntityObjectID=vm-1412;VMEntityVCID=D0DB4B81-E891-4DB4-95C6-7C4BA183B107
Some resources do not have any identifiers or have identifiers that act only as properties. The AdapterKind,
ResourceKind, and ResourceName fields uniquely identify these resources. You do not need to specify
identifiers for these resources.
16
VMware, Inc.
Chapter 3 Configuring the Relationships Adapter
Field Values
You must use keys, not display names, for the values in the parentAdapterKind, parentResKind,
childAdapterKind, childResKind, parentResIdentifiers, and childResIdentifiers columns in the source
relationships table.
For example, for a vCenter adapter, the adapter kind display name is VMware Adapter, but the key is
VMWARE, so you use VMWARE in the parentAdapterKind or childAdapterKind column.
You can find field values in the vCenter Operations Manager database.
Table 3‑2. Where to Find Field Values in the vCenter Operations Manager Enterprise Database
Object Type
Table Name
Field Name
AdapterKind
AdapterKind
ADAPTER_KEY
ResourceKind
ResourceKind
RESKND_KEY
ResourceName
AliveResource
Name
ResourceIdentifierKey
ResourceKindIdent
RKIDENT_KEY
ResourceIdentifierValue
ResourceIdentifier
STRINGVAL
To retrieve keys from the vCenter Operations Manager database, see “Retrieve Keys from the vCenter
Operations Manager Database,” on page 18.
Field Data Types
In SQL Server, all of the field data types are text: nvarchar(50). In Oracle, all of the field data types are
NVARCHAR2(50).
NOTE To fit multiple sets of key-value identifiers, parent and child resource identifiers must be larger, for
example, nvarchar(150).
Rows in the Source Relationships Table
Each row in the source relationships table defines a parent-child relationship between two resources. A
resource can be an existing resource or container, or a new container to add during the next collection cycle
of the Relationships adapter.
You identify a resource by its adapter kind, resource kind, resource name, and resource identifier fields.
Each parent and child resource has fields in each row of the source relationships table to hold these values.
Follow these conventions when you identify a resource in a row of the source relationships table.
n
The parentAdapterKind, parentResKind, parentResName, childAdapterKind, childResKind, and
childRes fields are always required.
n
Some resources require identifiers to uniquely identify the resource. The field names for resource
identifiers are parentResIdentifiers and childResIdentifiers. You specify a resource identifier as a keyvalue pair, for example, Port=22. Use a semicolon (;) to separate multiple key-value pairs.
n
Some resources do not have identifiers, or their identifiers serve as properties. For these resources, the
resource identifier field is NULL.
n
Use the parentIsContainer field to flag a parent resource as a container.
The following example shows two rows in a source relationships table. In the example, the resources Cisco1
and Cisco2 have no identifiers. Because the resource Linux is identified by its host IP address and port,
HostIP=10.1.15.22;Port=22 appears in its identifiers fields.
VMware, Inc.
17
Relationships Adapter Installation and Configuration Guide
Table 3‑3. Sample Source Relationships Table
parentI
parentAdapte
parentResNam
parentResIdentifier
sConta
childAdapter
rKind
parentResKind
e
s
iner
Kind
childResKind
childRes
ers
Cisco1
Cisco1AdapterI
Cisco1
NULL
0
Cisco2
Cisco2Adapter
Cisco2
NULL
10.1.15.48_Lin
HostIP=10.1.15.4
ux
8;Port=22
nstsance
SSH
Linux
childResIdentifi
Instance
10.1.15.22_Linu
HostIP=10.1.15.22;P
x
ort=22
0
SSH
Linux
Retrieve Keys from the vCenter Operations Manager Database
You can obtain keys and identifiers for data fields by accessing the vCenter Operations Manager database
and running SQL queries.
NOTE If you are using version 1.0.1 or later, you can also use the HTTP Post Adapter interface to retrieve
keys and identifiers for data fields.
Procedure
1
In a Web browser, type http://ip_address/dbAccessQuery.action where ip_address is the IP address
of the vCenter Operations Manager server.
2
Type your SQL query in the top right window.
For example:
select a.ADAPTER_KIND_ID, a.ADAPTER_KEY, b.RESKND_ID, b.RESKND_KEY, e.ATTRKEY_ID,
e.ATTR_KEY from AdapterKind a
inner join ResourceKind b on (b.ADAPTER_KIND_ID = a.ADAPTER_KIND_ID)
inner join AliveResource c on (c.RESKND_ID = b.RESKND_ID)
inner join ResourceAttributeKey d on (d.RESOURCE_ID = c.RESOURCE_ID)
inner join AttributeKey e on (e.ATTRKEY_ID = d.ATTRKEY_ID)
where a.ADAPTER_KEY = 'something' or b.RESKND_KEY = 'something'
3
Click the Execute SQL icon.
The results appear in the lower right window.
Example Source Relationships Table Schemas
Schema examples for two of the databases that the Relationships adapter supports.
Sample Schema for Oracle
This example is a table schema for Oracle.
CREATE TABLE Relationships(
parentAdapterKind nvarchar2(50) NOT NULL,
parentResKind nvarchar2(50) NOT NULL,
parentResName nvarchar2(50) NOT NULL,
childAdapterKind nvarchar2(50) NOT NULL,
childResKind nvarchar2(50) NOT NULL,
childRes nvarchar2(50) NOT NULL,
parentResIdentifiers nvarchar2(150) NULL,
childResIdentifiers nvarchar2(150) NULL,
parentIsContainer nvarchar2(50) NOT NULL
);
18
VMware, Inc.
Chapter 3 Configuring the Relationships Adapter
Sample Schema for SQL Server
This example is a table schema for SQL Server.
CREATE TABLE [dbo].[Relationships](
[parentAdapterKind] [nvarchar](50) COLLATE Latin1_General_CI_AI NOT NULL,
[parentResKind] [nvarchar](50) COLLATE Latin1_General_CI_AI NOT NULL,
[parentResName] [nvarchar](50) COLLATE Latin1_General_CI_AI NOT NULL,
[childAdapterKind] [nvarchar](50) COLLATE Latin1_General_CI_AI NOT NULL,
[childResKind] [nvarchar](50) COLLATE Latin1_General_CI_AI NOT NULL,
[childRes] [nvarchar](50) COLLATE Latin1_General_CI_AI NOT NULL,
[parentResIdentifiers] [nvarchar](150) COLLATE Latin1_General_CI_AI NULL,
[childResIdentifiers] [nvarchar](150) COLLATE Latin1_General_CI_AI NULL,
[parentIsContainer] [nvarchar](50) COLLATE Latin1_General_CI_AI NOT NULL
) ON [PRIMARY]
Creating a Relationships SQL File
The Relationships adapter uses a SELECT statement in an SQL file to read the source relationships table.
The RELATIONSHIPS.sql file in the conf folder contains a query that you can use as a template to create your
own relationships SQL files.
select parentResName PARENT_RESOURCENAME,
childRes CHILD_RESOURCENAME,
parentResKind PARENT_RESOURCEKIND,
childResKind CHILD_RESOURCEKIND,
parentAdapterKind PARENT_ADAPTERKIND,
childAdapterKind CHILD_ADAPTERKIND,
parentResIds PARENT_RESOURCEIDS,
childResIds CHILD_RESOURCEIDS,
parentIsContainer PARENT_IS_CONTAINER
from Relationships
The query in the RELATIONSHIPS.sql file works only if the name of your source relationships table is named
Relationships and the field names in the statement match the field names in your source relationships table.
If your source relationships table does not meet these requirements, modify the RELATIONSHIPS.sql file and
create a statement that works for your source relationships table.
Add an Adapter Instance
You must create an adapter instance for the Relationships adapter. The adapter instance defines the adapter
type, identifies the database that contains the source relationships table, and specifies the location of the
relationships SQL file.
You can create multiple adapter instances and assign a different relationships SQL file to each instance.
Prerequisites
n
Install the Relationships adapter. See Chapter 2, “Installing the Relationships Adapter,” on page 11.
n
Create the source relationships table. See “Creating the Source Relationships Table,” on page 16.
n
Create a relationships SQL file. See “Creating a Relationships SQL File,” on page 19.
n
Create a credential, or, if you plan to create a credential when you add the adapter instance, become
familiar with creating credentials. See “Add a Credential,” on page 21.
VMware, Inc.
19
Relationships Adapter Installation and Configuration Guide
Procedure
1
Log in to the Custom user interface as an administrator.
2
Select Environment > Configuration > Adapter Instances.
3
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
Select Relationship Adapter from the Adapter Kind drop-down menu.
5
Click the Add New Adapter Instance icon.
6
Type a name for the adapter in the Adapter Instance Name text box.
7
Configure the connection to the database that contains the source relationships table.
Option
Action
DB Type
Select the database type of the database that contains the source relationships table.
Host
Type the host name or IP address of the database that contains the source relationships table.
Port
Type the port number to connect to the database that contains the source relationships table. The
default port is 9432.
DB Name
Type the name of the database that contains the source relationships table
8
Type the name of the relationships SQL file to use to read the source relationships table in the
Relationship Sql file text box.
9
(Optional) To configure the Relationships adapter instance to clear child resource relationships only for
specific adapter kinds, type those adapter kinds in the Child Adapter Kinds To Clear text box.
Separate multiple adapter kinds with a comma.
When you type an adapter kind in this text box, the Relationships adapter instance clears the child
resources of that adapter kind and preserves all other child relationships. For example, if you type
SSH,General SQL Data Loader, the Relationships adapter instance clears relationships only for a parent
resource that has child resources of adapter SSH and General Sql Data Loader.
If you leave this text box blank (the default), the Relationships adapter instance clears all child
relationships before it creates new relationships based on the query that you specify.
The most practical use of this option is to add the child adapter kinds for relationships that this adapter
instance creates so that the relationships created by other adapters for a parent resource are preserved.
NOTE This option applies only to vCenter Operations Manager 5.x and later versions.
20
VMware, Inc.
Chapter 3 Configuring the Relationships Adapter
10
Select a Use Identifers option to specify whether the adapter instance can process resource
relationships without using resource identifiers.
To process resource relationships, the Relationships adapter uses a query that retrieves resource
information for both parent and child resources. This information includes an adapter kind, resource
kind, resource name, and resource identifier string for each parent and child resource.
Option
Description
true
The adapter instance uses resource identifiers to find parent and child
resources.
false
The adapter instance looks for resources that have the given adapter kind,
resource kind, and resource name combination.
Creating entries in the source relationships table is a non-trivial operation,
especially for columns of parent and child resource identifiers
(parentResIdentifiers and childResIdentifiers). If one of these unique
identifiers is missing or does not match the corresponding resource value,
the adapter does not create relationships. By setting this option to false,
you enable the adapter instance to find resources without using the
resource identifier columns.
Ths option applies only to vCenter Operations Manager 5.7.1 and later versions.
11
Select the credential to use to sign on to the data source from the Credential drop-down menu, or click
Add to add a new credential.
12
(Optional) Click Test to test the adapter instance.
13
Click OK to save your configuration.
Add a Credential
The Relationships adapter requires the user name and password of a user account that can read the database
that contains the source relationships table. You use this user name and password to create a credential for
the adapter instance in vCenter Operations Manager.
Prerequisites
Install the Relationships adapter. See Chapter 2, “Installing the Relationships Adapter,” on page 11.
Procedure
1
Log in to the Custom user interface as an administrator.
2
Select Environment > Configuration > Credentials.
3
Select Relationship Adapter from the Adapter Kind drop-down menu.
4
Select Relationship Adapter Credentials from the Credential Kind drop-down menu.
5
At the top of the list of credentials, next to Action, click Add.
6
Type a unique name for the credential instance in the Instance name text box.
7
Type the user name and password combination in the User name and Password text boxes.
8
Click OK to add the credential for the adapter kind.
The credential appears in the list in the Manage Credentials window.
VMware, Inc.
21
Relationships Adapter Installation and Configuration Guide
Modifying Database Connection Properties
The db.properties file in the conf folder contains database connection properties for the Relationships
adapter. You can modify these properties to customize adapter operation.
NOTE In a vApp installation, you modify the db.properties file on the Analytics virtual machine.
Table 3‑4. db.properties File Properties
Property
Description
Default Value
defaultAutoCommit
Sets the default auto-commit state of connections
that the connection pool creates.
true
maxActive
Defines the maximum number of active
connections that can be allocated at the same time
from the pool.
20
initialSize
Initial number of connections that the adapter
creates when the pool starts.
5
minIdle
Minimum number of connections that can remain
idle in the pool without creating extra
connections.
1
maxIdle
Maximum number of connections that can
remain idle in the pool without releasing extra
connections.
20
poolPreparedStatements
Enables or disables prepared statement pooling
for the pool.
false
maxOpenPreparedStatements
Maximum number of open statements that the
adapter can allocate at the same time from the
statement pool. A zero (0) value means there is no
limit.
0
maxWait
Maximum number of milliseconds that the pool
waits before it throws an exception when no
connections are available.
3000
PostgreSql_Driver
Defines the JDBC driver for the PostgreSql
database.
org.postgresql.Driver
PostgreSql_URL
Defines the URL for the PostgreSql database. The
variables correspond to the values for the adapter
instance.
jdbc\:postgresql\://host\:port/db
name
MsSql_Driver
Defines the JDBC driver for the MySql database.
com.microsoft.sqlserver.jdbc.SQLS
erverDriver
MsSql_URL
Defines the URL for the MySql database. The
variables correspond to the values for the adapter
instance.
jdbc\:sqlserver\://host\:port;Dat
abaseName\=dbname
MySql_Driver
Defines the JDBC driver for the MySql database.
com.mysql.jdbc.Driver
MySql_URL
Defines the URL for the MySql database. The
variables correspond to the values for the adapter
instance.
jdbc\:mysql\://host\:port/dbname
Oracle_Driver
Defines the JDBC driver for the Oracle database.
oracle.jdbc.driver.OracleDriver
Oracle_URL
Defines the URL for the Oracle database. The
variables correspond to the values for the adapter
instance.
jdbc\:oracle\:thin\:@host\:port\:
dbname
22
VMware, Inc.
Chapter 3 Configuring the Relationships Adapter
Modifying Adapter Properties
In vCenter Operations Manager 5.6 and later releases, the conf folder contains the
relationships.properties file. You can modify properties in this file to customize adapter operation.
NOTE In a vApp installation, you modify the relationships.properties file on the Analytics virtual
machine.
Table 3‑5. relationships.properties File Properties
Property
Description
Default Value
COLLECT_STATUS_NOTIFICATION_ENABLED
When you point to the collection status of a Relationships
adapter instance on the Environment Overview page in the
Custom user interface, a message can appear after the
collection status in the pop-up dialog box. This property
determines whether vCenter Operations Manager generates
notification events for the problems that these messages
describe.
false
MULTIPLE_RELATIONSHIPS_ENABLED
The Relationships adapter examines this property only if
the Use Identifiers option is set to false for the adapter
instance.
When this property is set to true, the Relationships adapter
creates multiple relationships if it discovers more than one
resource when it looks for parent or child resources that
have a given adapter kind, resource kind, and resource
name combination.
For example, if a parent resource lookup returns PR1 and
PR2 and a child resource lookup returns CR1, CR2, and
CR3, the adapter creates the following parent-child
relationships:
n PR1-CR1
n PR1-CR2
n PR1-CR3
n PR2-CR1
n PR2-CR2
n PR2-CR3
When this property is set to false (the default value), the
Relationships adapter logs an error if it discovers more than
one resource for a given adapter kind, resource kind, and
resource name combination.
This option applies to vCenter Operations Manager 5.7.1
and later versions only.
false
CACHE_UPDATE_INTERVAL
The Relationships adapter examines this property only if
the Use Identifiers option is set to false for the adapter
instance.
Specifies the time interval, in hours, to recall resource
lookups by adapter kind, resource kind, and resource name
combination.
This option applies to vCenter Operations Manager 5.7.1
and later versions only.
1
VMware, Inc.
23
Relationships Adapter Installation and Configuration Guide
Validate the Relationships in vCenter Operations Manager Enterprise
After you create an adapter instance for the Relationships adapter, use vCenter Operations Manager to
verify that the adapter updates resource relationships correctly.
Prerequisites
Add an adapter instance. See “Add an Adapter Instance,” on page 19.
Procedure
1
Log in to the Custom user interface as an administrator.
2
Select Environment > Advanced > Resource Relationship.
3
In the Parent Selection pane, select one of the parent resources that you defined in the source
relationships table.
4
Verify that the parent resource shows all of the child resources that you defined in the source
relationships table.
Example: Source Relationships Table and Resource Relationships
This example shows three records in a source relationships table. The table defines parent-child
relationships between a container resource named RelTestContainer and three child resources named
terazilla2.integrien.com, 000190300072_09, and qalabvm-107.
Figure 3‑1. Source Relationships Table Example
This example shows how these relationships appear in the user interface after the Relationships adapter
reads the source relationships table.
Figure 3‑2. Resource Relationship Page Example
24
VMware, Inc.
Chapter 3 Configuring the Relationships Adapter
What to do next
If the resource relationships are not updated as you expect, see “Adapter Does Not Update Relationships,”
on page 30.
VMware, Inc.
25
Relationships Adapter Installation and Configuration Guide
26
VMware, Inc.
Troubleshooting the Relationships
Adapter
4
Known troubleshooting information can help you diagnose and resolve problems with the Relationships
adapter.
This chapter includes the following topics:
n
“Troubleshooting a Relationships Adapter Instance,” on page 27
n
“View Collection Information,” on page 27
n
“Viewing System Log Files,” on page 29
n
“Adapter Cannot Connect to the Source Relationships Table,” on page 30
n
“Adapter Does Not Update Relationships,” on page 30
Troubleshooting a Relationships Adapter Instance
Perform these general troubleshooting steps to diagnose and correct problems with a Relationships adapter
instance.
1
View the collection status and collection state for the adapter instance resource in Custom user
interface. See “View Collection Information,” on page 27.
2
Check the adapter and collector logs for errors. See “Viewing System Log Files,” on page 29.
View Collection Information
You can view collection information for a Relationships adapter instance in the Custom user interface. This
information can help you diagnose and troubleshoot adapter problems.
Prerequisites
Become familiar with the collection states and status values. See “Collection States,” on page 28 and
“Collection Status Values,” on page 29.
Procedure
1
Log in to the Custom user interface as an administrator.
2
Select Environment > Environment Overview and find the Relationships adapter instance resource on
the List tab.
3
Point to the icon in the Collection State column to see whether vCenter Operations Manager should be
collecting data through the adapter instance.
The collection state appears in a pop-up window. If the adapter instance is set to collect data, the
collection state is Collecting.
VMware, Inc.
27
Relationships Adapter Installation and Configuration Guide
4
(Optional) If you have vCenter Operations Manager 5.6 or later, click the icon in the Collection State
column to see detailed information about the collection state.
5
Point to the icon in the Collection Status column to see whether vCenter Operations Manager is
receiving data through the adapter instance.
The collection status and a collection status message appear in a pop-up window. If
vCenter Operations Manager is receiving data through the adapter instance, the collection status is Data
Receiving.
In vCenter Operations Manager 5.6 and later, the Relationships adapter can generate an additional
message in the pop-up window. For example, if the adapter determines that a container resource that it
discovered in a previous collection cycle does not exist, the message Auto Discovered Resources Are
Not Created appears after the collection status. You might need to refresh the page to see the latest
status and message. For more detailed information, see the adapter log file.
Collection States
The resource collection state indicates whether vCenter Operations Manager should be collecting data for
the resource.
The resource collection state appears in a pop-up window when you point to an icon in the Collection State
column in the resource list on the Environment Overview page. If vCenter Operations Manager collects data
for a resource through more than one adapter instance, a separate icon appears for each adapter instance.
Table 4‑1. Collection States
State
Description
Collecting
Resource is set to collect data.
Not Collecting
Resource is set to not collect data.
Starting
Collection is starting.
Stopping
Collection is stopping.
Updating
Resource is being updated.
Failed
Resource configuration problem.
In Maintenance
Resource is in scheduled maintenance.
In Maintenance (Manual)
Resource is in manual maintenance.
Removing
Resource is being deleted.
If you click an icon in the Collection State column, detailed information appears in a pop-up window.
Table 4‑2. Detailed Collection State Information
28
Field
Description
Adapter Instance
Name of the adapter instance.
Collector
Name of the collector that the adapter instance uses.
Last Heartbeat
Amount of time since vCenter Operations Manager received a heartbeat message
from the adapter. A long period of time might indicate a connection problem.
Status
Status message from the collector.
Last Collection Time
Amount of time since the end of the last collection cycle and the number of metrics
that the adapter collected during that cycle.
Last Collection Duration
Length of time of the last collection cycle.
Metric Sparklines
Graphical representations of the last collection cycle duration and the number of
metrics and resources that the adapter collected during that cycle.
VMware, Inc.
Chapter 4 Troubleshooting the Relationships Adapter
Collection Status Values
The collection status value for a resource indicates whether vCenter Operations Manager is receiving data
for the resource. Collection status values appear in a pop-up window when you point to an icon in the
Collection Status column in the resource list on the Environment Overview page.
If vCenter Operations Manager collects metrics for a resource through more than one adapter instance, a
separate icon appears for each adapter instance in the Collection Status column.
A resource has a status value only if its collection state is Collecting. For information about collection states,
see “Collection States,” on page 28.
Table 4‑3. Collection Status Values
Status
Description
Data Receiving
vCenter Operations Manager is receiving data for the resource.
Old Data Receiving
Data is not current. The most recent value is at least five monitoring cycles old.
No Data Receiving
Adapter instance is collecting data, but vCenter Operations Manager has not received data for
the resource.
None
vCenter Operations Manager or collection was recently started and no data has been received
for five monitoring cycles.
Error
An error occurred when vCenter Operations Manager attempted to collect data for the resource.
Unknown
Status of the resource is not known because the adapter instance cannot connect to the resource.
Resource Down
Resource is not operational.
No parent resource
monitoring
Adapter instance resource is stopped.
Collection down
Collector or adapter instance is not operational.
NOTE Some adapter instances write customized status and messages. These messages typically provide
more information about data collection problems.
Viewing System Log Files
The Relationships adapter logs errors in the vCenter Operations Manager adapter and collector log files.
You can view the adapter and collector log files in the Custom user interface or in an external log viewer.
The Relationships adapter log files are in the vcenter-ops/user/log/adapters/RelationshipsAdapter folder.
The collector log files are in the vcenter-ops/user/log folder.
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.
You can set the logging level per class in the log4j.properties file in the vcenter-ops/log/conf/collector
folder, for example:
log4j.logger.com.integrien.adapter3.relationship.RelationshipProcessor=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.
29
Relationships Adapter Installation and Configuration Guide
Relationships Adapter Classes
The Relationships adapter uses certain adapter classes.
n
com.integrien.adapter3.relationship.RelationshipsAdapter
n
com.integrien.adapter3.relationship.RelationshipsConstants
n
com.integrien.adapter3.relationship.RelationshipProcessor
n
com.integrien.adapter3.relationship.properties.RelationshipsProperties
n
com.integrien.adapter3.relationship.objects.DBQuery
n
com.integrien.adapter3.relationship.exceptions.RelationshipsException
n
com.integrien.adapter3.relationship.dbaccess.DBConnectionManager
These adapter classes are only in vCenter Operations Manager 5.6 and later:
n
com.integrien.adapter3.relationship.objects.AdapterSpecificAttributes
n
com.integrien.adapter3.relationship.objects.CollectStatusNotificationEvent
Adapter Cannot Connect to the Source Relationships Table
A Relationships adapter instance cannot connect to the source relationships table.
Problem
vCenter Operations Manager returns an error when you click Test on the Add Adapter Instance window.
Cause
The adapter instance is misconfigured or the data in the source relationships table is not properly formed.
Solution
1
Verify that the adapter instance is configured to access the correct database.
2
Verify that the SELECT statement in the relationships SQL file matches the field names in the source
relationships table.
3
Verify that the fields in the source relationships table are large enough to hold the data.
4
Check the data in the source relationships table.
a
Verify that the required keys are present.
For example, AdapterKind and ResourceKind keys should be present for parent and child
resources.
b
If a resource has identifiers, verify that the identifiers are formatted correctly.
Resource identifiers must be in the format Key1=Val1;Key2=Val2;Key3-Val3, and so on.
5
Check the log files in the vcenter-ops/user/log/adapters/RelationshipsAdapter folder.
Adapter Does Not Update Relationships
Resource relationships are not updated in the vCenter Operations Manager user interface.
Problem
The resource relationships in the user interface are not as you expect.
30
VMware, Inc.
Chapter 4 Troubleshooting the Relationships Adapter
Cause
The allParents.txt file does not exist or the query statement in the relationships SQL file was changed. The
allParents.txt file keeps track of all parent resources that have relationships that the adapter instance
creates.
Solution
1
Verify that the allParents.txt file is in the work folder.
2
If the allParents.txt file is in the work folder, verify the query statement in the relationships SQL file.
3
If the allParents.txt file is missing from the work folder, restart the vCenter Operations Manager
Server service.
The allParents.txt file should appear in the work folder after the service restarts.
VMware, Inc.
31
Relationships Adapter Installation and Configuration Guide
32
VMware, Inc.
Index
A
U
adapter instances 19
adapter classes 30
adapter operation 9
audience information 5
updated information 7
V
validating resource relationships 24
C
collection information 27
collection states 28
collection status values 29
configuration steps 15
credentials 21
D
database connection problems 30
db.properties file 22
I
installing the adapter 11, 12
introduction 9
K
keys 18
L
log files 29
M
metrics, instance specific 9
R
relationship SQL file 19
relationship update problems 30
relationships_adapter3 folder 13
relationships.properties file 23
S
schemas 18
source relationships table 16, 17
system requirements 10
T
troubleshooting steps 27
VMware, Inc.
33
Relationships Adapter Installation and Configuration Guide
34
VMware, Inc.