1. Extensibility Programmer's Reference
  2. Defining Target Discovery

12 Defining Target Discovery

The discovery of targets in Enterprise Manager can be accomplished in several different ways including automated discovery scripts, manual addition of targets by specifying target properties, and manual addition of targets using guided discovery.

Automatic target discovery is the process by which targets are located and added to Enterprise Manager. Automatic discovery begins when the Oracle Management Agent starts up after installation. Targets located on the server where the Management Agent is running are discovered and sent to the Management Repository as targets that are not yet managed. The end user can choose which targets to monitor by promoting these targets as targets managed by Enterprise Manager.

This chapter contains the following sections:

Introduction to Defining Target Discovery

As a plug-in developer, you are responsible for the following steps within the discovery process:

  1. Create discovery metadata.

    Use the Discovery XML Schema Definition (XSD) for guidelines about creating a discovery metadata XML file.

    Within the metadata:

    • Define the discovery modules using the DiscoveryModule element.

    • Define discovery parameters (if required) using the DiscoveryInput element.

    For information about creating discovery metadata, see Creating Discovery XML.

  2. Create the discovery script using Perl.

    The discovery script enables the Management Agent to automatically discover all the target types belonging to a plug-in.

    For information about creating the discovery script, see Creating the Discovery Script.

  3. Identify additional Perl modules or JAR files that are required for discovery.

  4. Bundle the discovery metadata and contents into the plug-in staging directory (plugin_stage).

    1. Save the discovery XML in the plugin_stage/oms/metadata/discovery directory.

    2. Save the discovery content in the plugin_stage/discovery directory

    For information about packaging, see Packaging Discovery XML and Discovery Content.

  5. Repackage (if necessary) and deploy the plug-in.

    After the plug-in archive is created and the plug-in is deployed to the Management Server, the end user can initiate discovery using the discovery configuration UI for the discovery modules that are registered.

    For information about deploying the plug-in, see Validating, Packaging, and Deploying the Plug-in.

  6. Configure automatic discovery:

    1. Log in to Enterprise Manager.

    2. Select Setup, then select Add Target, and then select Configure Auto Discovery.

      The Configure Auto Discovery page appears.

    For more information about configuring automatic discovery, see Configuring Automatic Discovery For Plug-ins.

  7. Test discovery results.

    For information about testing discovery, see Setting Up and Testing Discovery.

Creating Discovery XML

Oracle provides a Discovery XSD so you can write discovery metadata XML to register with the discovery framework. Registering with discovery framework enables the discovery pages to launch discovery of the target types belonging to a plug-in.

For more information about the Discovery XSD, see the Extensibility Development Kit (EDK) specifications.

The following section and the Discovery Integration XML With Discovery Parameters example provide examples of discovery XML.

Generic Discovery Integration Example

In this example, discovery requires no information entered and promotion of the target does not require any special logic.

There are no special requirements for configuring the target except that you must have access to the UI.

The following example provides the discovery integration XML for this discovery.

Note:

You are not restricted on the naming of the discovery XML file. However, the standard convention is plugin_discovery.xml.

Example: Discovery Integration XML

<?xml version="1.0" encoding="UTF-8"?>
          <EmTargetDiscovery
               xmlns="http://www.oracle.com/EnterpriseGridControl/disc_metadata"
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xsi:schemaLocation="http://www.oracle.com/EnterpriseGridControl/disc_metadata discovery.xsd ">
               <DiscoveryInfo>
                     <AutomaticDiscovery>
                       <DiscoveryModule name="simple_disc_plugin" resourceBundlePkg="oracle.sysman.simpleplugin.rsc.simplePluinMsg">
              <Display NLSID="SIMPLE_DISC_MODULE">
                   <NlsValue>simple_disc_plugin</NlsValue>
              </Display>

                      <SupportedAgentOsList>
                          <SupportedAgentOs>2000</SupportedAgentOs>
                     </SupportedAgentOsList>
          <BasicDiscoveryInfo>
            <DiscoveryScript>SimplePluginDisc.pl</DiscoveryScript>
            <DiscoveryCategory>SIMPLE_PLUGIN_DISC</DiscoveryCategory>
          </BasicDiscoveryInfo>
                 <TypesDiscovered>
                     <TargetType>simple_plugin_target_type1</TargetType>
                     <TargetType>simple_plugin_target_type2</TargetType>
                 </TypesDiscovered>
       </DiscoveryModule>
      </AutomaticDiscovery>
     </DiscoveryInfo>
   </EmTargetDiscovery>

