Python エージェント:高度なインテグレーション

このドキュメントでは、New Relic Pythonエージェントのインストールに関するインテグレーションステップをより詳しく解説しています。

New Relic Pythongエージェントのインストール手順に関しては、標準的なインストールを参照してください。

インテグレーション手順の概要

New Relicパッケージをインストールして設定ファイルを作成した後は、アプリケーションにPythonエージェントを統合する必要があります。このステップでは、エージェントがアプリケーションの重要な関数およびWebリクエストをキャプチャーして、これをレポートすることが可能となります。

インテグレーションには2つのメソッドがあります:

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(人気のPythonのWebサーバー)を使用しており、起動コマンドが以下の場合:

gunicorn -w 3 wsgi:application

New Relicに統合された新しいコマンドは、以下になります:

NEW_RELIC_CONFIG_FILE=newrelic.ini newrelic-admin run-program gunicorn -w 3 wsgi:application
uWSGIをWSGIアプリケーション上で直接実行
newrelic-admin run-program uwsgi --socket /tmp/uwsgi.sock --single-interpreter --enable-threads wsgi.py
Paster serve

以下に示すのは、paster ini設定ファイルで指定されたWSGIアプリケーション上で、paster serveを使用してAdminスクリプトを実行する際の例になります:

newrelic-admin run-program paster serve production.ini

Adminスクリプトの使用をめぐるフレームワーク特有のドキュメンテーションに関しては、Webフレームワークおよびサーバーを参照してください。

以下に示すのは、Adminスクリプトを実行するにあたっての上級手順になります:

複数のラインにわたって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実行ファイルでAdminスクリプトを実行する

実行するコマンドが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のロケーションに関するメモ

実行するnewrelic-adminプログラムは、ご利用のアプリケーションが使用しているものと同じPythonインストレーションもしくは仮想環境に由来したものでなくてはいけません。異なるPythonインストレーションに由来するプログラム/コンポーネントを混合することはできません。これを行うと、エージェントが正しく動作しません。

仮想環境でsupervisordなどのプロセスマネジメントシステムを使用する場合、以下の設定を使用できます:

 [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

PATH環境変数が示すパスは、仮想環境で使用するものと同一のパスである点に注意してください。

このようなnewrelic-adminに関するオプション、またユーザーの環境変数に基づく様々な設定オプションの詳細に関しては、run-programおよびrun-pythonオプションに関する詳細なドキュメンテーションを参照してください。

Adminスクリプトの使用をめぐる詳細に関しては、Adminスクリプトの詳細を参照してください。

アプリケーションコードにおける手動インテグレーション

推奨されたAdminスクリプトインテグレーションメソッドを使用できないか、その使用を希望しない場合は、Webアプリケーションコード内でPythonエージェントを手動で初期化する必要があります。これには、アプリケーションにPythonエージェントパッケージをインポートして、呼び出しを行ってエージェントを初期化するプロセスが伴います。このコールは、アプリケーションのインポートメカニズムを修正することで、ライブラリがインポートされた場合にNew Relicエージェントが認識した関数クラスをリッスンします。

手動のインテグレーションでは、アプリケーションのスクリプトファイルの冒頭もしくはWSGIのエントリーポイントを持つモジュールに、以下を追加します。

標準的なPythonの機能性とは異なり、ここではインポートの順序が重要となります:最初に、New Relicパッケージをインポートする必要があります。

import newrelic.agent
newrelic.agent.initialize('/some/path/newrelic.ini')
... YOUR_OTHER_IMPORTS

この例において、/some/path/newrelic.iniPythonエージェントのインストレーション中に作成された設定ファイルのコピーのロケーションを表しています。設定ファイルは、ご利用のWebアプリケーションによって読み込み可能でなくてはいけません。

デプロイメント環境のオーバーライドの詳細に関しては、以下のドロップダウンを選択してください:

デプロイメント環境のオーバーライド

具体的なデプロイメント環境に対応したエージェントの設定ファイルでオーバーライドを指定するには、その環境名を2つ目の引数としてinitialize() 関数に供給する必要があります:

import newrelic.agent
newrelic.agent.initialize('/some/path/newrelic.ini', 'staging')

New Relic PythonパッケージをPythonの仮想環境にインストールした場合、sys.pathを起動もしくはセットアップした後で、上記ラインを追加し、仮想環境を見つける必要があります。

上記は、可能な限りいつでも、インストゥルメントされるモジュールのインポートに先行しなくてはいけません。Flaskを含む一部のWebフレームワークでは、これが必須となります。インストゥルメンテーションは、このフレームワークのコードのインポートを引き起こす、すべてのインポートの前に配置されない限り、正しく機能しません。

Adminスクリプトを使用しないものの、NEW_RELIC_CONFIG_FILENEW_RELIC_ENVIRONMENTの環境変数を使用してエージェントを設定したい場合は、引数なしでinitialize()関数を呼び出すことで自動的に利用できます。

import newrelic.agent
newrelic.agent.initialize()

あるいは、他のすべての構成設定のデフォルトが適切であれば、NEW_RELIC_LICENSE_KEYNEW_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アプリケーションのエントリーポイントが、別のモジュールからインポートされた関数もしくはオブジェクトである場合、ラッパーオブジェクトでラップします:

import myapp
application = myapp.WSGIHandler()

application = newrelic.agent.WSGIApplicationWrapper(application)

対応するWebフレームワークが使用されている場合でも、対応するWebフレームワーク周辺に追加のWSGIミドルウェアを追加するなど、依然としてデコレータもしくはラッパーを明白に使用する可能性があります。こうして、すべてのWSGIミドルウェアの実行が、エージェントによる監視によって確実に網羅されることになります。

デコレータとラッパーのさらなる詳細に関しては、wsgi_application()およびWSGIApplicationWrapperラッパーのドキュメンテーションを参照してください。

その他のヘルプ

推奨する詳細情報: