Solucionar problemas comunes

Importante

¡Agent Control y New Relic Control ahora están disponibles a nivel general para Kubernetes! El soporte para hosts Linux y hosts Windows también se encuentra en el programa de vista previa pública, de conformidad con nuestras políticas de versión preliminar.

Este documento cubre los pasos para solucionar problemas comunes al instalar u operar Agent Control. Está organizado por ambiente.

Solución de problemas de Kubernetes

Para diagnosticar errores durante el proceso de instalación, puede aumentar el nivel de logs del Agent Control agregando la siguiente configuración en su archivo values-newrelic.yaml :

agentControlDeployment:
  chartValues:
    config:
      log:
        level: trace

Nivel de logs predeterminado: info.
Otros niveles de log admitidos: debug y trace.
logs del recolector de OTel: para habilitar los logs de depuración en el recolector OpenTelemetry , agregue verboseLog: true.

Para inspeccionar los logs de Agent Control, ejecute el siguiente comando, reemplazando agent-control-*** con el nombre de su pod de Agent Control:

bash

$# Find the Agent Control pod name
$kubectl get pods -n newrelic-agent-control
$
$# Inspect the logs, replacing `agent-control-***` with your pod's name
$kubectl logs agent-control-*** -n newrelic-agent-control

Agent Control expone un extremo de estado local que puede emplear para verificar el estado del Agent Control y su agente gestionado. Este extremo está habilitado de forma predeterminada en el puerto 51200. Siga estos pasos para consultar el estado del clúster:

Reenviar un puerto local al pod principal agent-control :

bash

$kubectl port-forward <pod-name> 51200:51200

Aplicar el estado del agente:

bash

$curl localhost:51200/status

Cuando se instala el chart agent-control-bootstrap, se inicia un trabajo que instala todos los recursos y charts, y la instalación puede fallar con un error BackoffLimitExceeded:

bash

Error: UPGRADE FAILED: pre-upgrade hooks failed: job failed: BackoffLimitExceeded

Puede depurar los errores de instalación revisando los logs del trabajo de instalación:

bash

$kubectl logs agent-control-bootstrap-install-job-**** -n newrelic-agent-control

El control del agente requiere una credencial de autenticación válida para conectarse de forma segura al control de flota. Inicialmente, esta credencial se genera automáticamente a través de la UI del agente Control de instalación y está representada por los campos identityClientId y identityClientSecret en el archivo de valores. Por razones de seguridad, la credencial necesaria para instalar Agente Control caduca luego de 12 horas.

Si la instalación falla con un error BackoffLimitExceeded, a menudo indica una credencial vencida o no válida.

Verifique los logs del trabajo de Kubernetes responsable de configurar la identidad del sistema de Agent Control.

Primero, identifica el pod del trabajo:

bash

$kubectl describe job agent-control-generate-system-identity -n <your-namespace>

En la sección Events , busque entradas para el pod específico, de la siguiente manera:

bash

Events:
      Type     Reason                Age   From            Message
      ----     ------                ----  ----            -------
      Normal   SuccessfulCreate      88s   job-controller  Created pod: agent-control-generate-system-identity-jr6cg
      Normal   SuccessfulCreate      73s   job-controller  Created pod: agent-control-generate-system-identity-wnx2v
      Normal   SuccessfulCreate      50s   job-controller  Created pod: agent-control-generate-system-identity-8zsqd
      Normal   SuccessfulCreate      7s    job-controller  Created pod: agent-control-generate-system-identity-btqh7
      Warning  BackoffLimitExceeded  1s    job-controller  Job has reached the specified backoff limit

Ver los logs del pod fallido:

bash

$kubectl logs <pod-name> -n <your-namespace>

Ejemplo:

bash

$kubectl logs agent-control-generate-system-identity-btqh7 -n newrelic-agent-control

Luego de revisar los logs, vuelva a intentar la instalación usando Helm mientras observa si hay mensajes de error específicos y verifica los logs para detectar posibles problemas. A continuación se presentan algunos problemas conocidos y cómo interpretarlos:

Identidad de cliente no válida: Error getting system identity auth token. The API endpoint returned 404: Failed to find Identity: <identityClientId-value>
Identidad no válidaClientSecret: Error getting system identity auth token. The API endpoint returned 400: Bad client secret.
Identidad expirada: Error getting system identity auth token. The API endpoint returned 400: Expired client secret.
Faltan las licencias requeridas: Failed to create a New Relic System Identity for Fleet Control communication authentication. Please verify that your User Key is valid and that your Account Organization has the necessary permissions to create a System Identity: Exception while fetching data (/create) : Not authorized to perform this action or the entity is not found.

