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 \
    -output_file=myTemplate.xml

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.

<variables>
   <variable name="HOST1" value="myserver.company.com"/>
   <variable name="PASSWORD1" value="thepassword"/>
   <variable name="PORT1" value="7799"/>
   <variable name="PROTOCOL1" value="http"/>
</variables>

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="emrep.company.com:oracle_database:key_member" \
    -add_members="LISTENER_myserver.company.com:oracle_listener:key_member" \
    -add_members="myserver.company.com:host:key_member" \
    -timezone_region="PST8PDT" \
    -availabilty_type="ALL"

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" \
    -host="myserver.company.com"

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" \
    -keycomponents="emrep.company.com:oracle_database"

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="request.active" \
    -depTargetType="oracle_apache" \
    -depTargets="/EMGC_GCDomain/instance1/ohs1" \
    -threshold="125;100;GT" \
    -mode=CREATE

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="emrep.company.com" \
    -threshold="150;125;GT" \
    -mode=CREATE

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="myserver.company.com" \
    -metricName="Load" \
    -column="cpuUtil" \
    -promotedMetricKey="CPU Utilization (%)" \
    -threshold="80;70;GE" \
    -mode=CREATE

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" \
    -mode=CREATE

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" \
    -mode=CREATE

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.


Comments:

Jeff, This is a great post.
Can you explain how the availability percentage in the final screen is calculated. Typically you would need to define windows of availability (Days of the week, Times of day) and whether planned blackouts count as up or downtime in the calculation. In 10g/11g we had to perform row updates to tables as the emcli code wasn't comprehensive enough... Is this still the case (does another ER need to be raised?)
Liking the fact you tried to use the products emcli offering and felt the pain of the number of bugs encountered. I really hope the community get to grips with emcli as a batch api offering and demand it be continually improved to provide a reliable interface that cloud capabilities can adopt with confidence.

Posted by guest on April 29, 2013 at 03:37 PM PDT #

MOS note 417700.1 Overview of service level reporting in Enterprise Manager does a good job of explaining the features for SLAs'.

In Enterprise Manager Cloud Control 12c the emcli APIs have been improved to include a number of verbs for SLA reporting which include;

compare_sla -- Compare two SLA template XML files
delete_sla -- Delete one or more SLAs
disable_sla -- Disable a SLA
enable_sla -- Enable a SLA
export_sla -- Extract a SLA as XML
import_sla -- Import a SLA from XML
list_sla -- List the summary of one or more SLAs

Take a look at the Services vers in the documentation http://docs.oracle.com/cd/E24628_01/em.121/e17786/cli_verb_ref.htm#CACBEIGC

Posted by Jeff Barber on April 30, 2013 at 03:01 AM PDT #

Amazing tutorial. I have been using this for a lot of new automation for our systems. The question I have is this: Is it possible to use the emcli create_service verb to pass in parameters to the xml templates? So in my use case, the templates I created for the creation of the generic services are all unique. They are using HTTP Pings to different host names and ports. Each generic service has a unique port or host name. So, I had to create a template for each generic service. Would it be possible to have a single template for all of them, and then just pass in parameters to this template to override the specific values? That would save me a lot of time and space for files. Thank you again for your information.

Posted by Guinea on August 30, 2013 at 07:13 AM PDT #

The create_service verb takes the parameter -input_file. This parameter can be overloaded as follows;

-input_file=template:"/u01/app/oracle/home/myTemplate.xml"
-input_file=variables:"/u01/app/oracle/home/myVariables.xml"

So in your situation you can split out the main template and the substitution variables into two different files.

Posted by Jeff Barber on September 03, 2013 at 01:05 AM PDT #

That looks good and all, but I might be a little confused on the implementation. Wouldn't I still need a separate file for each set of variables for each generic service? Let's say I want to deploy a generic service for each host I have. I would create the generic service, pass in the template and then pass in the variables. Then for the next host, I would pass in the same template, but would have to generate a new file with the next host variables. Is that correct? That isn't any more efficient than the way I am doing it now; unless I can specify the host variable FROM the file when I create the service. variables:/opt/myVariables.xml;HOST4' something like that?

Posted by Guinea on September 09, 2013 at 06:51 AM PDT #

Your assumptions are correct, you would indeed need a separate variables file for each host, I will raise an enhancement request to cover this use case.

Posted by Jeff Barber on September 09, 2013 at 07:26 AM PDT #

Ok this is a strange circumstance but is there an escape character or work around to avoid the ';' separation in the -depTargetKeyValues parameter for the set_metric_promotion verb? My key value pair has a ; in it and I don't have a way to get it out of the name. So my parameter looks like this:

-depTargetKeyValues="Name1:Value1;Value2 | Name2:Value1;Value2"

Value1;Value2 is a single value for the Name pair. But emcli is treating the ; as a separator and cutting it off, causing it to fail. Is there a way to correct this syntactically?

Posted by Guinea on January 28, 2014 at 01:00 PM PST #

Is there a way to escape the ; within the parameters for set_metric_promotion? My value for the name:value pairs has a ; incorporated in it by default. It is not changeable, so my only option to get this value into the set_metric_promotion would be to find a way to escape the ; character within the name. Or change the delimiter for the parameter? The parameter is the depTargetKeyValues parameter.

Posted by Guinea on January 28, 2014 at 01:29 PM PST #

You can use the separator and sub-separator options (http://docs.oracle.com/cd/E24628_01/em.121/e17786/cli_verb_ref.htm#autoId1) to change the characters used, but as it says in the documentation this has not been implemented for all verbs. If you have tried it and it does not work then you will need to raise a Service Request and work the issue with support.

Posted by Jeff Barber on February 04, 2014 at 09:10 AM PST #

Post a Comment:
  • HTML Syntax: NOT allowed
About

Latest information and perspectives on Oracle Enterprise Manager.

Related Blogs




Search

Archives
« April 2014
SunMonTueWedThuFriSat
  
3
5
6
7
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
   
       
Today