Pythonエージェントパッケージをインストールして設定ファイルを作成した後、アプリケーションにPythonエージェントを統合する必要があります。このステップでは、エージェントがアプリケーションの重要な関数およびWebリクエストをキャプチャーして、これをレポートすることが可能となります。
インテグレーションには2つのメソッドがあります:
ヒント
Pythonなどのエージェント、およびその他のオブザーバビリティ プラットフォームを使用するには、New Relicファミリーに参加してください。サインアップして、わずか数秒で無料アカウントを作成できます。次に、毎月最大で100GBのデータを無料で取り込みます。期間無制限です。
Adminスクリプトのインテグレーションメソッド
コマンドライン経由でAdminスクリプトを使用する方法の簡単な解説に関しては、上級インストール手順のインテグレーションセクションを参照してください。以下に、詳細とコンテキストをさらに解説しています。
newrelic-admin
は、ご利用のWSGIサーバーもしくはWebアプリケーションの起動に使用するコマンドに接頭辞をつけます。このスクリプトは、起動コマンドにラップして、共通のフレームワークによって使用される一定の関数クラスにリッスンすることで機能します。(デフォルトでインストゥルメントされていない関数およびメソッドをインストゥルメントするには、カスタムインストゥルメンテーションを使用します。)
以下に示すのは、このスクリプトを実行した例です:
古いコマンド形式 | 新しいコマンド形式 |
---|
YOUR_ORIGINAL_COMMAND_OPTIONS
| NEW_RELIC_CONFIG_FILE=newrelic.ini newrelic-admin run-program YOUR_ORIGINAL_COMMAND_OPTIONS
|
VARIABLE=VALUE YOUR_ORIGINAL_COMMAND_OPTIONS
| NEW_RELIC_CONFIG_FILE=newrelic.ini VARIABLE=value newrelic-admin run-program YOUR_ORIGINAL_COMMAND_OPTIONS
|
以下の例では、Bourneシェルについて解説しています。異なるシェルに応じて、こうした解説を調整する必要があるかもしれません。
Gunicornを使用しており、起動コマンドが以下である場合:
gunicorn -w 3 wsgi:application
新しいagent-integratedコマンドは、次のようになります。
NEW_RELIC_CONFIG_FILE=newrelic.ini newrelic-admin run-program gunicorn -w 3 wsgi:application
newrelic-admin run-program uwsgi --socket /tmp/uwsgi.sock --single-interpreter --enable-threads wsgi.py
以下に示すのは、paster ini設定ファイルで指定されたWSGIアプリケーション上で、paster serveを使用してAdminスクリプトを実行する際の例になります:
newrelic-admin run-program paster serve production.ini
Adminスクリプトの使用をめぐるフレームワーク特有のドキュメンテーションに関しては、Webフレームワークおよびサーバーを参照してください。
以下に示すのは、Adminスクリプトを実行するにあたっての上級手順になります:
スクリプトを実行する前に、NEW_RELIC_CONFIG_FILE
環境変数を別々に設定してエクスポートできます。必ず、YOUR_COMMAND_OPTIONS
に関して既存のコマンドオプションを置き換えてください:
NEW_RELIC_CONFIG_FILE=newrelic.ini
export NEW_RELIC_CONFIG_FILE
newrelic-admin run-program YOUR_COMMAND_OPTIONS
起動コマンドがexec
を使用する場合、環境変数の設定とAdminスクリプトの実行を区別してください。必ず、YOUR_COMMAND_OPTIONS
に関して既存のコマンドオプションを置き換えてください:
NEW_RELIC_CONFIG_FILE=newrelic.ini
export NEW_RELIC_CONFIG_FILE
exec newrelic-admin run-program YOUR_COMMAND_OPTIONS
環境変数を別々の構成設定にしなくてはならないsupervisordなどのプロセス管理システムを使用する場合は、コマンドと同じラインに設定することはできません。
例えば、supervisordの下で、以下を使用することができます。既存のコマンドオプションをYOUR_COMMAND_OPTIONS
に置き換えてください。
[program:warpdrive]
command = newrelic-admin run-program YOUR_COMMAND_OPTIONS
environment = NEW_RELIC_CONFIG_FILE=newrelic.ini
実行するコマンドがpython
の実行ファイルであり、それがpython main.py
としてPythonコードファイル上で直接実行されている場合、以下のいずれかを使用してください:
newrelic-admin run-program python main.py
newrelic-admin run-python main.py
run-python
を使用することで、 Pythonインスタレーションにインストールされたもの、もしくはnewrelic-adminがインストールされた仮想環境と同じpython
の実行ファイルを必ず使用できます。
実行するnewrelic-adminプログラムは、ご利用のアプリケーションが使用しているものと同じPythonインストレーションもしくは仮想環境に由来したものでなくてはいけません。異なるPythonインストレーションに由来するプログラム/コンポーネントを混合することはできません。これを行うと、エージェントが正しく動作しません。
仮想環境でsupervisordなどのプロセスマネジメントシステムを使用する場合、以下の設定を使用できます:
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
PATH
環境変数が示すパスは、仮想環境で使用するものと同一のパスである点に注意してください。
このようなnewrelic-adminに関するオプション、またユーザーの環境変数に基づく様々な設定オプションの詳細に関しては、run-program
およびrun-python
オプションに関する詳細なドキュメンテーションを参照してください。
詳細に関しては、Adminスクリプトの詳細を参照してください。
アプリケーションコードにおける手動インテグレーション
推奨されるAdminスクリプトインテグレーションを使用できない場合は、Webアプリコード内でPythonエージェントを手動で初期化する必要があります。これには、アプリケーションにPythonエージェントパッケージをインポートして、呼び出しを行ってエージェントを初期化するプロセスが伴います。このコールは、アプリケーションのインポートメカニズムを修正することで、ライブラリがインポートされた場合にエージェントが認識した関数クラスをリッスンします。
手動のインテグレーションでは、アプリケーションのスクリプトファイルの冒頭もしくはWSGIのエントリーポイントを持つモジュールに、以下を追加します。
重要
標準的なPythonの機能性とは異なり、ここではインポートの順序が重要となります:最初に、パッケージをインポートする必要があります。
import newrelic.agent
newrelic.agent.initialize('/some/path/newrelic.ini')
... YOUR_OTHER_IMPORTS
この例において、/some/path/newrelic.iniはPythonエージェントのインストレーション中に作成された設定ファイルのコピーのロケーションを表しています。設定ファイルは、ご利用のWebアプリケーションによって読み込み可能でなくてはいけません。
特定のデプロイメント環境に対応したエージェント設定ファイルでオーバーライドを指定するには、initialize()
関数の2つ目の引数として、その環境名を指定する必要があります。PythonパッケージをPythonの仮想環境にインストールした場合、sys.pathを起動またはセットアップした後に上記ラインを追加して、仮想環境を見つける必要があります。
import newrelic.agent
newrelic.agent.initialize('/some/path/newrelic.ini', 'staging')
この手順は、可能な限り、インストゥルメントされるモジュールのインポートより先に行います。Flaskを含む一部のWebフレームワークでは、これが必須となります。インストゥルメンテーションは、そのフレームワークのコードがインポートされるすべてのインポートの前に配置しないと正しく機能しません。
Adminスクリプトを使用せず、NEW_RELIC_CONFIG_FILE
とNEW_RELIC_ENVIRONMENT
の環境変数を使用してエージェントを設定する場合は、引数なしでinitialize()
関数を呼び出すことで、これらの環境変数が自動的に読み込まれます。
newrelic.agent.initialize()
あるいは、他のすべての構成設定のデフォルトが適切であれば、NEW_RELIC_LICENSE_KEY
とNEW_RELIC_APP_NAME
の環境変数を設定することもできます。
Apache/mod_wsgiなどの組み込み環境では、一般的に、環境変数から設定を抽出することは難しくなります。これは通常、組み込みシステムではWSGIスクリプトファイルで利用可能なプロセスの環境変数を設定できないことが原因です。詳細については、initialize()関数のドキュメントをご覧ください。
サポートされていないWebフレームワーク
サポートされていないWebフレームワークを使用しているか、WerkzeugもしくはPasteなどのWSGIコンポーネントを使用してWSGIアプリケーションを構築している場合、WSGI アプリケーションのエントリーポイントを手動でラップする必要があるかもしれません。これは、メインとなるインテグレーション方法(Adminスクリプトの使用またはPythonエージェントの手動初期化)に加えて行います。
WSGIアプリケーションのエントリーポイントが、ファイル自体で宣言された関数である場合、デコレータを使用します:
@newrelic.agent.wsgi_application()
def application(environ, start_response):
WSGIアプリケーションのエントリーポイントが、別のモジュールからインポートされた関数もしくはオブジェクトである場合、ラッパーオブジェクトでラップします:
application = myapp.WSGIHandler()
application = newrelic.agent.WSGIApplicationWrapper(application)
サポートされるWebフレームワークが使用されている場合でも、デコレータまたはラッパーを明示的に使用できます。例えば、サポートされるWebフレームワーク周辺に追加のWSGIミドルウェアを設定する場合などです。こうして、すべてのWSGIミドルウェアの実行が、エージェントによる監視によって確実に網羅されることになります。
詳しくは、wsgi_application()とWSGIApplicationWrapperラッパーのドキュメントを参照してください。
その他のヘルプ
さらに支援が必要な場合は、これらのサポートと学習リソースを確認してください: