Solucionar problemas del monitoreo de IBM MQ OpenTelemetry

Valide el estado del recolector y revise los logs para identificar el problema:

$
sudo systemctl status nrdot-collector.service --no-pager
$
sudo journalctl -u nrdot-collector.service -n 200 --no-pager

Problemas de configuración:

• Errores de sintaxis YAML: compruebe la sangría y la sintaxis del archivo de configuración de su recolector
• Falta el archivo de entorno: asegúrese de que /etc/nrdot-collector/ibmmq-env exista
• Clave de licencia no válida: verá errores 401 o 403. Verifique su clave de licencia de New Relic

Valide el estado del recolector y revise los logs para identificar el problema:

$
kubectl -n ibmmq logs deploy/ibmmq-collector-opentelemetry-collector

Causas y soluciones comunes

Busque estos patrones de error en sus logs:

Problemas de configuración:

• Errores de sintaxis YAML: compruebe la sangría y la sintaxis del archivo de configuración de su recolector
• Archivo de entorno faltante: asegúrese de que el secreto newrelic-otlp-secret exista en el namespace ibmmq
• Clave de licencia no válida: verá errores 401 o 403. Verifique su clave de licencia de New Relic

Problemas específicos de Kubernetes:

• CreateContainerConfigError: falta el secreto newrelic-otlp-secret. Vuelva a ejecutar el paso Crear secreto de credenciales de New Relic
• spec.ports: Required value: falta service.enabled: false en values.yaml
• cannot list resource "pods" … forbidden: falta RBAC. Asegúrese de que clusterRole.create: true esté configurado en los valores de Helm

1. Verifique que los exportadores de IBM MQ estén funcionando:

   bash

   Copia

   $
   curl -s http://<exporter-host>:9157/metrics | grep '^ibmmq_qmgr_status'

   Debería ver una línea por gestor de colas. Si no ve ningún resultado, el exportador no funciona correctamente.

2. Compruebe que el recolector esté en buen estado y descubriendo objetivos.

   bash

   Copia

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

   otelcol_receiver_accepted_metric_points mayor que 0 confirma que el recolector encontró objetivos. otelcol_exporter_send_failed_metric_points debe permanecer en 0.

3. Verificar problemas de descubrimiento de objetivos

• Verifique que las variables IBMMQ_QMN_ENDPOINT apunten a exportadores que funcionen
• Asegúrese de que el recolector pueda alcanzar cada extremo del exportador
• Compruebe que la configuración del objetivo estático sea correcta

4. Verifique si las métricas se están recopilando pero no aparecen en New Relic:

• Región del extremo OTLP: confirme que el extremo coincida con la región de la cuenta de New Relic (EE. UU. o UE)

• Clave de licencia: verifique que su clave de licencia sea válida y tenga los permisos correctos

• Conectividad de red: asegúrese de que el recolector pueda alcanzar el extremo OTLP de New Relic

  Una región incorrecta descarta datos silenciosamente sin ningún error del lado del recolector.

1. Verifique que los exportadores de IBM MQ estén funcionando:

   bash

   Copia

   $
   curl -s http://<exporter-host>:9157/metrics | grep '^ibmmq_qmgr_status'

   Debería ver una línea por gestor de colas. Si no ve ningún resultado, el exportador no funciona correctamente.

2. Compruebe que el recolector esté en buen estado y descubriendo objetivos.

   bash

   Copia

   $
   kubectl -n ibmmq port-forward deploy/ibmmq-collector-opentelemetry-collector 8888:8888 &
   $
   curl -s http://localhost:8888/metrics | \
   >
     grep -E 'otelcol_(receiver_accepted|exporter_sent|exporter_send_failed)_metric_points'
   $
   kill %1 2>/dev/null

   otelcol_receiver_accepted_metric_points mayor que 0 confirma que el recolector encontró objetivos. otelcol_exporter_send_failed_metric_points debe permanecer en 0.

3. Compruebe si otelcol_receiver_accepted_metric_points se mantiene en 0:

• Los pods del administrador de colas deben llevar las anotaciones requeridas en la plantilla de pod, con prometheus.io/scrape establecido exactamente en "true"
• Los pods deben ejecutarse en el namespace ibmmq
• Asegúrese de que se aplique clusterRole.create: true —sin él, kubernetes_sd devuelve 403 Forbidden

4. Verifique si las métricas se están recopilando pero no aparecen en New Relic:

• Región del extremo OTLP: confirme que el extremo coincida con la región de la cuenta de New Relic (EE. UU. o UE)

• Clave de licencia: verifique que su clave de licencia sea válida y tenga los permisos correctos

• Conectividad de red: asegúrese de que el recolector pueda alcanzar el extremo OTLP de New Relic

  Una región incorrecta descarta datos silenciosamente sin ningún error del lado del recolector.

Esto casi siempre es causado por alterar la forma de la métrica crítica para la entidad. La síntesis de la entidad utiliza como clave las métricas con guion bajo sin procesar (ibmmq_*), la etiqueta qmgr sin procesar y un atributo target.name. Verifique que:

• Los nombres de las métricas no tienen puntos. Debería ver ibmmq_queue_depth, no ibmmq.queue.depth.

• La etiqueta qmgr está presente y no se le ha cambiado el nombre. Asegúrese de que no se muestre como ibmmq.queue_manager.name.

• El target.name se establece en las métricas y asegúrese de que no se muestre como camelCase targetName. Si targetName todavía está presente y transform/ibmmq-cleanup no se está ejecutando o está desordenado:

  FROM Metric SELECT uniques(target.name), uniques(qmgr) WHERE metricName LIKE 'ibmmq_%' SINCE 30 minutes ago

  Copia

  El orden del procesador en la configuración del recolector es fundamental — resourcedetection → transform/ibmmq-cleanup. Si reordenó o eliminó transform/ibmmq-cleanup, las métricas de IBM MQ se enrutan a la propia entidad del recolector en lugar de a una entidad IBMMQ_MANAGER. Restaure el orden documentado del pipeline.

New Relic espera una temporalidad delta para los contadores; Prometheus emite una acumulativa. El procesador cumulativetodelta/ibmmq los convierte in situ. Si los contadores parecen planos, confirme que el procesador esté presente en cada pipeline de métricas.

El valor target.name (establecido a través de la variable de entorno TARGET_NAME en Linux, o el reetiquetado targetName en Kubernetes) es el primer segmento de cada GUID de IBMMQ_MANAGER y IBMMQ_QUEUE. Cambiarlo después del despliegue crea entidades completamente nuevas y las antiguas se vuelven obsoletas, rompiendo los dashboards y las alertas que apuntan a los GUID antiguos. Elija un valor estable una vez y nunca lo cambie.

Si ya lo cambió, restaure el valor original de TARGET_NAME y reinicie el recolector. Las entidades nombradas correctamente reanudan el reporte; los duplicados creados con el nombre incorrecto dejan de recibir datos y desaparecen de la UI después de la ventana de reporte de la entidad de New Relic.