Add tags to Java applications and use tags to filter Application Monitoring metrics - Application Real-Time Monitoring Service: Central de Documentação do Alibaba Cloud

As tags no Application Real-Time Monitoring Service (ARMS) ajudam a organizar e observar dados, como métricas de monitoramento de aplicações, traces e logs. Este tópico descreve como adicionar tags às suas aplicações, usar tags de aplicação para filtrar aplicações e gerenciar permissões, além de utilizar tags de instância para filtrar dados nas páginas Application Details e Grafana View.

Pré-requisitos

Sua aplicação deve estar conectada ao Application Monitoring. Para mais informações, consulte Visão geral do Application Monitoring.

Aplicações Java também precisam atender aos seguintes requisitos:

Para aplicações em clusters de contêineres, verifique se o componente ack-onepilot está na versão v3.0.4 ou posterior e se o agente do ARMS está na versão v2.7.3.5 ou posterior.
Para aplicações em outros ambientes, confirme que a versão do agente do ARMS é v2.7.3.5 ou superior. Baixe a versão mais recente do agente do ARMS na aba Agent Release Notes da página Application Monitoring > Agent Management no console do ARMS.

Tipos de tags

O Application Monitoring oferece dois tipos de tags: tags de aplicação e tags de instância. Ambas utilizam pares chave-valor. Escolha o tipo mais adequado ao seu caso de uso.

Tags de aplicação

As tags de aplicação aplicam-se a aplicações do ARMS. Visualize ou modifique essas tags na página Application Monitoring > Application List no console do ARMS. Utilize-as para finalidades como filtragem de aplicações, gerenciamento de permissões e alocação de custos.

Tags de instância

Cada instância de aplicação representa um processo conectado ao ARMS com o mesmo nome de aplicação. Diferentemente das tags de aplicação, as tags de instância aplicam-se individualmente a cada instância, permitindo que diferentes instâncias da mesma aplicação possuam tags distintas.

Para instâncias descobertas automaticamente em um ambiente Kubernetes, o ARMS adiciona as seguintes tags padrão:

Chave da tag	Descrição
workloadKind	Tipo de workload onde a instância da aplicação executa, como Deployment.
workloadName	Nome do workload onde a instância da aplicação executa.
clusterName	Nome do cluster Kubernetes onde a instância da aplicação executa.
namespace	Namespace do Kubernetes onde a instância da aplicação executa.
version	Tag da imagem. Uma tag de instância personalizada pode sobrescrever este valor.
agentVersion	Versão do agente do ARMS.

Além das tags padrão, você pode adicionar tags de instância personalizadas. As instâncias também herdam todas as tags da aplicação pai. Os dados de monitoramento gerados pelo ARMS para uma instância incluem todas as tags de aplicação e de instância atribuídas a ela.

Nota

Recomendamos que as chaves das tags de instância personalizadas sigam as convenções de nomenclatura do Prometheus, correspondendo à expressão regular ^[a-zA-Z_][a-zA-Z0-9_]*$. Para chaves fora desse padrão, o agente do ARMS substitui caracteres inválidos por um sublinhado (_). Por exemplo, 1key:1value torna-se _key:1value.

Exemplo:

Conforme ilustrado na figura abaixo, a aplicação my-app possui duas instâncias. Os dados de métrica gerados pelo ARMS para a Instância B incluem as seguintes tags: {env: Dev, team: Observability, app: my-app, workloadKind: Deployment, workloadName: my-app, clusterName: ClusterA, namespace: nsA, gitVersion: 1.0.1}.

Adicionar tags de instância personalizadas

Adicionar tags de instância personalizadas no Kubernetes

Método 1 (recomendado): Injetar tags usando rótulos de pod

Se sua aplicação estiver implantada em um ambiente Kubernetes com instalação automática do agente do ARMS, adicione tags de instância personalizadas por meio de rótulos de pod.

Nota

Este método é adequado para aplicações implantadas tanto no Container Service for Kubernetes (ACK) quanto em ambientes Kubernetes genéricos. Para obter informações sobre como instalar automaticamente o agente do ARMS nesses ambientes, consulte Visão geral do Application Monitoring.

Tome como exemplo uma aplicação implantada em um ambiente ACK:

No console do ACK, acesse a página Deployments ou StatefulSets do cluster desejado. Selecione o namespace alvo, localize a aplicação e, na coluna Actions, escolha > View in YAML. Na caixa de diálogo Edit YAML, adicione suas tags personalizadas e clique em Update. A instância da aplicação reinicia para aplicar as novas tags.

