Résoudre les problèmes courants

Important

Agent Control et New Relic Control sont désormais disponibles en version générale pour Kubernetes ! La prise en charge des hôtes Linux et Windows fait également partie du programme public preview, conformément à nos politiques de pré-lancement.

Ce document décrit les étapes de dépannage des problèmes courants lors de l'installation ou de l'utilisation d'Agent Control. Il est organisé par environnement.

Dépannage Kubernetes

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 :

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 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 :

bash

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

Demander le statut de l'agent :

bash

$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 :

bash

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 :

bash

$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 identityClientId et identityClientSecret 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 :

bash

$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 :

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

Afficher les logs du pod défaillant :

bash

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

Exemple:

bash

$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 :

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

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 :

bash

$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 :

bash

$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.

bash

$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é) :

bash

$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 :

Sur votre hôte, installez l'outil NRDiag à l'aide du guide de démarrage.
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
```
$./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
```
$./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
```
$./nrdiag -suites K8s-agent-control --k8s-namespace=newrelic-agent-control --ac-agents-namespace=newrelic
```

Le résultat attendu devrait ressembler au rapport suivant :

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.

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.

Dépannage des hôtes Linux

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
```
$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
```
$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`
```

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

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:
      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"

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.

Redémarrer le contrôle de l'Agent.
Si le journal file est activé, vérifiez le fichier local correspondant en fonction du paramètre path. Ou utilisez votre outil de dépannage de logs préféré tel que journalctl -u new-relic-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 :

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

Redémarrer le contrôle de l'Agent.

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

bash

$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_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 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 :

Type d'agent	Erreur	Notes de dépannage
(Tous les agents)	Erreur lors de l'application de la configuration à distance : impossible de résoudre la configuration	Vérifiez le format de votre configuration. La configuration n'est peut-être pas un fichier `.yaml` valide ou des champs obligatoires sont manquants.
(Tous les agents)	Configuration invalide : valeurs restreintes détectées	Vérifiez le contenu de votre configuration. Des paramètres spécifiques peuvent ne pas être disponibles pour le type d'agent cible en fonction de la politique de sécurité.
(Tous les agents)	`exit code 1`	Vérifiez votre configuration. Des valeurs inattendues provoquent l'arrêt de l'agent avec une erreur inattendue.
Agent d'infrastructure	`exit code 1`	Vérifiez votre configuration. Des valeurs inattendues provoquent l'arrêt de l'agent d'infrastructure avec une configuration inattendue. Consultez les paramètres pris en charge.

Dépannage des hôtes Windows

Si Agent Control n'est pas en cours d'exécution ou sain, suivez ces étapes de diagnostic dans l'ordre :

1. Vérifier l'état du service :

Get-Service -Name newrelic-agent-control

Attendu : Status : Running. S'il est arrêté ou manquant, passez à l'étape 2.

2. Vérifier les logs du service :

