Escrever métricas do Prometheus usando o arquivo secundário do Prometheus

O arquivo secundário do Managed Service para Prometheus do Cloud Run é a maneira recomendada pelo Google para receber monitoramento no estilo do Prometheus para serviços do Cloud Run. Se o serviço do Cloud Run gravar métricas do OTLP, use o arquivo secundário do OpenTelemetry. No entanto, para serviços que gravam métricas do Prometheus, use o arquivo secundário do Managed Service para Prometheus descrito neste documento.

Este documento explica como fazer o seguinte:

• Adicione o arquivo secundário do Managed Service para Prometheus a um serviço atual do Cloud Run.
• Crie um app de exemplo com o arquivo secundário. É possível usar o app de exemplo para ver como o arquivo secundário funciona se você não tiver um serviço do Cloud Run.

O arquivo secundário usa o Google Cloud Managed Service para Prometheus no lado do servidor e uma distribuição do OpenTelemetry Collector, personalizado para cargas de trabalho sem servidor, no lado do cliente. Essa distribuição personalizada inclui algumas alterações para oferecer suporte ao Cloud Run. O coletor executa uma raspagem de dados de inicialização após 10 segundos e de encerramento, não importa a duração da instância. Para máxima confiabilidade, recomendamos que os serviços do Cloud Run que executam o arquivo secundário também usem uma CPU sempre alocada. Para mais informações, consulte Alocação de CPU (serviços). Algumas tentativas de raspagem poderão falhar se a alocação da CPU for limitada devido ao baixo número de consultas por segundo (QPS). Uma CPU sempre alocada permanece disponível.

O arquivo secundário depende do recurso de vários contêineres (arquivo secundário) do Cloud Run para executar o coletor como um contêiner de arquivo secundário junto com o contêiner de carga de trabalho. Para mais informações sobre arquivos secundários no Cloud Run, consulte Como implantar vários contêineres em um serviço (arquivos secundários).

O arquivo secundário do Managed Service para Prometheus para Cloud Run apresenta uma nova configuração, RunMonitoring, um subconjunto do recurso personalizado PodMonitoring do Kubernetes. A maioria dos usuários pode usar a configuração RunMonitoring padrão, mas também é possível criar configurações personalizadas. Para mais informações sobre as configurações RunMonitoring padrão e personalizadas, consulte Adicionar o arquivo secundário a um serviço do Cloud Run.

Antes de começar

Esta seção descreve a configuração necessária para usar este documento.

Instalar e configurar a gcloud CLI

Muitas das etapas descritas neste documento usam a Google Cloud CLI. Para informações sobre como instalar a CLI gcloud, consulte Como gerenciar componentes da CLI do Google Cloud.

Ao invocar comandos gcloud, especifique o identificador para seu projeto do Google Cloud. É possível definir um projeto padrão para a Google Cloud CLI e eliminar a necessidade de inseri-lo com todos os comandos. Para definir seu projeto como padrão, digite este comando:

gcloud config set project PROJECT_ID

Também é possível definir uma região padrão para o serviço do Cloud Run. Para definir uma região padrão, digite o seguinte comando:

gcloud config set run/region REGION

Ativar APIs

Ative as seguintes APIs no seu projeto do Google Cloud:

• API Cloud Run Admin: run.googleapis.com
• API Artifact Registry: artifactregistry.googleapis.com
• API Cloud Monitoring: monitoring.googleapis.com
• API Cloud Logging: logging.googleapis.com
• (Opcional) Se você criar uma configuração RunMonitoring personalizada, será necessário ativar a API Secret Manager: secretmanager.googleapis.com
• (Opcional) Se você executar o aplicativo de amostra usando o Cloud Build, também será necessário ativar as seguintes APIs:
  • API Cloud Build: cloudbuild.googleapis.com
  • API Identity and Access Management: iam.googleapis.com Para saber mais, consulte Criar e executar o app de exemplo.

Para conferir as APIs ativadas no seu projeto, execute o seguinte comando:

gcloud services list

Para ativar uma API que não está ativada, execute um dos seguintes comandos:

gcloud services enable run.googleapis.com
gcloud services enable artifactregistry.googleapis.com
gcloud services enable secretmanager.googleapis.com
gcloud services enable monitoring.googleapis.com
gcloud services enable logging.googleapis.com
gcloud services enable cloudbuild.googleapis.com
gcloud services enable iam.googleapis.com

Conta de serviço do Cloud Run

Por padrão, os jobs e serviços do Cloud Run usam a conta de serviço padrão do Compute Engine, PROJECT_NUMBER-compute@developer.gserviceaccount.com. Essa conta de serviço geralmente tem os papéis do Identity and Access Management (IAM) necessários para gravar as métricas e os registros descritos neste documento:

• roles/monitoring.metricWriter
• roles/logging.logWriter

Se você criar uma configuração RunMonitoring personalizada, sua conta de serviço também precisará ter os seguintes papéis:

• roles/secretmanager.admin
• roles/secretmanager.secretAccessor

Também é possível configurar uma conta de serviço gerenciada pelo usuário para o Cloud Run. Uma conta de serviço gerenciada pelo usuário também precisa ter esses papéis. Para mais informações sobre contas de serviço do Cloud Run, consulte Como configurar a identidade do serviço.

Configurar e adicionar o arquivo secundário a um serviço do Cloud Run

O arquivo secundário do Managed Service para Prometheus do Cloud Run apresenta uma nova configuração, RunMonitoring, que é um subconjunto do recurso personalizado PodMonitoring do Kubernetes. A configuração RunMonitoring usa as opções PodMonitoring existentes para oferecer suporte ao Cloud Run e eliminar algumas opções específicas do Kubernetes.

É possível usar a configuração RunMonitoring padrão ou criar uma configuração personalizada. As seções abaixo descrevem as duas abordagens. Não é necessário fazer as duas. Para mais informações sobre como usar configurações padrão ou personalizadas, selecione a guia correspondente.

apiVersion: monitoring.googleapis.com/v1beta
kind: RunMonitoring
metadata:
  name: run-gmp-sidecar
spec:
  endpoints:
  - port: 8080
    path: /metrics
    interval: 30s

apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  annotations:
    run.googleapis.com/launch-stage: ALPHA
    run.googleapis.com/cpu-throttling: 'false'
  name: my-cloud-run-service
spec:
  template:
    metadata:
      annotations:
        run.googleapis.com/execution-environment: gen2
+       run.googleapis.com/container-dependencies: '{"collector":["app"]}'
    spec:
      containers:
      - image: "REGION-docker.pkg.dev/PROJECT_ID/run-gmp/sample-app"
        name: app
        startupProbe:
          httpGet:
            path: /startup
            port: 8000
        livenessProbe:
          httpGet:
            path: /liveness
            port: 8000
        ports:
        - containerPort: 8000
+     - image: "us-docker.pkg.dev/cloud-ops-agents-artifacts/cloud-run-gmp-sidecar/cloud-run-gmp-sidecar:1.1.1"
+       name: collector

gcloud run services replace run-service.yaml --region=REGION

apiVersion: monitoring.googleapis.com/v1beta
kind: RunMonitoring
metadata:
  name: my-custom-cloud-run-job
spec:
  endpoints:
  - port: 8080
    path: /metrics
    interval: 10s
    metricRelabeling:
    - action: replace
      sourceLabels:
      - __address__
      targetLabel: label_key
      replacement: label_value
  targetLabels:
    metadata:
    - service
    - revision

gcloud secrets create mysecret --data-file=custom-config.yaml

gcloud secrets versions add mysecret --data-file=custom-config-updated.yaml

apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  annotations:
    run.googleapis.com/launch-stage: ALPHA
    run.googleapis.com/cpu-throttling: 'false'
  name: my-cloud-run-service
spec:
  template:
    metadata:
      annotations:
        run.googleapis.com/execution-environment: gen2