Si ve un mensaje de error como el que se muestra a continuación en los logs del del OpenTelemetry recopilador de pod, es posible que indique una New Relic clave de licencia de no válida. Esto impide que el recolector pueda exportar telemetry data a New Relic:

bash

2024-06-13T13:46:05.898Z error exporterhelper/retry_sender.go:126 Exporting failed. The error is not retryable. Dropping data. {"kind": "exporter", "data_type": "metrics", "name": "otlphttp/newrelic", "error": "Permanent error: error exporting items, request to https://otlp.nr-dat ││ go.opentelemetry.io/collector/exporter/exporterhelper.(*retrySender).send

Solución

Confirme que está empleando una clave de licencia de New Relic válida en su configuración.

Si no se crean los pods de un agente gestionado, puede haber un problema con su HelmRelease.

Compruebe el estado de la versión de Helm:

bash

$kubectl get helmrelease open-telemetry -n newrelic

Un lanzamiento exitoso y saludable debe mostrar READY: True y STATUS: InstallSucceeded.

Si la liberación falló, los campos STATUS y READY indicarán el problema. Dependiendo del tipo de error, es posible que el problema raíz no se refleje completamente en el campo de estado. Para obtener más detalles, emplee kubectl para describir el recurso HelmRelease:

bash

$kubectl describe helmrelease open-telemetry -n newrelic

Al eliminar agent-control-bootstrap, se inicia un trabajo que elimina todos los recursos y charts creados.

Si la desinstalación muestra un error como: * job agent-control-bootstrap-uninstall-job failed: BackoffLimitExceeded

Puede ver los logs del trabajo para depurar el error.

bash

$kubectl logs agent-control-bootstrap-uninstall-job-*** -n newrelic-agent-control

Si se cancela el comando helm delete mientras se ejecuta, el desinstalador del job continuará funcionando, eliminando los charts y los recursos, pero el secreto de helm agent-control-bootstrap podría seguir existiendo. En ese caso, no podrá actualizar ni instalar el chart, obteniendo el error:

Error: UPGRADE FAILED: "agent-control-bootstrap" has no deployed releases

Ejecutar la desinstalación nuevamente no funcionará, los logs del trabajo de desinstalación mostrarán un error como:

Error: uninstall: Release not loaded: agent-control-cd: release: not found

Solución

Elimine todos los secretos de Helm de su lanzamiento (cambie agent-control-bootstrap por el nombre de su lanzamiento si se cambió):

bash

$kubectl delete secrets -l "name=agent-control-bootstrap"

Luego puede realizar la instalación nuevamente.

La herramienta de diagnóstico New Relic NRDiag es una utilidad que recopila recursos y logs relacionados con el control del agente en su clúster para la depuración. Siga estos pasos para recopilar todos los datos:

En su host, instale la herramienta NRDiag empleando la guía de introducción.
Ejecute la suite de control del agente K8s:
consejo
Cerciorar de que kubectl y helm estén instalados.
- Ejecute el comando en el namespace establecido en el contexto de kubeconfig:
bash
```
$./nrdiag -suites K8s-agent-control
```
- Especifique un namespace diferente para el agente Control usando el indicador --k8s-namespace :
bash
```
$./nrdiag -suites K8s-agent-control --k8s-namespace=newrelic
```
- Especifique un espacio de nombres diferente para los subagentes utilizando el indicador ac-agents-namespace:
bash
```
$./nrdiag -suites K8s-agent-control --k8s-namespace=newrelic-agent-control --ac-agents-namespace=newrelic
```

El resultado esperado debería parecer al siguiente reporte:

bash

Check Results
-------------------------------------------------
Info     K8s/Flux/Charts [Successfully collected Flux Helm Charts]
Info     K8s/Resources/Config [Successfully collected K8s configMaps ]
Info     K8s/AgentControl/agent-control-status-server [Successfully collected K8s agent-control status se...]
Info     K8s/Resources/Daemonset [Successfully collected K8s newrelic-infrastructure...]
Info     K8s/Resources/Pods [Successfully collected K8s newrelic-infrastructure...]
Info     K8s/Flux/Repositories [Successfully collected Flux Helm Repositories]
Info     K8s/AgentControl/helm-controller-logs [Successfully collected K8s agent-control helm-cont...]
Info     K8s/Env/Version [kubectl version output successfully collected]
Info     K8s/Resources/Deploy [Successfully collected K8s newrelic-infrastructure...]
Info     K8s/Helm/Releases [Successfully collected the list of helm releases]
Info     K8s/AgentControl/agent-control-logs [Successfully collected K8s agent-control agent-con...]
Info     K8s/Flux/Releases [Successfully collected Flux Helm Releases]
Info     K8s/AgentControl/source-controller-logs [Successfully collected K8s agent-control source-co...]
See nrdiag-output.json for full results.

Todos los logs y recursos relacionados con Agent Control se guardan en el archivo nrdiag_output.zip en el directorio actual. Puede analizar el contenido del archivo zip o abrir un ticket de soporte con el soporte de New Relic para obtener asistencia adicional.

Solución de problemas de hosts Linux

Si recibe el mensaje de error Installing agent-control (Unsupported), consulte los requisitos del sistema y asegúrese de ejecutar una versión de sistema operativo compatible.

Si ve Installing agent-control (Failed), siga estos pasos:

Revise los logs proporcionados con el script de instalación:
- Si ve Error creating an identity, asegúrese de que su clave de usuario pertenezca a un usuario de la plataforma con el rol de Administrador de todo el producto.
Verifique el estado del servicio newrelic-agent-control:
bash
```
$sudo systemctl status newrelic-agent-control
```
Si el servicio aparece en estado failed o stopped, esto significa que el agente se instaló pero hay un problema que impide su funcionamiento normal. Verifique los logs de los servicios del agente utilizando journalctl (o cualquier herramienta de Linux similar):
bash
```
$journalctl -u newrelic-agent-control
```
Si no hay información disponible, consulta cómo ejecutar el agente en modo de depuración para acceder a logs detallados que expliquen por qué no se puede iniciar el servicio.
Si el servicio no está instalado, intente agregar --debug al final del comando de instalación de la CLI de la instalación guiada y vuelva a ejecutarlo. Esto habilita el logging detallado para el script de instalación y puede proporcionar contexto adicional que explique el error.
Opcionalmente, responda yes cuando se le solicite enviar logs a New Relic para ayudar a solucionar problemas de la instalación. Una vez enviados, se puede acceder a los logs con la siguiente consulta NRQL:
```
SELECT * FROM Log WHERE hostname = `your-host-name`
```

Para acceder a los logs, primero necesitará habilitar el logging del agente siguiendo estos pasos:

Para habilitar el logging en un archivo, utilice la opción log en el archivo de configuración de Agent Control:

# Fleet Control connection settings
  #fleet_control:

  # managed agents settings
  #agents:

  # agent logging settings
  log:
    level: debug
    file:
      enable: true
      # Add a custom path if needed, default path: /var/log/newrelic-agent-control/agent-control.log
      # path: "/path/to/agent-control.log"
    # Optional formatting settings
    format:
      # Include the target module (disabled by default for better readability)
      target: true
      # Custom timestamp format "%Y-%m-%dT%H:%M:%S"
      timestamp: "%Y"

Los valores posibles del nivel de log son:

trace
debug
info (por defecto)
warning
error
Los logs del agente de infraestructura subyacente y/o del recopilador de OpenTelemetry se incluyen cuando el nivel es debug o trace.

Reiniciar el Control del Agente.
Si el log file está habilitado, verifique el archivo local correspondiente según la configuración path. O utilice su herramienta preferida de solución de problemas de logs, como journalctl -u new-relic-agent-control.

Para acceder a los detalles del estado de salud, primero deberá habilitar el servidor local siguiendo estos pasos:

Agregue las siguientes configuraciones en el archivo de configuración de Agent Control:

server:
    enabled: true
    # default values (change if needed)
    #host: "127.0.0.1"
    #port: 51200

Reiniciar el Control del Agente.

Consulte el endpoint de estado utilizando el siguiente comando:

bash

$curl 127.0.0.1:51200/status

El servidor devolverá la información de salud en formato json, ejemplo:

{
  "agent_control": {
    "healthy": true
  },
  "fleet_control": {
    "enabled": true,
    "endpoint": "https://opamp.service.newrelic.com/v1/opamp",
    "reachable": true
  },
  "sub_agents": {
    "nr-otel-collector": {
      "agent_id": "nr-otel-collector",
      "agent_type": "newrelic/com.newrelic.opentelemetry.collector:0.1.0",
      "healthy": true
    },
    "nr-infra-agent": {
      "agent_id": "nr-infra-agent",
      "agent_type": "newrelic/com.newrelic.infrastructure:0.1.0",
      "healthy": false,
      "last_error": "process exited with code: exit status: 1"
    }
  }
}

Agent Control realiza ciertas validaciones antes de recibir y aplicar la configuración remota de Fleet Control. Además, las configuraciones pueden tener un formato válido (por ejemplo, una estructura .yaml válida) pero incluir valores inesperados para ciertos ajustes (por ejemplo, un string cuando se espera un integer). La siguiente tabla muestra errores comunes para los diferentes agentes admitidos:

Tipo de agente	Error	Notas de solución de problemas
(Todos los agentes)	Error al aplicar la configuración remota: no se pudo resolver la configuración	Revise su formato de configuración. La configuración podría no ser un archivo `.yaml` válido, o podrían faltar campos obligatorios.
(Todos los agentes)	Configuración no válida: valores restringidos detectados	Revise el contenido de su configuración. Es posible que la configuración específica no esté disponible para el tipo de agente de destino según la política de seguridad.
(Todos los agentes)	`exit code 1`	Revise su configuración. Valores inesperados hacen que el agente salga con un error inesperado.
Agente de infraestructura	`exit code 1`	Revise su configuración. Valores inesperados están causando que el agente de infraestructura salga con una configuración inesperada. Revise la configuración admitida.

Solución de problemas de hosts de Windows

Si Agent Control no se está ejecutando o no está en buen estado, siga estos pasos de diagnóstico en orden:

1. Verificar el estado del servicio:

Get-Service -Name newrelic-agent-control

Se esperaba: Status : Running. Si está detenido o falta, proceda al paso 2.

2. Revise los logs del servicio:

Vea el archivo de log más reciente (los archivos de log incluyen sufijos de fecha como newrelic-agent-control.log.2026-02-09-11):

Get-ChildItem "C:\ProgramData\New Relic\newrelic-agent-control\logs\" -Filter "newrelic-agent-control.log.*" | Sort-Object LastWriteTime -Descending | Select-Object -First 1 | Get-Content -Tail 50

Sugerencia

Configuración de logging de archivo: Agent Control requiere una configuración explícita para habilitar el log de archivo. Si no existen archivos de log, agregue esto a su local_config.yaml:

log:
  file:
    enabled: true

Luego, reinicie el servicio para que aparezcan los logs.

3. Pruebe la ejecución manual:

Ejecute Agent Control desde la línea de comandos para evitar problemas específicos del servicio:

cd "C:\Program Files\New Relic\newrelic-agent-control"
.\newrelic-agent-control.exe --config "C:\Program Files\New Relic\newrelic-agent-control\local-data\agent-control\local_config.yaml"

Si se ejecuta correctamente desde la línea de comandos pero no como servicio, esto indica problemas de antivirus o de permisos.

4. Verificar el tipo de flota:

Asegúrese de que la flota sea de tipo "Host - Windows". Usar "Host - Linux" provocará fallas. Verifique en la IU de Fleet Control en los detalles de la flota.

5. Verifique si hay conflictos de puertos:

Agent Control utiliza el puerto 51200 para su endpoint de salud:

netstat -ano | findstr :51200

Si otro proceso está utilizando este puerto, identifíquelo:

Get-Process -Id (Get-NetTCPConnection -LocalPort 51200).OwningProcess

6. Verificar la conectividad de red:

Probar conexión con Fleet Control:

Test-NetConnection -ComputerName fleet-control.newrelic.com -Port 443
Test-NetConnection -ComputerName download.newrelic.com -Port 443

Ambos deberían mostrar TcpTestSucceeded : True.

7. Revise la sintaxis de configuración:

Verifique si hay errores de sintaxis YAML:

Get-Content "C:\Program Files\New Relic\newrelic-agent-control\local-data\agent-control\local_config.yaml"

Busque problemas comunes: sangría incorrecta, dos puntos faltantes, caracteres especiales sin comillas.

8. Verifique si hay agentes en conflicto:

Verifique que los agentes de New Relic existentes estén desinstalados:

Get-Service -Name newrelic-infra -ErrorAction SilentlyContinue
Get-Process -Name newrelic-infra -ErrorAction SilentlyContinue

Si alguno de los comandos devuelve resultados, desinstale el agente de infraestructura antes de continuar.

9. Verifique los privilegios de administrador:

Confirme que PowerShell se está ejecutando como administrador:

([Security.Principal.WindowsPrincipal][Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)

Debería devolver True.

10. Reinicie el servicio:

Después de solucionar los problemas, reinicie el servicio:

Restart-Service -Name newrelic-agent-control
Start-Sleep -Seconds 30
Get-Service -Name newrelic-agent-control
Invoke-WebRequest -Uri "http://localhost:51200/status" -UseBasicParsing

Mensaje de error común

Error/Síntoma	Causa probable	Solución
`Error 1067: The process terminated unexpectedly`	Bloqueo del antivirus, error de configuración o dependencias faltantes	Agregue exclusiones de antivirus, verifique la sintaxis de configuración, revise los logs del servicio para obtener detalles
El servicio se inicia y se detiene inmediatamente	Error en el archivo de configuración o credenciales inválidas	Revise `local_config.yaml`, verifique la clave de licencia y las credenciales de la flota
`Port 51200 already in use`	Conflicto de puerto con otra aplicación	Identifique el proceso que usa el puerto con `netstat`, detenga el servicio en conflicto
`Failed to connect to Fleet Control`	Bloqueo de red/firewall, o configuración incorrecta de la flota	Pruebe la conectividad con `Test-NetConnection`, verifique el ID y el tipo de flota
`Invalid fleet type` error en los logs	El tipo de flota no es "Host - Windows"	Vuelva a crear la flota con el tipo correcto en la IU de Fleet Control
El servicio no inicia, se ejecuta bien desde la línea de comandos	Antivirus o política de seguridad de Windows bloqueando el servicio	Agregue exclusiones para ejecutables y directorios, consulte con el equipo de seguridad
`License key validation failed`	Clave de licencia incorrecta, vencida o faltante	Verifique la clave de licencia en el archivo de configuración, asegúrese de que sea válida para su cuenta
No aparecen datos en la interfaz de usuario después de más de 10 minutos	Agente no desplegado o configuración no sincronizada	Revise la IU de Fleet Control para ver el estado del despliegue, verifique la configuración de la flota

Obtener ayuda adicional

Si la solución de problemas no resuelve su problema:

Habilite el logging de depuración editando local_config.yaml:
```
log:
  level: debug
```
Reinicie el servicio y reproduzca el problema

Recopilar logs para soporte:

Get-ChildItem "C:\ProgramData\New Relic\newrelic-agent-control\logs\" -Filter "newrelic-agent-control.log.*" | Sort-Object LastWriteTime -Descending | ForEach-Object { Get-Content $_.FullName } | Out-File -FilePath "$env:USERPROFILE\Desktop\agent-control-debug.log"

Contacte al Soporte de New Relic con los logs recopilados

Te ofrecemos esta traducción automática para facilitar la lectura.

Importante

Solución de problemas de Kubernetes

Habilitar el log de depuración

Estado extremo

Fallo de liberación Helm

Licencia New Relic no válida

Error de HelmRelease para el agente gestionado

Ver errores de desinstalación de Helm

Imposibilidad de instalar o actualizar después de una desinstalación cancelada

Solucionar problemas con NRDiag

consejo

Solución de problemas de hosts Linux

No se puede instalar a través de New Relic CLI

Diagnosticar problemas con el logging del agente

Punto de conexión de estado de salud local

Configuración remota inválida o inesperada con Fleet Control

Solución de problemas de hosts de Windows

Sugerencia

Mensaje de error común

Obtener ayuda adicional

Te ofrecemos esta traducción automática para facilitar la lectura.

Solucionar problemas comunes

Importante

Solución de problemas de Kubernetes.css-21sua1{background:none;border:none;width:0;padding:0;}

Estado extremo

Fallo de liberación Helm

Licencia New Relic no válida

Error de HelmRelease para el agente gestionado

Ver errores de desinstalación de Helm

Imposibilidad de instalar o actualizar después de una desinstalación cancelada

Solucionar problemas con NRDiag

Solución de problemas de hosts Linux

No se puede instalar a través de New Relic CLI

Diagnosticar problemas con el logging del agente

Punto de conexión de estado de salud local

Configuración remota inválida o inesperada con Fleet Control

Solución de problemas de hosts de Windows

Sugerencia

Mensaje de error común

Obtener ayuda adicional

Solución de problemas de Kubernetes