Python agent scriptd'administration : utilisation avancée

Le script d'administration de l'agent Python est utilisé pendant le processus d'installation. Lorsque le package de l'agent Python est installé, le script newrelic-admin est également installé dans le répertoire bin de l'installation Python ou de l'environnement virtuel.

Ce document donne des détails plus approfondis sur ces utilisations du script d'administration :

• Génération du fichier de configuration initial de l'agent
• Valider votre fichier de configuration
• Test de la connexion à New Relic
• Envelopper le démarrage d'une application Web Python autonome

Structure de sous-commande

Pour exécuter des sous-commandes, fournissez le nom de la sous-commande comme premier argument du script newrelic-admin . Ajoutez ensuite toutes les options après le nom de la sous-commande. Par exemple:

$
newrelic-admin help

help <command>

Lorsqu'il est exécuté sans autre argument, cela fournit une liste de toutes les sous-commandes acceptées :

$
newrelic-admin help
 Usage: newrelic-admin command [options]
 
 Type 'newrelic-admin help <command>'for help on a specific command.
 
 Available commands are:
   generate-config
   license-key
   local-config
   network-config
   record-deploy
   run-program
   run-python
   server-config
   validate-config

Pour afficher des détails supplémentaires sur une sous-commande, exécutez la commande help avec la sous-commande et l’une de ses options. Par exemple:

$
newrelic-admin help generate-config
 Usage: newrelic-admin generate-config license_key [output_file]
 
 Generates a sample agent configuration file for <license_key>.

generate-config license_key [output_file]

Génère un exemple de fichier de configuration d'agent. L'option license_key est votre clé de licence.

Par défaut, le fichier de configuration d'exemple sera dirigé vers la sortie standard et sera affiché sur votre écran. Pour capturer la sortie, vous pouvez plutôt l'enregistrer dans un fichier en donnant le nom du fichier comme option output_file .

Lorsque le fichier de configuration de l'agent d'échantillon est généré, seule l'option de clé de licence dans le fichier est mise à jour. Vous devez toujours modifier le fichier et apporter des modifications aux options app_name et log_file selon le cas. Pour plus d'informations, voir Installation de l'agent Python.

Si vous ne pouvez pas exécuter la commande generate-config pour produire le fichier de configuration initial de l'agent, vous pouvez télécharger un exemple de fichier de configuration à partir de download.newrelic.com/python_agent/release/newrelic.ini.

validate-config config_file [log_file]

Valide la syntaxe d'un fichier de configuration d'agent donné par l'option config_file .

Il peut s'agir de la configuration de l'agent générée par generate-config et modifiée ultérieurement, ou d'un fichier de configuration de l'agent créé en téléchargeant l'exemple de fichier de configuration à partir du site de téléchargement.

En plus de valider la syntaxe du fichier de configuration, l'utilisation du license_key contenu dans le fichier de configuration de l'agent pour identifier votre compte testera également si une connexion peut être établie avec nos serveurs.

Cette sous-commande peut donc être utilisée pour s'assurer que le DNS est disponible pour résoudre le nom d'hôte de notre hôte collecteur de données et qu'il y a une connectivité réseau disponible et qu'aucun pare-feu ne bloque l'accès.

En vous connectant à nos serveurs, le test créera une application sous votre compte appelée Python Agent Test. Dans cette application, une petite quantité de données de transaction Web simulées et d'erreurs seront signalées. Après un certain temps, cette application de votre compte pourra être supprimée de la liste Applications si vous le souhaitez.

Lorsque ce test est exécuté, un fichier de log sera créé à l'emplacement :

/tmp/python-agent-test.log

Si vous devez remplacer cet emplacement, vous pouvez fournir l'option log_file . Pour que ce qui serait écrit dans le fichier de log soit affiché sur votre écran, vous pouvez utiliser stdout ou stderr comme valeur passée comme option log_file.

Lorsque vous utilisez un service d'hébergement tel que Heroku où un fichier de configuration d'agent ne serait normalement pas utilisé, cette sous-commande peut toujours être utilisée pour tester la connexion avec nous. Pour Heroku, les informations de clé de licence sont définies dans une variable d'environnement configurée automatiquement par Heroku lorsque vous ajoutez le module complémentaire New Relic à votre instance Heroku.

