構文
newrelic.agent.function_trace(name=None, group=None, label=None, params=None, terminal=False)
デフォルトではインストルメント化されていない関数、メソッド、ジェネレータ、コルーチンをインストルメント化するために使用します。
説明
function_trace
は、関数、メソッド、ジェネレータ、およびコルーチンに追加するデコレータです。このデコレーターを追加することで、 トランザクション の追加情報(トランザクショントレース情報を含む)を収集することができます。(アプリのコードに触れずに関数を計測する別の方法として、 コンフィグファイルに関数をリストアップする方法があります。)
function_trace
では、装飾された関数の中で発生するすべての関数のプロファイルを得ることはできません。この機能は、装飾された関数を New Relic UI のノードとして追加し、その関数に費やされた時間を記録するものです。その関数内で起こっていることについてより詳細な情報が必要な場合は、その関数の子関数にも関数トレースを適用する必要があります。
function_trace
デコレータは、 agent version 2.102.0.85 以降のジェネレータおよびコルーチンで使用できます。これらのオブジェクトのタイミングは、消費が開始されたときに始まり、オブジェクトが使い果たされたときやスコープ外に出たときに終了します。これは、以前のバージョンでは、ジェネレータまたはコルーチンオブジェクト自体の作成にかかった時間を表す指標であったのに対し、変更されています。
このデコレーターは、スタティックメソッドやクラスメソッド用のデコレーターなど、既存のデコレーターと組み合わせて使用することができます。複数のデコレーターを入れ子にする場合は、 function_trace
デコレーターを一番外側のデコレーターにしてください。
重要
ラップされているデコレータについては、その実装にPython標準ライブラリの functools.wraps()
を使用してください。(あるいは、デコレータが、正しい名前のイントロスペクションを可能にするために必要な、最も内側のラップされたオブジェクトの正しい名前の属性を伝搬することを確認してください)。これが行われていない場合、メトリックが報告される際には、入れ子になったデコレータ関数の名前(最も内側にラップされた関数ではない)が使用されます。
代替コールフォーム
デコレーターを使用できない設定の場合は、以下の代替コールフォームを利用できます。
コンテキストマネージャー
FunctionTrace
コンテキスト マネージャは、渡すべきパラメータがランタイム前に決定できない場合に使用します。(たとえば、インポート時に関数名がわからない場合など) コンテキスト マネージャを使用してメトリックに名前を付ける場合は、必ず名前とメトリック パスのプレフィックスを指定する必要があります。
FunctionTrace
クラスは、コンテキストマネージャーを実装し、 with
ステートメントと組み合わせて使用します。 FunctionTrace
クラスは、トランザクションに対して時間をトレースするために利用できる最下位のプリミティブです。
with
ステートメントは、タイムアウトするものの境界を定義するもので、単一の関数ではありません。したがって、コンテキストマネージャーは、任意のコードブロックに適用することができます。したがって、そのコードブロックは、複数の関数の呼び出しを含むこともあれば、追跡したい時間指向のアルゴリズムを実装した自己完結型のコードブロックであることもあります。
重要
過度に多くの回数呼び出されるコードブロックのトレースは避けてください。例えば、何度も実行されるループのコンテキスト内では使用しないでください。生成されたデータは、パフォーマンスのオーバーヘッドになります。より良い解決策は、ループを囲むことです。
ラッパー
トレースしたい特定の関数がどこにあるか事前にわかっている場合は、 function_trace
デコレータを使うことができます。 しかし、 トレースが必要な関数をすべて把握していない場合(例えば、ルーティングシステムの一部として動的に検索されている場合など)は、 FunctionTraceWrapper
を使って、登録時や呼び出し時に関数をラップする必要があります。**
パスベースのラッピング
wrap_function_trace
は、宣言されているコードの外側で関数をラップするために使用します。例えば、変更したくないライブラリコードを計測するために使用します。これらの通話フォーマットの違いについては、 Different call formats をご覧ください。
パラメータ
デコレーターのパラメータ
newrelic.agent.function_trace(name=None, group=None, label=None, params=None, terminal=False)
このコールには、以下のパラメータが含まれています。
パラメーター | 説明 |
---|---|
文字列 | オプションです。関数名を指定します。設定されていない場合は、キャプチャされた関数名がデフォルトとなります。 |
文字列 | オプションです。 省略された場合、グループはデフォルトで |
文字列 | オプションです。トランザクション・トレース内のセグメントにコールアウト形式のフラグを追加します。デフォルトは |
ディクト | オプションです。トランザクション・トレースのセグメントに追加するカスタム・パラメータ。 |
boolean | オプションです。Trueの場合、子供のセグメントは記録されません。デフォルトはFalseです。 |
コンテキストマネージャのパラメータ
newrelic.agent.FunctionTrace(name, group=None, label=None, params=None, terminal=False)
コンテキストマネージャーのパラメータには、 パラメータ から function_trace
までのすべてのパラメータが含まれます。 name
パラメータは必須であり、オプションではありません。
パラメーター | 説明 |
---|---|
文字列 | 必須項目です。関数名です。 |
ラッパーのパラメーター
newrelic.agent.FunctionTraceWrapper(wrapped, name=None, group=None, label=None, params=None, terminal=False)
ラッパーのパラメータには、すべての パラメータ for function_trace
と、 wrapped
パラメータが含まれます。
パラメーター | 説明 |
---|---|
機能 | 必要です。ラッピングされる機能 |
パスベースのラッピングパラメータ
newrelic.agent.wrap_function_trace(module, object_path, name=None, group=None, label=None, params=None, terminal=False)
パラメータには、すべての パラメータ for function_trace
とこれらのパラメータが含まれます。
パラメーター | 説明 |
---|---|
オブジェクト | 必要です。インストルメント化する機能を含むモジュール。 |
文字列 | 関数の場所へのパスです。 |
例
function_trace
例 [#trace_example]function_trace
デコレーターの使用例です。
import newrelic.agent
class _Database(UserDict.DictMixin):
...
@newrelic.agent.function_trace() def _commit(self): ...
@newrelic.agent.function_trace()def open(file, flag=None, mode=0666):...
function_trace
デコレーターをネイティブのコルーチンで使用した例です。
import newrelic.agent
class _Database(UserDict.DictMixin):
...
@newrelic.agent.function_trace() async def _commit(self): ...
@newrelic.agent.function_trace()async def open(file, flag=None, mode=0666):...
コンテクストマネージャーの例 [#context-mgr-example]FunctionTrace
コンテキストマネージャーの使用例です。
import newrelic.agent
def dispatch_request(self, request): adapter = self.url_map.bind_to_environ(request.environ) try: endpoint, values = adapter.match() function = getattr(self, 'on_' + endpoint) with newrelic.agent.FunctionTrace( endpoint, 'Python/EndPoint'): return function(request, **values) except HTTPException as e: return e
ラッパーの例
使用例 FunctionTraceWrapper
:
Werkzeug を使った URL ルーティングでは、まず getattr()
を使ってクラスのメソッドを動的に検索し、その結果を呼び出すための名前が得られます。
def dispatch_request(self, request): adapter = self.url_map.bind_to_environ(request.environ) try: endpoint, values = adapter.match() return getattr(self, 'on_' + endpoint)(request, **values) except HTTPException as e: return e
終点の関数をトレースしたい場合は、次のように書き換えることができます。
import newrelic.agent
def dispatch_request(self, request): adapter = self.url_map.bind_to_environ(request.environ) try: endpoint, values = adapter.match() function = getattr(self, 'on_' + endpoint) function = newrelic.agent.FunctionTraceWrapper(function) return function(request, **values) except HTTPException as e: return e
エンドポイント名にちなんでメトリックの名前を付けたい場合(呼び出されている関数の識別子に基づいてメトリックの名前を付けるのではなく)、 FunctionTraceWrapper
オブジェクトの作成時に、使用する名前に加えて代替のメトリック・パス・プレフィックスを指定することができます。
import newrelic.agent
def dispatch_request(self, request): adapter = self.url_map.bind_to_environ(request.environ) try: endpoint, values = adapter.match() function = getattr(self, 'on_' + endpoint) function = newrelic.agent.FunctionTraceWrapper( function, name=endpoint, group='Python/EndPoint') return function(request, **values) except HTTPException as e: return e
この例では、エンドポイントが help
と呼ばれていた場合、最終的な測定値は次のようになります。
Python/EndPoint/help
トランザクションのパフォーマンスブレークダウンでは、カテゴリーは Python
、セグメント名は EndPoint/help
となります。このセグメント名は、スロートランザクションのトレースでもノード名として表示されます。**