You can create custom metrics to supplement built-in metrics such as Business Transaction call count and response time. You can also create metrics for multiple application contexts.

Custom metrics are dependent on the application context; in situations with multiple contexts, you must specify the correct context name for custom metrics to apply to the associated application context. See Create Alternate Application Contexts.

For example, the default application context uses a null pointer or empty string as its name. The appd_sdk_init method tells the SDK to connect to the Controller and create the default application context (i.e. no name is specified).

struct appd_config* cfg = appd_config_init();
appd_config_set_controller_host(cfg, host.c_str());
appd_config_set_controller_port(cfg, port);
appd_config_set_controller_account(cfg, account_name.c_str());
appd_config_set_controller_access_key(cfg, access_key.c_str());
appd_config_set_controller_use_ssl(cfg, useSSL?1:0);
appd_config_set_app_name(cfg, app_name.c_str());
appd_config_set_tier_name(cfg, tier_name.c_str());
appd_config_set_node_name(cfg, node_name.c_str());
appd_sdk_init(cfg);

To specify an alternative application context, you must provide a name string (not a default null pointer). Use the appd_sdk_add_appd_context method to create an alternative application context. In the example below, we create an alternative application context called "context2." You will use that name string to create custom metrics, not the actual configuration structure.

const char* name = "context2";
struct appd_context_config* cfg2 = appd_context_config_init(name));
appd_context_config_set_controller_account(cfg2, ac.second.ac_account_get().c_str());
appd_context_config_set_controller_access_key(cfg2, ac.second.ac_access_key_get().c_str());
appd_context_config_set_controller_host(cfg2, ac.second.ac_host_get().c_str());
appd_context_config_set_controller_port(cfg, ac.second.ac_port_get());
appd_context_config_set_controller_use_ssl(cfg2, ac.second.ac_use_ssl_get() ? 1 : 0);
appd_context_config_set_app_name(cfg2, ac.second.ac_app_get().c_str());
appd_context_config_set_tier_name(cfg2, ac.second.ac_tier_get().c_str());
appd_context_config_set_node_name(cfg2, ac.second.ac_node_get().c_str());
appd_sdk_add_app_context(cfg2);

The Custom Metrics path may or may not go the same Controller; similar to business transactions in separate nodes, your program can process two business transactions from different nodes: one aligns with the default application context and the other with the alternative application context. You must specify that your method strings begin with Custom Metrics|, not Custom Metric|.

You can use the following methods to create a custom metric:

• appd_custom_metric_add()

• appd_custom_metric_report()

Default Application Context

The appd_custom_metric_add() method registers a custom metric for the default context.

appd_custom_metric_add(nullptr, "Custom Metrics|my_default_custom_metric" , time_rollup_type, cluster_rollup_type, hole_handling_type);

The appd_custom_metric_report() creates an application context named "my_default_custom_metric."

appd_custom_metric_report(nullptr, "Custom Metrics|my_default_custom_metric",some_value);

The appd_custom_metric_report creates a default application context and an alternative application context named my_second_custom_metric.

Alternate Application Context

For an alternative context, the appd_custom_metric_add() method registers a custom metric for the alternative application context.

appd_custom_metric_add(name, "Custom Metrics|my_second_custom_metric" , time_rollup_type, cluster_rollup_type, hole_handling_type);

or

appd_custom_metric_add("context2", "Custom Metrics|my_second_custom_metric" , time_rollup_type, cluster_rollup_type, hole_handling_type);

The appd_custom_metric_report creates a default application context and an alternative application context named my_second_custom_metric.

Default Application Context

appd_custom_metric_report(name, "Custom Metrics|my_second_custom_metric",some_value);

Alternate Application Context

appd_custom_metric_report("context2", "Custom Metrics|my_second_custom_metric",some_value);

In the Controller, the custom metrics folder appears under the associated tier as "Custom Metrics" in the Metric Browser with two entities: my_default_custom_metric and my_second_custom_metric.

The following example illustrates a call with both method signatures.

appd_custom_metric_add("app_context", "Custom Metrics|Memory|Total Memory Usage",
APPD_TIMEROLLUP_TYPE_AVERAGE, APPD_CLUSTERROLLUP_TYPE_INDIVIDUAL,
APPD_HOLEHANDLING_TYPE_RATE_COUNTER);

The method passes the application context ("Total Memory Usage") and the path to the metric ( appd_custom_metric_report() Custom Metrics > Memory in the Metric Browser) to the Controller. The additional parameters define how the metric is processed. With the metric declared, your code can then report data to the metric with the appd_custom_metric_report() method, as follows:

appd_custom_metric_report("app_context", "Custom Metrics|Memory|Total Memory Usage", 1234);

See C/C++ SDK Resource Management to simplify your instrumentation on C++ applications.

Metric Handling Parameters

Like built-in metrics, the Controller applies some standard processing functions to custom metric values. These functions can define, for example, how the metric is rolled up over time. How the Controller processes a custom metric depends on the nature of the metric; for a metric that represents the state of the machine, the Controller captures the last observed value for the metric. For a call rate metric, the Controller uses an average value. The following section provides information about the parameters you can use to define metric handling by the Controller.

Time Rollup Type

The time_rollup_type parameter tells the Controller how to roll up values for the metric over time. There are three ways in which the Controller can roll up metrics, as follows:

• It can calculate the average of all reported values in the time period. An example of a built-in metric that uses this is the Average Response Time metric.
• Sum of all reported values in that minute. This operation behaves like a counter. An example metric is the Calls per Minute metric.
• Current is the last reported value in the minute. If no value is reported in that minute, the last reported value is used. An example of a metric that uses this would be a machine state metric, such as Max Available (MB) metric.

Cluster Rollup Type

The appd_cluster_rollup_type parameter tells the Controller how to aggregate metric values for the tier—a cluster of nodes.

• Individual: Aggregates the metric value by averaging the metric values across each node in the tier. For example, Hardware Resources|Memory|Used % is a built-in metric that uses the individual rollup type.
• Collective: Aggregates the metric value by adding up the metric values for all the nodes in the tier. For example, Agent|Metric Upload|Metrics uploaded is a built-in metric that uses the collective rollup type.

Hole Handling Type

A particular metric may not report data for a given minute. The appd_hole_handling_type parameter tells the Controller how to set the metric count for that time slice. The count is set to zero if the hole handling type is REGULAR_COUNTER, and set to one if RATE_COUNTER. In effect, REGULAR_COUNTER does not affect aggregation while RATE_COUNTER does.

For example, consider four time slices with the data 9, 3, 0, 12. Notice that the third time slice is zero filled, with no metric being reported for that time slice. The sum of the values is 9+3+0+12 = 24.

If the metric is REGULAR_COUNTER, the count for the third times slice would be zero, and therefore the overall count would be 1+1+0+1 = 3. If the metric is RATE_COUNTER the overall count would be 1+1+1+1 = 4. In the case of the REGULAR_COUNTER, the average would be 24/3 = 8, while for the RATE_COUNTER the average would be 24/4 = 6.

Built-in metrics that use the regular counter hole-handling type include Average Response Time, Average CPU Used, and Number of Stalls. Built-in metrics that use the rate counter hole-handling type include BT Calls per minute and Errors per minute.