Monitore o IBM MQ auto-hospedado com OpenTelemetry

Instalar o coletor NRDOT

Baixe e instale o pacote NRDOT para a sua distribuição Linux. Substitua <NRDOT_VERSION> pela tag de versão mais recente da página nrdot-collector-releases (por exemplo, v0.12.0).

• Para Debian/Ubuntu:

  bash

  Copiar

  $
  curl -LO https://github.com/newrelic/nrdot-collector-releases/releases/download/<NRDOT_VERSION>/nrdot-collector_<NRDOT_VERSION>_linux_amd64.deb
  $
  sudo dpkg -i nrdot-collector_<NRDOT_VERSION>_linux_amd64.deb

• Para RHEL/Rocky/Amazon Linux:

  bash

  Copiar

  $
  curl -LO https://github.com/newrelic/nrdot-collector-releases/releases/download/<NRDOT_VERSION>/nrdot-collector_<NRDOT_VERSION>_linux_amd64.rpm
  $
  sudo dnf install ./nrdot-collector_<NRDOT_VERSION>_linux_amd64.rpm

Configurar o NRDOT Collector

Configure o NRDOT Collector para coletar métricas do IBM MQ e enviá-las para o New Relic. Esta configuração lida com três tarefas principais:

• Conecte-se aos seus gerenciadores de filas
• Limpe os dados
• Enviar os dados para o New Relic

1. Para criar o diretório e o arquivo de configuração do coletor com as permissões necessárias, execute:

   bash

   Copiar

   $
   # Config directory — group-readable by nrdot only (it will hold secrets)
   $
   sudo install -d -o root -g nrdot -m 0750 /etc/nrdot-collector
   $
   
   $
   # Create the config file with correct permissions
   $
   sudo install -o root -g nrdot -m 0640 /dev/null /etc/nrdot-collector/ibmmq-config.yaml
   $
   sudo -u nrdot ${EDITOR:-vi} /etc/nrdot-collector/ibmmq-config.yaml

