Primeiros passos com o OpenTelemetry Collector

Neste documento, descrevemos como configurar o OpenTelemetry Collector para coletar métricas padrão do Prometheus e informá-las ao Google Cloud Managed Service para Prometheus. O OpenTelemetry Collector é um agente que pode ser implantado e configurado para exportar para o Managed Service para Prometheus. A configuração é semelhante à execução do Managed Service para Prometheus com coleção autoimplantada.

É possível escolher o coletor do OpenTelemetry em vez da coleção implantada automaticamente pelos seguintes motivos:

  • O OpenTelemetry Collector permite encaminhar dados de telemetria para vários back-ends configurando diferentes exportadores no pipeline.
  • O Collector também é compatível com sinais de métricas, registros e traces. Portanto, ao usá-lo, é possível lidar com todos os três tipos de indicadores em um agente.
  • O formato de dados independentes de fornecedor (OpenOTelemetry Protocol, ou OTLP) do OpenTelemetry é compatível com um forte ecossistema de bibliotecas e componentes do Collector conectáveis. Isso oferece várias opções de personalização para receber, processar e exportar dados.

A desvantagem desses benefícios é que a execução do OpenTelemetry Collector exige uma abordagem de implantação e manutenção autogerenciada. A abordagem escolhida depende das suas necessidades específicas, mas, neste documento, oferecemos diretrizes recomendadas para configurar o OpenTelemetry Collector usando o Managed Service para Prometheus como back-end.

Antes de começar

Nesta seção, descrevemos a configuração necessária para as tarefas descritas neste documento.

Configurar projetos e ferramentas

Para usar o Google Cloud Managed Service para Prometheus, você precisa dos seguintes recursos:

  • Um projeto do Google Cloud com a API Cloud Monitoring ativada.

    • Se você não tiver um projeto do Google Cloud, faça o seguinte:

      1. No Console do Google Cloud, acesse Novo projeto:

        Crie um novo projeto

      2. No campo Project Name, insira um nome para o projeto e clique em Criar.

      3. Acesse o Faturamento:

        Acessar "Faturamento"

      4. Selecione o projeto recém-criado se ele ainda não estiver selecionado na parte superior da página.

      5. Você precisará escolher um perfil para pagamentos atual ou criar um novo.

      A API Monitoring é ativada por padrão para novos projetos.

    • Se você já tem um projeto do Google Cloud, verifique se a API Monitoring está ativada:

      1. Acessar APIs e serviços

        Acessar APIs e serviços

      2. Selecione o projeto.

      3. Clique em Ativar APIs e serviços.

      4. Pesquise "Monitoring".

      5. Nos resultados da pesquisa, clique em "API Cloud Monitoring".

      6. Se a opção "API ativada" não for exibida, clique no botão Ativar.

  • Um cluster do Kubernetes. Se você não tiver um cluster do Kubernetes, siga as instruções no Guia de início rápido do GKE.

Você também precisa das seguintes ferramentas de linha de comando:

  • gcloud
  • kubectl

As ferramentas gcloud e kubectl fazem parte da Google Cloud CLI. Para mais informações sobre como instalá-los, consulte Como gerenciar componentes da CLI do Google Cloud. Para ver os componentes da CLI gcloud que você instalou, execute o seguinte comando:

gcloud components list

Configurar o ambiente

Para evitar inserir repetidamente o ID do projeto ou o nome do cluster, execute a seguinte configuração:

  • Configure as ferramentas de linha de comando da seguinte maneira:

    • Configure a CLI gcloud para se referir ao ID do projeto do Google Cloud:

      gcloud config set project PROJECT_ID

    • Configure a CLI kubectl para usar o cluster:

      kubectl config set-cluster CLUSTER_NAME

    Para mais informações sobre essas ferramentas, consulte estes recursos:

Configurar um namespace

Crie o namespace NAMESPACE_NAME do Kubernetes para os recursos que você criar como parte do aplicativo de exemplo:

kubectl create ns NAMESPACE_NAME

Verificar as credenciais da conta de serviço

Pule essa seção se o cluster do Kubernetes tiver a Identidade da carga de trabalho ativada.

Quando executado no GKE, o Managed Service para Prometheus recuperará automaticamente as credenciais do ambiente com base na conta de serviço padrão do Compute Engine. A conta de serviço padrão tem as permissões necessárias, monitoring.metricWriter e monitoring.viewer, por padrão. Se você não usar a Identidade da carga de trabalho e tiver removido qualquer um desses papéis da conta de serviço do nó padrão, será necessário adicionar novamente essas permissões que faltam antes de continuar.

