Passer au contenu principal
Lorsqu’une demande de support arrive à support@appsignal.com, nous avons quelques procédures pour déboguer d’où peut venir un problème. Puisqu’il est bon de partager, voici quelques-unes de nos procédures. Consultez également notre liste de problèmes connus pour une liste de problèmes pouvant affecter votre application.

​
Diagnose

Notre gem Ruby, notre paquet Elixir, notre paquet Node.js et notre paquet Python sont fournis avec un outil en ligne de commande de diagnostic intégré qui affiche des informations sur la configuration de la bibliothèque AppSignal et l’environnement dans lequel elle s’exécute. Toutes ces informations peuvent aider à trouver une cause potentielle d’un problème. Si vous ouvrez une demande de support, nous vous demanderons généralement de l’exécuter en premier. 
# Ruby
appsignal diagnose

# Elixir
mix appsignal.diagnose

# With an Elixir release (`mix release`) binary:
bin/your_app eval ":appsignal_tasks.diagnose()"

# With a Distillery release binary:
bin/your_app command appsignal_tasks diagnose

# Node.js
npx @appsignal/cli diagnose

# Python
python -m appsignal diagnose
La commande diagnose doit être exécutée dans le répertoire d’une application sur laquelle la bibliothèque AppSignal est installée. À moins que l’application ne soit configurée avec des variables d’environnement, il est nécessaire de fournir à la commande diagnose un environnement. L’environnement aidera AppSignal à charger la configuration correcte à diagnostiquer. 
# Ruby
APPSIGNAL_APP_ENV=production appsignal diagnose
# --environment option support since Ruby gem version 2.0.4
appsignal diagnose --environment=production

# Elixir
MIX_ENV=production mix appsignal.diagnose
# Or with the release binary
bin/your_app command appsignal_tasks diagnose

# Node.js
NODE_ENV=production npx @appsignal/cli diagnose

# Python
APPSIGNAL_APP_ENV=production python -m appsignal diagnose

​
Informations de diagnostic

La commande diagnose affichera les données suivantes.
  • Informations sur l’agent
    • Version du gem Ruby / paquet Elixir / paquet Node.js / paquet Python
    • Version de l’agent
    • Chemin d’installation du gem Ruby
    • Extension C / Nif chargée : yes/no
  • Informations sur l’hôte
    • Architecture matérielle
    • Système d’exploitation
    • Version Ruby / Elixir & OTP / Node.js / Python
    • Détection Heroku - visible uniquement sur Heroku
    • Détection de conteneur
    • L’utilisateur actuel est l’utilisateur root : yes/no
  • Diagnostics de l’Agent
    • Démarre l’agent en mode diagnostic
    • Validation de la configuration de l’agent
    • Initialisation du logger de l’agent
    • Vérification de la possibilité d’écrire dans le chemin du fichier de verrouillage de l’agent
  • Configuration
  • Validation de la clé Push API
    • Teste si la clé Push API utilisée est une clé valide sur AppSignal.com.
  • Informations sur les chemins
    • Teste tous les chemins requis pour vérifier s’ils sont accessibles en écriture. Affiche également la propriété de l’utilisateur actuel.
    • current_path - chemin dans lequel la commande diagnose est exécutée. Devrait être un chemin pour l’application que vous essayez de déboguer. Habituellement le même que root_path. (Ruby uniquement)
    • root_path - chemin de l’application. AppSignal essaiera de trouver un fichier config/appsignal.rb/config/appsignal.yml ici. (Ruby uniquement)
    • log_dir_path - chemin dans lequel le fichier journal est créé.
    • log_file_path - chemin dans lequel le fichier journal est créé. Est vide si aucun chemin viable n’a pu être trouvé.
  • Informations d’installation (Ruby uniquement)
    • Quelque chose a pu mal se passer pendant l’installation de l’agent AppSignal. Cette section affiche les fichiers install.log et mkmf.log (Makefile log).
Les options suivantes doivent être correctement configurées pour qu’AppSignal démarre. C’est le strict minimum, d’autres configurations peuvent également affecter l’instrumentation.
  • La configuration Environment / env est définie.
  • La configuration name est définie.
  • La configuration push_api_key est définie.
  • La configuration active est définie sur true.
  • La clé Push API est validée. Une connexion internet est requise pour cela.

​
Configuration

