Pythonのエージェント管理スクリプト。高度な使い方

Pythonエージェントアドミンスクリプトは、インストールプロセスで使用されます。Pythonエージェントパッケージがインストールされると、 newrelic-admin スクリプトもPythonインストールまたは仮想環境の bin ディレクトリにインストールされます。

このドキュメントでは、これらのアドミン・スクリプトの使い方について、さらに詳しく説明しています。

エージェント初期設定ファイルの生成
設定ファイルの検証
New Relicへの接続テスト
スタンドアロンPythonウェブアプリケーションのラッピング起動

サブコマンドの構造

サブコマンドを実行するには、 newrelic-admin スクリプトの第一引数にサブコマンドの名前を指定します。次に、サブコマンドの名前の後にオプションを追加します。例えば、次のようになります。

newrelic-admin help

help<コマンド>

引数を指定せずに実行すると、受け付けたすべてのサブコマンドのリストが表示されます。

$ newrelic-admin help
    Usage: newrelic-admin command [options]

    Type 'newrelic-admin help <command>' for help on any of the commands listed in this document.

To view additional details about a subcommand, run the help command with the subcommand and any of its options. For example:

    $ 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] (ライセンスキーの生成)

エージェント設定ファイルのサンプルを生成します。 license_key オプションは、 New Relic のライセンスキー。

デフォルトでは、サンプルの設定ファイルは標準出力に送られ、画面に表示されます。出力をキャプチャするには、代わりにファイル名を output_file オプションで指定して、ファイルに保存することができます。

サンプルのエージェント設定ファイルが生成されると、ファイル内のライセンスキーオプションのみが更新されます。それでも、ファイルを編集して、 app_name と log_file のオプションを適宜変更する必要があります。詳細については、 Python エージェントのインストールを参照してください。

generate-config コマンドを実行して初期エージェント構成ファイルを作成できない場合は、 download.newrelic.com/python_agent/release/newrelic.ini からサンプル構成ファイルをダウンロードすることができます。

validate-config config_file [log_file]を参照してください。

config_file オプションで指定されたエージェント設定ファイルの構文を検証します。

これは、 generate-config によって生成され、その後編集されたエージェント構成、またはダウンロードサイトからサンプル構成ファイルをダウンロードして作成されたエージェント構成ファイルであるかもしれません。

設定ファイルの構文を検証するだけでなく、エージェントの設定ファイルに含まれる license_key を使用してお客様のアカウントを識別することで、当社のサーバーへの接続が可能かどうかをテストします。

このサブコマンドは、データコレクタホストのホスト名を解決するためのDNSが利用可能であること、ネットワーク接続が可能であること、ファイアウォールがアクセスをブロックしていないことを確認するために使用できます。

当社のサーバーに接続すると、テストはお客様のアカウント下に Python Agent Test というアプリケーションを作成します。このアプリケーションには、少量のシミュレートされたウェブトランザクションデータとエラーが報告されます。一定期間経過後、お客様のアカウントのこのアプリケーションは、必要に応じて Applications リストから削除することができます。

このテストが実行されると、その場所にログファイルが作成されます。

/tmp/python-agent-test.log

この場所を上書きする必要がある場合は、 log_file オプションを指定することができます。ログファイルに書き込まれた内容を画面に表示するには、 stdout または stderr を log_file オプションで渡される値として使用します。

Herokuのように、通常はエージェント設定ファイルを使用しないホスティングサービスを使用する場合でも、このサブコマンドを使用して当社への接続をテストすることができます。Heroku の場合、ライセンスキーの情報は、New Relic アドオンを Heroku インスタンスに追加した際に Heroku が自動的に設定する環境変数に定義されます。

ライセンスキーを定義するために環境変数が使用されているこのケースでは、接続性テストを実行するために、エージェント設定ファイルのパスの代わりに、 config_file オプションに - という値を渡します。つまり、Herokuインスタンスでコマンドを実行するには、次のようにします。

heroku run newrelic-admin validate-config - stdout

なお、今回はログファイル用に stdout を用意していますが、そうでない場合は生成されたログファイルを別途取得する必要があります。

初めてPythonエージェントをセットアップするとき、あるいは新しいホスト上で、データが問題なく報告されるかどうかをテストするために、このサブコマンドを使用することが推奨されます。詳細については、 Testing the Python agent を参照してください。

run-program ...

... として与えられた Python Web アプリケーションのコマンドラインを実行しますが、起動時に自動的にエージェントの初期化を強制します。