Se você não estiver executando no GKE, consulte Fornecer credenciais explicitamente.

Configurar uma conta de serviço para a Identidade da carga de trabalho

Você poderá pular esta seção se o cluster do Kubernetes não tiver a Identidade da carga de trabalho ativada.

O Managed Service para Prometheus captura dados de métricas usando a API Cloud Monitoring. Se o cluster estiver usando a identidade da carga de trabalho, você precisa conceder permissão à conta de serviço do Kubernetes para a API Monitoring. Esta seção descreve:

Criar e vincular a conta de serviço

Essa etapa aparece em vários lugares na documentação do Managed Service para Prometheus. Se você já realizou esta etapa como parte de uma tarefa anterior, não é necessário repeti-la. Pule para Autorizar a conta de serviço.

A sequência de comandos a seguir cria a conta de serviço gmp-test-sa e a vincula à conta de serviço padrão do Kubernetes no namespace NAMESPACE_NAME:

gcloud config set project PROJECT_ID \
&&
gcloud iam service-accounts create gmp-test-sa \
&&
gcloud iam service-accounts add-iam-policy-binding \
  --role roles/iam.workloadIdentityUser \
  --member "serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE_NAME/default]" \
  gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \
&&
kubectl annotate serviceaccount \
  --namespace NAMESPACE_NAME \
  default \
  iam.gke.io/gcp-service-account=gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com

Se você estiver usando um namespace ou uma conta de serviço diferente do GKE, ajuste os comandos adequadamente.

Autorizar a conta de serviço

Grupos de permissões relacionadas são coletados em papéis, e você concede os papéis a um principal, neste exemplo, a conta de serviço do Google Cloud. Para mais informações sobre os papéis do Monitoring, consulte Controle de acesso.

O comando a seguir concede à conta de serviço do Google Cloud, gmp-test-sa, os papéis da API Monitoring necessários para gravar dados de métricas.

Se você já concedeu à conta de serviço do Google Cloud um papel específico como parte da tarefa anterior, não é necessário fazer isso novamente.

gcloud projects add-iam-policy-binding PROJECT_ID\
  --member=serviceAccount:gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \
  --role=roles/monitoring.metricWriter

Depurar a configuração da Identidade da carga de trabalho

Se você estiver com problemas para fazer a Identidade da carga de trabalho funcionar, consulte a documentação para verificar a configuração da Identidade da carga de trabalho e o Guia de solução de problemas da Identidade da carga de trabalho.

Como erros de digitação e cópias e colagens incompletas são as fontes mais comuns de erros ao configurar a Identidade da carga de trabalho, é altamente recomendável usar as variáveis editáveis e os ícones clicáveis de copiar/colar incorporados nos exemplos de código nestas instruções.

Identidade da carga de trabalho em ambientes de produção

O exemplo descrito neste documento vincula a conta de serviço do Google Cloud à conta de serviço padrão do Kubernetes e concede à conta de serviço do Google Cloud todas as permissões necessárias para usar a API Monitoring.

Em um ambiente de produção, convém usar uma abordagem mais refinada, com uma conta de serviço para cada componente, cada uma com permissões mínimas. Para mais informações sobre como configurar contas de serviço para gerenciamento de identidades de carga de trabalho, consulte Como usar a Identidade da carga de trabalho.

Configurar o OpenTelemetry Collector

Nesta seção, vamos mostrar como configurar e usar o OpenTelemetry Collector para extrair métricas de um aplicativo de exemplo e enviar os dados para o Google Cloud Managed Service para Prometheus. Para informações de configuração detalhadas, consulte as seguintes seções:

O coletor do OpenTelemetry é análogo ao binário de agente do Managed Service para Prometheus. A comunidade do OpenTelemetry publica regularmente versões, incluindo código-fonte, binários e imagens de contêiner.

É possível implantar esses artefatos em VMs ou clusters do Kubernetes usando as práticas recomendadas padrão ou usar o criador de coletores para criar seu próprio coletor, consistindo apenas no componentes necessários. Para criar um coletor para uso com o Managed Service para Prometheus, você precisa dos seguintes componentes:

  • O Exportador do Managed Service para Prometheus, que grava suas métricas no Managed Service para Prometheus.
  • Um receptor para extrair suas métricas. Neste documento, presumimos que você esteja usando o receptor do OpenTelemetry Prometheus, mas o exportador do Managed Service para Prometheus é compatível com qualquer receptor de métricas do OpenTelemetry.
  • Processadores para agrupar e marcar suas métricas em lotes para incluir identificadores de recursos importantes, dependendo do seu ambiente.

Esses componentes são ativados usando um arquivo de configuração transmitido ao Collector com a sinalização --config.

As seções a seguir explicam como configurar cada um desses componentes com mais detalhes. Neste documento, descrevemos como executar o coletor no GKE e em outro lugar.

Configurar e implantar o Collector

Não importa se você está executando a coleção no Google Cloud ou em outro ambiente, ainda é possível configurar o Coletor OpenTelemetry para exportar para o Managed Service para Prometheus. A maior diferença está em como você configura o coletor. Em ambientes que não são do Google Cloud, pode haver mais formatação de dados de métricas necessários para que ela seja compatível com o Managed Service para Prometheus. No entanto, no Google Cloud, grande parte dessa formatação pode ser detectada automaticamente pelo Collector.

Executar o OpenTelemetry Collector no GKE

É possível copiar a configuração a seguir em um arquivo chamado config.yaml para configurar o OpenTelemetry Collector no GKE:

receivers:
  prometheus:
    config:
      scrape_configs:
      - job_name: 'SCRAPE_JOB_NAME'
        kubernetes_sd_configs:
        - role: pod
        relabel_configs:
        - source_labels: [__meta_kubernetes_pod_label_app_kubernetes_io_name]
          action: keep
          regex: prom-example
        - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_path]
          action: replace
          target_label: __metrics_path__
          regex: (.+)
        - source_labels: [__address__, __meta_kubernetes_pod_annotation_prometheus_io_port]
          action: replace
          regex: (.+):(?:\d+);(\d+)
          replacement: $1:$2
          target_label: __address__
        - action: labelmap
          regex: __meta_kubernetes_pod_label_(.+)

processors:
  resourcedetection:
    detectors: [gcp]
    timeout: 10s

  transform:
    # "location", "cluster", "namespace", "job", "instance", and "project_id" are reserved, and
    # metrics containing these labels will be rejected.  Prefix them with exported_ to prevent this.
    metric_statements:
    - context: datapoint
      statements:
      - set(attributes["exported_location"], attributes["location"])
      - delete_key(attributes, "location")
      - set(attributes["exported_cluster"], attributes["cluster"])
      - delete_key(attributes, "cluster")
      - set(attributes["exported_namespace"], attributes["namespace"])
      - delete_key(attributes, "namespace")
      - set(attributes["exported_job"], attributes["job"])
      - delete_key(attributes, "job")
      - set(attributes["exported_instance"], attributes["instance"])
      - delete_key(attributes, "instance")
      - set(attributes["exported_project_id"], attributes["project_id"])
      - delete_key(attributes, "project_id")

  batch:
    # batch metrics before sending to reduce API usage
    send_batch_max_size: 200
    send_batch_size: 200
    timeout: 5s

  memory_limiter:
    # drop metrics if memory usage gets too high
    check_interval: 1s
    limit_percentage: 65
    spike_limit_percentage: 20

# Note that the googlemanagedprometheus exporter block is intentionally blank
exporters:
  googlemanagedprometheus:

service:
  pipelines:
    metrics:
      receivers: [prometheus]
      processors: [batch, memory_limiter, resourcedetection, transform]
      exporters: [googlemanagedprometheus]

A configuração anterior usa o receptor do Prometheus e o exportador do Managed Service para o Prometheus para extrair os endpoints de métricas nos pods do Kubernetes e exportar para o Managed Service para Prometheus. Os processadores de pipelines formatam e agrupam os dados em lote.

Para saber mais detalhes sobre o que cada parte dessa configuração faz, além de configurações para diferentes plataformas, consulte as seções detalhadas abaixo sobre como extrair dados e como adicionar processadores.

Ao executar em clusters com uma configuração atual do Prometheus, substitua todos os caracteres $ por $$ para evitar o acionamento da substituição de variável de ambiente. Para mais informações, consulte Métricas do Scrape Prometheus.

É possível modificar essa configuração com base no ambiente, no provedor e nas métricas que você quer extrair, mas a configuração de exemplo é um ponto de partida recomendado para executar no GKE.

Executar o OpenTelemetry Collector fora do Google Cloud

Executar o OpenTelemetry Collector fora do Google Cloud, como no local ou em outros provedores de nuvem, é semelhante a executar o Collector no GKE. No entanto, as métricas copiadas são menos prováveis de incluir automaticamente os dados que melhor formatam esses dados para o Managed Service para Prometheus. Portanto, é preciso cuidado para configurar o coletor e formatar as métricas para que elas sejam compatíveis com o Managed Service para Prometheus.

