22 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:

When to Use Chargeback APIs
Retreiving Metering Data from Enterprise Manager

When to Use Chargeback APIs

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.

Retreiving Metering Data from Enterprise Manager

This section describes the process of retreiving 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 specified a target type in the target_type field, enter the name of the target here. 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.

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","

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.