Defining a Chargeback Entity Type

17 Defining a Chargeback Entity Type

Chargeback provides a way to meter and charge for resource use, where a resource is an entity known to Enterprise Manager. Typically, these entities are managed entities of type host, database, and WebLogic Server, for which specific metrics can be collected and charged. An administrator assigns rates and other usage factors to these metrics so they become charge items in something called a charge plan that is assigned to a target instance. A daily Chargeback job collects the metrics and calculates charges against resource use.

Although Enterprise Manager recognizes hundreds of entity types, relatively few are enabled for Chargeback out-of-box. As a plug-in developer you can use the extensibility feature to enable Chargeback on entity types defined within the plug-in, by leveraging extensibility Metadata Services (MDS). To take advantage of MDS, you create an XML file that models a new Chargeback entity type on an Enterprise Manager managed entity (ME) and defines charge items based on Enterprise Manager metrics and configurations.

This chapter describes how to define a new entity type to be added to Chargeback. The chapter contains the following sections:

Chargeback Extensibility Toolkits

Besides the internal implementation of the Chargeback extensibility framework, the following toolkits are available to plug-in developers:

Chargeback metadata service (MDS) registration XML schema

emSDK\emMrsXsds\oracle\sysman\emSDK\chargeback\ChargebackMetadata.xsd
Chargeback callback signature and built-in implementation (built-in callback enables the plug-in developer to register the callback in the Chargeback metadata file for the new entity type)

Included in the pl/sql package GC$CHARGEBACK

The pl/sql callback has the following signature:
```
PROCEDURE add_entity_callback_name(
p_em_entity_guid IN RAW,
p_usage_mode_name IN VARCHAR2 DEFAULT NULL,
p_entity OUT GC$CBA_ENTITY);
```

Using these tools, you can define Chargeback metadata to provide Chargeback support for a new entity type of a managed Enterprise Manager target type and register the built-in callback so that entity instances can be added using the Chargeback user interface and incorporated in the daily job schedule.

Steps to Develop and Test New Chargeback Entity Type

The basic flow to develop and test a new Chargeback entity type involves the following tasks:

Define the Chargeback metadata for the entity and charge items. Include the appropriate callbacks to interact with the Chargeback user interface.
Register the Chargeback metadata file. An alternate course of action is to include the XML file in a plug-in and deploy the plug-in.
Create a charge plan in Chargeback that includes the charge items defined in the metadata.
Add the new entity type to Chargeback using the Add Entities wizard.
Assign the charge plan you created to the added entity type.
Trigger the daily data collection job to populate the tables.
Run reports in Chargeback on the new entity type to view charges and metrics.

The Chargeback Model

This section describes the basic concepts as they relate to the primary elements within the Chargeback metadata file.

Enterprise Manager Entity Type

The Enterprise Manager entity type serves as a model for the Chargeback entity type to be defined. Typically it is an Enterprise Manager target type recognized as a manageable entity (ME).

Chargeback Entity Type

The Chargeback entity type is modeled after its container Enterprise Manager entity type. The Chargeback entity type is characterized by its usage mode; that is, how it is to be metered. Usage mode can involve parent-child relationships with other Chargeback entity types. A Chargeback entity type that is metered directly typically has a set of charge items defined.

More than one Chargeback entity type can be modeled after an Enterprise Manager entity type, but only one can be active in a given release.

Usage Mode

Usage mode defines how the Chargeback entity type is to be metered: directly or through its member entity types. It can also indicate which charge items to meter. A Chargeback entity type can have different usage modes to suit different situations, but only one can be the default.

Charge Template

The charge template indicates the charge items through which to meter the Chargeback entity type. One charge template serves for each usage mode related to direct metering. A composite or parent Chargeback entity type does not require a charge template as they have no direct charge items.

Charge Item

A ChargeItem element in the Chargeback metadata file is akin to a charge item type definition. It defines the type of data to be collected and how.

A charge item can be based on an ME configuration, metric, or property. A charge item can also be a fixed amount.

Entity Callback

There are two entity instance level callbacks that can be registered for each Chargeback entity type.

Add entity callback–called by the Chargeback Add Entities wizard when the administrator selects an entity to add to Chargeback. There are two built-in implementations, intended for plug-in developers:

gc$chargeback.add_em_entity_cb(
    p_em_entity_guid IN RAW,
    p_usage_mode_name IN VARCHAR2 DEFAULT NULL,
    p_entity OUT GC$CBA_ENTITY);

gc$chargeback.add_em_entity_and_members_cb(
    p_em_entity_guid IN RAW,
    p_usage_mode_name IN VARCHAR2 DEFAULT NULL,
    p_entity_arr OUT GC$CBA_ENTITY_ARR);

Add member callback–called both by the Chargeback Add Entities wizard when the administrator selects an entity to add to Chargeback, and by the Chargeback data collection job to discover members that may have been added to the composite entity. There is one built-in implementation, also intended for plug-in developers:
```
gc$chargeback.add_entity_members_cb(
    p_em_entity_guid IN RAW,
    p_usage_mode_name IN VARCHAR2 DEFAULT NULL,
    p_entity_arr OUT GC$CBA_ENTITY_ARR); 
```

Both gc$chargeback.add_em_entity_and_members_cb and gc$chargeback.add_entity_members_cb are implemented based on a chargeback_parent association.

The built-in callbacks do not apply automatically to the Chargeback entity type. The Chargeback entity instance will not be visible in the Add Entities wizard unless you register the applicable callback in the Chargeback metadata file. You cannot override these callbacks.

Sample Chargeback MDS XML File

The sample Chargeback metadata file complements the Host Sample included in the EDK. It proposes to add Chargeback support for the Host Sample to include a fixed base charge for each host instance in addition to a rate charged for each gigabyte of storage and memory used on the host instance.

<?xml version="1.0" encoding="UTF-8" ?>
<ChargebackMetadata name="demo_hostsample_cba" description="Chargeback meta data for demo_hostsample" version="1.0"
                    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <ChargebackEntityType name="demo_hostsample" displayLabel="Demo Plugin Sample Host" labelNlsId="name" description="Chargeback entity type for sample target type demo_hostsample"
                        descriptionNlsId="" mappingEmEntityType="demo_hostsample" 
                        resourceBundle="oracle.sysman.eml.rsc.chargeback.demo_hostsample_cbaMsg" defaultUsageMode="metered">
    <ChargeItems>
      <!-- fixed item -->
      <ChargeItem name="BaseCharge" displayLabel="Base Charge" labelNlsId="em_ct_base_chg" type="fixed"
                  dataType="number" category="instance" aggregationType="sum" description="Base charge for a demo_hostsample instance">
        <QueryExpression type="internal"></QueryExpression>
      </ChargeItem>
            <!-- config -->
         <!-- usage -->
      <ChargeItem name="memUsageMB" displayLabel="Memory Usage" labelNlsId="em_ct_mem_usg" type="metric"
                  dataType="number" unit="GB" unitNlsId="em_ct_u_GB" category="memory"
                  aggregationType="avg" description="Memory used (GB)">
        <QueryExpression type="internal" valueColumn="value/(1024*1024)"
                         emEntityGuidColumn="entity_guid"
                         metricGroup="MemoryPerf" metricColumn="MemTotal"
                         utcCollectionDateColumn="collection_time_utc">
        </QueryExpression>
      </ChargeItem>
      <ChargeItem name="diskUsageGB" displayLabel="Disk Space Usage" labelNlsId="em_ct_disk_usg" type="metric"
                  dataType="number" unit="GB" unitNlsId="em_ct_u_GB" category="storage"
                  aggregationType="avg" description="Disk storage used (GB)">
        <QueryExpression type="internal" valueColumn="value/(1024*1024)"
                         emEntityGuidColumn="entity_guid"
                         metricGroup="FilesystemPerf" metricColumn="UsedKB"
                         utcCollectionDateColumn="collection_time_utc">
        </QueryExpression>
      </ChargeItem>
    </ChargeItems>
    <ChargeTemplates>
      <ChargeTemplate name="demo_hostsampleMetered" displayLabel="Charge template for metering demo_hostsample" 
                      labelNlsId="http_dedicated" description="Charegeback charge template for metering Http demo_hostsample"
                      descriptionNlsId="demo_hostsample_desc" usageMode="metered" isMaster="yes"></ChargeTemplate>
    </ChargeTemplates>
    <UsageModes>
      <UsageMode name="metered" displayLabel="Metered" labelNlsId="metered" type="dedicated" isChargeable="yes"
                 isNavigational="no" defaultChargeTemplate="demo_hostsampleMetered" description="The usage is metered in demo_hostsample level."></UsageMode>
    </UsageModes>
  </ChargebackEntityType>
  <EntityCallbacks>
    <EntityCallback callbackProc="GC$CHARGEBACK.add_em_entity_cb" type="addEmEntity" entityType="demo_hostsample"/>
  </EntityCallbacks>
