Monitoring operational metrics using the API

After you set up your IBM® Key Protect service instance, you can manage monitoring metrics by using the service API.

Metrics settings

Metrics for Key Protect service instances is an extra policy that allows you to receive the operational metrics for your Key Protect instance. When you enable this policy, Monitoring can be used to monitor any operations that are performed on the resources in your Key Protect instance.

Enabling metrics is only available through the Key Protect API. To find out more about accessing the Key Protect APIs, check out Setting up the API.

Before you enable operational metrics for your Key Protect instance, keep in mind the following considerations:

When you enable metrics for your Key Protect instance, metrics are only reported after the time that the policy is enabled. Once your metrics policy is enabled, you will see operational metrics for all API requests that occur in your instance after the the policy is activated. You will not be able to view any metrics prior to the time that the policy is enabled.
You will need to provision a Monitoring instance for your policy in order to see the metrics. You will need to provision a Monitoring instance that is located in the same region as the Key Protect instance that you would like to receive operational metrics for. Once you provision the Monitoring instance, you will need to enable platform metrics.

Enabling metrics for your Key Protect instance with the Console

After creating a Key Protect instance, provisioning a Monitoring, and enabling platform metrics, complete the following steps to enable a metrics policy:

Log in to the IBM Cloud console.
Go to Menu > Resource List to view a list of your resources.
From your IBM Cloud resource list, select your provisioned instance of Key Protect.
On the Instance policies page, click the Enable button in the metrics policy section.

Enabling metrics for your Key Protect instance with the API

As an instance manager, enable a metrics policy for a Key Protect instance by making a PUT call to the following endpoint.

https://<region>.kms.cloud.ibm.com/api/v2/instance/policies?policy=metrics

Retrieve your authentication credentials to work with the API.

To enable metrics policies, you must be assigned a Manager IAM access policy for your Key Protect instance. To learn how IAM roles map to Key Protect service actions, check out Service access roles.

Enable a metrics policy for your Key Protect instance by running the following curl command.

curl -X  PUT \
"https://<region>.kms.cloud.ibm.com/api/v2/instance/policies?policy=metrics" \
-H "accept: application/vnd.ibm.kms.policy+json" \
-H "authorization: Bearer <IAM_token>" \
-H "bluemix-instance: <instance_ID>" \
-H "content-type: application/vnd.ibm.kms.policy+json" \
-d '{
        "metadata": {
            "collectionType": "application/vnd.ibm.kms.policy+json",
            "collectionTotal": 1
        },
        "resources": [
            {
                "policy_type": "metrics",
                "policy_data": {
                        "enabled": false
                }
            }
        ]
    }'

Replace the variables in the example request according to the following table.

Describes the variables that are needed to enable a metrics policy.
Variable	Description
region	Required. The region abbreviation, such as `us-south` or `eu-gb`, that represents the geographic area where your Key Protect instance resides. For more information, see Regional service endpoints.
IAM_token	Required. Your IBM Cloud access token. Include the full contents of the IAM token, including the Bearer value, in the curl request. For more information, see Retrieving an access token.
instance_ID	Required. The unique identifier that is assigned to your Key Protect service instance. For more information, see Retrieving an instance ID.

A successful request returns an HTTP `204 No Content` response, which
indicates that your Key Protect instance
is now enabled for reporting operational metrics.

This new policy only reports on operations that occur after the policy is
enabled.
{: note}

Optional: Verify that the metrics policy was created by browsing the policies that are available for your Key Protect instance.

$ curl -X GET \
    "https://<region>.kms.cloud.ibm.com/api/v2/instance/policies?policy=metrics" \
    -H "accept: application/vnd.ibm.kms.policy+json" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>"

Disabling metrics for your Key Protect instance with the API

As an instance manager, disable an existing metrics policy for a Key Protect instance by making a PUT call to the following endpoint.

https://<region>.kms.cloud.ibm.com/api/v2/instance/policies?policy=metrics

Retrieve your authentication credentials to work with the API.

To disable metrics policies, you must be assigned a Manager access policy for your Key Protect instance. To learn how IAM roles map to Key Protect service actions, check out Service access roles.

Disable an existing metrics policy for your Key Protect instance by running the following curl command.

$ curl -X PUT \
    "https://<region>.kms.cloud.ibm.com/api/v2/instance/policies?policy=metrics" \
    -H "accept: application/vnd.ibm.kms.policy+json" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>" \
    -H "content-type: application/vnd.ibm.kms.policy+json" \
    -d '{
            "metadata": {
                "collectionType": "application/vnd.ibm.kms.policy+json",
                "collectionTotal": 1
            },
            "resources": [
                {
                    "type": "application/vnd.ibm.kms.policy+json",
                    "metrics": {
                        "enabled": false
                    }
                }
            ]
        }'

Replace the variables in the example request according to the following table.

Describes the variables that are needed to enable metrics policies.
Variable	Description
region	Required. The region abbreviation, such as `us-south` or `eu-gb`, that represents the geographic area where your Key Protect instance resides. For more information, see Regional service endpoints.
IAM_token	Required. Your IBM Cloud access token. Include the full contents of the IAM token, including the Bearer value, in the curl request. For more information, see Retrieving an access token.
instance_ID	Required. The unique identifier that is assigned to your Key Protect service instance. For more information, see Retrieving an instance ID.

A successful request returns an HTTP `204 No Content` response, which
indicates that the metrics policy was updated for your service
instance.

Optional: Verify that the metrics policy was updated by browsing the policies that are available for your Key Protect instance.

```sh {: codeblock}
$ curl -X GET \
    "https://<region>.kms.cloud.ibm.com/api/v2/instance/policies?policy=metrics" \
    -H "accept: application/vnd.ibm.kms.policy+json" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>"
```

What's next

To find out more about configuring your Key Protect instance with Monitoring, check out Monitoring Operational Metrics.