After the previous XML is registered, the discovery framework can launch discovery of simplePluginType using the SimplePluginDisc.pl discovery script.

Discovery Script Example

For example, you can have the following content in the SimplePluginDisc.pl script to discover two target instances:

#all the discovery scripts get emdRoot and hostname of the agent as arguments to the script.
my ($emdRoot, $hostName) = @ARGV;
#Discovery root is sent to the script as env variable.
my $discovery_root = $ENV{DISC_ROOT};
print "\<Targets\>\n";
print  "\<Target TYPE=\"simple_plugin_target_type1\" NAME=\"smpl_tgt1\"\>\n";
print  "\<Property  NAME=\"Prop1\"   VALUE=\"prop1_foo\"/\>\n";
print "     \<Property NAME=\"Prop2\" VALUE=\"prop2_value_bar\"/\>\n";
print "   \<\/Target\>\n";
print "  \<Target TYPE=\"simple_plugin_target_type2\" NAME=\"smpl_tgt2\"\>\n";
print "    \<Property  NAME=\"Prop1\"   VALUE=\"value_foo\"/\>\n";
print "     \<Property NAME=\"Prop2\" VALUE=\"value_bar\"/\>\n";
print "   \<\/Target\>\n";
print  "\<\/Targets\>\n";

This script produces the following output:

<Targets>
       <Target type ="simple_plugin_target_type1" NAME="smpl_tgt1" >
          <Property NAME="Prop1"  VALUE="prop1_foo" />
           <Property NAME="Prop2" VALUE="prop2_value_bar" />
        </Target>
       <Target type="simple_plugin_target_type2" NAME="smpl_tgt2" >
             <Property NAME="Prop1" VALUE="value_foo" />
             <Property  NAME="Prop2" VALUE="value_bar" />
       </Target>
 </Targets>

After your plug-in is deployed on the Management Server, the discovery module is listed in the Discovery UI. Users can configure discovery of this module on one or more Management Agents. This causes the discovery content of the plug-in to be deployed on the Management Agent and subsequently causing the discovery script to be run at the Management Agent.

For example, when you run this discovery script through autodiscovery, the targets will be generated and sent to the Management Server as Not Yet Managed targets. Using the Discovery Results UI, you can promote these two targets as managed targets by Enterprise Manager.

Note:

There are methods for writing debug information such as EMD_PERL_INFO, EMD_PERL_DEBUG, and EMD_PERL_ERROR, which can be accessed through the Perl package emdcommon.pm. You can then find the trace information (written through Perl methods) in the Oracle Management Agent trace file (emagent_perl.trc) in the Management Agent log directory.

Overview of the Discovery Metadata Elements

Table 12-1 describes the key elements that define the discovery metadata:

Table 12-1 Key Elements in a plugin_discovery.xml File

Element Description

EmTargetDiscovery

The root element for the file

DiscoveryInfo

Specifies one or more autodiscovery modules for this plug-in. Each auto discovery module is associated with a discovery script that is run on the Management Agent

AutomaticDiscovery

Specifies the autodiscovery module

DiscoveryModule

This is an element within the autodiscovery module. It includes the name attribute, which defines the name of the discovery module.

SupportedAgentOSList

Specifies the list of Management Agent platforms on which this discovery is supported. It includes the SupportedAgentOS attribute, which defines the platforms. The valid value is 2000 (All platforms).

BasicDiscoveryInfo

Specifies the discovery script to be run and an optional category name. It includes the following attributes:

  • DiscoveryScript: Defines the name of the discovery script

  • DiscoveryCategory: Defines the category name (optional)

TypesDiscovered

Specifies the list of target types that can be discovered using this discovery module. It includes the TargetType attribute, which defines the target type name.

DiscoveryInput

Specifies the information to be entered by the user during discovery. The information entered by the user is available as environment variables in the discovery script running at the Management Agent

Creating the Discovery Script

After the discovery XML is registered, the discovery framework uses a discovery script to launch discovery.

To create a discovery script:

  1. Use Perl to write the top-level discovery script. This script can call Java, Shell, and so on.

  2. By default, three variables are provided to the discovery Perl script:

    1. The discovery framework provides emdRoot and the host name of the Management Agent as arguments to the script:

      For example: 

      my ($emdRoot, $hostName) = @ARGV;

    2. The discovery root directory is sent to the script as an environment variable.

      For example:

      my $discovery_root = $ENV{DISC_ROOT};

    3. If there are discovery inputs, then they are made available as environment variables.

      For example: 

      my $crs_home = $ENV{‘CRS_HOME'};

Ideally, the output of the discovery script returns all the name-value pairs that are required to add a target of a target type. If not, the user must provide any remaining values at target promotion time.

The Sample Discovery Script example provides an example of a discovery Perl script.

Discovered Targets DTD

The discovery Perl script must produce output which conforms to the following Document Type Definition (DTD):

Example: Discovered Targets DTD

<!ELEMENT Targets (Target*) >
<!ATTLIST Targets
 >

<!--

     Target defines a target instance, it may also define Properties

     TYPE(required)      : the target type.
     NAME(required)      : the target name.  It must be unique within a type
                           across all nodes.

     DISPLAY_NAME(optional)      : the display name for a target.will be 
                                   defaulted to NAME if not given.
-->

<!ELEMENT Target (Property*) >
<!ATTLIST Target
           TYPE                CDATA #REQUIRED
           NAME                CDATA #REQUIRED
           DISPLAY_NAME        CDATA #IMPLIED
 >

<!--
     A Property tag describes a name-value pair of target instance properties

     NAME(required)      : the property name .
     VALUE(required)     : the property value.
-->
<!ELEMENT Property EMPTY>
<!ATTLIST Property
           NAME CDATA #REQUIRED
           VALUE CDATA #REQUIRED
 >

Packaging Discovery XML and Discovery Content

The following sections describe where to include the discovery XML and content in the plug-in staging directory.

Location of the Discovery Metadata File

When you complete the discovery metadata XML file, include the file in the following directory of the plug-in staging directory:

plugin_stage/oms/metadata/discovery

Package Discovery Content

Discovery content refers to all the Perl scripts, Perl modules, and JAR files (if any) that are required to perform discovery of a particular target type

For Enterprise Manager, discovery content is shipped to the Management Agent only when the user attempts discovery for the first time. Discovery content corresponding to a particular discovery module will reside in its own area.

Discovery and monitoring scripts are separate. Both are parts of your plug-in. You can run discovery without monitoring content. The lifecycle of both are managed by the discovery or plug-in lifecycle frameworks and is transparent to plug-in developers.

You must package the discovery content required for discovering a particular target type. For example, for an existing database discovery, the discovery content is oracledb.pl along with any required utilities for running database discovery.

Note:

You must package the discovery metadata file with the Oracle Management Server archive and not the Management Agent archive.

Create a discovery directory under plugin_stage for installing content for each discovery plug-in. For more information about the directories under plugin_stage, see Validating, Packaging, and Deploying the Plug-in.

Example: Directory Structure for Installing Discovery Content

plugin_stage/discovery/
                      |
                      |
                      |__other subdirectories created as you specified

For Oracle Database discovery, the discovery content might look similar to the following:

plugin_stage/discovery/
                       |
                       |
                       |___oracledb.pl
                           |
                           |
                           |__utl
                                 |
                                 |___oracledbUtl.pl
                                     |
                                     |___initParamFileUtl.pl
                                     |
                                     |___winRegistry.pl

If any custom Perl modules are required for the discovery process, then place the modules under a similar directory structure as shown previously. The discovery root variable provided to the discovery script can be used to load this Perl module. For example, if your perl modules are placed under the plugin_stage/discovery/utl/pm directory, then you can load them from the discovery script as follows: 

my ($emdRoot,$hostName,$crsHome) = @ARGV;
my $discovery_root = $ENV{DISC_ROOT};
require "$discovery_root/utl/pm/propertiesFileParser.pm";
require "$discovery_root/utl/pm/Targets.pm";

Note:

Perl content that will be used by the discovery module and for other purposes, such as administration of the targets, should be packaged with the discovery bundle as well as the plug-in bundle.

Java Content Required by Discovery Scripts

Some discovery scripts (such as for Oracle Fusion Middleware) use JAR files in the process of discovery. If the JAR files are discovery-specific only, then they should be in discovery area.

If there are Java methods written to perform discovery, then they should be moved to a separate class file where possible, to avoid shipping content not required by discovery.

Oracle recommends separating discovery content and management content so that discovery can be performed independent of the management content present. This helps you to decide whether you want to install the plug-in to manage the discovered targets, if any. The discovery content should be lightweight and include the files necessary for discovery only.

For example, you can place the JAR containing discovery-specific code of the particular discovery module under the following directory: 

plugin_stage/discovery/lib

Note:

The individual discovery script is responsible for constructing the class path.

You can create your own directory structure in the discovery content area for a particular discovery module. The top level Perl scripts responsible for each discovery module, such as Fusion Middleware, construct the class path before running the Java utilities that they use. Because the JAR files specific to a discovery module will be in their own discovery content area, the discovery Perl script can construct the required class path easily. Again, the code responsible for performing discovery only should be separated out and installed in the discovery content area specific to the particular discovery module.

Setting Up and Testing Discovery

For testing purposes, you can run discovery:

  1. Log in to Enterprise Manager.
    https://em_host:em_port/em/
  2. From the console, select Setup, then Add Target, and then Configure Auto Discovery.

    The Configure Auto Discovery page appears.

  3. In the Configure Auto Discovery tables, under Discovery Module, select Multiple Target-Type Discovery on Single Host.

    The Target Discovery (Agent Based) page appears.

  4. Select the required agent host name and click Run Discovery Now.

    When target discovery is complete, a Completed Successfully window appears.

Manually Adding Targets

In addition to automatic discovery, Enterprise Manager allows you to manually add hosts as well as a wide variety of Oracle software and components as managed targets. When you add a target manually, you do not need to go through the process of discovery by adding the target directly. Discovering targets in this way eliminates the need to consume resources on the agent to perform discovery when it is not needed.

You must be able to specify the properties of a target to be managed and create an Enterprise Manager managed target.

Not all target types can be manually added. During registration with the discovery framework, the target type owner indicates whether a target type can be manually added or not.

See the following sections for instructions:

Manually Adding Host Targets

A wizard guides you through the process of manually deploying a Management Agent to a new host target.

For instructions on installing a Management Agent, see "Installing Oracle Management Agent" in the Enterprise Manager Basic Installation Guide.

Manually Adding Non-Host Targets

A configuration page or wizard based on target type metadata listing all the instance properties required to manage target is displayed.

You can specify a name for the target and provide the required configuration information.

To add targets manually to Enterprise Manager:

  1. Log in into Enterprise Manager.
  2. From the Setup menu, select Add Target, then select Add Targets Manually.

    Enterprise Manager displays the Add Targets Manually page.

  3. Under the Add Targets Manually page, go to the Add Targets Manually sub-section and select one of the following options:

    • Add Non-Host Targets Using Guided Process

      From the Target Types list, select one of the target types to add, such as Oracle Cluster and High Availability Service, Oracle Database Machine, or WebLogic Domain Discovery, then click Add Using Guided Discovery. This process will also add related targets.

    • Add Non-Host Targets by Specifying Target Monitoring Properties

      From the Target Type list, select one of the target types to add, such as Fusion J2EE Application, Applications Utilities, or Supplier Portal, and from the Monitoring Agent list, select the required Monitoring Agent, then click Add Manually.

  4. After you select the target type, you will follow a wizard specific to the target type to add the target.

    Upon confirmation, the target becomes a managed target in Enterprise Manager. Enterprise Manager accepts the information, performs validation of the supplied data where possible and starts monitoring the target.

Configuring and Promoting Targets for Monitoring by Enterprise Manager

Discovery of targets on Enterprise Manager managed hosts provides you with a list of targets such as new databases, and SQL servers which are not yet managed by Enterprise Manager. This helps you to determine if any of the new targets found are candidates for monitoring and managing by Enterprise Manager.

The Enterprise Manager UI allows you to review discovered unmanaged targets and promote targets to be managed by Enterprise Manager for monitoring.

Examples for Using Generic Discovery Framework

You can use the generic discovery UI to launch and schedule discovery to run periodically at the Management Agent. For the generic discovery UI to launch discovery, you must specify the inputs that are required through the registration XML. Enterprise Manager uses this information to construct the generic discovery UI.

Discovery Integration Example Requiring User Input

In this example, discovery requires the user to enter information. The user is prompted to enter values for CRS_HOME and CRS_HOME1. The user does not have to enter a value for CRS_HOME but a value for CRS_HOME1 is mandatory

There are no special requirements for configuring the target except that you must have access to the UI.

Note:

While supported, Oracle does not recommend the use of required discovery inputs because it eliminates the benefits of automatic discovery. You can use optional discovery inputs as hints to optimize the discovery process.

Example: Discovery Integration XML With Discovery Parameters

<?xml version="1.0" encoding="UTF-8"?>
     <EmTargetDiscovery
        xmlns="http://www.oracle.com/EnterpriseGridControl/disc_metadata"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

        xsi:schemaLocation="http://www.oracle.com/EnterpriseGridControl/disc_metadata discovery.xsd ">
        <DiscoveryInfo>
             <AutomaticDiscovery>
                    <DiscoveryModule name="simple_disc_plugin" resourceBundlePkg="oracle.sysman.simpleplugin.rsc.simplePluinMsg">

              <Display NLSID="SIMPLE_DISC_MODULE_MSG_ID">
                  <NlsValue>simple_disc_plugin</NlsValue>
              </Display>
             <SupportedAgentOsList>
                    <SupportedAgentOs>2000</SupportedAgentOs>
             </SupportedAgentOsList>

             <BasicDiscoveryInfo>
            <DiscoveryScript>simple_plugin_disc.pl</DiscoveryScript>
            <DiscoveryCategory>SIMPLE_PLUGIN_DISC</DiscoveryCategory>
             </BasicDiscoveryInfo>
             <TypesDiscovered>
                    <TargetType>simple_plugin_target_type1</TargetType>
                    <TargetType>simple_plugin_target_type2</TargetType>
             </TypesDiscovered>

             <!-- optional discovery hint -->
             <DiscoveryInput name="CRS_HOME" isRequired="false">
             </DiscoveryInput>

             <!-- a required discovery input -->
             <DiscoveryInput name="CRS_HOME1" isRequired="true">
             </DiscoveryInput>

      </DiscoveryModule>
      </AutomaticDiscovery>
     </DiscoveryInfo>
   </EmTargetDiscovery>

After the previous XML is registered, the discovery framework can launch discovery using the simple_plugin_disc.pl discovery script

The simple_plugin_disc.pl script can access the discovery parameters as illustrated in the sample simple_plugin_disc.pl script.

Example: Sample Discovery Script

my $discovery_root = $ENV{DISC_ROOT};

#Inputs passed to the script.
my $crs_home = $ENV{'CRS_HOME'};
my $crs_home1 = $ENV{'CRS_HOME1'};

#add the logic here to find the targets.

print "\<Targets\>\n";
print " \<Target TYPE=\"simple_plugin_target_type1\" NAME=\"smpl_tgt1\"\>\n";
print "   \<Property  NAME=\"Prop1\"  VALUE=\"prop1_foo\"/\>\n";
print "     \<Property NAME=\"Prop2\" VALUE=\"prop2_value_bar\"/\>\n";
print "   \<\/Target\>\n";
print "  \<Target TYPE=\"simple_plugin_target_type2\" NAME=\"smpl_tgt2\"\>\n";
print "   \<Property  NAME=\"Prop1\"  VALUE=\"value_foo\"/\>\n";
print "     \<Property NAME=\"Prop2\" VALUE=\"value_bar\"/\>\n";
print "   \<\/Target\>\n";
print  "\<\/Targets\>\n";

Note:

For guidelines about the output of the discovery Perl script, see Discovered Targets DTD.

Configuring Automatic Discovery For Plug-ins

You can configure automatic discovery for targets in a plug-in to run at the Management Agent-side. Currently, automatic discovery is scheduled to run every day.

Configuration is done from the Oracle Management Server where your metadata resides.

Note:

For plug-ins deployed before the Management Agents are installed or plug-ins deployed to new hosts, discovery runs every 24 hours automatically (only if discovery does not require any user inputs).

You can configure parameters from the Enterprise Manager UI after the Management Agents are installed or deployed.

After discovery, the targets are sent to Enterprise Manager. The end user can then review the targets and choose which targets to monitor by promoting the targets as targets managed by Enterprise Manager.