+       run.googleapis.com/container-dependencies: '{"collector":["app"]}'
+       run.googleapis.com/secrets: 'mysecret:projects/PROJECT_ID/secrets/mysecret'
    spec:
      containers:
      - image: "REGION-docker.pkg.dev/PROJECT_ID/run-gmp/sample-app"
        name: app
        startupProbe:
          httpGet:
            path: /startup
            port: 8000
        livenessProbe:
          httpGet:
            path: /liveness
            port: 8000
        ports:
        - containerPort: 8000
+     - image: "us-docker.pkg.dev/cloud-ops-agents-artifacts/cloud-run-gmp-sidecar/cloud-run-gmp-sidecar:1.1.1"
+       name: collector
+       volumeMounts:
+       - mountPath: /etc/rungmp/
+         name: config
+     volumes:
+     - name: config
+       secret:
+         items:
+         - key: latest
+           path: config.yaml
+         secretName: 'mysecret'

gcloud run services replace run-service.yaml --region=REGION

apiVersion: monitoring.googleapis.com/v1beta
kind: RunMonitoring
metadata:
  name: my-custom-cloud-run-job
spec:
  endpoints:
  - port: 8080
    path: /metrics
    interval: 10s
    metricRelabeling:
    - action: replace
      sourceLabels:
      - __address__
      targetLabel: label_key
      replacement: label_value
  targetLabels:
    metadata:
    - service
    - revision

Criar e executar um app de exemplo

Nesta seção, descrevemos como executar o arquivo secundário do Managed Service para Prometheus com um app de exemplo. Esta seção é opcional. Se você já tiver um serviço do Cloud Run e quiser implantar o arquivo secundário com ele, consulte Adicionar o arquivo secundário do Managed Service para Prometheus a um serviço do Cloud Run.

Clone o repositório run-gmp-sidecar

Para conseguir o app de exemplo e os arquivos de configuração dele, clone o repositório run-gmp-sidecar executando o seguinte comando:

git clone https://github.com/GoogleCloudPlatform/run-gmp-sidecar/

Depois de clonar o repositório, mude para o diretório run-gmp-sidecar:

cd run-gmp-sidecar

Criar e executar o app de exemplo

O app de exemplo requer o Docker ou um sistema de build de contêiner semelhante para Linux. Você pode criar e executar o app de amostra de uma das seguintes maneiras:

• Usar o Cloud Build para executar sem suporte local ao Docker. Se você usar o Cloud Build, também precisará ativar a API Cloud Build.
• Crie e execute o app de exemplo manualmente.

As seções a seguir descrevem as duas abordagens. Não é necessário fazer as duas. Para mais informações, selecione a guia de uma das abordagens.

./create-sa-and-ar.sh

gcloud builds submit . --config=cloudbuild-simple.yaml --region=REGION