É possível definir a configuração a seguir em um arquivo chamado config.yaml para configurar o OpenTelemetry Collector para implantação em um cluster do Kubernetes que não seja do GKE:

receivers:
  prometheus:
    config:
      scrape_configs:
      - job_name: 'SCRAPE_JOB_NAME'
        kubernetes_sd_configs:
        - role: pod
        relabel_configs:
        - source_labels: [__meta_kubernetes_pod_label_app_kubernetes_io_name]
          action: keep
          regex: prom-example
        - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_path]
          action: replace
          target_label: __metrics_path__
          regex: (.+)
        - source_labels: [__address__, __meta_kubernetes_pod_annotation_prometheus_io_port]
          action: replace
          regex: (.+):(?:\d+);(\d+)
          replacement: $1:$2
          target_label: __address__
        - action: labelmap
          regex: __meta_kubernetes_pod_label_(.+)

processors:
  resource:
    attributes:
    - key: "cluster"
      value: "CLUSTER_NAME"
      action: upsert
    - key: "namespace"
      value: "NAMESPACE_NAME"
      action: upsert
    - key: "location"
      value: "REGION"
      action: upsert

  transform:
    # "location", "cluster", "namespace", "job", "instance", and "project_id" are reserved, and
    # metrics containing these labels will be rejected.  Prefix them with exported_ to prevent this.
    metric_statements:
    - context: datapoint
      statements:
      - set(attributes["exported_location"], attributes["location"])
      - delete_key(attributes, "location")
      - set(attributes["exported_cluster"], attributes["cluster"])
      - delete_key(attributes, "cluster")
      - set(attributes["exported_namespace"], attributes["namespace"])
      - delete_key(attributes, "namespace")
      - set(attributes["exported_job"], attributes["job"])
      - delete_key(attributes, "job")
      - set(attributes["exported_instance"], attributes["instance"])
      - delete_key(attributes, "instance")
      - set(attributes["exported_project_id"], attributes["project_id"])
      - delete_key(attributes, "project_id")

  batch:
    # batch metrics before sending to reduce API usage
    send_batch_max_size: 200
    send_batch_size: 200
    timeout: 5s

  memory_limiter:
    # drop metrics if memory usage gets too high
    check_interval: 1s
    limit_percentage: 65
    spike_limit_percentage: 20

exporters:
  googlemanagedprometheus:
    project: "PROJECT_ID"

service:
  pipelines:
    metrics:
      receivers: [prometheus]
      processors: [batch, memory_limiter, resource, transform]
      exporters: [googlemanagedprometheus]

Essa configuração faz o seguinte:

Ao executar em clusters com uma configuração atual do Prometheus, substitua todos os caracteres $ por $$ para evitar o acionamento da substituição de variável de ambiente. Para mais informações, consulte Métricas do Scrape Prometheus.

Para informações sobre as práticas recomendadas para configurar o coletor em outras nuvens, consulte Amazon EKS ou Azure AKS.

Implantar o aplicativo de exemplo

O aplicativo de exemplo emite a métrica de contador example_requests_total e a métrica de histograma example_random_numbers (entre outras) na porta metrics. O manifesto desse exemplo define três réplicas.

Para implantar o aplicativo de exemplo, execute o seguinte comando:

kubectl -n NAMESPACE_NAME apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/v0.8.2/examples/example-app.yaml

Criar a configuração do coletor como um ConfigMap

Depois de criar a configuração e colocá-la em um arquivo chamado config.yaml, use esse arquivo para criar um ConfigMap do Kubernetes com base no arquivo config.yaml. Quando o coletor é implantado, ele monta o ConfigMap e carrega o arquivo.

Para criar um ConfigMap chamado otel-config com a sua configuração, use o seguinte comando:

kubectl -n NAMESPACE_NAME create configmap otel-config --from-file config.yaml

Implantar o coletor

Crie um arquivo chamado collector-deployment.yaml com o conteúdo a seguir:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: NAMESPACE_NAME:prometheus-test
rules:
- apiGroups: [""]
  resources:
  - pods
  verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: NAMESPACE_NAME:prometheus-test
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: NAMESPACE_NAME:prometheus-test
subjects:
- kind: ServiceAccount
  namespace: NAMESPACE_NAME
  name: default
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: otel-collector
spec:
  replicas: 1
  selector:
    matchLabels:
      app: otel-collector
  template:
    metadata:
      labels:
        app: otel-collector
    spec:
      containers:
      - name: otel-collector
        image: otel/opentelemetry-collector-contrib:0.92.0
        args:
        - --config
        - /etc/otel/config.yaml
        volumeMounts:
        - mountPath: /etc/otel/
          name: otel-config
      volumes:
      - name: otel-config
        configMap:
          name: otel-config

Crie a implantação do coletor no cluster do Kubernetes executando o seguinte comando:

kubectl -n NAMESPACE_NAME create -f collector-deployment.yaml

Depois de iniciar o pod, ele verifica o aplicativo de amostra e informa as métricas ao Managed Service para Prometheus.

Para informações sobre as maneiras de consultar seus dados, veja Consultar usando o Cloud Monitoring ou Consultar usando o Grafana.

Fornecer credenciais explicitamente

Durante a execução no GKE, o avaliador de regras recupera as credenciais automaticamente do ambiente com base na conta de serviço do nó. Em clusters do Kubernetes que não são do GKE, as credenciais precisam ser explicitamente fornecidas ao OpenTelemetry Collector usando sinalizações ou a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS.

  1. Defina o contexto para seu projeto de destino:

    gcloud config set project PROJECT_ID

  2. Crie uma conta de serviço:

    gcloud iam service-accounts create gmp-test-sa

    Nesta etapa, é criada a conta de serviço que você pode já tiver criado nas instruções de Identidade da carga de trabalho.

  3. Conceda as permissões necessárias à conta de serviço:

    gcloud projects add-iam-policy-binding PROJECT_ID\
  --member=serviceAccount:gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \
  --role=roles/monitoring.metricWriter

  4. Crie e faça o download de uma chave para a conta de serviço:

    gcloud iam service-accounts keys create gmp-test-sa-key.json \
  --iam-account=gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com

  5. Adicione o arquivo de chave como secret ao cluster que não é do GKE:

    kubectl -n NAMESPACE_NAME create secret generic gmp-test-sa \
  --from-file=key.json=gmp-test-sa-key.json

  6. Abra o recurso de implantação do OpenTelemetry para edição:

    kubectl -n NAMESPACE_NAME edit deployment otel-collector

  1. Adicione o texto exibido em negrito ao recurso:

    apiVersion: apps/v1
kind: Deployment
metadata:
  namespace: NAMESPACE_NAME
  name: otel-collector
spec:
  template
    spec:
      containers:
      - name: otel-collector
        env:
        - name: "GOOGLE_APPLICATION_CREDENTIALS"
          value: "/gmp/key.json"
...
        volumeMounts:
        - name: gmp-sa
          mountPath: /gmp
          readOnly: true
...
      volumes:
      - name: gmp-sa
        secret:
          secretName: gmp-test-sa
...

  2. Salve o arquivo e feche o editor. Depois que a alteração é aplicada, os pods são recriados e começam a autenticar no back-end da métrica com a conta de serviço especificada.

Coletar métricas do Prometheus

Esta seção e a seção seguinte fornecem mais informações de personalização para usar o OpenTelemetry Collector. Essas informações podem ser úteis em determinadas situações, mas nenhuma delas é necessária para executar o exemplo descrito em Configurar o OpenTelemetry Collector.

Se os aplicativos já estiverem expondo endpoints do Prometheus, o OpenTelemetry Collector poderá coletar esses endpoints usando o mesmo formato de configuração de coleta que você usaria com qualquer configuração padrão do Prometheus. Para fazer isso, ative o receptor do Prometheus na configuração do coletor.

Uma configuração de receptor simples do Prometheus para pods do Kubernetes pode ter a seguinte aparência:

receivers:
  prometheus:
    config:
      scrape_configs:
      - job_name: 'kubernetes-pods'
        kubernetes_sd_configs:
        - role: pod
        relabel_configs:
        - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_scrape]
          action: keep
          regex: true
        - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_path]
          action: replace
          target_label: __metrics_path__
          regex: (.+)
        - source_labels: [__address__, __meta_kubernetes_pod_annotation_prometheus_io_port]
          action: replace
          regex: (.+):(?:\d+);(\d+)
          replacement: $1:$2
          target_label: __address__
        - action: labelmap
          regex: __meta_kubernetes_pod_label_(.+)

service:
  pipelines:
    metrics:
      receivers: [prometheus]

Essa é uma configuração de extração simples baseada em descoberta de serviços que você pode modificar conforme necessário para extrair seus aplicativos.

