To manage the metrics through the Admin Portal, navigate to the product page of the product that you want to manage. Then, click Integration: → Methods & Metrics. The page displays the metrics for the product.

To create a new metric, click New metric and complete the form.

To manage the metrics through the CLI Toolbox, you can use the 3scale metric super command.

You can create a new metric by using the 3scale metric create command. For example, if you want to create a metric metric1 for the product1 product in the 3scale tenant, then a possible command is as follows:

[student@workstation ~]$ 3scale metric create 3scale-tenant product1 metric1 --unit=1

You can update an existing metric by using the 3scale metric apply command. The following command updates the name for the metric1 metric.

[student@workstation ~]$ 3scale metric apply 3scale-tenant product1 metric1 --name=metric2

You can list the existing metrics by using the 3scale metric list.

[student@workstation ~]$ 3scale metric list 3scale-tenant product1
ID	FRIENDLY_NAME	SYSTEM_NAME	UNIT	DESCRIPTION
8	Hits	hits	hit	Number of API hits
10	status-203	status-203	1	status 203

The previous commands include several options to modify the metric, such as name or description. For a complete understanding of the options associated to every command, visit the official Red Hat documentation.

A metric can be linked to a mapping rule. When you create a mapping rule, you have the option to select a metric to increment. If a metric is linked to a mapping rule, then the metric gets incremented every time that the mapping rule receives a request.

If the metric is not linked to a mapping rule, then an external system must perform the incrementation. APIcast includes a policy, Custom Metrics, which you can use to increment a metric based on the HTTP status code of the response of the API. For example, if you want to track the number of 300 status codes that your API returns, then you can configure the Custom Metrics policy to increment a metric on every response that meets the criteria.

To add the policy, navigate to Integration: → Policies and click Add policy. Then, select Custom Metrics from the policies list. For the policy to work, you must give it priority over the default APIcast policy policy.

The policy is composed of one or several operations combined by a condition.

You can consider that every operation is an equality expression with two operands: left and right. The operation holds an op field, which is applied to the left and right operands.

left (op) right

The left and right fields can be plain text, or Liquid (the programming language) expressions. In the Liquid programming language, variables are enclosed with two brackets (for example, {{variable}}). The policy provides the built-in variable {{status}}, which is used to get the status code of the response. For example, if you only want the metric to be incremented when the status code is 404, then the expression is similar to the following:

404 matches {{status}}

3scale API Management evaluates the previous expression on every request, and only increments the metric if the evaluation is true. You can include complex expressions by creating several operations combined by a logical expression (and or or).

(404 matches {{status}}) OR (500 matches {{status}})

The previous expression increments the metric if the status code is equal to 404 or 500.

To configure the policy, you must complete the form, which includes several fields.

Figure 6.1: Sample product with a configured Custom Metrics policy

The following table explains the fields involved in the configuration of the policy.