register_application (PythonエージェントAPI)

構文

newrelic.agent.register_application(name=None, timeout=None)

Pythonエージェントを直ちに登録します。エージェントを手動で初期化する場合に使用します。

説明

initialize が呼ばれたとき、Pythonのエージェントをセットアップしますが、エージェントを コレクター に登録しません。この呼び出しでは、エージェントをコレクターに登録します。

これは主に、ウェブ以外の バックグラウンド・トランザクション APIを使用してインスツルメンテーションされたものに使用されます。ウェブ以外のトランザクションで使用する場合は、 register_application を、 initialize の呼び出し後、できるだけ早く呼び出してください。

Webトランザクションの場合、エージェントは通常、最初のWebリクエストまたはバックグラウンドタスクが発生したときに自動的に登録されます。エージェントは、コレクターから サーバー側の設定 を受け取ります。登録には1秒ほどかかるため、通常、最初のトランザクションから詳細が失われます。 register_application で強制的に登録することで、これらのデータをすべて収集することができますが、そうすると、アプリケーションは登録が完了するのを待ってから Web リクエストを処理したり、バックグラウンドタスクを実行したりすることになります。

スクリプト自体がWSGIサーバを実行する場合は、メインスクリプトファイルのメインプログラムスレッドから register_application を呼び出します。Apache/mod_wsgiまたはuWSGIを使用している場合は、WSGIスクリプトファイルから呼び出しを行い、 initialize の直後に呼び出しを配置してください。

このコールは、 アプリケーション と同じように、アプリケーションオブジェクトを返します。アプリケーションオブジェクトは、現在のエージェントが監視しているアプリケーションへの参照を取得するために使用され、いくつかのPythonエージェントAPIコールで使用されます。

グローバルインポートロック中の呼び出しを避ける

register_application を、Python のグローバルインポートロックが保持されているときにゼロ以外のタイムアウトで呼び出さないでください。言い換えれば、モジュールがインポートされている間、グローバルスコープのモジュールファイル内で呼び出さないでください。これを行うと、この呼び出しによって生成されたバックグラウンドスレッドとの間で一時的なデッドロックが発生する可能性があります(デッドロックはタイムアウトが切れるまで解消されません)。

多くのWSGIサーバは、標準的なPythonモジュールインポートメカニズムを介してWSGIアプリケーションを含むモジュールをインポートすることに注意してください。そのような場合、グローバルなインポートロックが保持され、上述のデッドロック問題が発生する可能性があります。

Gunicornの場合。先ほど説明したデッドロックの問題は、Gunicornを使用している場合にも発生します。この問題は、WSGIモジュールから register_application をトリガーすることは、親プロセスにモジュールをプリロードすることになるので安全ではありません。 register_application をGunicornで使用するには（タイムアウトの有無にかかわらず）、 post_fork() コールバックから呼び出してください。これはApache/mod_wsgiでは問題ありません。これらのツールはこのようなことをしないように設計されていますので、WSGIアプリケーションがロードされたときにバックグラウンドスレッドを作成しても安全です。

ワーカープロセスのフォーク後の呼び出し

子ワーカープロセスでトランザクションを記録している場合、子ワーカープロセスがフォークされる前に親プロセスで register_application を呼び出さないでください。フォークする前に register_application を呼び出すと、プロセスがフォークされたときにバックグラウンドのエージェントスレッドが殺されてしまいます。親スレッドがデータをコレクタに報告しているため、エージェントは子ワーカープロセスからデータを報告することができません。

パラメータ

戻り値

他のPythonエージェントAPIコールで使用可能なアプリケーションオブジェクトを返します。

例

バックグラウンドタスクの登録

この例では、ウェブ以外のバックグラウンドタスクを長いタイムアウトで登録しています。通常、ウェブアプリケーションでは、非常に短いタイムアウト（デフォルトは0）を設定しますが、頻度の低い非ウェブタスクでは、初期化と登録が確実に行われるように、より長いタイムアウトを設定することがあります。

import newrelic.agent

newrelic.agent.initialize('newrelic.ini')
newrelic.agent.register_application(timeout=10.0)

@newrelic.agent.background_task()
def main():
    pass

if __name__ == '__main__':
    main()