2. Cole a seguinte configuração no arquivo de configuração criado, substituindo os espaços reservados pelos seus valores reais:

   extensions:
     health_check:
       endpoint: 127.0.0.1:13133
   
   processors:
   
     filter/ibmmq-overhead:
       metrics:
         exclude:
           match_type: regexp
           metric_names:
             - "^go_.*"
             - "^process_.*"
             - "^promhttp_.*"
             - "^scrape_.*"
   
     filter/ibmmq-queues:
       metrics:
         datapoint:
           - 'attributes["queue"] != nil and IsMatch(attributes["queue"], "^SYSTEM\\.(ADMIN\\.|MQSC\\.|DEFAULT\\.|AUTH\\.|CHANNEL\\.|CHLAUTH\\.|CICS\\.|SYNCPOINT\\.|INTERNAL\\.|PENDING\\.|PROTECTION\\.|BROKER\\.|AMQP\\.|DOTNET\\.|REST\\.|RETAINED\\.|SELECTION\\.|DURABLE\\.|HIERARCHY\\.|DDELAY\\.)")'
           - 'attributes["queue"] != nil and IsMatch(attributes["queue"], "^SYSTEM\\.CLUSTER\\.(COMMAND|HISTORY)\\.QUEUE$")'
           - 'attributes["queue"] != nil and IsMatch(attributes["queue"], "^AMQ\\.")'
   
     resourcedetection:
       detectors: [env, ec2, system]
       system:
         resource_attributes:
           host.name:
             enabled: true
           host.id:
             enabled: true
   
     transform/ibmmq-cleanup:
       metric_statements:
         - context: resource
           statements:
             - delete_key(attributes, "server.address")
             - delete_key(attributes, "server.port")
             - delete_key(attributes, "url.scheme")
         - context: datapoint
           statements:
             # Rename the injected identity labels to their OTel dotted form — the
             # names New Relic's IBM MQ entity synthesis keys on. qmgr / queue stay raw.
             - set(attributes["target.name"], attributes["targetName"]) where attributes["targetName"] != nil
             - delete_key(attributes, "targetName")
             - set(attributes["cluster.name"], attributes["clusterName"]) where attributes["clusterName"] != nil
             - delete_key(attributes, "clusterName")
             - delete_key(attributes, "instance")
             - delete_key(attributes, "job")
   
     memory_limiter/ibmmq:
       check_interval: 1s
       limit_mib: 512
       spike_limit_mib: 256
   
     cumulativetodelta/ibmmq: {}
   
     batch/ibmmq:
       send_batch_size: 1000
       timeout: 200ms
   
   exporters:
   
     otlphttp/ibmmq:
       endpoint: ${env:NEW_RELIC_OTLP_ENDPOINT}
       headers:
         api-key: ${env:NEW_RELIC_LICENSE_KEY}
   
   receivers:
   
     prometheus/ibmmq-qm1:
       config:
         scrape_configs:
           - job_name: 'ibmmq-qm1'
             scrape_interval: ${env:IBMMQ_SCRAPE_INTERVAL:-60s}
             scrape_timeout: 15s
             static_configs:
               - targets:
                   - "${env:IBMMQ_QM1_ENDPOINT:-localhost:9157}"
                 labels:
                   targetName: "${env:TARGET_NAME}"
                   clusterName: "${env:IBMMQ_CLUSTER_NAME:-}"
   
   service:
     pipelines:
       metrics/ibmmq-qm1:
         receivers: [prometheus/ibmmq-qm1]
         processors:
           - filter/ibmmq-overhead
           - filter/ibmmq-queues
           - resourcedetection
           - transform/ibmmq-cleanup
           - memory_limiter/ibmmq
           - cumulativetodelta/ibmmq
           - batch/ibmmq
         exporters: [otlphttp/ibmmq]
   
     extensions: [health_check]

   Copiar

   Importante

   Não reordene nem remova processadores. A ordem da cadeia de processadores é fundamental para a síntese de entidade. O processador transform/ibmmq-cleanup deve ser executado após o processador resourcedetection. Inverter essa ordem faz com que as métricas do IBM MQ se associem à própria entidade do coletor em vez de entidades IBMMQ_MANAGER, o que impede que os dados sejam exibidos nos dashboards.

   O que esta configuração faz

   Esta configuração cria um pipeline que coleta métricas de gerenciadores de filas do IBM MQ e roteia dados estruturados para o New Relic. Cada componente executa uma função específica:

   Componente	Descrição
   health_check	Fornece um endpoint de integridade em 127.0.0.1:13133 que retorna {"status":"Server available"} para verificar se o coletor está em execução e para solucionar problemas de inicialização.
   prometheus/ibmmq-qm1	Conecta-se ao exportador de cada gerenciador de filas a cada 60 segundos para coletar métricas. Cada gerenciador de filas usa um receptor independente; se um gerenciador de filas falhar, os receptores restantes continuarão operando normalmente. Para adicionar mais gerenciadores de filas, consulte a seção Adicionar outro gerenciador de filas.
   filter/ibmmq-overhead	Remove as métricas próprias internas do exportador (como go_* e process_*) que não contêm um sinal do IBM MQ. Isso otimiza os custos de ingestão de dados ao filtrar a telemetria desnecessária.
   filter/ibmmq-queues	Exclui as filas internas do sistema IBM MQ (SYSTEM.* e AMQ.*) para que apenas as filas do aplicativo se tornem entidades IBMMQ_QUEUE. Isso reduz a contagem total de entidades e concentra o monitoramento em ativos críticos.
   transform/ibmmq-cleanup	Este é um componente crítico que mapeia métricas para as entidades apropriadas do IBM MQ no New Relic. Sem esse componente, os dados aparecem como métricas genéricas do coletor em vez de sintetizar as entidades IBMMQ_MANAGER e IBMMQ_QUEUE com dashboards e alertas associados.
   memory_limiter/ibmmq	Limita o uso de memória a 512MB (com tolerância a picos de 256MB) para evitar que o coletor exceda os limites de recursos do sistema.
   batch/ibmmq	Agrupa as métricas antes da transmissão para reduzir a sobrecarga da rede, agrupando até 1.000 pontos de dados por solicitação.
   otlphttp/ibmmq	Exporta as métricas processadas para o New Relic usando a chave de licença configurada para autenticação e o endpoint regional designado.

   Cada gerenciador de filas usa um pipeline independente para que um problema com uma instância não afete as outras. A ordem dos processadores é crítica, não reordene ou remova processadores, ou as métricas falharão ao mapear corretamente para as entidades do IBM MQ.

Definir variáveis de ambiente do NRDOT

A configuração do seu coletor usa variáveis de ambiente para valores específicos da implantação, como a chave de licença do New Relic e os endpoints do gerenciador de filas. Essa abordagem mantém os segredos separados dos arquivos de configuração e facilita o ajuste das configurações sem editar o YAML.

1. Crie um arquivo de ambiente para o coletor NRDOT:

   bash

   Copiar

   $
   # Owner nrdot, mode 0600 — this file holds the license key
   $
   sudo install -o nrdot -g nrdot -m 0600 /dev/null /etc/nrdot-collector/ibmmq-env
   $
   sudo -u nrdot ${EDITOR:-vi} /etc/nrdot-collector/ibmmq-env