'f:readyReplicas': {}
        'f:replicas': {}
        'f:updatedReplicas': {}
    manager: kube-controller-manager
    operation: Update
    subresource: status
    time: '2023-11-16T09:39:32Z'
  name: mall-gateway
  namespace: arms-apm-demo
  resourceVersion: '943537'
  uid: xxxd0b1bf76f42
spec:
  progressDeadlineSeconds: 600
  replicas: 1
  revisionHistoryLimit: 10
  selector:
    matchLabels:
      app: mall-gateway
  strategy:
    rollingUpdate:
      maxSurge: 25%
      maxUnavailable: 25%
    type: RollingUpdate
  template:
    metadata:
      labels:
        gitVersion: '1.0.2'  # Add a custom instance tag
        app: mall-gateway
        armsPilotAutoEnable: 'on'
        armsPilotCreateAppName: mall-gateway
    spec:
      containers:
      - env:
        - name: SERVICE_NAME

Método 2: Injetar tags usando uma variável de ambiente do pod

Nota

Para utilizar este método em uma aplicação Java, a versão do agente do ARMS deve ser 4.0.0 ou superior.
Para aplicações Go, utilize a versão 1.5.0 ou posterior do agente do ARMS.
No caso de aplicações Python, é necessária a versão 1.3.0 ou mais recente do agente do ARMS.

Para injetar tags personalizadas disponíveis apenas após a criação do pod (como podName), adicione uma variável de ambiente do sistema operacional ao script de inicialização do contêiner da aplicação. Siga estas etapas:

Adicione uma variável de ambiente chamada ARMS_HOST_TAGS ao contêiner da sua aplicação. Defina seu valor com as tags de instância desejadas. Separe múltiplas tags usando o formato key1:value1&key2:value2. Exemplo: export ARMS_HOST_TAGS="gitVersion:1.0.2&ip:192.168.1.101".
Reinicie a aplicação para que a alteração tenha efeito.

Adicionar tags para agentes instalados manualmente

Aplicações Java

Método 1: Usar um parâmetro -D

Acrescente o parâmetro -Darms.host.tags="${yourLabel}" ao comando de inicialização da sua aplicação Java.

Substitua ${yourLabel} pelas tags de instância que deseja adicionar. Use o formato key1:value1&key2:value2 para múltiplas tags. Por exemplo: -Darms.host.tags="gitVersion:1.0.2&ip:192.168.1.101".

Método 2: Modificar o arquivo de configuração

Agente v4.0.0 ou posterior

Conforme descrito em Modificar o arquivo de configuração e a região de relatório padrão do agente Java, crie um arquivo de configuração com extensão .properties em qualquer diretório. No arquivo, adicione o campo profiler.tags.customtags e defina seu valor com as tags de instância desejadas. Utilize o formato key1:value1&key2:value2 para múltiplas tags. Exemplo:
```
#profiler.tags.customtags=key1:value1&key2:value2
profiler.tags.customtags=gitVersion:1.0.2&ip:192.168.1.101
```
Adicione o parâmetro -Dotel.javaagent.configuration-file=${path/to/config/file} aos parâmetros de inicialização da sua aplicação Java ou defina a variável de ambiente OTEL_JAVAAGENT_CONFIGURATION_FILE=${path/to/config/file}.
Nota
- Substitua ${path/to/config/file} pelo caminho completo do arquivo de configuração criado. Por exemplo: -Dotel.javaagent.configuration-file=/home/admin/config/agent-config.properties ou OTEL_JAVAAGENT_CONFIGURATION_FILE=/home/admin/config/agent-config.properties.
- Caso tanto o parâmetro de inicialização quanto a variável de ambiente estejam configurados, o parâmetro de inicialização terá precedência.
Reinicie o processo da aplicação.

Agente anterior à versão v4.0.0

Conforme descrito em Modificar o arquivo de configuração e a região de relatório padrão do agente Java, modifique o campo profiler.tags.customtags no arquivo arms-agent.config, localizado no diretório de instalação do agente. Adicione tags de instância personalizadas no formato key1:value1&key2:value2. Exemplo:
```
#profiler.tags.customtags=key1:value1&key2:value2
profiler.tags.customtags=gitVersion:1.0.2&ip:192.168.1.101
```
Reinicie o processo da aplicação.

Aplicações Go

Declare uma variável de ambiente e reinicie o processo da aplicação.

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

Aplicações Python

Declare uma variável de ambiente e reinicie o processo da aplicação.

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

Injetar tags de aplicação via rótulos de pod

Importante

Para aplicações Java, apenas o componente ack-onepilot v3.0.16 ou posterior suporta a injeção de tags de aplicação via rótulos de pod.
No caso de aplicações Go, o suporte à injeção de tags via rótulos de pod exige o componente ack-onepilot v3.2.0 ou superior.
Para aplicações Python, utilize o componente ack-onepilot v4.1.1 ou posterior para injetar tags via rótulos de pod.
O Método 2 para injeção de tags de aplicação requer o ack-onepilot v4.1.2 ou versão mais recente.