Dans ce cas où une variable d'environnement est utilisée pour définir la clé de licence, pour exécuter le test de connectivité, transmettez la valeur - pour l'option config_file à la place du chemin d'accès au fichier de configuration de l'agent. Donc, pour exécuter la commande sur votre instance Heroku, vous utiliseriez :

$
heroku run newrelic-admin validate-config - stdout

Notez que nous avons fourni stdout pour le fichier de log dans ce cas, sinon il serait nécessaire de récupérer séparément le fichier de log généré.

Il est recommandé, lors de la configuration de l'agent Python pour la première fois, ou même peut-être sur un nouvel hôte, d'utiliser cette sous-commande pour tester si les données peuvent être signalées correctement. Pour plus d’informations, voir Test de l’agent Python.

run-program ...

Exécute la ligne de commande pour une application Web Python donnée comme ... mais force l'initialisation de l'agent automatiquement au démarrage.

Il s'agit d'une méthode de raccourci permettant de démarrer une application Web Python sans avoir à apporter manuellement des modifications à l'application Web pour ajouter du code permettant d'initialiser spécifiquement l'agent Python. Il peut être utilisé dans n'importe quelle situation où un framework Web Python ou un serveur WSGI est utilisé où l'instrumentation est automatiquement ajoutée pour encapsuler le point d'entrée de l'application WSGI. En d’autres termes, dans les situations où seul le code d’initialisation de l’agent devait être ajouté.

La configuration de l'agent lors de l'utilisation de cette méthode peut être fournie de deux manières différentes. Si vous utilisez un fichier de configuration d'agent complet, l'emplacement de cette configuration peut être fourni par la variable d'environnement NEW_RELIC_CONFIG_FILE .

Si vous utilisiez gunicorn par exemple, vous pourriez dire :

NEW_RELIC_CONFIG_FILE=newrelic.ini newrelic-admin run-program gunicorn wsgi:application

OU

$
NEW_RELIC_CONFIG_FILE=newrelic.ini
$
export NEW_RELIC_CONFIG_FILE
$

$
newrelic-admin run-program gunicorn wsgi:application

Lors de la spécification de l'emplacement du fichier de configuration à l'aide de la variable d'environnement NEW_RELIC_CONFIG_FILE, les variables d'environnement supplémentaires suivantes peuvent être définies pour personnaliser la manière dont le fichier de configuration est traité.

NEW_RELIC_ENVIRONMENT:Le nom d'un environnement de déploiement spécifique. Si cela est spécifié, la configuration de remplacement supplémentaire sera lue à partir d'une section de déploiement distincte dans le fichier de configuration. La section du fichier de configuration pour un environnement de déploiement spécifique doit être nommée newrelic:environment où environment est remplacé par le nom spécifié par cette variable d'environnement

Au lieu d'un fichier de configuration d'agent complet, vous pouvez également définir des variables d'environnement fournissant uniquement les informations clés de configuration de l'agent. Les variables d'environnement qui peuvent être définies dans ce cas sont :

• NEW_RELIC_LICENSE_KEY - Votre New Relic clé de licence.
• NEW_RELIC_APP_NAME - Le nom de l' application pour laquelle vous souhaitez signaler des données dans l' UI. Si non défini, la valeur par défaut est Python Application.
• NEW_RELIC_LOG - Le chemin vers un fichier à utiliser pour le agent log. Si ce paramètre n'est pas défini, aucun logging n'aura lieu. Peut également être défini sur stdout ou stderr pour que le logging soit envoyé vers la sortie standard ou l'erreur standard pour le processus.
• NEW_RELIC_LOG_LEVEL - Le niveau auquel le logging sera généré par l'agent. Si non défini, la valeur par défaut est info. Les valeurs possibles, par ordre croissant de détail, sont : critical, error, warning, info et debug.

Des variables d'environnement individuelles sont utilisées lors de l'hébergement de votre application sur Heroku. Les variables d'environnement seront définies automatiquement comme approprié par l'environnement Heroku lorsque vous ajoutez le module complémentaire New Relic. Il n'est donc pas nécessaire lors de l'utilisation d'Heroku de définir l'une des variables d'environnement ci-dessus lors de l'utilisation de la commande newrelic-admin avec cette option depuis votre Procfile.