</ChargebackMetadata>

Table 17-1 lists the key elements in the Chargeback MDS XML file used to define a new Chargeback entity type. See the ChargebackMetadata.xsd for the complete set of all elements and attributes available.

Table 17-1 Key Elements for Defining a New Chargeback Entity Type

Element	Attribute	Description
`ChargebackMetadata`	`name`	(Required) Unique name of the Chargeback entity set.
`ChargebackEntityType`	`name`	(Required) Unique name of the Chargeback entity type.
`NA`	`displayLabel`	(Required) Display label of the Chargeback entity type.
`NA`	`mappingEmEntityType`	Enterprise Manager manageable entity type of the Chargeback entity type, if applicable.
`NA`	`defaultUsageMode`	Default usage mode that applies to the Chargeback entity type. The entity type can have multiple usage modes, but only one can be the default.
`ChargeItem`	`name`	(Required) Unique name of the charge item.
`NA`	`displayLabel`	(Required) Display label of the charge item.
`NA`	`type`	(Required) The charge item's data source. Can be: `metric`, `config`, `property`, or `fixed`.
`NA`	`dataType`	(Required) Charge item data type. Can be: `string` or `number`.
`NA`	`aggregationType`	How to aggregate data collected hourly into a daily total. Acceptable values are `sum` (total the hourly numbers) or `avg` (take the average of the hourly numbers). Default is `avg`.
`NA`	`isChargeable`	Stipulates that the administrator can set a rate directly on the charge item when creating a charge plan. Default is `yes`.
`NA`	`canBeChargeSetCond`	Stipulates that the set of charge plan rates defined for a charge plan configuration apply to the Chargeback entity instance only if the instance has the same value as the plan conditional value for the charge item. Default is `no`.
`NA`	`canBeChargeRateCond`	Stipulates that the administrator can set a conditional rate on the charge item such that it is applicable only for a Chargeback entity with the specific value on the item. Default is `yes`.
`NA`	`category`	Logical resource category of the charge item. Can be: `activity`, `cpu`, `instance` , `memory`, `storage`, `network`, `service`, `software`, `uptime`, or `unclassified`. Default is `unclassified`.
`Key`	`name`	(Required) Name of the charge item key column.
`NA`	`displayLabel`	(Required) Display label of the charge item key.
`QueryExpression`	`type`	(Required) Type of query expression. Defines how to collect the charge item data. For purposes of this discussion, `internal` is the expected value. This means that the metric, config, or property of the ME type is pulled into Chargeback based on the metric group and column names, the configuration view and column names or the property name, respectively.
`NA`	`entityNameColumn` `emEntityTypeColumn` `emEntityNameColumn` `emEntityGuidColumn` `utcCollectionDateColumn` `collectionDateColumn` `keyColumn`	These attributes are common to all charge items. They define the data to be extracted from the Enterprise Manager repository for the entity type.
`NA`	`metricGroup` `metricColumn`	These attributes are specific to charge items based on metrics.
`NA`	`viewName` `valueColumn`	These attributes are specific to charge items based on configurations.
`NA`	`propertyName` `valueColumn`	These attributes are specific to charge items based on target properties.
`ChargeTemplate`	`name`	(Required) Unique name of the charge template to used for the Chargeback entity type.
`NA`	`displayLabel`	(Required) The charge template display label.
`NA`	`usageMode`	(Required) Usage mode name associated with the charge template.
`NA`	`isMaster`	Stipulates that the charge template is the master template for the Chargeback entity type. A master charge template contains all the charge items defined for the Chargeback entity type so there is no need to include an item list as part of the `chargeTemplate` element. In the absence of a master charge template, however, the element must include the list of charge items in the Chargeback metadata file. Acceptable values are `yes` or `no`. Default is `no`.
`UsageMode`	`name`	(Required) Unique name of the Chargeback entity type's usage mode.
`NA`	`displayLabel`	(Required) Usage mode display label.
`NA`	`type`	Usage mode type. Acceptable values are `dedicated` (where the entity type is metered by instance, for example) or `shared` (where the entity type is metered by service, for example). Default is `dedicated`.
`NA`	`defaultChargeTemplate`	Charge template in the Chargeback entity type that can serve as the default for the current usage mode.
`NA`	`isChargeable`	Stipulates that an entity using this usage mode can be chargeable. Acceptable values are `yes` or `no`. Default is `yes`.
`NA`	`isNavigational`	Stipulates that the entity using the this usage mode is navigational; that is, it has children. Acceptable values are `yes` or `no`. Default is `no`.
`EntityCallback`	`entityType`	(Required) Name of the entity type to which it applies.
`NA`	`type`	The type of entity callback. Acceptable values are `addEmEntity` or `addMembers`.
`NA`	`callbackProc`	(Required) Identifies the entity callback procedure.

