Oracle® Enterprise Manager Cloud Control Extensibility Programmer's Guide 12c Release 2 (12.1.0.2) Part Number E25159-04 |
|
|
PDF · Mobi · ePub |
This chapter contains the following sections:
A plug-in is a group of files (such as target definition files, collection scripts to collect metrics from targets, and any custom UI components to customize user interfaces) that has been added to a plug-in archive using the Enterprise Manager Extensibility Development Kit (EDK). The plug-in files must be added to an archive before they become a plug-in officially. A plug-in archive file (*.opar) associates the files together as an official plug-in.
Each plug-in defines a new type or types of target that can be monitored by Enterprise Manager. A target, or more specifically, a target instance, can be defined as any entity that can be monitored within an enterprise. This entity can be an application running on a server, the server itself, the network, or any of its constituent parts.
Enterprise Manager makes managing target instances simple by enabling you to add new target instances to the management framework from the Enterprise Manager console. Then you can take advantage of Enterprise Manager's monitoring and administrative features.
A plug-in consists of several types of files that serve specific functions at different tiers within the Enterprise Manager framework. For example, the target type metadata file is an integral part of defining a new target type. The EDK requires the target type metadata file, in addition to a default collection file, to create a new plug-in within the plug-in archive.
To create a new plug-in, you must have the following (minimum requirement):
When you use plug-ins to define custom target types for monitoring by Enterprise Manager, you can centralize all of your management information in the console.
When you introduce a new target type to Cloud Control, the management features included in Enterprise Manager are automatically supported for the new targets by default. This includes core management features such as:
You can also choose to enable additional management features for your target types by using application programming interfaces (APIs) supported by the EDK. These features include:
Each of these management features requires additional metadata files, and possibly the creation of scripts, that must be packaged with the plug-in.
This section describes the new features of Enterprise Manager plug-ins:
Extensibility Development Kit (EDK)
This release provides an EDK to support the development of custom plug-ins for managing target types not supported out of the box.
Plug-in and Connector Lifecycle Management
The Self Update feature provides a user-friendly mechanism for downloading and deploying metadata plug-ins and connectors. A console for managing the lifecycle of plug-ins has also been provided, enabling standardized management of different plug-in types and simplified deployment of plug-ins to Oracle Management Server and Management Agents.
A key component of the Enterprise Manager Cloud Control architecture is the Extensibility framework. To enable Oracle partners to extend the Enterprise Manager platform, an Extensibility Development Kit (EDK) is provided with the product.
The EDK is a collection of tools, utilities, and documentation, including:
Enterprise Manager Extensibility documentation: Provides general guidelines for programming Enterprise Manager plug-ins
Reference Implementation: Provides a reference code implementation, code snippets, and so on for various Enterprise Manager features
Build time tools to verify EDK conformance: A tool that you can use to validate and report any violations, with respect to Enterprise Manager Extensibility guidelines
Packaging Tool: A tool to package the plug-in components tool (empdk
)
Verification Tool: A tool to validate plug-in code components and to report violations (if any).
The EDK includes a command line utility called empdk
. Use this utility to package or validate a plug-in archive. For information about the empdk
commands and their options, see the Oracle Enterprise Manager Extensibility Programmer's Reference.
After you download the EDK, unpackage it on your local system, and change your current directory to the location where you unpacked the EDK. The EDK contains reference documentation and guides to help you with plug-in development as well as the API reference you might need to integrate while developing plug-ins.
For information about downloading the EDK, see Section 2.4, "Installing the Extensibility Development Kit (EDK)".
The EDK archive contains the following directories:
\bin
Contains the empdk
utility, which you use to:
Validate the structure of your plug-in
Package your plug-in
Convert the metadata for existing (pre-Cloud Control 12) plug-ins to the new metadata formats
\doc
Contains the Oracle Enterprise Manager Extensibility Programmer's Guide and Programmer's Reference, as well as the EDK API Reference documentation, including documentation on Management Views. Review overview.html for links to the documentation provided.
You can also access the EDK API Reference documentation directly through its index page (sdk_api_ref.html).
\lib
Contains internal libraries used by the EDK.
\oui
Contains internal libraries used by the EDK.
\samples
Contains a complete reference implementation of a plug-in, packaged as demo_hostsample.zip. The sample metadata files included should be used as examples of the files referenced throughout the EDK documentation.
View the README packaged with the archive for instructions on building, deploying, and using the sample plug-in.
Other utilities referenced in this documentation, including EM CLI and EMCTL, are installed with Enterprise Manager and are typically deployed to the Oracle Management Service (OMS) host.
Note:
Before installing the EDK, you must have the following:Latest version of the EDK ZIP archive from the Self Update console. (To access the Self Update console, from the Cloud Control console, select Setup, then Extensibility, and then Self Update.)
Java version 1.6.0_24 or later
Local system running Solaris, Linux, HP-UX, AIX, or Windows with New Technology File System (NTFS)
To install the EDK:
Download the EDK ZIP archive to your local system using one of the following options:
Using the Enterprise Manager Cloud Control console
Log in to Enterprise Manager Cloud Control.
From the Setup menu, select Extensibility, then select Development Kit.
The Extensibility Development Kit (EDK) page appears.
Under Installing the EDK, select Download the Extensibility Development Kit to your workstation.
Save 12.1.0.2.0_edk_partner.zip to your local system.
Using the Enterprise Manager Command Line Utility (EM CLI), open a command prompt and run the following command:
emcli get_ext_dev_kit
This command downloads the EDK ZIP archive to the same directory from where you ran the command and does not require any parameters.
Note:
For information about setting up EM CLI, see the Oracle Enterprise Manager Cloud Control Extensibility Reference Guide.Set your JAVA_HOME environment variable and ensure that it is part of your PATH. For example:
setenv JAVA_HOME /usr/local/packages/j2sdk1.6.0_24 setenv PATH $JAVA_HOME/bin:$PATH
Unpackage the downloaded EDK ZIP archive to a directory on your local system. For example:
Unzip 12.1.0.2.0_edk_partner.zip
This command creates the following directories under the directory (release_edk_partner) where you unpackaged the EDK ZIP archive:
release_edk_partner
|
bin
doc
lib
oui
samples
README
For more information about the directory contents, see Section 2.3.1, "Contents of the EDK".
Developing a plug-in involves:
Designing the set of entities to be included in the plug-in
Defining the metadata that describes them to Enterprise Manager
Packaging and delivering the plug-in so that users can deploy and use it in Enterprise Manager installations
Figure 2-1 depicts the lifecycle of a plug-in.
The plug-in lifecycle represents the transition of a plug-in through the following stages:
Publish: Publishes plug-in at Oracle Enterprise Manager Store
Download: Enterprise Manager Server downloads plug-ins from Oracle Enterprise Manager Store
Deploy: Deploys the plug-in to Oracle Management Service (OMS) and Management Agents
Upgrade: Upgrades the plug-in to a later version (download and deploy)
The first step in developing your plug-in is to design the contents of your plug-in. At the highest level, this includes deciding what set of target types will be included in the plug-in (a plug-in may include management metadata for one or more target types) and defining what set of management capabilities you want to support for each target type. (The complete available list is included in Section 2.6, "Plug-in Contents and Packaging").
Before creating plug-in files, you must define which parameters of the target type are required to monitor and manage your new component accurately. This involves:
Identifying performance and configuration metrics that should be collected.
Determining how often each metric should be collected. Oracle recommends that the collection frequency for any metric should not be less than once every five minutes.
Based on customer-specific operational practices, specifying default warnings and/or critical thresholds. Whenever a threshold is crossed, Enterprise Manager raises an incident, informing administrators of potential problems.
These metrics and collection settings are the required components of every plug-in. Additional capabilities such as job definitions, custom User Interface, and so on, are optional. Each feature to be included in the plug-in requires additional thought and design to determine what aspects of the target should be manageable for those features.
Some of the key features to consider when designing your plug-in include the following:
Administrative features that are necessary to manage the target, such as administrative tasks or larger, and more complex jobs that may require automation support (for example, scheduling)
Configuration data to be used for managing the target including associations between the target and other targets in network
Reports and customized user interfaces to be provided for end-users to manage the targets
This is not a complete list and the information for integrating with each subsystem is summarized in this guide and provided in detail in the Enterprise Manager Programmer's Reference.
The plug-in contents and packaging section includes the following topics:
Each plug-in includes the plug-in metadata, which is defined in XML files that represent all the information about a plug-in.
Plug-in metadata is used during plug-in deployment. It contains properties that identify the plug-in, such as name and version, and declares the set of target types that will be added to Enterprise Manager Cloud Control.
Most of the Enterprise Manager features exposed to you through the Enterprise Manager EDK require the construction of metadata files (in XML). These metadata files define the items that are integrated for that target type for the particular subsystem. For example, a plug-in might contain a metadata XML file that defines the job types that are available for that target type. After deployment, the jobs will be available to be submitted or executed for any instance of that target type.
Target type metadata consists of the metrics you want to expose and the methods used to retrieve and compute those metrics. The target type metadata file tells the Oracle Management Agent what data to retrieve and how to obtain that data for this particular target type.
In addition to the metrics to be collected for the target type, the target type metadata includes the target properties and credentials information. The target properties are the key set of properties that help to define the target. These properties are typically static though Enterprise Manager does support the ability to define dynamic instance properties that are evaluated by the Management Agent. For information about defining dynamic instance properties, refer to the Enterprise Manager Programmer's Reference.
The plug-in includes a default collections file, which defines the frequency at which metrics and configuration data will be collected
The Enterprise Manager Extensibility Framework provides the support for packaging these metadata files in the EDK as well as for deploying these files to the appropriate subsystem within Enterprise Manager. This may include deploying information to the Management Server, or to the Management Agent, or both in some cases. For more information about packaging metadata files in the EDK, see Section 2.6.3, "Plug-in Packaging Structure".
In certain instances, the metadata includes references to other components packaged with the plug-in. For example, a job type definition might include a step that executes a Perl script against one of the targets to perform an administrative task. In this case, the job type definition is declared in the metadata and included in the Management Server part of the plug-in while the script is included in the Management Agent part of the plug-in.
For a complete list of all metadata services available and the detailed documentation describing the use of each service, see the Enterprise Manager Programmer's Reference.
The final step in developing a plug-in is to package it into a plug-in archive. This step takes a staging directory (plugin_stage) as input where the files that comprise the plug-in are located. Example 2-1 summarizes the directory structure and the location for the files.
Example 2-1 Plug-in Directory Structure
plugin_stage/ | plugin.xml agent/ | plugin_registry.xml default_collection/ | target_type.xml metadata/ | target_type.xml scripts/ | scripts oms/ | metadata/ | default_collection/ | target_type.xml derivedAssoc/ | derivedAssoc_rule.xml discovery/ | discovery.xml gccompliance/ | compliance_rule.xml jobTypes/ | job_type.xml mpcui/ | mpcui.xml reports/ | report.xml snapshotlive/ | target-type_ecmdef.xml targetType/ | target_type.xml discovery/ | discovery scripts
For information about the contents of the plug-in directory, see the Enterprise Manager Programmer's Reference.
After you have packaged the plug-in, you can distribute the plug-in archive (OPAR) file to the Enterprise Manager administrators that require support for the target types included in that plug-in. In this mode, Oracle does not certify the quality or safety of the plug-in for use in a production environment and appropriate evaluation in a test environment is strongly encouraged before deploying a plug-in that is not certified by Oracle.
To make the plug-in available for deployment, the Enterprise Manager administrator must import the plug-in archive into the Enterprise Manager installation. After this is complete, the plug-in will be available to be deployed in the same way as any other plug-in downloaded from Oracle. For information the plug-in import command, see the Enterprise Manager Programmer's Reference.
After a plug-in has been imported into Enterprise Manager, the Enterprise Manager administrator must explicitly deploy the plug-in to the Management server and to the appropriate Management Agents.
Plug-in deployment can be accomplished through the Enterprise Manager command line facility (EM CLI) or by selecting Extensibility from the Setup menu in the Enterprise Manager console. For information about the use of these options, see the Enterprise Manager Programmer's Reference.
If a plug-in includes support for automated discovery, Enterprise Manager deploys the plug-in to the appropriate Management Agent automatically as targets are discovered and marked as manageable targets (promoted) in Enterprise Manager. To enable automated discovery, you must include the appropriate discovery metadata in the plug-in.
For plug-ins that do not include support for the automated discovery of targets, the Enterprise Manager administrator must add targets to the Enterprise Manager console manually, specifying the Management Agents where the targets are located. In this case, the Enterprise Manager administrator must deploy the plug-in to those Management Agents before manually adding the target.
As new versions of a plug-in are released, the Enterprise Manager administrator can import the new plug-in by using the self-update feature of Enterprise Manager to download the new version from the Oracle Store, or by importing the new plug-in archive if it is a private distribution.
At this point, the new plug-in version is available in Enterprise Manager but not deployed to any of the Management Servers or Agents. The Enterprise Manager administrator must explicitly deploy the new plug-in version using the same process for deployment described in Section 2.8, "Deploying a Plug-in".