All Products
Search

This Product

    Application Real-Time Monitoring Service:Add and use tags

    Document Center

    Application Real-Time Monitoring Service:Add and use tags

    Last Updated:May 14, 2025

    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.

    image

    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.image.png

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

    Note

    This method is supported in ARMS agents V4.0.0 or later for Java, V1.5.0 or later for Go, and V1.3.0 or later for Python.

    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:

    1. 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".

    2. After the environment variable takes effect, start the process.

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

    Java

    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 V4.0.0 or later

    1. Refer to Modify ARMS agents for Java parameters and data reporting regions and create a .properties configuration file in any directory. In the configuration file, add the profiler.tags.customtags field and specify its value as the instance tag that you want to add. Separate multiple tags in the key1:value1&key2:value2 format. Example:

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

    2. Add -Dotel.javaagent.configuration-file=${path/to/config/file} or the environment variable OTEL_JAVAAGENT_CONFIGURATION_FILE=${path/to/config/file} to the startup command of your Java application.

      Note

      • Replace ${path/to/config/file} with the full path of the configuration file that you created in the previous step. Example: -Dotel.javaagent.configuration-file=/home/admin/config/agent-config.properties or OTEL_JAVAAGENT_CONFIGURATION_FILE=/home/admin/config/agent-config.properties.

      • If both the startup command and environment variable are configured, the startup command takes precedence.

    3. Restart the Java process.

    ARMS agent earlier than V4.0.0

    1. Refer to Modify ARMS agents for Java parameters and data reporting regions and modify the profiler.tags.customtags field in the arms-agent.config configuration file of the agent installation package. You can add custom instance tags in the key1:value1&key2:value2 format. Example:

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

    2. Restart the Java process.

    Go

    Declare environment variables and restart the application process.

    #export ARMS_HOST_TAGS=key1:value1&key2:value2
export ARMS_HOST_TAGS="gitVersion:1.0.2&ip:192.168.1.101"

    Python

    Declare environment variables and restart the application process.

    #export ARMS_HOST_TAGS=key1:value1&key2:value2
export ARMS_HOST_TAGS="gitVersion:1.0.2&ip:192.168.1.101"

    Add tags to applications deployed in Kubernetes environments using pod labels

    Use either of the following ways to add tags:

    Important

    The version requirements for ack-onepilot:

    • V3.0.16 or later for Java

    • V3.2.0 or later for Go

    • V4.1.1 or later for Python

    Use the prefix app.customAppKey.

    A pod label prefixed with app.customAppKey. 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

    Add the environment variable ARMS_APP_LABELS

    To reuse existing pod labels as application tags, configure ack-onepilot V4.1.2 or later:

    1. Log on to the ACK console. In the left-side navigation pane, click Clusters.

    2. On the Clusters page, find the cluster you want to manage and click its name. In the left-side pane, choose Workloads > Deployments.

    3. On the Deployments page, click the ack-onepilot component. Generally, it is named ack-onepilot-ack-onepilot in the ack-onepilot namespace.

      image.png

    4. In the upper-right corner of the page that appears, click Edit.

    5. Scroll down until you see the Environments section. Click Add, add the environment variable ARMS_APP_LABELS, and set the value to a comma-separated string. After configuration, all keys listed in /spec/template/metadata/labels matching ARMS_APP_LABELS are registered as application tags.

      image

    6. Wait for the ack-onepilot component to restart and pass health checks. Then, restart your application pods to apply the labels.

      image.png

    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

    1. Log on to the ARMS console. In the left-side navigation pane, choose Application Monitoring > Application List.

    2. 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.

      3. Note

      Icons displayed in the Language column indicate languages in which applications are written.

      Java图标: Java application

      image: Go application

      image: Python application

      Hyphen (-): application monitored in Managed Service for OpenTelemetry.

    3. 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

    1. Log on to the ARMS console. In the left-side navigation pane, choose Application Monitoring > Application List.

    2. 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.

      3. Note

      Icons displayed in the Language column indicate languages in which applications are written.

      Java图标: Java application

      image: Go application

      image: Python application

      Hyphen (-): application monitored in Managed Service for OpenTelemetry.

    3. In the left-side navigation pane, click Grafana view. On the page that appears, configure tags to view metrics.

      GrafanaView