Skip Headers
Oracle® Enterprise Manager Cloud Administration Guide
12c Release 3 (12.1.0.3)

E28814-10
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

30 Chargeback and Metering EMCLI Verbs

This chapter describes the EMCLI verbs used for Chargeback and Metering and provides details on verb names, descriptions, parameters and syntax. Examples of verb output and commands are also provided. This chapter contains the following sections:

30.1 Using Custom Charge Items

The following sections provide some sample commands along with descriptions and examples. These verbs are used in the following circumstances:

  • You would like to meter/charge based on the metric extension/custom configuration that you have defined. Custom Charge Items can also be used for out of box metrics and target properties. Note that Chargeback only supports metric extensions without key columns.

  • These Custom Charge Items, when created in Chargeback, allow you to meter or charge for the custom item like any existing charge items that are shipped along with a plug-in, such as CPU Utilization. Note that the EM_CBA_ADMIN role is required to access these verbs.

30.1.1 list_charge_item_candidates

This section describes the list_charge_item_candidate data verb.

  • Description: This verb lists the items that can be registered to Chargeback.

  • Verb Syntax

    emcli list_charge_item_candidates 
       -target_type=<target type> 
       -source_data_type=<metric|config|property> 
       -target_name=<target name> 
       -config_name=<config name> 
       -config_data_source=<target name> 
       -all 
    

    The following properties can be defined:

    • target_type: Required parameter. Name of target type. In Enterprise Manager release 12.1.0.2, you can specify the target_type as oracle_databases, oracle_vm_guest, host, oracle_pdb, or weblogic_j2eeserver.

    • source_data_type: Valid values are metric, config, and property.

    • target_name: If you specify a target_name, the metering /charge data will be retrieved only for this target. If you do not specify a valid target_name, or if the specified target has not been enabled in the given date-range, then no data is generated. If this parameter is not specified, All targets for the specified target-type will be included.

    • config_name: Required parameter if source_data_type=config.

    • config_data_source: Data Source of the configuration. Required parameter if source_data_type=config.

    • all: Displays all items, including out of box metrics of target type. Without this option, only user defined Metric Extensions, and Custom Configurations will be displayed.

Examples

emcli list_charge_item_candidates -target_type="oracle_database" -source_data_type="metric" 
emcli list_charge_item_candidates -target_type="oracle_database" -source_data_type="config" -target_name="myDatabase" -config_name="myCustomCCS" -config_data_source="ccsfile"

30.1.2 create_charge_item

This section describes the create_charge_item data verb.

  • Description: This creates a charge item for Chargeback.

  • Verb Syntax

    emcli create_charge_item -input_file="property_file:<full path of property file>" 
    

    The option [-input_file] is the full path of file and contains the item properties. The following properties can be defined in the file:

    • target_type: Required parameter. Name of target type. Supported target types for this release are oracle_database, oracle_vm_guest, host, oracle_pdb, and weblogic_j2eeserver.

    • source_data_type: Required parameter. Type of source data. Valid values are metric, config, and property.

    • item_name: Required parameter. The name of the item.

    • metric_group: Metric group name as listed in list_item_candidates. This is a required property if source_data_type=metric.

    • metric_column: Metric column name as listed in list_item_candidates. Required property if source_data_type=metric.

    • config_view: Config view name as listed in list_item_candidates. Required property if source_data_type=config.

    • config_key: Config key name as listed in list_item_candidates. Required property if source_data_type=config.

    • config_column: Config column name as listed in list_item_candidates. Required property if source_data_type=config.

    • config_data_source: Data source of configuration metric. Required property if source_data_type=config.

    • property: Property name as listed in list_item_candidates. Required property if source_data_type=property.

    • item_displayname: Required property. Display name of item

    • unit: Display name of unit

    • aggregation_type: Type of aggregation to be used for this item, only applicable for numberic data type. Valid values are sum and avg. Default value is avg.

    • is_config_condition: Is item will be used for conditions in Chargeplan. Valid values are 0, 1. Default value is 0.

    • item_category: Category of item. Default value is instance. Valid values are cpu, storage, memory, network, and instance.

    • data_type: Type of data. Default value is number. Valid values are string and number.

Examples

emcli create_charge_item -input_file="property_file:/home/user/property_file"
Contents of /home/user/property_file: 
       target_type=host 
       source_data_type=metric 
       item_name=total_proc 
       metric_group=Load 
       metric_column=noOfProcs 
       item_displayname=Total Processes 
       unit=process 
       aggregation_type=avg 
       item_category=instance 
       data_type=number 
emcli create_charge_item -input_file="property_file:/home/user/property_file" 
Contents of /home/user/property_file: 
       target_type=oracle_database 
       source_data_type=config 
       item_name=custom_config 
       config_view=myCustomCCS 
       config_key=region 
       config_column=country 
       config_data_source=regionList.txt 
       item_display_name=Region of Instance 
       item_category=instance 
       data_type=string 

30.1.3 delete_charge_item

This section describes the delete_charge_item data verb.

  • Description: This deletes the custom item from Chargeback

  • Verb Syntax

    emcli delete_charge_item  -target_type=<target type> -item_name=<Item name>
    

    The following properties can be defined in the file:

    • target_type is the name of target type and is a required parameter.. Supported target types for this release are oracle_database, oracle_vm_guest, host, oracle_pdb, and weblogic_j2eeserver.

    • item_name is the name of the item and is a required parameter.

Examples

emcli delete_charge_item -target_type="oracle_database" -item_name="SampleMetricExtension"
emcli delete_charge_item -target_type="host" -item_name="SampleCustomConfig"

30.2 Examples of Custom Charge Item Verb Use

The following sections provide end-to-end examples in the correct use of Custom Charge Item verbs for custom configurations.

30.2.1 Metric Extension (PGA)

In this example, a metric extension "PGA" with a metric column named "PGA Memory" is created for a database instance target to collect PGA size.

Figure 30-1 PGA Memory

metric extension for pga
  1. Log in to EMCLI and use the Chargeback EMCLI verb list_charge_item_candidates to list the items that can be registered to Chargeback.

    Figure 30-2 list_charge_item_candidates

    list_charge_item_candidates
  2. Create a property file prop_file to generate the custom charge item for the PGA Memory metric column.

    For this metric, the charge rate will be based on the average value over a number of samples, with aggregation_type is set to "avg".

    Figure 30-3 Set aggregation_type

    create custom charge item for "PGA Memory"
  3. Create custom item in Chargeback using create_charge_item EMCLI verb.

    Figure 30-4 Create custom item

    create custom item
  4. Once the custom charge item is created, the Charge Plans page shows the new custom item. Rates can be set against custom items similar to those set for out-of-box charge items.

    Figure 30-5 Create Plan: Custom Plan

    create plan: custom plan

    As the aggregation_type is set to "avg", the charge rate is related to a time period (for example, per GB per timeperiod).

    Figure 30-6 Confirmation

    confirmation screen

30.2.2 Metric Extension (Application A Orders)

A metric extension named "Application A Orders" with a metric column called "Orders Processed" is created for a database instance target. This metric collects the number of orders processed by Application A.

Figure 30-7 Metric Extensions