Notez que le programme encapsulé doit utiliser la même installation Python ou le même environnement virtuel que celui dans lequel le package de l'agent Python et le script newrelic-admin ont été installés. Si ce n'est pas le cas, le script wrapper n'aura aucun effet et vous risquez même de rencontrer une erreur au démarrage de l'interpréteur Python en raison de l'impossibilité de trouver le package Python newrelic .

Si vous utilisez sudo pour démarrer votre application WSGI en tant qu'autre utilisateur, sachez que la configuration par défaut de sudo sera généralement telle que les variables d'environnement utilisateur du shell dans lequel sudo est exécuté seront ignorées. Dans ce cas, vous devrez modifier la configuration sudoers pour permettre le passage des variables d'environnement spécifiques. Vous pouvez également créer un script shell qui définit les variables d’environnement et exécute votre application WSGI sous newrelic-admin. Pour démarrer votre application WSGI en tant qu'utilisateur différent, exécutez sudo sur ce script plutôt que directement sur votre application WSGI.

L'utilisation d'un script wrapper supplémentaire pour définir les variables d'environnement et exécuter votre application WSGI sous newrelic-admin peut également être requise lors de l'utilisation de supervisord si des problèmes surviennent avec les paramètres des variables d'environnement dans la configuration supervisord qui ne sont pas transmis correctement.

run-python ...

Exécute l'exécutable python à partir de l'installation Python ou de l'environnement virtuel dans lequel newrelic-admin est installé avec les arguments donnés comme ... mais force l'initialisation de l'agent automatiquement au démarrage.

Il s'agit d'une méthode de raccourci permettant de démarrer une application Web Python sans avoir à apporter manuellement des modifications à l'application Web pour ajouter du code permettant d'initialiser spécifiquement l'agent Python. Il peut être utilisé dans n'importe quelle situation où un framework Web Python ou un serveur WSGI est utilisé où l'instrumentation est automatiquement ajoutée pour encapsuler le point d'entrée de l'application WSGI. En d’autres termes, dans les situations où seul le code d’initialisation de l’agent devait être ajouté.

Comme pour la sous-commande run-program ci-dessus, les variables d’environnement sont utilisées pour configurer l’agent Python. Si vous utilisiez directement l'exécutable python par exemple, vous pourriez dire :

NEW_RELIC_CONFIG_FILE=newrelic.ini newrelic-admin run-python wsgi.py

OU

$
NEW_RELIC_CONFIG_FILE=newrelic.ini 
$
export NEW_RELIC_CONFIG_FILE 
$

$
newrelic-admin run-python wsgi.py

license-key config_file [log_file]

Affiche la clé de licence qui sera utilisée. Cela peut être utilisé dans n'importe quel script de démarrage avant le démarrage WSGI application de log l' réelle pour la clé de licence dans le but de vérifier que la valeur correcte est utilisée.

Il peut être utilisé avec le fichier de configuration de l'agent :

$
newrelic-admin license-key newrelic.ini

OU

Si vous définissez la clé de licence à l'aide de variables d'environnement, utilisez - comme nom du fichier de configuration :

$
NEW_RELIC_LICENSE_KEY='YOUR-LICENSE-KEY'
$
export NEW_RELIC_LICENSE_KEY 
$

$
newrelic-admin license-key -

La sortie sera sous la forme :

license_key = 'YOUR-LICENSE-KEY'

Si aucune clé de licence n'a été trouvée dans le fichier de configuration de l'agent ou récupérée à partir des variables d'environnement utilisateur, la sortie sera :

license_key = None

network-config config_file [log_file]

Affiche la configuration réseau qui sera utilisée. Cela peut être utilisé dans n'importe quel script de démarrage avant le démarrage de l' réelle pour WSGI application la log du réseau configuration dans le but de vérifier que les valeurs correctes sont utilisées.

Il peut être utilisé avec le fichier de configuration de l'agent :

$
newrelic-admin network-config newrelic.ini

OU

Si vous définissez des informations de proxy à l'aide de variables d'environnement, utilisez - comme nom du fichier de configuration :

$
NEW_RELIC_PROXY_HOST=proxy.example.com
$
export NEW_RELIC_PROXY_HOST
$

