Ao realizar o monitoramento do IBM MQ com coletores OpenTelemetry, você pode encontrar problemas com a inicialização do coletor, fluxo de dados ou síntese de entidade. Este guia ajuda você a diagnosticar e corrigir problemas comuns para implantações de host Linux e Kubernetes.
O Collector não inicia ou não permanece em execução
Valide o status do seu coletor e verifique os logs para identificar o problema:
bash
$
sudo systemctl status nrdot-collector.service --no-pager
Você deve ver uma linha por gerenciador de filas. Se você não vir nenhuma saída, o exportador não está funcionando corretamente.
Verifique se o seu coletor está íntegro e descobrindo destinos.
bash
$
curl http://127.0.0.1:13133
$
# Expected: {"status":"Server available", ...}
otelcol_receiver_accepted_metric_points maior que 0 confirma que o coletor encontrou destino. otelcol_exporter_send_failed_metric_points deve permanecer em 0.
Verifique problemas de descoberta de destino
Verifique se suas variáveis IBMMQ_QMN_ENDPOINT apontam para exportadores em funcionamento
Certifique-se de que o coletor possa acessar cada endpoint do exportador
Verifique se a configuração do seu destino estático está correta
Verifique se as métricas estão sendo coletadas, mas não aparecem no New Relic:
Região do endpoint OTLP: confirme se o seu endpoint corresponde à região da sua conta do New Relic (EUA vs. UE)
Chave de licença: verifique se sua chave de licença é válida e tem as permissões corretas
Conectividade de rede: certifique-se de que o coletor consegue alcançar o endpoint OTLP da New Relic
Uma região incorreta descarta dados silenciosamente sem nenhum erro do lado do coletor.
Verifique se os seus exportadores do IBM MQ estão funcionando:
otelcol_receiver_accepted_metric_points maior que 0 confirma que o coletor encontrou destino. otelcol_exporter_send_failed_metric_points deve permanecer em 0.
Verifique se otelcol_receiver_accepted_metric_points permanece em 0:
Os pods do seu gerenciador de filas devem conter as anotações necessárias no modelo de pod, com prometheus.io/scrape definido exatamente como "true"
Os pods devem ser executados no namespace ibmmq
Certifique-se de que clusterRole.create: true seja aplicado — sem ele, kubernetes_sd retorna 403 Forbidden
Verifique se as métricas estão sendo coletadas, mas não aparecem no New Relic:
Região do endpoint OTLP: confirme se o seu endpoint corresponde à região da sua conta do New Relic (EUA vs. UE)
Chave de licença: verifique se sua chave de licença é válida e tem as permissões corretas
Conectividade de rede: certifique-se de que o coletor consegue alcançar o endpoint OTLP da New Relic
Uma região incorreta descarta dados silenciosamente sem nenhum erro do lado do coletor.
Nenhuma entidade do IBM MQ aparece no New Relic
Se você vir métricas do IBM MQ no New Relic, mas nenhuma entidade IBMMQ_MANAGER ou IBMMQ_QUEUE aparecer:
Verifique a ordem dos processadores: o processador transform/ibmmq-cleanupdeve ser executado apósresourcedetection. Se essa ordem for invertida, as métricas chegarão na própria entidade do coletor em vez das entidades do IBM MQ, e os dashboards ficarão em branco.
Verifique os rótulos obrigatórios: as suas métricas devem incluir estes rótulos:
Rótuloqmgr: o exportador mq-metric-samples deve emitir isso com o nome do gerenciador de filas (por exemplo, qmgr="QM1")
Rótuloqueue: para métricas no nível da fila, deve conter o nome da fila
Atributotarget.name: vem da sua variável de ambiente TARGET_NAME e forma o GUID da entidade
Verifique a consistência de TARGET_NAME: nunca altere o valor de TARGET_NAME após a implantação inicial. Esse valor se torna parte do GUID de cada entidade (target.name:qmgr), e alterá-lo cria novas entidades e deixa as existentes órfãs, quebrando dashboards e alertas.
Visibilidade de dados
Isso é quase sempre causado pela alteração do formato da métrica crítica da entidade. A síntese de entidade usa como chave as métricas brutas com sublinhado (ibmmq_*), o rótulo qmgr bruto e um atributo target.name. Verifique se:
Os nomes das métricas não são pontilhados. Você deve ver ibmmq_queue_depth, não ibmmq.queue.depth.
O rótulo qmgr está presente e não foi renomeado. Garantido que não seja exibido como ibmmq.queue_manager.name.
O target.name está definido na métrica e certifique-se de que não seja exibido como camelCase targetName. Se targetName ainda estiver presente e transform/ibmmq-cleanup não estiver em execução ou estiver desordenado:
FROM Metric SELECT uniques(target.name), uniques(qmgr)WHERE metricName LIKE'ibmmq_%' SINCE 30 minutes ago
A ordem do processador na configuração do coletor é fundamental — resourcedetection → transform/ibmmq-cleanup. Se você reordenou ou removeu transform/ibmmq-cleanup, as métricas do IBM MQ são roteadas para a própria entidade do coletor em vez de uma entidade IBMMQ_MANAGER. Restaure a ordem documentada do pipeline.
O New Relic espera temporalidade delta para contadores; o Prometheus emite cumulativa. O processador cumulativetodelta/ibmmq os converte no local. Se os contadores parecerem planos, confirme se o processador está presente em cada pipeline de métrica.
O valor target.name (definido por meio da env TARGET_NAME no Linux, ou do relabel targetName no Kubernetes) é o primeiro segmento de cada GUID IBMMQ_MANAGER e IBMMQ_QUEUE. Alterá-lo após a implantação cria entidades totalmente novas e as antigas ficam obsoletas, quebrando dashboards e alertas que apontam para os GUIDs antigos. Escolha um valor estável uma vez e nunca o altere.
Se você já o alterou, restaure o valor TARGET_NAME original e reinicie o coletor. As entidades nomeadas corretamente voltam a reportar; as duplicatas criadas com o nome errado param de receber dados e expiram da interface após a janela de relatórios de entidade do New Relic.