metric extensions
  1. Log in to EMCLI and use the Chargeback EMCLI verb list_charge_item_candidates to list the items that can be registered to Chargeback.

    Figure 30-8 list_charge_item_candidates

    list_charge_item_candidates
  2. Create a property file prop_file2 to generate a custom charge item for the "Orders Processed" metric column.

    For this metric, the charge rate will be based on total number of orders processed, with aggregation_type set to "sum".

    Figure 30-9 Set Aggregation Type

    set aggregation type
  3. Create a custom item in Chargeback using the create_charge_item EMCLI verb.

    Figure 30-10 create-charge_item

    create_charge_item
  4. Once the custom charge item is created, the Charge Plans page shows the new custom item. Rates can be set against a custom item similar to those set for out-of-box charge items.

    Figure 30-11 Set Rates: Custom Plan

    set rates: custom plan

    As the aggregation_type is set to "sum", the charge rate does not depend upon time periods but rather on the total value of "Orders Processed".

    Figure 30-12 Confirmation

    confirmation screen
  5. Add the database target to Chargeback and assign the "Custom Plan".

    Figure 30-13 Cost Center and Charge Plan Assignment

    cost center and charge plan assignments
  6. Following the daily ETL run, the charge/usage is calculated against new custom items. The charge/usage of custom items can be viewed from the Chargeback report page.

    Figure 30-14 Details

    details screen

30.2.3 Configuration Extensions

A configuration extension named "Config Extensions" is created for the database instance target. This collects the number of high available tablespaces and the name of each high available tablespace as shown below. In this example, the high available tablespaces value is used as the basis of the new custom charge item.

Figure 30-15 Configuration Extensions

configuration extensions
  1. Log in to EMCLI and use the Chargeback EMCLI verb list_charge_item_candidates to list the configuration items that can be registered to Chargeback. Note that config_name is the name of the configuration extension shown on the UI ("Config Extensions" in this case). Similarly, config_data_source is the name of the config column shown on the UI (in this case "tmp/dbconfig.xml").

    Figure 30-16 list_charge_item_candidates

    list_charge_item_candidates
  2. Create a property file prop_file1 to generate a custom charge item for the "Number of High Available Tablespaces" metric column.

    Note that the config_key value comes from the output of the "Custom Config Key" column in the output of the list_charge_item_candidates verb described previously. Similarly, the value of the config_view should be the value of "Custom Config Name" above.

    Figure 30-17 Number of High Available Tablespaces

    number of high available tablespaces
  3. Create a custom item in Chargeback using the create_charge_item EMCLI verb.

    Figure 30-18 create_charge_item

    create_charge_item
  4. Once the custom charge item is created, the Charge Plans page shows the new custom item. Rates can be set against a custom item similar to those set for regular out-of-box charge items.

    Figure 30-19 Set Rates: New Plan

    set rates: new plan

    Figure 30-20 Confirmation

    confirmation
  5. Add the database target to Chargeback and assign the "New Plan".

    Figure 30-21 New Plan

    New Plan
  6. After the daily ETL run, the charge/usage is calculated against new custom items. The charge/usage of custom items can be viewed from the Chargeback report page.

30.3 Retrieving Metering Data from Enterprise Manager

The Chargeback APIs can be used to integrate Enterprise Manager with Billing and Revenue Management systems (including Oracle BRM) and also to provide flexible chargeback mechanisms. Some examples include:

  • Integration with a billing system with different rate plans for small, medium, and large configurations.

  • To calculate chargeback for a flexible time period. For example, months starting from 15th and ending on the 15th.

  • To rationalize chargeback based on other attributes that are not captured by Enterprise Manager.

  • To adjust or round up chargeback based on usage. For example charge is calculated for the full-day even if the usage is for the partial day.

This section describes the process of retrieving metering data using the get_metering_data verb.