2. Adicione seu valor como KEY=VALUE linhas ao arquivo, substituindo os espaços reservados por seus valores reais:

   # /etc/nrdot-collector/ibmmq-env
   
   # --- Required ---
   
   # New Relic ingest license key (40 chars, suffix NRAL)
   NEW_RELIC_LICENSE_KEY=<YOUR-LICENSE-KEY>
   
   # Stable host identity — first segment of every IBMMQ entity GUID
   TARGET_NAME=<YOUR-HOSTNAME>
   
   # mq-metric-samples exporter endpoints, one per queue manager
   IBMMQ_QM1_ENDPOINT=localhost:9157
   
   # --- Optional (shown with defaults) ---
   
   # OTLP endpoint: US prod default shown; For more information, refer to [New Relic OTLP endpoint](https://docs.newrelic.com/docs/opentelemetry/best-practices/opentelemetry-otlp).
   NEW_RELIC_OTLP_ENDPOINT=https://otlp.nr-data.net:4318
   
   # Optional tag grouping for the IBMMQ_MANAGER entity (does not affect the entity GUID).
   # Leave unset to omit cluster.name (nullable); set it to group QMs under one cluster tag.
   # IBMMQ_CLUSTER_NAME=prod-mq-cluster
   
   # Scrape interval — must be >= the mq-metric-samples pollInterval (default 60s)
   IBMMQ_SCRAPE_INTERVAL=60s

   Copiar

   Cuidado

   Não altere o valor de TARGET_NAME após a implantação inicial. Esse valor forma o primeiro segmento de cada GUID de entidade IBMMQ_MANAGER e IBMMQ_QUEUE (target.name:qmgr). Alterar esse valor após a implantação cria novas entidades e deixa as existentes órfãs, o que quebra os dashboards e alertas associados. Selecione uma string estável durante a configuração inicial, como o QMID do gerenciador de filas. Para obter mais informações, consulte O Modelo de Entidade do IBM MQ.

   Defina as seguintes variáveis de ambiente no seu shell para verificar a configuração antes de iniciar o coletor:

   Variável	Obrigatório	Descrição
   NEW_RELIC_LICENSE_KEY	Sim	Sua chave de licença de ingestão da New Relic.
   TARGET_NAME	Sim	Um identificador para o seu host, como nome do host ou ID do gerenciador de filas. Não altere isso após a implantação inicial, pois se torna parte dos IDs da sua entidade.
   IBMMQ_QM1_ENDPOINT	Sim	Localização do exportador do seu primeiro gerenciador de filas. Por exemplo, localhost:9157 se estiver em execução no mesmo host.
   NEW_RELIC_OTLP_ENDPOINT	Não	Endpoint OTLP da New Relic para sua região. Para mais informações, consulte o endpoint OTLP da New Relic.
   IBMMQ_CLUSTER_NAME	Não	Nome do Cluster para agrupar seus gerenciadores de filas no New Relic.
   IBMMQ_SCRAPE_INTERVAL	Não	Intervalo de coleta para exportar métricas para o New Relic. O intervalo de coleta padrão é de 60 segundos.

Configure o serviço systemd do NRDOT

1. Crie um arquivo drop-in systemd para carregar os arquivos de configuração e ambiente.

   bash

   Copiar

   $
   sudo mkdir -p /etc/systemd/system/nrdot-collector.service.d
   $
   sudo tee /etc/systemd/system/nrdot-collector.service.d/ibmmq.conf > /dev/null << 'EOF'
   $
   [Service]
   $
   EnvironmentFile=/etc/nrdot-collector/ibmmq-env
   $
   ExecStart=
   $
   ExecStart=/usr/bin/nrdot-collector --config /etc/nrdot-collector/ibmmq-config.yaml
   $
   MemoryMax=1G
   $
   LimitNOFILE=65536
   $
   NoNewPrivileges=true
   $
   ProtectSystem=strict
   $
   ProtectHome=true
   $
   EOF

   A linha ExecStart= vazia limpa o comando padrão, e a segunda linha define o comando personalizado. Isso evita que o coletor inicie duas vezes. As outras configurações carregam o arquivo de ambiente, limitam o uso de memória e melhoram a segurança.

2. Após criar o drop-in, verifique se o systemd pode analisá-lo sem erros:

   bash

   Copiar

   $
   sudo systemd-analyze verify /etc/systemd/system/nrdot-collector.service
   $
   # No output means no syntax errors

Iniciar o coletor NRDOT e verificar

1. Inicie o coletor e ative-o para ser executado automaticamente na inicialização:

   bash

   Copiar

   $
   sudo systemctl daemon-reload
   $
   sudo systemctl enable --now nrdot-collector.service
   $
   sudo systemctl status nrdot-collector.service --no-pager

   O comando status deve mostrar Active: active (running). Se você vir Active: failed, verifique os logs com journalctl -u nrdot-collector.service -n 200 --no-pager.

2. Verifique se o coletor está saudável:

   bash

   Copiar

   $
   curl -sS http://127.0.0.1:13133
   $
   # Expected: {"status":"Server available", ...}

3. Confirme se sua métrica do IBM MQ está fluindo para o New Relic. Aguarde 60 segundos após o início do coletor e, em seguida, verifique seus dados usando a consulta de verificação em Encontre e consulte seus dados.

Visualize seus dados no New Relic

Assim que seu coletor estiver em execução e as métricas estiverem fluindo, você verá seus gerenciadores de filas como entidades IBMMQ_MANAGER no New Relic, com suas filas como entidades IBMMQ_QUEUE filhas. Para obter detalhes sobre como encontrar seus dados, executar consultas e configurar dashboards e alertas, consulte Encontrar e consultar seus dados.