function_trace (Python API d'agent)

Syntaxe

newrelic.agent.function_trace(name=None, group=None, label=None, params=None, terminal=False)

Utilisé pour instrumenter des fonctions, des méthodes, des générateurs et des coroutines qui ne sont pas instrumentés par défaut.

Description

function_trace est un décorateur permettant d'ajouter des fonctions, des méthodes, des générateurs et des coroutines. L'ajout de ce décorateur vous permet de collecter des informations de transaction supplémentaires (y compris des informations trace de transaction). (Une autre façon d'instrumenter les fonctions sans avoir à toucher au code de votre application est de les répertorier dans le fichier de configuration.)

function_trace ne vous donne pas un profil complet de toutes les fonctions qui se produisent dans une fonction décorée. Ce qu'il fait, c'est ajouter la fonction décorée en tant que nœud dans l'UI New Relic et capturer le temps passé dans cette fonction. Si vous avez besoin de plus de détails sur ce qui se passe dans cette fonction, vous devrez également appliquer la trace de fonction aux fonctions enfants de la fonction.

Le décorateur function_trace peut être utilisé sur les générateurs et les coroutines avec la version d'agent 2.102.0.85 ou supérieure. La synchronisation de ces objets commence lorsque la consommation commence et se termine lorsque l'objet est épuisé ou sort du champ d'application. Il s’agit d’un changement par rapport aux versions précédentes où la métrique représentait le temps nécessaire à la création du générateur ou de l’objet coroutine lui-même.

Vous pouvez utiliser le décorateur en conjonction avec les décorateurs existants, y compris ceux pour les méthodes statiques et de classe. Lors de l'imbrication de plusieurs décorateurs, choisissez le décorateur function_trace comme décorateur le plus externe.

Formes d'appel alternatives

Pour les configurations où vous ne pouvez pas utiliser le décorateur, ces formulaires d'appel alternatifs sont disponibles :

Le gestionnaire de contexte

Le gestionnaire de contexte FunctionTrace est utilisé lorsque le paramètre à transmettre ne peut pas être déterminé avant l'exécution. (Par exemple, vous ne connaissez peut-être pas le nom d’une fonction au moment de l’importation.) Lorsque vous utilisez le gestionnaire de contexte pour nommer une métrique, vous devez toujours fournir le nom et le préfixe du chemin de la métrique.

La classe FunctionTrace implémente le gestionnaire de contexte et est utilisée conjointement avec l'instruction with . La classe FunctionTrace est la primitive de niveau le plus bas disponible pour tracer le temps par rapport à une transaction.

L'instruction with définit les limites de ce qui est chronométré et non une fonction unique. Ainsi, le gestionnaire de contexte pourrait être appliqué à un bloc de code arbitraire. Le bloc de code peut donc contenir des appels à plusieurs fonctions, ou il peut s'agir d'un bloc de code autonome implémentant un algorithme orienté temporel que vous souhaitez suivre.

L'emballage

Si vous savez à l'avance où se trouvent les fonctions spécifiques que vous souhaitez trace, vous pouvez utiliser le décorateur function_trace. Cependant, si vous don't connaissez toutes les fonctions qui doivent être tracées (par exemple, si elles sont recherchées dynamiquement dans le cadre d'un système de routage), vous devez alors utiliser FunctionTraceWrapper pour encapsuler la fonction au moment de l'enregistrement ou au moment de l'appel.

Enveloppement basé sur le chemin

wrap_function_trace est utilisé pour encapsuler des fonctions en dehors du code dans lequel elles sont déclarées. Par exemple : vous pouvez l'utiliser pour instrumenter le code de la bibliothèque que vous ne souhaitez pas modifier.

Pour en savoir plus sur les différences entre ces formats d’appel, voir Différents formats d’appel.

Paramètres

paramètre pour le décorateur

newrelic.agent.function_trace(name=None, group=None, label=None, params=None, terminal=False)

Cet appel inclut ces paramètres :

paramètre pour le gestionnaire de contexte

newrelic.agent.FunctionTrace(name, group=None, label=None, params=None, terminal=False)

Le paramètre pour le gestionnaire de contexte inclut tous les paramètres de function_trace. Le paramètre name est obligatoire et non facultatif.

Paramètres de l'enveloppe

newrelic.agent.FunctionTraceWrapper(wrapped, name=None, group=None, label=None, params=None, terminal=False)

Le paramètre du wrapper inclut tous les paramètres de function_trace et un paramètre wrapped :

Paramètre d'emballage basé sur le chemin

newrelic.agent.wrap_function_trace(module, object_path, name=None, group=None, label=None, params=None, terminal=False)

Le paramètre inclut tous les paramètres de function_trace et ces paramètres :

Exemples

function_trace

Un exemple d'utilisation du décorateur 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):
...

Un exemple d'utilisation du décorateur function_trace avec des coroutines natives :

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):
...

Exemple de gestionnaire de contexte

Un exemple d'utilisation du gestionnaire de contexte 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, <DNT>**values)
    except HTTPException as e:
        return e

Exemple d'enveloppe

Un exemple d'utilisation du FunctionTraceWrapper:

Le routage d'URL avec Werkzeug génère un nom qui est d'abord utilisé pour rechercher dynamiquement une méthode d'une classe à l'aide de getattr() et le résultat est ensuite invoqué :

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, **</DNT>values)
    except HTTPException as e:
        return e

Si vous souhaitez trace la fonction point de terminaison, vous pouvez la réécrire comme suit :

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, <DNT>**values)
    except HTTPException as e:
        return e

Si vous souhaitez nommer la métrique d'après le nom du point de terminaison (plutôt que de nommer la métrique en fonction de l'identifiant de la fonction appelée), vous pouvez fournir le nom à utiliser ainsi qu'un préfixe de chemin de métrique alternatif lors de la création de l'objet 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, **</DNT>values)
    except HTTPException as e:
        return e

Pour cet exemple, si le point de terminaison était appelé help, la métrique finale serait :

Python/EndPoint/help

Dans la répartition des performances d'une transaction, la catégorie serait Python et le nom du segment EndPoint/help. Ce nom de segment apparaîtra également dans la trace lente de la transaction comme nom de nœud.