get_metering_data

  • Description: This verb generates comma-separated output with each row or line containing usage (and optionally charge) information for the specified parameters.

  • Verb Syntax:

  • emcli get_metering_data
    [-start_date=<start date in mmddyyyy> [-end_date=<end_date in mmddyyyy>]]
    [ -target_type=<target type> [-target_name= <target name> ] ]
    [ -cost_center=<cost center name> ]
    [ -charge] 
    
    

    All the parameters of this verb are optional. If no parameters are specified, the following default values will be used:

    • Start and End Date: The start and end date of the current report cycle.

    • Target Type: The default value for this parameter is 'All'.

    • Cost Center: The name of the user who has logged in.

    • Charge: If this option is not specified, the metering data will be retrieved.

    The parameters are described below:

    • start_date: The value for this parameter must be specified in mmddyyyy format. If you specify this parameter, the output metering/charge information will be filtered accordingly. If the start_date is not specified, the start date for current report cycle will be used.

      In this scenario the start_date means midnight on the start date.

    • end_date: This parameter must be used along with the start_date parameter. The value for this parameter must be given in mmddyyyy format. If you specify this parameter, the output metering/charge information will be filtered accordingly. If the end_date is not specified, the end date for current report cycle will be used.

      In this scenario the end_date means midnight on the end date.

    • target_type: In Enterprise Manager release 12.1.0.2, you can specify the target_type as oracle_databases, oracle_vm_guest, host, or weblogic_j2eeserver. If the targets of the specified target_type have been enabled within the specified date range, appropriate metering or charge data (data for all targets of the specified target_type) will be retrieved. If this parameter is not specified, All target types will be included.

    • target_name: If you specify a target_name, the metering /charge data will be retrieved only for this target. If you do not specify a valid target_name, or if the specified target has not been enabled in the given date-range, then no data is generated. If this parameter is not specified, All targets for the specified target-type will be included.

    • cost_center: If specified, the value of this parameter must be the same as the internal cost-center (as displayed on Cost-Center tab in the Chargeback application). If the specified value is a valid cost-center in the given date range, appropriate metering/charge data will be retrieved. If not, then no data will be generated. If this option is not specified, the default value for the parameter is considered as the logged in user. To retrieve metering/charge information for all cost-centers, specify "All Users" in quotes. Each user is also a consumer (for example, cost-center) in Chargeback. Dependent on their privileges, the logged-in user is shown relevant metering/charge information across different targets.

      Note:

      The privileges required to view target information in Chargeback are:
      • VIEW_CAT_TARGET: Allows you to view information for a specific target (active or inactive).

      • VIEW_ANY_CAT_TARGET: Allows you to view information for any Chargeback target (active or inactive).

    • -charge: If this parameter is not specified, only the metering data will be retrieved. If this option is specified, both metering and charge information will be retrieved.

30.3.1 get_metering_data Output

This verb generates the following output:

  • CONSUMER_NAME: Name of the cost-center.

  • TARGET_TYPE: Type of target.

  • TARGET_NAME: Name of the target.

  • ITEM_TYPE: Type of the item or metric. Possible values are: config, fixed, metric, property, and usage.

  • CATEGORY_NAME: Possible values are: cpu, memory, storage, activity, instance, network, service, and software.

  • ENTITY_NAME: Name of the shared entity (valid when the target is enabled in Chargeback in shared mode).

  • ITEM_DISPLAY_NAME: Display name of the item or metric (in English language). Note: Translation support is currently not available.

  • VALUE_AVERAGE: Average value for the metric on the given date (valid for numeric metrics).

  • STRING_VALUE: Value for the metric data (valid for string-based metrics).

  • DATA_TYPE: Data type of the metric. This can be string or number.

  • UNIT: Unit of the metric data (for example, req and GB).

  • COLLECTION_DATE: Date on which the data is collected from the Enterprise Manager metric or configuration tables.

  • PLAN_NAME: Name of the Charge Plan associated with the particular target.

  • CHARGE: Charge value for the specific metric of the target on the particular date.

  • DEFINED_RATE: Charge rate defined in the charge plan associated with the target.

  • RATE_TYPE: Type of the rate. Possible values are: No value (blank), Flat, config, and usage.

  • RATE_FACTOR: Adjustment rate for universal metrics, as defined in the associated extended Chargeplan.

  • CHARGE_RATE_UNIT: Unit, corresponding to the metric or item, as defined in the Charge Plan for the specific rate. For example, for an item or metric named CPU Utilization (%) or CPU Utilization (%) per service, the value will be "CPU". For a metric or item named Base Charge, the value will be "instance", a metric named 'User Requests', the value will be "req"). If the rate defined in Chargeplan is $1 per MB per day, the value for this column will be "MB" .

  • CHARGE_TIME_UNIT: Time unit as defined in the Charge Plan for the specific rate. (such as, hourly, daily, weekly, monthly, yearly). For example, if the rate defined in Charge Plan is $1 per MB per Day, value for this column will be daily.