Método 1:

Se um rótulo de pod possuir o prefixo app.customAppKey., o ARMS o identifica como uma tag de aplicação, e não como uma tag de instância.

Por exemplo, no código abaixo, o ARMS adiciona a tag de aplicação env: dev à aplicação associada a este workload.

  template:
    metadata:
      labels:
        app.customAppKey.env: dev
        app: mall-gateway
        armsPilotAutoEnable: 'on'
        aliyun.com/app-language: golang  # Required for Go applications to identify the application language. Not required for Java applications.
        armsPilotCreateAppName: mall-gateway

Método 2:

Para reutilizar rótulos de pod existentes como tags de aplicação, configure o componente ack-onepilot.

Pré-requisitos

A versão do ack-onepilot deve ser 4.1.2 ou superior.

Procedimento

Localize o Deployment do componente ack-onepilot. Geralmente, ele se chama ack-onepilot-ack-onepilot e está localizado no namespace ack-onepilot.

Confirme se a contagem de pods do Deployment exibe 2/2, indicando que o componente ack-onepilot está executando corretamente.
Adicione a variável de ambiente ARMS_APP_LABELS ao Deployment do componente ack-onepilot. Esta variável é uma string de chaves separadas por vírgulas. Após essa configuração, qualquer chave em /spec/template/metadata/labels listada na variável ARMS_APP_LABELS será identificada como uma tag de aplicação.

Por exemplo, se você definir o valor de ARMS_APP_LABELS como env,group, as tags com as chaves env e group nos rótulos do pod serão identificadas como tags de aplicação.
Aguarde o reinício do componente ack-onepilot e a aprovação nas verificações de integridade. Em seguida, reinicie sua aplicação para aplicar as tags.

No console do ACK, na página de detalhes do Deployment ack-onepilot-ack-onepilot, confirme se o status de prontidão é 2/2 e se o status de todos os pods é Running. Isso indica que o componente está pronto.

Nota

No ARMS, uma aplicação é um conceito agregado que representa um conjunto de instâncias. Uma aplicação pode ter múltiplas instâncias, provenientes de diversos workloads ou clusters Kubernetes. Portanto, injetar tags de aplicação via rótulos de pod é uma prática conveniente para cenários de DevOps, mas apresenta certas limitações.
Tags de aplicação injetadas por rótulos de pod podem apenas ser adicionadas. Não é possível removê-las excluindo o rótulo do YAML. Para modificar ou excluir uma tag, utilize o console do ARMS ou a OpenAPI.
Se múltiplos workloads mapearem para a mesma aplicação ARMS, a injeção de tags via rótulos de pod pode causar conflitos. Garanta a consistência das tags de aplicação entre esses workloads.

Usar tags de aplicação

Filtrar aplicações

Na página Application List do ARMS e durante a criação de regras de alerta, utilize tags de aplicação para filtrar aplicações rapidamente.

Controle de acesso baseado em tags

Gerencie permissões do Resource Access Management (RAM) com base em tags de aplicação. Para mais informações, consulte Políticas personalizadas do RAM para Application Monitoring.

Usar tags de instância

Filtrar dados por tag de instância

Faça login no console do ARMS. No painel de navegação à esquerda, escolha Application Monitoring > Application List.
Na página Application List, selecione uma região no topo e clique no nome da aplicação desejada.

Nota
Os ícones na coluna Language indicam a linguagem de programação da aplicação:

: Uma aplicação Java conectada ao Application Monitoring.

: Uma aplicação Go conectada ao Application Monitoring.

: Uma aplicação Python conectada ao Application Monitoring.

-: Uma aplicação conectada ao Managed Service for OpenTelemetry.
Nas páginas de detalhes da aplicação, filtre os dados de monitoramento por tags de instância. Por exemplo, compare e analise dados com base nos números de versão da imagem.

Consultar métricas por tag no Grafana

Faça login no console do ARMS. No painel de navegação à esquerda, escolha Application Monitoring > Application List.
Na página Application List, selecione uma região no topo e clique no nome da aplicação desejada.

Nota
Os ícones na coluna Language indicam a linguagem de programação da aplicação:

: Uma aplicação Java conectada ao Application Monitoring.

: Uma aplicação Go conectada ao Application Monitoring.

: Uma aplicação Python conectada ao Application Monitoring.

-: Uma aplicação conectada ao Managed Service for OpenTelemetry.
No painel de navegação à esquerda, clique em Grafana View. No topo da página, selecione diferentes tags para filtrar as métricas.