function_trace (PythonエージェントAPI)

構文

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 デコレーターを一番外側のデコレーターにしてください。

代替コールフォーム

デコレーターを使用できない設定の場合は、以下の代替コールフォームを利用できます。

コンテキストマネージャー

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)

このコールには、以下のパラメータが含まれています。

コンテキストマネージャのパラメータ

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 となります。このセグメント名は、スロートランザクションのトレースでもノード名として表示されます。**