$
NEW_RELIC_PROXY_PORT=8888
$
export NEW_RELIC_PROXY_PORT
$

$
newrelic-admin network-config -

La sortie sera sous la forme :

host = 'collector.newrelic.com'
port = 0
proxy_host = 'proxy.example.com'
proxy_port = 8888
proxy_user = None
proxy_pass = None
ssl = True

Une valeur de 0 pour le port indique que le numéro de port, 80 ou 443, sera automatiquement sélectionné selon qu'une connexion SSL est utilisée pour communiquer avec notre collecteur de données.

local-config config_file [log_file]

Génère la configuration de l'agent local en fonction des valeurs par défaut intégrées, des variables d'environnement et de tout fichier de configuration de l'agent. Ces informations peuvent être demandées par notre support technique lorsque vous essayez de déboguer des problèmes de démarrage de l'agent. Il peut être utilisé avec le fichier de configuration de l'agent :

$
newrelic-admin local-config newrelic.ini

OU

Si vous définissez des paramètres à l'aide de variables d'environnement, vous pouvez utiliser - comme nom du fichier de configuration :

$
newrelic-admin local-config -

server-config config_file [log_file]

Génère la configuration complète pour une application spécifique. Il s'agira de la configuration de l'agent local, remplacée par toute configuration côté serveur pour l'application spécifique. Ces informations peuvent être demandées par notre support technique lorsque vous essayez de déboguer des problèmes de démarrage de l'agent.

Il peut être utilisé avec le fichier de configuration de l'agent :

$
newrelic-admin server-config newrelic.ini

OU

Si vous modifiez des paramètres à l'aide de variables d'environnement, vous pouvez utiliser - comme nom du fichier de configuration :

$
newrelic-admin server-config -

Afin d'obtenir la configuration côté serveur, ce script forcera l'enregistrement de l'agent pour l'application spécifique définie par la configuration. Si cette application n'apparaît pas déjà dans l'interface utilisateur d'APM, une entrée sera créée pour elle, mais aucune donnée métrique ne sera signalée à son sujet.

description du fichier de configuration record-déployer

Il New Relic API applications'agit d'un wrapper autour de l' REST pour enregistrer le déploiement de votre . Vous pouvez également enregistrer le déploiement directement via l' API REST.

Pour utiliser la commande :

1. Ajoutez votre clé API dans le fichier de configuration de l'agent (newrelic.ini) en ajoutant une ligne similaire à la suivante dans la section [newrelic] :

   api_key=substitute-your-api-key-here

   Copier

2. Appelez la commande newrelic-admin depuis la ligne de commande. (Ne l'ajoutez pas à votre fichier de configuration.) en utilisant la structure de sous-commande suivante :

   bash

   Copier

   $
   newrelic-admin record-deploy config_file description [revision changelog user]

Cette sous-commande a deux arguments obligatoires :

• config_file: Chemin vers le nom du fichier de configuration
• description: Texte pour décrire ou identifier le déploiement ; par exemple, les commentaires de validation Git

Il existe également trois arguments facultatifs :

• revision: Identifie une révision spécifique en cours de déploiement
• changelog: Fournit un log détaillé des modifications apportées
• user:Identifie la personne responsable du déploiement

Autres conseils avancés

Voici quelques instructions avancées pour exécuter le script d'administration :

$
NEW_RELIC_CONFIG_FILE=newrelic.ini
$
export NEW_RELIC_CONFIG_FILE
$

$
newrelic-admin run-program YOUR_COMMAND_OPTIONS

$
NEW_RELIC_CONFIG_FILE=newrelic.ini
$
export NEW_RELIC_CONFIG_FILE
$

$
exec newrelic-admin run-program YOUR_COMMAND_OPTIONS

[program:warpdrive]
command = newrelic-admin run-program YOUR_COMMAND_OPTIONS
environment = NEW_RELIC_CONFIG_FILE=newrelic.ini

$
newrelic-admin run-program python main.py
$

$
newrelic-admin run-python main.py

[program:warpdrive]
command = newrelic-admin run-program  
environment = PATH="/path/to/python/app/venv/bin",NEW_RELIC_CONFIG_FILE="newrelic.ini"
directory = /path/to/python/app
user = www-data