About NLS IDs

NLS IDs are mostly optional in the XML file. If not defined explicitly in the file, they are generated internally based on a formula. For example:

The entity type display name nls id becomes e_entity_type_name
The entity type description nls id becomes e_entity_type_name_desc
Similarly, usage mode display name nls id becomes u_usage_mode_name
The usage mode description name nls id becomes u_usage_mode_name_desc

This autogeneration satisfies the requirements of the ResourceBundle file.

Registering the Chargeback MDS

Manually run the registration service to register the plug-in by executing a command similar to the following:

emctl register oms metadata
  -service chargeback -core -sysman_pwd <sysmanPWD>
  -file <directory> demo_hostsample_cba.xml

Where directory is the location of the Chargeback metadata file. Upon successful registration, proceed with testing.

As an alternative to registering the plug-in, you can include the XML file in the plug-in and deploy the plug-in. The XML file appears in the oms/metadata/chargeback folder in the Oracle Plug-in Archive (OPAR) file. Administrators as well as plug-in developers can use this method.

Testing the Entity Type Plug-in

Having defined and registered the plug-in, proceed with the following tasks to ensure proper setup. Tasks are outlined here. For details, see Chargeback Administration in Enterprise Manager Cloud Administration Guide. All tasks assume that you are logged in to Enterprise Manager and working in Chargeback (select Chargeback from the Enterprise menu).

Create a Charge Plan

Create a charge plan for the Demo Plugin Sample Host that includes the charge items defined in the Chargeback metadata file.

On the Charge Plans tab, select Plan on the Create menu.
Name the plan (Demo Host Plan), then click Add to select the Demo Plugin Sample Host entity type.
Click Add Item and select the Base Charge item defined in the Chargeback metadata file. Click OK.

Repeat for the other items defined in the Chargeback metadata file (Disk Space Usage and Memory Usage).
Set rates for the three charge items. Base Charge is a flat rate per period. The other two are per GB/period charges.
Click Save to complete plan creation.

Add an Entity of the New Type

Add an entity of the new type to Chargeback to track charge and metering data.

On the Entities tab, click the Add Entities button.
In the wizard, click Add.
Search for entities of type Demo Plugin Sample Host and select one to add to Chargeback. Leave the default usage mode (Metered). Click Next.
Select the row of the entity you just added and click the Assign Plan button.
Select the plan (Sample Host Plan) in the list and click OK. Click Next.
Review your selections and click Submit. Chargeback confirms that the entity was added. The entity appears in the table together with its charge plan assignment.

Review Chargeback Data

Chargeback data collection occurs on a 24-hour cycle, but you can cause it to happen on-demand. On the Entities tab, select On-demand data collection from the Action menu. The tables are updated to reflect the most recent data.

View charge and metering data for the Demo Plugin Sample Host entity type.

Select the Reports tab in Chargeback.
Search for Demo Plugin Sample Host under Entities.
Select a metric to view.
Click the View Report button to recalculate based on your selections. The summary graphs redraw to display charge percentages.
View details in the lower pane. Reconfigure the display by changing the options.