Résoudre les problèmes courants

Pour diagnostiquer les erreurs pendant le processus d'installation, vous pouvez augmenter le niveau de log pour Agent Control en ajoutant le paramètre suivant dans votre fichier values-newrelic.yaml :

agentControlDeployment:
  chartValues:
    config:
      log:
        level: trace

• Niveau de log par défaut : info.
• Autres niveaux de log pris en charge : debug et trace.
• Collecteur de logs OTel : pour activer les logs de débogage dans le collecteur OpenTelemetry, ajoutez verboseLog: true.

Pour inspecter les logs de contrôle de l'agent, exécutez la commande suivante, en remplaçant agent-control-*** par le nom de votre pod de contrôle de l'agent :

$
# 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 expose un point de terminaison d'état local que vous pouvez utiliser pour vérifier l'état d'Agent Control et de ses agents gérés. Ce point de terminaison est activé par défaut sur le port 51200. Suivez ces étapes pour interroger l’état cluster :

Transférer un port local vers le pod principal agent-control :

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

Demander le statut de l'agent :

$
curl localhost:51200/status

Lorsque le chart agent-control-bootstrap est installé, un Job est lancé pour installer toutes les ressources et les charts, et l'installation peut échouer avec une erreur BackoffLimitExceeded :

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

Vous pouvez déboguer les erreurs d'installation en consultant les logs du job d'installation :

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

Agent Control nécessite des informations d'authentification valides pour se connecter en toute sécurité au contrôle de la flotte. Initialement, ces informations d'identification sont générées automatiquement via l'interface utilisateur d'installation d'Agent Control et sont représentées par les champs systemIdentity.parentIdentity.clientId et systemIdentity.parentIdentity.clientSecret dans le fichier de valeurs. Pour des raisons de sécurité, les informations d'identification nécessaires à l'installation d'Agent Control expirent après 12 heures.

Si l'installation échoue avec une erreur BackoffLimitExceeded, cela indique souvent des informations d'identification expirées ou non valides.

Vérifiez les logs du travail Kubernetes responsable de la configuration de l'identité du système Agent Control.

Tout d’abord, identifiez le pod du travail :

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

Dans la section Events , recherchez les entrées pour le pod spécifique, comme suit :

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

Afficher les logs du pod défaillant :

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

Exemple:

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

Après avoir examiné les logs, réessayez l'installation à l'aide Helm tout en monitorant les messages d'erreur spécifiques et en vérifiant les logs pour détecter d'éventuels problèmes. Vous trouverez ci-dessous quelques problèmes connus et comment les interpréter :

• IdentitéClientId non valide : Error getting system identity auth token. The API endpoint returned 404: Failed to find Identity: <identityClientId-value>
• IdentitéClientSecret non valide : Error getting system identity auth token. The API endpoint returned 400: Bad client secret.
• Identité expirée : Error getting system identity auth token. The API endpoint returned 400: Expired client secret.
• Autorisations requises manquantes : 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 vous voyez un message d'erreur comme celui ci-dessous dans le log OpenTelemetry du de déploiement du collecteur pod, cela peut indiquer une clé de licence New Relic invalide. Cela empêche le collecteur de pouvoir exporter les données télémétriques vers New Relic :

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

Solution

Confirmez que vous utilisez une clé de licence New Relic valide dans votre configuration.

Si le pod d'un agent géré n'est pas créé, il peut y avoir un problème avec son HelmRelease.

Vérifiez l'état de la sortie Helm :

$
kubectl get helmrelease open-telemetry -n newrelic

Une sortie réussie et saine doit afficher READY: True et STATUS: InstallSucceeded.

Si la sortie a échoué, les champs STATUS et READY indiqueront le problème. Selon le type d’erreur, le problème racine peut ne pas être entièrement reflété dans le champ d’état. Pour obtenir plus de détails, utilisez kubectl pour décrire la ressource HelmRelease :

$
kubectl describe helmrelease open-telemetry -n newrelic

Lors de la suppression de agent-control-bootstrap, un job est lancé pour supprimer toutes les ressources et les charts créés.

Si la désinstallation affiche une erreur comme : * job agent-control-bootstrap-uninstall-job failed: BackoffLimitExceeded

Vous pouvez consulter les logs de la tâche pour déboguer l'erreur.

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

Si la commande helm delete est annulée en cours d'exécution, le job de désinstallation continuera de fonctionner, supprimant les charts et les ressources, mais le secret helm agent-control-bootstrap peut toujours exister. Dans ce cas, vous ne pourrez pas mettre à jour ou installer le chart, et vous obtiendrez l'erreur :

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

Relancer la désinstallation ne fonctionnera pas, les logs de la tâche de désinstallation afficheront une erreur telle que :

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

Solution

Supprimez tous les secrets Helm de votre release (remplacez agent-control-bootstrap par le nom de votre release si ce dernier a été modifié) :

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

Vous pouvez ensuite procéder à nouveau à l'installation.

L'outil de diagnostic New Relic NRDiag est un utilitaire qui rassemble les ressources et les logs liés au contrôle des agents dans votre cluster à des fins de débogage. Suivez ces étapes pour collecter toutes les données :

1. Sur votre hôte, installez l'outil NRDiag à l'aide du guide de démarrage.

2. Exécutez la suite K8s Agent Control :

   conseil

   Assurez-vous que kubectl et helm sont installés.

   • Exécutez la commande dans l'espace de nommage défini dans le contexte de kubeconfig :
   bash

   Copier

   $
   ./nrdiag -suites K8s-agent-control

   • Spécifiez un espace de nommage différent pour le contrôle de l'agent à l'aide de l'indicateur --k8s-namespace :
   bash

   Copier

   $
   ./nrdiag -suites K8s-agent-control --k8s-namespace=newrelic

   • Spécifiez un espace de noms différent pour les sous-agents à l'aide de l'option ac-agents-namespace :
   bash

   Copier

   $
   ./nrdiag -suites K8s-agent-control --k8s-namespace=newrelic-agent-control --ac-agents-namespace=newrelic