Ao executar em clusters com uma configuração atual do Prometheus, substitua todos os caracteres $ por $$ para evitar o acionamento da substituição de variável de ambiente. Isso é especialmente importante para o valor replacement na seção relabel_configs. Por exemplo, se você tiver a seguinte seção relabel_config:

- source_labels: [__address__, __meta_kubernetes_pod_annotation_prometheus_io_port]
  action: replace
  regex: (.+):(?:\d+);(\d+)
  replacement: $1:$2
  target_label: __address__

Em seguida, reescreva como:

- source_labels: [__address__, __meta_kubernetes_pod_annotation_prometheus_io_port]
  action: replace
  regex: (.+):(?:\d+);(\d+)
  replacement: $$1:$$2
  target_label: __address__

Para saber mais, consulte a documentação OpenTelemetry.

Em seguida, recomendamos que você use processadores para formatar as métricas. Em muitos casos, os processadores precisam ser usados para formatar as métricas corretamente.

Adicionar processadores

Os processadores do OpenTelemetry modificam os dados de telemetria antes da exportação. É possível usar os processadores abaixo para garantir que suas métricas sejam escritas em um formato compatível com o Managed Service para Prometheus.

Detectar atributos de recursos

O exportador do Managed Service para Prometheus para o OpenTelemetry usa o recurso monitorado prometheus_target para identificar exclusivamente pontos de dados de séries temporais. O exportador analisa os campos obrigatórios do recurso monitorado dos atributos de recursos nos pontos de dados das métricas. Os campos e os atributos de onde os valores são copiados são:

  • project_id: detectado automaticamente pelo Application Default Credentials, gcp.project.id ou project na configuração do exportador (consulte Como configurar o exportador)
  • local: location, cloud.availability_zone, cloud.region
  • cluster: cluster, k8s.cluster_name
  • namespace: namespace, k8s.namespace_name
  • job: service.name + service.namespace
  • instância: service.instance.id

Se esses rótulos não forem definidos como valores exclusivos, podem ocorrer erros de "série temporal duplicada" ao exportar para o Managed Service para Prometheus.

O receptor do Prometheus define automaticamente o atributo service.name com base em job_name na configuração de extração de dados e o atributo service.instance.id com base na instance de destino da extração. O receptor também define k8s.namespace.name ao usar role: pod na configuração da extração.

Recomendamos preencher os outros atributos automaticamente usando o processador de detecção de recursos. No entanto, dependendo do seu ambiente, alguns atributos podem não ser detectados automaticamente. Nesse caso, é possível usar outros processadores para inserir esses valores manualmente ou analisá-los a partir de rótulos de métricas. As seções a seguir ilustram as configurações para fazer esse processamento em várias plataformas

GKE

Ao executar o OpenTelemetry no GKE, você só precisa ativar o processador de detecção de recursos para preencher os rótulos de recursos. Verifique se as métricas ainda não contêm rótulos de recursos reservados. Se isso é inevitável, consulte Evitar conflitos de atributos de recursos renomeando atributos.

processors:
  resourcedetection:
    detectors: [gcp]
    timeout: 10s

Essa seção pode ser copiada diretamente para seu arquivo de configuração, substituindo a seção processors, se já existir.

Amazon EKS

O detector de recursos EKS não preenche automaticamente os atributos cluster ou namespace. É possível fornecer esses valores manualmente usando o processador de recursos, como mostrado no exemplo a seguir:

processors:
  resourcedetection:
    detectors: [eks]
    timeout: 10s

  resource:
    attributes:
    - key: "cluster"
      value: "my-eks-cluster"
      action: upsert
    - key: "namespace"
      value: "my-app"
      action: upsert

Também é possível converter esses valores de rótulos de métricas usando o processador groupbyattrs. Consulte Mover rótulos de métricas para rótulos de recursos abaixo.

Azure AKS

O detector de recursos AKS não preenche automaticamente os atributos cluster ou namespace. É possível fornecer esses valores manualmente usando o processador de recursos, conforme mostrado no exemplo a seguir:

processors:
  resourcedetection:
    detectors: [aks]
    timeout: 10s

  resource:
    attributes:
    - key: "cluster"
      value: "my-eks-cluster"
      action: upsert
    - key: "namespace"
      value: "my-app"
      action: upsert

Também é possível converter esses valores de rótulos de métricas usando o processador groupbyattrs. Consulte Mover rótulos de métricas para rótulos de recursos.

Ambientes locais e que não sejam de nuvem