La configuration est essentielle. Elle est importante, car sans elle, l’agent AppSignal ne saura pas quelle application il instrumente ni dans quel environnement. À l’aide des informations de diagnose, nous voyons si nous pouvons trouver un problème avec la configuration de l’agent. Les agents AppSignal disposent de plusieurs méthodes de configuration. Nous vous recommandons de lire le sujet de configuration pour commencer, en particulier la configuration minimale requise, l’ordre de chargement de la configuration et les pages des options de configuration si vous rencontrez des problèmes.

​
Aucune donnée n’apparaît

Il peut y avoir de nombreuses raisons pour lesquelles une application n’est pas détectée par AppSignal. Ce n’est que lorsque les serveurs AppSignal commencent à recevoir des données d’une application qu’elle est créée dans l’interface utilisateur sur AppSignal.com ; si aucune donnée n’est reçue, aucune application n’est créée. Lorsqu’une intégration est cassée ou mal configurée, il peut être long de retracer le problème. Pour exclure l’agent AppSignal et son traitement, nous pouvons envoyer des « demo samples ». 
# Ruby
appsignal demo --environment=development

# Elixir
MIX_ENV=prod mix appsignal.demo
# Or with the release binary
bin/your_app command appsignal_tasks demo

# Node.js
npx @appsignal/cli demo

# Python
python -m appsignal demo --environment=production
Cette commande envoie une fausse requête web et un échantillon d’erreur aux serveurs AppSignal pour l’application. Une fois les données reçues, les serveurs AppSignal commencent à traiter les données et créent une application sur AppSignal.com. Dans chaque intégration, ce processus est également utilisé dans l’outil en ligne de commande d’installation pour aider au processus d’installation. Notez que la commande « demo » doit être exécutée dans le répertoire d’une application sur laquelle l’agent AppSignal est installé.

​
Journaux

Lorsqu’aucun problème n’est trouvé dans les informations de diagnostic, les journaux de l’agent sont la prochaine chose à examiner. Les agents AppSignal créent des fichiers journaux pour afficher des informations utiles et les problèmes rencontrés dans l’agent lui-même. Par défaut, les agents enregistrent les journaux de niveau « info » et supérieurs (warning & error). Pour enregistrer plus de données pertinentes pour le débogage, définissez l’option log_level (Ruby / Elixir / Python) / logLevel (Node.js) sur debug.

​
Contenu des journaux

Le fichier journal AppSignal contient des informations provenant de trois composants AppSignal différents. Il préfixera chaque entrée de journal avec un horodatage, le nom du composant, le PID du processus, l’indicateur de niveau de journal et le message de journal lui-même. Les composants d’agent disponibles sont :
  • process Implémentation spécifique au langage (Ruby / Elixir).
  • extension Extension en langage C à l’implémentation du langage. S’exécute dans le même processus que process.
  • agent Agent système AppSignal en Rust. Un processus séparé.

​
Décomposition des messages de journal

​
Décomposition des messages de journal du logger de fichier