Logs are available at [
https://console.cloud.google.com/cloud-build/builds/637860fb-7a14-46f2-861e-09c1dc4cea6b?project=PROJECT_NUMBER].

gcloud run services describe my-cloud-run-service --region=REGION --format="value(status.url)"

https://my-cloud-run-service-abcdefghij-ue.a.run.app

export GCP_PROJECT=PROJECT_ID
export REGION=REGION

gcloud artifacts repositories create run-gmp \
    --repository-format=docker \
    --location=${REGION}

apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  annotations:
    run.googleapis.com/launch-stage: ALPHA
    run.googleapis.com/cpu-throttling: 'false'
  name: my-cloud-run-service
spec:
  template:
    metadata:
      annotations:
        run.googleapis.com/execution-environment: gen2
        run.googleapis.com/container-dependencies: '{"collector":["app"]}'
    spec:
      containers:
      - image: "%SAMPLE_APP_IMAGE%"
        name: app
        startupProbe:
          httpGet:
            path: /startup
            port: 8000
        livenessProbe:
          httpGet:
            path: /liveness
            port: 8000
        ports:
        - containerPort: 8000
      - image: "us-docker.pkg.dev/cloud-ops-agents-artifacts/cloud-run-gmp-sidecar/cloud-run-gmp-sidecar:1.1.1"
        name: collector

sed -i s@%SAMPLE_APP_IMAGE%@REGION-docker.pkg.dev/${GCP_PROJECT}/run-gmp/sample-app@g run-service-simple.yaml

gcloud run services replace run-service-simple.yaml --region=REGION
   

https://my-cloud-run-service-abcdefghij-ue.a.run.app

gcloud run services set-iam-policy my-cloud-run-service policy.yaml --region=REGION

Verifique se o app está em execução:

Para verificar se o serviço do Cloud Run executou corretamente o app de exemplo, use o utilitário curl para acessar o endpoint metrics do serviço.

1. Defina a variável de ambiente SERVICE_URL como o URL do serviço do Cloud Run da etapa anterior:

   export SERVICE_URL=SERVICE_URL
   

2. Envie uma solicitação ao URL do serviço executando o seguinte comando:

   curl $SERVICE_URL
   

Se o app tiver sido iniciado com sucesso, você verá a seguinte resposta:

User request received!

Visualizar métricas do app no Metrics Explorer

O contêiner de amostra app grava as seguintes métricas:

• foo_metric: o horário atual como um valor de ponto flutuante (medidor).
• bar_metric: o horário atual como um valor de ponto flutuante (contador).

Para visualizar essas métricas no Metrics Explorer, faça o seguinte:

1. No Console do Google Cloud, acesse a página do leaderboard Metrics Explorer:

   Acesse o Metrics explorer

   Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Monitoring.

2. Na barra de ferramentas do painel do criador de consultas, selecione o botão code MQL ou code PromQL.

3. Verifique se PromQL está selecionado na opção de ativar/desativar Idioma. A alternância de idiomas está na mesma barra de ferramentas que permite formatar sua consulta.

4. Insira a seguinte consulta no painel do editor:

   foo_metric
   

5. Clique em Adicionar consulta.

6. Na barra de ferramentas do painel do criador de consultas, selecione o botão code MQL ou code PromQL.

7. Verifique se PromQL está selecionado na opção de ativar/desativar Idioma. A alternância de idiomas está na mesma barra de ferramentas que permite formatar sua consulta.

8. Insira a seguinte consulta no segundo painel do editor:

   bar_metric
   

9. Clique em Executar consulta.

10. Para ver detalhes sobre as métricas, no seletor chamado Tabela de gráficos Ambos, selecione Ambos.

Limpeza

Quando terminar de testar o app de exemplo, use o script clean-up-cloud-run.sh no repositório run-gmp-sidecar para excluir os seguintes recursos que você possa ter criado para a amostra:

• O serviço do Cloud Run.
• O repositório do Artifact Registry.
• A conta de serviço criada para o Cloud Build.

A exclusão desses recursos garante que não haja custos após a execução da amostra.

Para limpar o app de exemplo, execute o script clean-up-cloud-run.sh:

./clean-up-cloud-run.sh

Visualizar métricas próprias no Metrics Explorer

O arquivo secundário do Managed Service para Prometheus informa as seguintes métricas sobre si mesmo ao Cloud Monitoring:

• agent_uptime: o tempo de atividade do coletor de arquivos secundários (contador).
• agent_memory_usage: a memória consumida pelo coletor de arquivo secundário (medidor).
• agent_api_request_count: o número de solicitações de API do coletor secundário (contador).
• agent_monitoring_point_count: o número de pontos de métricas gravados no Cloud Monitoring pelo coletor do arquivo secundário (contador).

Para visualizar as próprias métricas do arquivo secundário no Metrics Explorer, faça o seguinte:

1. No Console do Google Cloud, acesse a página do leaderboard Metrics Explorer:

   Acesse o Metrics explorer

   Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Monitoring.

2. Na barra de ferramentas do painel do criador de consultas, selecione o botão code MQL ou code PromQL.

3. Verifique se PromQL está selecionado na opção de ativar/desativar Idioma. A alternância de idiomas está na mesma barra de ferramentas que permite formatar sua consulta.

4. Insira o nome da métrica que você quer consultar no painel do editor, por exemplo:

   agent_api_request_count
   

5. Clique em Executar consulta.

6. Para ver detalhes sobre as métricas, no seletor chamado Tabela de gráficos Ambos, selecione Ambos.

Visualizar os registros próprios na Análise de registros

O arquivo secundário do Managed Service para Prometheus grava registros no Cloud Logging. O arquivo secundário grava registros no tipo de recurso monitorado do Logging cloud_run_revision.

Para visualizar os registros do arquivo secundário na Análise de registros, faça o seguinte:

1. No console do Google Cloud, acesse a página do Análise de registros.

   Acessar a Análise de registros

   Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Geração de registros.

2. Selecione o tipo de recurso Revisão do Cloud Run ou insira a consulta a seguir e clique em Executar consulta:

   resource.type="cloud_run_revision"
   

Sobre as métricas coletadas

Quando as métricas emitidas pelo arquivo secundário são ingeridas no Cloud Monitoring, as métricas são gravadas em relação ao tipo de recurso monitorado prometheus_target do Cloud Monitoring. Esse tipo de recurso é usado tanto para métricas do aplicativo quanto métricas próprias do arquivo secundário.

Ao gravar as métricas, o arquivo secundário define os rótulos de recursos da seguinte maneira:

• project_id: o ID do projeto do Google Cloud em que o contêiner está em execução.
• location: a região do Google Cloud em que o contêiner está sendo executado.
• cluster: o valor __run__.
• namespace: o nome do serviço do Cloud Run em execução vem da variável de ambiente K_SERVICE.
• job: nome da configuração RunMonitoring; o padrão é run-gmp-sidecar.
• instance: o valor faas.ID:PORT da carga de trabalho local de que o contêiner está configurado para extrair métricas. O valor faas.ID é o ID da instância do Cloud Run.

O arquivo secundário também adiciona os seguintes rótulos de métricas:

• instanceId: o ID da instância do Cloud Run.
• service_name: o nome do serviço do Cloud Run em execução.
• revision_name: o nome da revisão do Cloud Run em execução.
• configuration_name: o nome da configuração do Cloud Run em execução.

Esses rótulos de métricas são adicionados por padrão. Se você usar uma configuração RunMonitoring personalizada, poderá omitir os rótulos service_name, revision_name e configuration_name usando o Opção targetLabels na especificação RunMonitoring. Também é possível usar uma configuração personalizada para remarcar os valores dos rótulos service_name, revision_name e configuration_name.

Todos os outros rótulos que aparecem com as métricas ingeridas vêm da sua métrica. Se um rótulo definido pelo usuário entrar em conflito com um dos fornecidos pelo sistema, o rótulo definido pelo usuário será prefixado com a string exported_. Por exemplo, um rótulo especificado pelo usuário namespace="playground" entra em conflito com o rótulo namespace definido pelo sistema, então o rótulo do usuário aparece como exported_namespace="playground".

Tipo de métrica

Quando as métricas emitidas pelo arquivo secundário são ingeridas no Cloud Monitoring, as métricas são gravadas como prometheus.googleapis.com, e o tipo da métrica do Prometheus é anexado ao final do nome. Por exemplo, o app de exemplo emite uma métrica de medidor do Prometheus chamada foo_metric. No Cloud Monitoring, a métrica é armazenada como o tipo de métrica prometheus.googleapis.com/foo_metric/gauge.

Ao consultar a métrica com PromQL, é possível usar o nome do Prometheus, conforme ilustrado em Visualizar métricas do app no Metrics Explorer e Visualizar métricas próprias no Metrics Explorer. Ao usar ferramentas como o criador de consultas ou a linguagem de consulta do Monitoring (MQL, na sigla em inglês) no Metrics Explorer, o tipo de métrica do Cloud Monitoring é relevante.

Faturamento

As métricas emitidas pelo arquivo secundário são ingeridas no Cloud Monitoring com o prefixo prometheus.googleapis.com. As métricas com esse prefixo são cobradas pelo número de amostras ingeridas. Para mais informações sobre faturamento e o Managed Service para Prometheus, consulte Faturamento.