Com ambientes locais ou que não sejam de nuvem, provavelmente não é possível detectar automaticamente nenhum dos atributos de recurso necessários. Nesse caso, é possível emitir esses rótulos nas métricas e movê-los para atributos de recursos (consulte Mover rótulos de métricas para rótulos de recursos) ou definir manualmente todos os atributos de recurso, como mostrado no exemplo a seguir:

processors:
  resource:
    attributes:
    - key: "cluster"
      value: "my-on-prem-cluster"
      action: upsert
    - key: "namespace"
      value: "my-app"
      action: upsert
    - key: "location"
      value: "us-east-1"
      action: upsert

Em Criar configuração do coletor como um ConfigMap, você verá como usar a configuração. Esta seção pressupõe que você colocou sua configuração em um arquivo chamado config.yaml.

O atributo de recurso project_id ainda pode ser definido automaticamente ao executar o coletor com o Application Default Credentials. Se o Collector não tiver acesso ao Application Default Credentials, consulte Como configurar project_id.

Como alternativa, é possível definir manualmente os atributos de recursos necessários em uma variável de ambiente, OTEL_RESOURCE_ATTRIBUTES, com uma lista separada por vírgulas de pares de chave-valor, por exemplo:

export OTEL_RESOURCE_ATTRIBUTES="cluster=my-cluster,namespace=my-app,location=us-east-1"

Em seguida, use o processador do detector de recursos env para definir os atributos do recurso:

processors:
  resourcedetection:
    detectors: [env]

Renomear os atributos para evitar conflitos de atributos de recursos

Se as métricas já tiverem rótulos que entrem em conflito com os atributos de recurso necessários (como location, cluster ou namespace), renomeie-os para evitar a colisão. A convenção do Prometheus é adicionar o prefixo exported_ ao nome do rótulo. Para adicionar esse prefixo, use o processador de transformação.

A configuração processors abaixo renomeia possíveis conflitos e resolve chaves conflitantes da métrica:

processors:
  transform:
    # "location", "cluster", "namespace", "job", "instance", and "project_id" are reserved, and
    # metrics containing these labels will be rejected.  Prefix them with exported_ to prevent this.
    metric_statements:
    - context: datapoint
      statements:
      - set(attributes["exported_location"], attributes["location"])
      - delete_key(attributes, "location")
      - set(attributes["exported_cluster"], attributes["cluster"])
      - delete_key(attributes, "cluster")
      - set(attributes["exported_namespace"], attributes["namespace"])
      - delete_key(attributes, "namespace")
      - set(attributes["exported_job"], attributes["job"])
      - delete_key(attributes, "job")
      - set(attributes["exported_instance"], attributes["instance"])
      - delete_key(attributes, "instance")
      - set(attributes["exported_project_id"], attributes["project_id"])
      - delete_key(attributes, "project_id")

Mover rótulos de métricas para rótulos de recursos

Em alguns casos, suas métricas podem relatar rótulos intencionalmente, como namespace, porque seu exportador está monitorando vários namespaces. Por exemplo, ao executar o exportador kube-state-metrics.

Nesse cenário, esses rótulos podem ser movidos para atributos de recursos usando o processador groupbyattrs:

processors:
  groupbyattrs:
    keys:
    - namespace
    - cluster
    - location

No exemplo acima, com uma métrica com os rótulos namespace, cluster e/ou location, esses rótulos serão convertidos para os atributos de recurso correspondentes.

Limitar solicitações de API e uso de memória

Dois outros processadores, o processador em lote e o processador do limitador de memória, permitem limitar o consumo de recursos do coletor.

Processamento em lote

Com as solicitações em lote, é possível definir quantos pontos de dados enviar em uma única solicitação. O Cloud Monitoring tem um limite de 200 séries temporais por solicitação. Ative o processador em lote usando as seguintes configurações:

processors:
  batch:
    # batch metrics before sending to reduce API usage
    send_batch_max_size: 200
    send_batch_size: 200
    timeout: 5s

Limitação de memória

Recomendamos ativar o processador do limitador de memória para evitar que o coletor falhe em momentos de alta capacidade. Ative o processamento usando as configurações a seguir:

processors:
  memory_limiter:
    # drop metrics if memory usage gets too high
    check_interval: 1s
    limit_percentage: 65
    spike_limit_percentage: 20

Configurar o exportador googlemanagedprometheus

Por padrão, o uso do exportador googlemanagedprometheus no GKE não requer configurações adicionais. Para muitos casos de uso, você só precisa ativá-lo com um bloco vazio na seção exporters:

exporters:
  googlemanagedprometheus:

