Add tags to applications and use tags to query metrics - Application Real-Time Monitoring Service

The tags of Application Real-Time Monitoring Service (ARMS) allow you to organize and monitor data such as Application Monitoring metrics, traces, and logs. This topic describes how to connect an application to the tag center, add tags to the application, and use tags to query metrics on the application details and Grafana view pages.

Prerequisites

An application is monitored by Application Monitoring. For more information, see Application Monitoring overview.

For a Java application, the following requirements must be met:

If the application is deployed in a Kubernetes cluster, the version of ack-onepilot is V3.0.4 or later and the version of the ARMS agent is V2.7.3.5 or later.
If the application is deployed in another environment, the version of the ARMS agent is V2.7.3.5 or later. To obtain the latest installation package of the ARMS agent, perform the following operations: Log on to the ARMS console. In the left-side navigation pane, choose Application Monitoring > Agent Management. On the Agent Management page, click the Agent Release Notes tab.

Tag types

Application Monitoring provides application tags and instance tags. Select a tag type based on your business requirements. Both application tags and instance tags use key-value pairs. You can add multiple key-value pairs at the same time.

Application tags

To view or modify application tags, log on to the ARMS console. In the left-side navigation pane, choose Application Monitoring > Application List. You can use application tags to query applications, manage application permissions, and split bills.

Instance tags

Each application monitored in Application Monitoring can contain multiple application instances, and each application instance represents a process. Different application instances that belong to the same application may have different instance tags.

To application instances that are automatically connected from Kubernetes environments to Application Monitoring, ARMS adds the following tags by default.

Tag key	Description
workloadKind	The type of the workload to which the application instance belongs. Example: Deployment.
workloadName	The name of the workload to which the application instance belongs.
clusterName	The name of the Kubernetes cluster to which the application instance belongs.
namespace	The namespace of the Kubernetes cluster to which the application instance belongs.
version	The image tag. It can be overwritten by a custom instance tag.
agentVersion	The version of the ARMS agent.

In addition to the default instance tags, you can add custom instance tags. At the same time, instance tags added to an application are fully inherited and displayed with the monitoring data of each application instance.

Note

We recommend that the keys of custom instance tags comply with the metric and label conventions of Prometheus. Keys must be specified based on the regular expression ^[a-zA-Z_][a-zA-Z0-9_]*$. For keys not specified based on the regular expression, the ARMS agent uses underscores (_) to replace the non-compliant fragments. For example, 1key:1value is replaced with _key:1value.

Example:

As shown in the following figure, the application my-app contains two instances: Instance A and Instance B. The metric of Instance B has the following tags: env: Dev, team: Observability, app: my-app, workloadKind: Deployment, workloadName: my-app, clusterName: ClusterA, namespace: nsA, and gitVersion: 1.0.2.

Add custom instance tags

Add custom instance tags to applications deployed in Kubernetes environments

Method 1 (recommended): Use pod labels to add custom instance tags

To applications that are deployed in Kubernetes environments and have the ARMS agent automatically installed, you can add custom instance tags by using pod labels.

Note

This method is suitable for applications deployed in Container Service for Kubernetes (ACK) or other Kubernetes environments. For information about how to automatically install the ARMS agent for applications deployed in ACK or other Kubernetes environments, see Application Monitoring overview.

Take an application deployed in an ACK cluster as an example:

Log on to the ACK console. In the left-side navigation pane of the cluster details page, click Deployments or StatefulSets. On the page that appears, select a namespace, find the Deployment or StatefulSet, and then choose More > View in YAML in the Actions column. In the Edit YAML dialog box, add custom tags and click Update. The application instance will be restarted, and new instance tags will be added.

Method 2: Use a pod environment variable to add custom instance tags

Note

This method is supported only in an ARMS agent V4.0.0 or later for Java applications.

To add custom instance tags that can be obtained only after pods are created, such as podName, you can add an environment variable in the startup script of the container. Perform the following steps:

Add an environment variable named ARMS_HOST_TAGS to the container. Set the value to the instance tags. Format: key1:value1&key2:value2. Example: export ARMS_HOST_TAGS="gitVersion:1.0.2&ip:192.168.1.101".
After the environment variable takes effect, start the process.

Add custom instance tags to applications that have the ARMS agent manually installed

Java application

Method 1: Add a -D command-line parameter

Add a -D command-line parameter named -Darms.host.tags="${yourLabel}" to the startup parameters of the application.

Replace ${yourLabel} with the instance tags that you want to add. Format: key1:value1&key2:value2. Example: -Darms.host.tags="gitVersion:1.0.2&ip:192.168.1.101".

Method 2: Modify the configuration file

ARMS agent earlier than V4.0.0

To add custom instance tags to applications that have the ARMS agent manually installed, modify the profile.tags.customtags field of the arms-agent.config configuration file in the agent installation package. Format: key1:value1&key2:value2. Example:
```
#profiler.tags.customtags=key1:value1&key2:value2
profiler.tags.customtags=gitVersion:1.0.2&ip:192.168.1.101
```
Restart the Java process.

ARMS agent V4.0.0 or later

Create a configuration file with the .properties extension in a directory. Add the profiler.tags.customtags field to the configuration file. Set the value to the instance tags that you want to add. Format: key1:value1&key2:value2. Example:
```
#profiler.tags.customtags=key1:value1&key2:value2
profiler.tags.customtags=gitVersion:1.0.2&ip:192.168.1.101
```
Add -Dotel.javaagent.configuration-file=${path/to/config/file} to the startup parameters of the application.
Replace ${path/to/config/file} with the full path of the configuration file. Example: -Dotel.javaagent.configuration-file=/home/admin/config/agent-config.properties.
Restart the Java process.

Go application

Declare environment variables and restart the application process.

#export profiler.tags.customtags=key1:value1&key2:value2
export profiler.tags.customtags=gitVersion:1.0.2&ip:192.168.1.101

Use pod labels to add application tags to applications deployed in Kubernetes environments

Important

For Java applications, only the ack-onepilot component V3.0.16 or later support application tags.

If a pod label is prefixed with app.customAppKey., it is recognized as an application tag, rather than an instance tag.

In the following code, ARMS adds an application tag env: dev to the application.

  template:
    metadata:
      labels:
        app.customAppKey.env: dev
        app: mall-gateway
        armsPilotAutoEnable: 'on'
        aliyun.com/app-language: golang  # Specify a Go application.
        armsPilotCreateAppName: mall-gateway

Note

In ARMS, an application is a collection of multiple application instances. It can have multiple application instances, or belong to multiple workloads or Kubernetes clusters. You can use pod labels to efficiently add application tags in DevOps scenarios. However, this method has some limitations.
Application tags that are added by using pod labels cannot be directly deleted or modified. To modify or delete existing tag keys, you must modify the YAML file and then use the ARMS console or API operations.
If multiple workloads belong to the same application, application tags added by using pod labels may conflict with each other. You must ensure the consistency of application tags.

Use application tags

Application query

When you view the application list or create alert rules in the ARMS console, you can use application tags to query applications.

Tag-based permission management

You can manage RAM permissions based on application tags. For more information, see Attach a custom policy to a RAM user.

Use instance tags

Query monitoring data on the application details page

Log on to the ARMS console. In the left-side navigation pane, choose Application Monitoring > Application List.
On the Application List page, select a region in the top navigation bar and click the name of the application that you want to manage.
Note
If the icon is displayed in the Language column, the application is connected to Application Monitoring. If a hyphen (-) is displayed, the application is connected to Managed Service for OpenTelemetry.
In various modules of the application details page, you can use instance tags to query monitoring data. For example, you can compare and analyze monitoring data based on image versions.

Query metrics on the Grafana view page

Log on to the ARMS console. In the left-side navigation pane, choose Application Monitoring > Application List.
On the Application List page, select a region in the top navigation bar and click the name of the application that you want to manage.
Note
If the icon is displayed in the Language column, the application is connected to Application Monitoring. If a hyphen (-) is displayed, the application is connected to Managed Service for OpenTelemetry.
In the left-side navigation pane, click Grafana view. On the page that appears, configure tags to view metrics.