3. Le résultat attendu devrait ressembler au rapport suivant :

   bash

   Copier

   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.

4. Tous les logs et ressources liés à Agent Control sont enregistrés dans le fichier nrdiag_output.zip du répertoire courant. Vous pouvez analyser le contenu du fichier zip ou ouvrir un ticket de support auprès du support New Relic pour obtenir une assistance supplémentaire.

Si vous recevez le message d'erreur Installing agent-control (Unsupported), veuillez consulter la configuration requise et assurez-vous d'utiliser une version de système d'exploitation prise en charge.

Si vous voyez Installing agent-control (Failed), suivez ces étapes :

• Vérifiez les logs fournis avec le script d'installation :

  • Si vous voyez Error creating an identity, veuillez vous assurer que votre clé utilisateur appartient à un utilisateur de la plateforme avec le rôle Admin tous produits.

• Vérifiez l'état du service newrelic-agent-control :

  bash

  Copier

  $
  sudo systemctl status newrelic-agent-control

  Si le service apparaît à l'état failed ou stopped, cela signifie que l'agent a été installé mais qu'un problème empêche son fonctionnement normal. Vérifiez les logs des services de l'Agent avec journalctl (ou tout autre outil Linux similaire) :

  bash

  Copier

  $
  journalctl -u newrelic-agent-control

  Si aucune information n'est disponible, vérifiez comment exécuter l'agent en mode débogage pour accéder aux logs détaillés expliquant pourquoi le service ne peut pas démarrer.

• Si le service n'est pas installé, essayez d'ajouter --debug à la fin de la commande d'installation CLI de l'installation guidée et relancez-la. Cela active le logs détaillé pour le script d'installation et peut fournir un contexte supplémentaire expliquant l'erreur.

• Facultativement, répondez yes lorsqu'il vous est demandé d'envoyer des logs à New Relic pour aider au dépannage de l'installation. Une fois soumis, les logs sont accessibles avec la requête NRQL suivante :

  SELECT * FROM Log WHERE hostname = `your-host-name`

  Copier

Pour accéder aux logs, vous devez d'abord activer le logs de l'agent en suivant ces étapes :

1. Pour activer le logs de fichier, utilisez le paramètre log dans le fichier de configuration Agent Control :

   # Fleet Control connection settings
   #fleet_control:
   
   # managed agents settings
   #agents:
   
   # agent logging settings
   log:
     level: debug
     file:
       enabled: true
       # Add a custom path if needed, default directory: /var/log/newrelic-agent-control/agent-control/
       # Logs rotate daily, so the file name is prefixed with the current date, e.g. 2026-09-18.newrelic-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"

   Copier

   Les valeurs possibles pour le niveau de log sont :

• trace

• debug

• info (défaut)

• warning

• error

  Les logs de l'agent d'infrastructure sous-jacent et/ou du collecteur OpenTelemetry sont inclus lorsque le niveau est debug ou trace.

2. Redémarrer Agent Control :

   bash

   Copier

   $
   sudo systemctl restart newrelic-agent-control

3. Si le log file est activé, vérifiez le fichier de log le plus récent dans le répertoire indiqué par le paramètre path (les fichiers sont datés, par ex. 2026-09-18.newrelic-agent-control.log). Ou utilisez votre outil de dépannage de logs préféré tel que journalctl -u newrelic-agent-control.

Pour accéder aux détails de l'état de santé, vous devez d'abord activer le serveur local en suivant ces étapes :

1. Ajoutez les paramètres suivants dans le fichier de configuration d'Agent Control :

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

   Copier

2. Redémarrer Agent Control :

   bash

   Copier

   $
   sudo systemctl restart newrelic-agent-control

3. Interrogez le point de terminaison de statut à l'aide de la commande suivante :

   bash

   Copier

   $
   curl 127.0.0.1:51200/status

   Le serveur renverra les informations sur l'état de santé au format json, exemple :

   {
     "agent_control": {
       "healthy": true
     },
     "fleet": {
       "enabled": true,
       "endpoint": "https://opamp.service.newrelic.com/v1/opamp",
       "reachable": true
     },
     "agents": {
       "nr-otel-collector": {
         "agent_id": "nr-otel-collector",
         "agent_type": "newrelic/com.newrelic.opentelemetry.collector:0.1.0",
         "agent_start_time_unix_nano": 1730000000000000000,
         "health_info": {
           "healthy": true,
           "start_time_unix_nano": 1730000000000000000,
           "status_time_unix_nano": 1730000010000000000
         }
       },
       "nr-infra-agent": {
         "agent_id": "nr-infra-agent",
         "agent_type": "newrelic/com.newrelic.infrastructure:0.1.0",
         "agent_start_time_unix_nano": 1730000000000000000,
         "health_info": {
           "healthy": false,
           "last_error": "process exited with code: exit status: 1",
           "start_time_unix_nano": 1730000000000000000,
           "status_time_unix_nano": 1730000010000000000
         }
       }
     }
   }

   Copier

Agent Control effectue certaines validations avant de recevoir et d'appliquer la configuration à distance de Fleet Control. De plus, les configurations peuvent avoir un format valide (par exemple, une structure .yaml valide) mais inclure des valeurs inattendues pour certains paramètres (par exemple, un string alors qu'un integer est attendu). Le tableau suivant présente les erreurs courantes pour les différents agents pris en charge :