Version de développement

Cette documentation décrit la version « next » (develop), non encore publiée. Pour la version stable, basculez sur « v5 » dans l'en-tête.

Performance et Optimisation

Analyser les hooks Python dans les performances

Visualiser les appels de hooks personnalisés sur la timeline de l'enregistreur de performances.

Analyser les hooks Python dans les performances

Aperçu

L'Enregistreur de Dodock (Recorder) capture la trace d'une requête HTTP ou d'une tâche de fond. Dans la version en développement, chaque appel à un hook déclaré dans le fichier hooks.py d'une application apparaît sur la timeline. La ligne indique le hook, l'application d'origine, la durée et le nombre de requêtes SQL déclenchées.

Cette page s'adresse aux développeurs et aux administrateurs qui cherchent la cause d'une lenteur. En v5, seuls les doc_events sont tracés : pour les autres hooks, seule leur activité SQL apparaît.

Pourquoi les hooks n'apparaissaient pas

Les hooks définis dans hooks.py sont invoqués à différents moments du cycle de vie d'une requête :

additional_timeline_content
has_permission
permission_query_conditions
extend_bootinfo
et bien d'autres

Ces appels se produisent souvent en dehors du traçage des méthodes de documents (Document.run_method). Sans traçage dédié, seules leurs requêtes SQL apparaissent : la source d'une lenteur reste difficile à trouver.

Fonctionnement

Lorsqu'une session d'enregistrement est active, avec l'option « Capture document lifecycle timeline » cochée :

Le Recorder enveloppe la résolution d'attributs via frappe.get_attr pour intercepter les fonctions définies comme hooks.
Chaque fonction résolue est instrumentée individuellement et enregistrée comme une ligne sur la timeline.
La ligne indique le nom du hook, l'application qui l'a fourni, le temps écoulé et le nombre de requêtes SQL exécutées pendant l'appel.
L'instrumentation s'applique uniquement à l'enregistreur actif ; aucune autre requête concurrente n'est affectée.

Exclusions

Ces hooks ne sont pas tracés individuellement :

Hook	Raison
`doc_events`	Déjà tracé avec les méthodes du document (`run_method`)
`filters_config`	Lu à chaque analyse de filtre
`override_doctype_class`, `override_doctype_dashboards`, `override_whitelisted_methods`	Résolus au chargement, pas appelés pendant la requête
`scheduler_events`	Exécutés par le planificateur, hors requête

Où consulter les résultats

Ouvrez la liste Enregistreur (/desk/recorder).
Cliquez sur Démarrer. Dans la fenêtre Configurer l'enregistreur, laissez cochée l'option « Capture document lifecycle timeline » (libellé non traduit), puis cliquez sur Commencer à enregistrer.
Reproduisez votre scénario, puis cliquez sur Arrêter.
Ouvrez le détail d'une requête enregistrée.
Sur la timeline, les lignes correspondant aux hooks apparaissent au même niveau que les appels de méthodes et les requêtes SQL.

      
flowchart LR
    A[Démarrage Recorder] --> B[Résolution hook via frappe.get_attr]
    B --> C{Hook instrumenté?}
    C -- Oui --> D[Exécution tracée]
    D --> E[Ligne timeline: hook, app, durée, SQL]
    C -- Exclusions --> F[Pas de trace dédiée]
    C -- doc_events --> G[Trace via run_method]

Bonnes pratiques

Profitez des détails temporels : comparez la durée d'un hook au nombre de requêtes SQL qu'il génère pour détecter les inefficiences.
Repérez les hooks chronophages : un hook consommant la majorité du temps d'une requête peut être optimisé ou désactivé temporairement pour confirmer son impact.
Évitez le sur-enregistrement : arrêtez le Recorder dès que votre scénario est reproduit pour ne pas saturer la timeline.