No entanto, o exportador fornece algumas opções de configuração opcionais. As seções a seguir descrevem as outras definições de configuração.

Como definir project_id

Para associar sua série temporal a um projeto do Google Cloud, o recurso monitorado prometheus_target precisa ter project_id definido.

Ao executar o OpenTelemetry no Google Cloud, o exportador do Managed Service para Prometheus define esse valor com base no Application Default Credentials encontrado. Se nenhuma credencial estiver disponível ou você quiser modificar o projeto padrão, terá duas opções:

  • Defina project na configuração do exportador
  • Adicione um atributo de recurso gcp.project.id às suas métricas.

É altamente recomendável usar o valor padrão (não definido) para project_id em vez de defini-lo explicitamente, quando possível.

Defina project na configuração do exportador

O trecho de configuração a seguir envia métricas para o Managed Service para Prometheus no projeto MY_PROJECT do Google Cloud:

receivers:
  prometheus:
    config:
    ...

processors:
  resourcedetection:
    detectors: [gcp]
    timeout: 10s

exporters:
  googlemanagedprometheus:
    project: MY_PROJECT

service:
  pipelines:
    metrics:
      receivers: [prometheus]
      processors: [resourcedetection]
      exporters: [googlemanagedprometheus]

A única mudança em relação aos exemplos anteriores é a nova linha project: MY_PROJECT. Essa configuração é útil se você souber que todas as métricas provenientes desse coletor precisam ser enviadas para MY_PROJECT.

Definir o atributo de recurso gcp.project.id

É possível definir a associação do projeto por métrica adicionando um atributo de recurso gcp.project.id às suas métricas. Defina o valor do atributo como o nome do projeto a que a métrica vai ser associada.

Por exemplo, se a métrica já tiver um rótulo project, esse rótulo poderá ser movido para um atributo de recurso e renomeado como gcp.project.id usando processadores na configuração do coletor, como mostrado abaixo. exemplo:

receivers:
  prometheus:
    config:
    ...

processors:
  resourcedetection:
    detectors: [gcp]
    timeout: 10s

  groupbyattrs:
    keys:
    - project

  resource:
    attributes:
    - key: "gcp.project.id"
      from_attribute: "project"
      action: upsert

exporters:
  googlemanagedprometheus:

service:
  pipelines:
    metrics:
      receivers: [prometheus]
      processors: [resourcedetection, groupbyattrs, resource]
      exporters: [googlemanagedprometheus]

Definir as opções do cliente

O exportador googlemanagedprometheus usa clientes gRPC para o serviço gerenciado para Prometheus. Portanto, há opções opcionais disponíveis para configurar o cliente gRPC:

  • compression: ativa a compactação gzip para solicitações gRPC, o que é útil para minimizar as taxas de transferência de dados ao enviar dados de outras nuvens para o Managed Service para Prometheus (valores válidos: gzip).
  • user_agent: substitui a string do user agent enviada em solicitações para o Cloud Monitoring; no momento, se aplica apenas a métricas. O padrão é o número do build e da versão do coletor do OpenTelemetry, por exemplo, opentelemetry-collector-contrib 0.92.0.
  • endpoint: define o endpoint para onde os dados de métricas serão enviados.
  • use_insecure: se verdadeiro, usa o gRPC como transporte de comunicação. Tem efeito apenas quando o valor endpoint não é "".
  • grpc_pool_size: define o tamanho do pool de conexões no cliente gRPC.
  • prefix: configura o prefixo de métricas enviadas ao Managed Service para o Prometheus. O padrão é prometheus.googleapis.com. Não altere esse prefixo. Isso faz com que as métricas não possam ser consultadas com o PromQL na IU do Cloud Monitoring.

Na maioria dos casos, não é necessário alterar os valores padrão. No entanto, é possível alterá-los para acomodar circunstâncias especiais.

Todas essas configurações são definidas em um bloco metric na seção do exportador googlemanagedprometheus, como mostrado no exemplo a seguir:

receivers:
  prometheus:
    config:
    ...

processors:
  resourcedetection:
    detectors: [gcp]
    timeout: 10s

exporters:
  googlemanagedprometheus:
    metric:
      compression: gzip
      user_agent: opentelemetry-collector-contrib 0.92.0
      endpoint: ""
      use_insecure: false
      grpc_pool_size: 1
      prefix: prometheus.googleapis.com

service:
  pipelines:
    metrics:
      receivers: [prometheus]
      processors: [resourcedetection]
      exporters: [googlemanagedprometheus]

A seguir