これは、Pythonエージェントを初期化するコードを追加するためにWebアプリケーションを手動で変更することなく、Python Webアプリケーションを起動するためのショートカット方法です。この方法は、PythonウェブフレームワークやWSGIサーバーを使用し、WSGIアプリケーションのエントリーポイントをラップするために自動的にインスツルメンテーションが追加されるような状況であれば、どのような場合でも使用することができます。言い換えれば、エージェントの初期化コードのみを追加する必要がある状況です。

この方法では、2つの異なる方法でエージェント構成を提供できます。完全なエージェント設定ファイルを使用する場合は、その設定の場所を NEW_RELIC_CONFIG_FILE 環境変数で指定することができます。

例えばgunicornを使っていたとしたら、次のようになります。

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

または

NEW_RELIC_CONFIG_FILE=newrelic.ini
export NEW_RELIC_CONFIG_FILE

newrelic-admin run-program gunicorn wsgi:application

NEW_RELIC_CONFIG_FILE 環境変数を使用して設定ファイルの場所を指定する場合、設定ファイルの処理方法をカスタマイズするために、以下の追加の環境変数を設定することができます。

NEW_RELIC_ENVIRONMENT: 特定のデプロイメント環境の名前です。指定された場合、追加のオーバーライド設定は、設定ファイル内の別のデプロイメントセクションから読み込まれます。特定のデプロイメント環境のための設定ファイルのセクションは、 newrelic:environment のように命名されなければなりません。 environment は、この環境変数で指定された名前に置き換えられます。

完全なエージェント設定ファイルの代わりに、主要なエージェント設定情報のみを提供する環境変数を設定することもできます。この場合に設定可能な環境変数は以下の通りです。

NEW_RELIC_LICENSE_KEY - Your New Relic ライセンスキー.
NEW_RELIC_APP_NAME - UIでデータを報告したいアプリケーションの名前です。定義されていない場合、デフォルトでは Python Application となります。
NEW_RELIC_LOG - エージェントのログに使用されるファイルのパスです。定義されていない場合は、ロギングは行われません。また、 stdout または stderr に設定することで、プロセスの標準出力または標準エラーにログを記録することができます。
NEW_RELIC_LOG_LEVEL - エージェントによってログが出力されるレベルです。定義されていない場合のデフォルトは、 info です。設定可能な値は、詳細度の高い順に以下のとおりです。 critical, error, warning, info , debug 。

個々の環境変数は、Heroku でアプリケーションをホストする際に使用されます。これらの環境変数は、New Relic アドオンを追加した際に Heroku の環境によって適切に自動的に設定されます。したがって、Heroku を使用する場合、 newrelic-admin コマンドにこのオプションを付けて Procfile を使用する際には、上記の環境変数を設定する必要はありません。

ラッピングされたプログラムは、Pythonエージェントパッケージや newrelic-admin スクリプトがインストールされた環境と同じPythonインストールまたは仮想環境を使用している必要があることに注意してください。もしそうでなければ、ラッパースクリプトは何の効果もなく、Pythonインタープリタの起動時に newrelic Pythonパッケージが見つからないというエラーが発生することもあります。

sudo を使用して別のユーザとしてWSGIアプリケーションを起動する場合、デフォルトの sudo の設定では、通常、 sudo を実行するシェルのユーザ環境変数が無視されることに注意してください。この場合、特定の環境変数を渡せるように sudoers の設定を変更する必要があります。あるいは、環境変数を設定し、 newrelic-admin でWSGIアプリケーションを実行するシェルスクリプトを作成します。WSGIアプリケーションを別のユーザーとして起動するには、WSGIアプリケーションに直接ではなく、そのスクリプトに対して sudo を実行します。

newrelic-admin の下で環境変数を設定してWSGIアプリケーションを実行するための追加のラッパースクリプトの使用は、 supervisord を使用する際に、 supervisord の設定内の環境変数の設定が正しく引き継がれないという問題が発生した場合にも必要になることがあります。

run-python ...

python 実行ファイルを、 newrelic-admin がインストールされているPythonインストールまたは仮想環境から、 ... として与えられた引数で実行しますが、起動時に自動的にエージェントの初期化を強制します。

上記の run-program サブコマンドと同様に、環境変数は Python エージェントの設定に使用されます。例えば python 実行ファイルを直接使用していた場合、次のようになります。

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

または

NEW_RELIC_CONFIG_FILE=newrelic.ini 
export NEW_RELIC_CONFIG_FILE 

newrelic-admin run-python wsgi.py

license-key config_file [log_file].

使用される予定のライセンスキーを出力します。これは、実際のWSGIアプリケーションが起動する前のスタートアップスクリプトで使用することができ、正しい値が使用されているかどうかを検証する目的でライセンスキーを記録します。

エージェント設定ファイルと一緒に使用することができます。

newrelic-admin license-key newrelic.ini

または

環境変数を使用してライセンスキーを設定する場合は、設定ファイル名に - を使用してください。

NEW_RELIC_LICENSE_KEY='YOUR-LICENSE-KEY'
    export NEW_RELIC_LICENSE_KEY 
    
    newrelic-admin license-key -

という形で出力されます。

license_key = 'YOUR-LICENSE-KEY'

エージェントの設定ファイルにライセンスキーが見つからない場合や、ユーザーの環境変数からライセンスキーが検出されない場合は、次のように出力されます。

license_key = None

network-config config_file [log_file]を参照してください。

使用されるネットワーク構成を出力します。これは、実際のWSGIアプリケーションが起動する前のスタートアップスクリプトで、正しい値が使用されているかどうかを検証する目的で、ネットワーク構成をログに記録するために使用することができます。

エージェント設定ファイルと一緒に使用することができます。

newrelic-admin network-config newrelic.ini

または

環境変数でプロキシ情報を設定する場合は、設定ファイル名に - を使用してください。

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 -

という形で出力されます。

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

0 port の値は、データコレクタとの通信に SSL 接続が使用されているかどうかに基づいて、80 または 443 のいずれかのポート番号が自動的に選択されることを示します。

local-config config_file [log_file].

ビルトインのデフォルト、環境変数、および任意のエージェント設定ファイルに基づいて、ローカルのエージェント設定を出力します。この情報は、エージェント起動時の問題をデバッグする際に、テクニカルサポートから要求されることがあります。これは、エージェント設定ファイルと一緒に使用することができます。

newrelic-admin local-config newrelic.ini

または

環境変数を使用して何らかの設定を行う場合は、設定ファイル名として - を使用することができます。

newrelic-admin local-config -

server-config config_file [log_file]を指定します。

特定のアプリケーションの完全な設定を出力します。これは、特定のアプリケーションのためのサーバー側の設定によって上書きされる、ローカルエージェントの設定になります。この情報は、エージェント起動時の問題をデバッグする際に、テクニカルサポートから要求されることがあります。

エージェント設定ファイルと一緒に使用することができます。

newrelic-admin server-config newrelic.ini

または

環境変数を使って何か設定を変更する場合は、設定ファイルの名前に - を使用することができます。

newrelic-admin server-config -

サーバー側の設定を取得するために、このスクリプトは、設定によって定義された特定のアプリケーションのためのエージェント登録を強制します。そのアプリケーションがAPMのユーザーインターフェイスにまだ表示されていない場合、そのためのエントリが作成されますが、そのアプリケーションに対するメトリックデータは報告されません。

record-deploy config_file description

これは、アプリケーションのデプロイメントを記録するための New Relic REST API のラッパーです。また、REST API を通じて直接デプロイメントを記録することもできます。

コマンドを使用するには

APIキーを、エージェント設定ファイル (newrelic.ini) の [newrelic] セクションに以下のような行を追加してください。
```
api_key=substitute-your-api-key-here
```
コマンドラインから newrelic-admin コマンドを呼び出します。(設定ファイルには追加しないでください。)以下のようなサブコマンド構成で呼び出します。
```
newrelic-admin record-deploy config_file description [revision changelog user]
```

このサブコマンドには2つの必須引数があります。

config_file: コンフィグファイル名へのパス
説明: デプロイメントを説明または識別するためのテキスト。例えば、Git コミットコメント

また、3つのオプションの引数があります。

リビジョン: デプロイされている特定のリビジョンを示す。
changelog: どのような変更が行われたかの詳細なログを提供します。
user: デプロイメントの責任者を特定する。

本書は、お客様のご参考のために原文の英語版を機械翻訳したものです。

Pythonのエージェント管理スクリプト。高度な使い方

サブコマンドの構造

help<コマンド>

generate-config license_key [output_file] (ライセンスキーの生成)

validate-config config_file [log_file]を参照してください。

run-program ...

run-python ...

license-key config_file [log_file].

network-config config_file [log_file]を参照してください。

local-config config_file [log_file].

server-config config_file [log_file]を指定します。

record-deploy config_file description