Monday Apr 29, 2013

Creating a generic service with emcli ( Oracle Enterprise Manager Command Line Interface )

This blog walks you through the steps to create an Enterprise Manager Cloud Control 12c generic service using the command line API emcli.  At the end of the walk through you will have created a service consisting of;
  • A Host, an Oracle Fusion Middleware Farm, a Database and a Listener
  • HTTP and JDBC Service Test

  • System based performance and usage metrics

  • Service based performance metrics

The following emcli verbs will be used during the exercise;

For this exercise we need to create an XML file consisting of the service test definitions and substitution variables.  The documentation for the create_service verb implies that we can specify separate files in the -input_file parameter, one for the tests and one for the variables; however the documentation is wrong and this is being addressed by (Bug 16329952).

The XML schema definition transaction-template.xsd, contains the definition for both variables and template files, however we recommend that you create a template from an existing service definition using the UI and then use the emcli verb extract_template_tests command to extract a pre-existing template, however if you are comfortable with XML file creation then you can review the examples template.xml and variables.xml.

Creating a template from an existing service definition

Using the UI navigate to Enterprise > Monitoring > Monitoring Templates

Click on the Create button

Click on Target for the Copy Monitoring Settings using option button and enter the name of an existing service that you want to copy and then click Continue.

In the next screen provide the Name of the template and click OK; this will accept the defaults that were provided from the target being copied.

Extract the service test definition from the template using emcli.

emcli extract_template_tests \
    -templateName="myTemplate" \
    -templateType=generic_service \

At this point you need to edit the file myTemplate.xml and ensure that you have the correct values for the substitution variables at the top of the file.

   <variable name="HOST1" value=""/>
   <variable name="PASSWORD1" value="thepassword"/>
   <variable name="PORT1" value="7799"/>
   <variable name="PROTOCOL1" value="http"/>

Create the System and Service definition

Now we can start by creating the system definition.

emcli create_system \
    -name="mySystem" \
    -add_members="EMGC_GCDomain:oracle_ias_farm" \
    -add_members="" \
    -add_members="" \
    -add_members="" \
    -timezone_region="PST8PDT" \

Before we can create the service we must first ensure that we have a beacon to replay the tests.  Create a beacon on an existing agent.

emcli add_target \
    -name="myBeacon" \
    -type="oracle_beacon" \

Now we are ready to create the service.

emcli create_service \
    -name="myService" \
    -type="generic_service" \
    -availType="test" \
    -availOp="or" \
    -timezone_region="PST8PDT" \
    -systemname="mySystem" \
    -systemtype="generic_system" \
    -input_file=template:"/u01/app/oracle/home/myTemplate.xml" \
    -beacons="myBeacon:Y" \

NOTE: Although -timezone_region is optional if it is not specified then the availability computation of the targets will fail and the service and its tests will always show status pending.  Therefore you MUST specify the timezone_region parameter (Bug 16344350).

Additionally if you try to create a service with a name that has been used before it will fail with the error;

Oracle Error :ORA-20233: Target with guid CB9DED6762A117EC708709489C883230 does not exist

This is fixed by Patch 10096491.

We can now create a bunch of Usage and Performance metrics for the service definition that we can alert on.  The key to these metrics is the MGMT$METRIC_COLLECTION view, from this view you will use the METRIC_NAME and METRIC_COLUMN field for the metric definitions for each target type. First we will create the Usage metrics which can only be based on the system definition and not the service.

Let’s add a Usage metric based on the Active HTTP Requests across all targets on the system definition.

emcli set_metric_promotion \
    -name="myService" \
    -type="generic_service" \
    -category=Usage \
    -basedOn=system \
    -aggFunction=AVG \
    -promotedMetricKey="Active HTTP Requests" \
    -metricName="ohs_server" \
    -column="" \
    -depTargetType="oracle_apache" \
    -depTargets="/EMGC_GCDomain/instance1/ohs1" \
    -threshold="125;100;GT" \

Now one for the Average Active Sessions for the database targets in the system.

emcli set_metric_promotion \
    -name="myService" \
    -type="generic_service" \
    -category=Usage \
    -basedOn=system \
    -aggFunction=AVG \
    -promotedMetricKey="Average Active Sessions" \
    -metricName="instance_throughput" \
    -column="avg_active_sessions" \
    -depTargetType="oracle_database" \
    -depTargets="" \
    -threshold="150;125;GT" \

Next the Performance metrics, the first one based on the system definition for CPU Utilization (%).

emcli set_metric_promotion \
    -name="myService" \
    -type="generic_service" \
    -category=Performance \
    -basedOn=system \
    -aggFunction=AVG \
    -depTargetType="host" \
    -depTargets="" \
    -metricName="Load" \
    -column="cpuUtil" \
    -promotedMetricKey="CPU Utilization (%)" \
    -threshold="80;70;GE" \

The second based on the Total Time (ms) for the JDBC test

emcli set_metric_promotion \
    -name="myService" \
    -type="generic_service" \
    -category=Performance \
    -basedOn=test \
    -aggFunction=AVG \
    -testname="Database Login" \
    -testtype="JDBC" \
    -beacons="myBeacon" \
    -promotedMetricKey="Total Time (ms)" \
    -column="total_time" \
    -metricName="jdbc_response" \
    -metricLevel=TXN \
    -threshold="200;100;GT" \

The third based on the Perceived Total Time (ms) for the Homepage test

emcli set_metric_promotion \
    -name="myService" \
    -type="generic_service" \
    -category=Performance \
    -basedOn=test \
    -aggFunction=AVG \
    -testname="Homepage" \
    -testtype="HTTP" \
    -beacons="myBeacon" \
    -promotedMetricKey="Perceived Total Time (ms)" \
    -column="avg_response_time" \
    -metricName="http_response" \
    -metricLevel=TXN \
    -threshold="12000;6000;GT" \

At this point the Service homepage in Cloud Control looks like;

You will notice it does not show a chart, the metrics do not appear however if you navigate to Usage or Performance metrics page and click OK the metrics appear on the chart and you have to do this for both Usage and Performance.


Latest information on Oracle Enterprise Manager and Oracle Management Cloud.

Related Blogs


« July 2016