Consulter le fichier journal le plus récent (les fichiers logs incluent des suffixes de date comme 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

Conseil

Configuration du logging de fichier : Agent Control nécessite une configuration explicite pour activer le logging de fichier. Si aucun fichier de log n'existe, ajoutez ceci à votre local_config.yaml:

log:
  file:
    enabled: true

Redémarrez ensuite le service pour que les logs apparaissent.

3. Tester l'exécution manuelle :

Exécutez Agent Control depuis la ligne de commande pour contourner les problèmes spécifiques au service :

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"

S'il s'exécute correctement depuis la ligne de commande mais pas en tant que service, cela indique des problèmes d'antivirus ou de permissions.

4. Vérifier le type de flotte :

Assurez-vous que la flotte est de type "Host - Windows". L'utilisation de "Host - Linux" entraînera des échecs. Vérifiez dans l'interface utilisateur Fleet Control sous les détails de la flotte.

5. Vérifier les conflits de port :

Agent Control utilise le port 51200 pour son point de terminaison de santé :

netstat -ano | findstr :51200

Si un autre processus utilise ce port, identifiez-le :

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

6. Vérifier la connectivité réseau :

Test de connexion à Fleet Control :

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

Les deux devraient afficher TcpTestSucceeded : True.

7. Vérifier la syntaxe de configuration :

Recherchez des erreurs de syntaxe YAML :

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

Recherchez les problèmes courants : indentation incorrecte, deux-points manquants, caractères spéciaux non mis entre guillemets.

8. Rechercher des agents en conflit :

Vérifiez que les agents New Relic existants sont désinstallés :

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

Si l'une des commandes renvoie des résultats, désinstallez l'Agent d'infrastructure avant de continuer.

9. Vérifier les privilèges d'administrateur :

Vérifiez que PowerShell s'exécute en tant qu'administrateur :

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

Devrait renvoyer True.

10. Redémarrez le service :

Après avoir résolu les problèmes, redémarrez le service :

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

Message d'erreur courant

Erreur/Symptôme	Cause probable	Solution
`Error 1067: The process terminated unexpectedly`	Blocage par l'antivirus, erreur de configuration ou dépendances manquantes	Ajoutez des exclusions antivirus, vérifiez la syntaxe de la configuration, consultez les logs du service pour plus de détails
Le service démarre puis s'arrête immédiatement	Erreur de fichier de configuration ou identifiants invalides	Examinez `local_config.yaml`, vérifiez la clé de licence et les identifiants de la flotte
`Port 51200 already in use`	Conflit de port avec une autre application	Identifier le processus utilisant le port avec `netstat`, arrêter le service en conflit
`Failed to connect to Fleet Control`	Blocage réseau/pare-feu, ou configuration incorrecte de la flotte	Tester la connectivité avec `Test-NetConnection`, vérifier l'ID et le type de flotte
`Invalid fleet type` erreur dans les logs	Le type de flotte n'est pas "Host - Windows"	Recréez la flotte avec le type correct dans l'interface Fleet Control
Le service ne démarre pas, fonctionne correctement depuis la ligne de commande	Antivirus ou stratégie de sécurité Windows bloquant le service	Ajoutez des exclusions pour les exécutables et les répertoires, vérifiez auprès de l'équipe de sécurité
`License key validation failed`	Clé de licence incorrecte, expirée ou manquante	Vérifiez la clé de licence dans le fichier de configuration, assurez-vous qu'elle est valide pour votre compte
Aucune donnée ne s'affiche dans l'interface utilisateur après plus de 10 minutes	Agent non déployé ou configuration non synchronisée	Vérifiez le statut du déploiement dans l'interface utilisateur Fleet Control, vérifiez la configuration de la flotte

Obtenir de l'aide supplémentaire

Si le dépannage ne résout pas votre problème :

Activez le logs de débogage en modifiant local_config.yaml:
```
log:
  level: debug
```
Redémarrez le service et reproduisez le problème

Collecter les logs pour le support :

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"

Contactez le support New Relic avec les logs collectés

Cette traduction automatique est fournie pour votre commodité.

Important

Dépannage Kubernetes

Activer la logging de débogage

Point de terminaison d'état

Helm de la sortie du gouvernail

Licence New Relic non valide

Échec de HelmRelease pour les agents gérés

Afficher les erreurs de désinstallation Helm

Impossibilité d'installer ou de mettre à jour après une désinstallation annulée

Dépannage avec NRDiag

conseil

Dépannage des hôtes Linux

Impossible d'installer via New Relic CLI

Diagnostiquer les problèmes de logs de l'agent

Point de terminaison de l'état de santé local

Configuration à distance invalide ou inattendue avec Fleet Control

Dépannage des hôtes Windows

Conseil

Message d'erreur courant

Obtenir de l'aide supplémentaire

Cette traduction automatique est fournie pour votre commodité.

Résoudre les problèmes courants

Important

Dépannage Kubernetes.css-21sua1{background:none;border:none;width:0;padding:0;}

Point de terminaison d'état

Helm de la sortie du gouvernail

Licence New Relic non valide

Échec de HelmRelease pour les agents gérés

Afficher les erreurs de désinstallation Helm

Impossibilité d'installer ou de mettre à jour après une désinstallation annulée

Dépannage avec NRDiag

Dépannage des hôtes Linux

Impossible d'installer via New Relic CLI

Diagnostiquer les problèmes de logs de l'agent

Point de terminaison de l'état de santé local

Configuration à distance invalide ou inattendue avec Fleet Control

Dépannage des hôtes Windows

Conseil

Message d'erreur courant

Obtenir de l'aide supplémentaire

Dépannage Kubernetes