Text
[2016-10-19T11:06:18 (process) #11329][DEBUG] Starting appsignal
 ^                    ^         ^      ^      ^
 |                    |         |      |      Message
 |                    |         |      Log level
 |                    |         Process PID
 |                    Agent component
 Timestamp in host time zone

​
Décomposition des messages de journal STDOUT

Pour les loggers STDOUT, le gem Ruby AppSignal préfixe un préfixe « appsignal » reconnaissable au message afin que les messages AppSignal spécifiques puissent être filtrés avec grep dans la sortie de journal du processus parent.
Text
[2016-10-19T11:06:18 (process) #11329][DEBUG] appsignal: Starting appsignal
 ^                    ^         ^      ^      ^          ^
 |                    |         |      |      |          Message
 |                    |         |      |      AppSignal prefix
 |                    |         |      Log level
 |                    |         Process PID
 |                    Agent component
 Timestamp in host time zone

​
Emplacement des journaux

Il existe deux méthodes pour sauvegarder les journaux de la bibliothèque AppSignal. En écrivant les journaux dans un fichier journal et en imprimant les journaux dans le STDOUT du processus. Voir la configuration log pour plus d’informations. Les journaux écrits dans un fichier journal ne sont pas écrits dans les fichiers journaux de votre application, mais ont leur propre fichier appsignal.log. Selon les autorisations d’un hôte, l’agent écrira les journaux à un emplacement différent. Le gem Ruby essaiera d’abord de créer un fichier journal dans le répertoire d’une application. Pour les applications Ruby on Rails, il créera un fichier journal dans le répertoire log/ à la place. S’il n’arrive pas à créer un fichier journal, il se rabattra sur le répertoire /tmp du système. C’est également là que sont enregistrés les autres fichiers de l’agent AppSignal. Le paquet Elixir écrira les fichiers journaux dans le fichier journal /tmp/appsignal.log. S’il échoue complètement à trouver un emplacement accessible en écriture pour sauvegarder ses journaux, il les affichera dans le STDOUT du processus de l’application parent. Cela peut également être configuré avec l’option :log. L’agent système n’est actuellement pas capable de se connecter à STDOUT, il enregistrera donc toujours dans le fichier appsignal.log même lorsque le journal est configuré sur STDOUT. Pour qu’AppSignal vous indique où il écrira ses journaux, consultez la sortie de la commande diagnose.

​
Rotation des journaux

AppSignal n’effectue pas de rotation des journaux pour ses fichiers journaux. Nous recommandons de configurer un outil système tel que logrotate pour gérer la taille des fichiers et la rétention.

​
Journaux de l’agent autonome

Si vous utilisez l’agent autonome AppSignal, vous pouvez accéder aux journaux avec la commande suivante :
Bash
sudo journalctl -u appsignal-agent
(La commande sudo peut être facultative dans certains environnements tels que les conteneurs.)

​
Fichiers journaux sur Heroku

Sur la plateforme d’hébergement Heroku, la bibliothèque d’intégration écrira automatiquement dans STDOUT. Étant donné que l’agent ne peut pas écrire dans STDOUT, il continuera à écrire dans le fichier appsignal.log. Sur Heroku, il n’est pas possible de voir le contenu du fichier journal avec heroku run bash puis de lire le fichier journal, en raison de la façon dont les Dynos Heroku sont conteneurisés. Heroku fournit un module complémentaire appelé « Heroku Exec » pour permettre d’exécuter des commandes dans le même conteneur dyno que votre application. À l’aide de ce module complémentaire, nous pouvons lire le fichier journal sur les dynos de votre application. 
# Install the Exec add-on as described on the Heroku website:
# https://devcenter.heroku.com/articles/heroku-exec
$ heroku ps:exec
$ cat /path/to/appsignal.log

​
L’agent est-il en cours d’exécution ?

Lorsqu’une application avec l’intégration AppSignal démarre, elle lance l’agent système AppSignal. Cet agent s’exécute en tant que processus séparé et communique avec l’application. Après avoir traité les données d’instrumentation, c’est cet agent qui envoie les données aux serveurs AppSignal, pas l’agent spécifique au langage. Lorsque l’agent système n’est pas en cours d’exécution, aucune donnée ne peut être traitée ou envoyée à AppSignal. Il est important de savoir si l’agent système est en cours d’exécution. Vous pouvez le trouver dans la liste des processus sous le nom appsignal-agent. 
ps aux | grep appsignal
Exécutez la commande ps sur la ligne de commande de votre hôte pour vérifier si l’agent est en cours d’exécution pendant que votre application exécute AppSignal.

​
Autres questions

De nombreux facteurs peuvent être en jeu lorsqu’un problème survient. Choses à vérifier quand AppSignal ne semble pas fonctionner ou qu’aucun journal n’est disponible.
  • Depuis quand le problème se produit-il ?
    • L’agent a-t-il été mis à jour ?
    • D’autres bibliothèques ont-elles été mises à jour ?
  • Que disent les journaux de l’agent AppSignal avec l’option log_level définie sur debug ?
  • Le système d’exploitation est-il pris en charge ?
  • L’« extension » s’est-elle installée et chargée correctement ? Les réponses devraient se trouver dans la sortie de « diagnose ».
  • L’application s’exécute-t-elle à l’intérieur d’un système conteneurisé ?
  • Les serveurs d’application sont-ils synchronisés à l’aide de NTP pour éviter la dérive d’horloge ?
  • Votre problème est-il mentionné dans notre liste de problèmes connus ?

​
Créer un état reproductible

Si les étapes décrites ci-dessus n’ont pas révélé la cause du problème, une bonne étape suivante consiste à essayer de reproduire la situation dans la configuration la plus minimale possible. Créez une application de test avec aussi peu de configuration que possible, en chargeant uniquement les bibliothèques et dépendances minimales requises. Avec cet exemple d’application reproductible, nous pouvons commencer à retracer la cause du problème.

​
Nous contacter

N’hésitez pas à nous contacter si vous rencontrez des problèmes lors du débogage des agents AppSignal. Nous sommes là pour vous aider.