Example: Sample Output

"CONSUMER_NAME","TARGET_TYPE","TARGET_NAME","ITEM_TYPE","CATEGORY_NAME","ENTITY_NAME","ITEM_DISPLAY_NAME","STRING_VALUE","PLAN_NAME","COLLECTION_DATE","CHARGE","VALUE_AVERAGE","DEFINED_RATE","RATE_TYPE","RATE_FACTOR","CHARGE_RATE_UNIT","CHARGE_TIME_UNIT","NORMALIZE_RATE","ADJUST_RATE","DATA_TYPE","UNIT" 

"linbo","oracle_vm_guest","mySite/myWls/AdminServer:agent_push","fixed","instance"," ","Base Charge","","zone_plan",15-OCT-11 00:00:00,72,1,"3","flat",1,"instance","hourly",1,1,"number",""
"linbo","oracle_vm_guest","mySite/myWls/AdminServer:agent_push","fixed","instance"," ","Base Charge","","zone_plan",16-OCT-11 00:00:00,72,1,"3","flat",1,"instance","hourly",1,1,"number",""
"linbo","oracle_vm_guest","mySite/myWls/AdminServer:agent_push","fixed","instance"," ","Base Charge","","zone_plan",17-OCT-11 00:00:00,72,1,"3","flat",1,"instance","hourly",1,1,"number",""
"linbo","oracle_vm_guest","mySite/myWls/AdminServer:agent_push","fixed","instance"," ","Base Charge","","zone_plan",18-OCT-11 00:00:00,72,1,"3","flat",1,"instance","hourly",1,1,"number",""
"linbo","oracle_vm_guest","mySite/myWls/Cluster-0_vm0:assembly1","fixed","instance"," ","Base Charge","","zone_plan",15-OCT-11 00:00:00,72,1,"3","flat",1,"instance","hourly",1,1,"number","

30.3.1.1 Examples

A few examples are shown in the following section:

  • emcli get_metering_data: Returns metering information for all targets (active or enabled in Chargeback) for the current report cycle for the logged in user.

  • emcli get_metering_data -charge: Returns metering and charge information for all targets (active or enabled in Chargeback) for the current report cycle for the logged in user.

  • emcli get_metering_data -start_date=01202011-cost_center=ORG1: Returns metering information for all targets (active or enabled in Chargeback) starting from 20th January 2011 until the end of the month for the ORG1 cost-center.

  • emcli get_metering_data -start_date=01152011 -end_date=02152011 -target_type=oracle_database: Returns metering information for all Oracle DB targets (active or enabled in Chargeback) that are owned by the logged in user, starting from 15th January 2011 until the 15th February 2011.

  • emcli get_metering_data -target_type=host target_name=my_host -cost_center=organization1: Returns metering and charge information for "my_host" target (of type host) for the current report cycle for "organization1" cost-center.

  • emcli get_metering_data -cost_center="All Users": Returns metering and charge information for all targets (active or enabled in Chargeback) in the current report cycle for all cost centers.

  • Log in as cba_admin_user (who is the Chargeback Administrator) and enter the following commands:

    • emcli get_metering_data: Returns metering information for all targets (active or enabled in Chargeback) for the current report cycle for the cba_admin_user.

    • emcli get_metering_data -cost_center=ssa_user1: Returns metering information for all targets (active or enabled in Chargeback) that are owned by the ssa_user1 in the cost center in the current report cycle.

  • If the value specified for the cost center, target type, and / or target name is incorrect, no data is generated. For example, the following commands will not generate data:

    • emcli get_metering_data -target_type=unknown

    • emcli get_metering_data -target_type=oracle_database -target_name=unknown_target

      Note: There is no target with the name unknown_target configured in Enterprise Manager.