Options d'initialisation

Pour réaliser l'initialisation, pgbench accepte les arguments suivants en ligne de commande :

Options des benchmarks

Pour réaliser un benchmark pgbench accepte les arguments suivants en ligne de commande :

Options courantes

pgbench accepte les arguments suivants en ligne de commande :

Quelles sont les « transactions » réellement exécutées dans pgbench ?

pgbench exécute des scripts de tests choisis de façon aléatoire à partir d'une sélection. Les scripts pourraient inclure des scripts internes indiqués avec l'option -b et des scripts fournis par l'utilisateur indiqués avec l'option -f. Chaque script peut se voir affecter un poids spécifique après un caractère @ pour modifier sa probabilité de sélection. Le poids par défaut est de 1. Les scripts avec un poids de 0 sont ignorés.

Le script interne par défaut (aussi appelé avec -b tpcb-like) exécute sept commandes par transaction choisies de façon aléatoire parmi aid, tid, bid et delta. Le scénario s'inspire du jeu de tests de performance TPC-B benchmark mais il ne s'agit pas réellement de TPC-B, d'où son nom.

Si vous sélectionnez le script interne simple-update (ou -N), les étapes 4 et 5 ne sont pas inclus dans la transaction. Ceci évitera des contentions au niveau des mises à jour sur ces tables mais le test ressemblera encore moins à TPC-B.

Si vous sélectionnez le script interne select-only (ou -S), alors seul le SELECT est exécuté.

Scripts personnalisés

pgbench est capable d'utiliser des scénarios de test de performances personnalisés, en remplaçant le script de transactions par défaut (décrit ci-dessus) par un script de transactions lu depuis un fichier spécifié avec l'option (-f). Dans ce cas, une « transaction » est comptabilisée comme une exécution du fichier script.

Un fichier script contient une ou plusieurs commandes SQL terminées par des points-virgules. Les lignes vides et les lignes commençant par -- sont ignorées. Les fichiers scripts peuvent aussi contenir des « méta-commandes », qui seront interprétées par pgbench comme indiqué plus bas.

Il est possible de procéder facilement à de la substitution de variables dans les fichiers scripts. Les variables peuvent être instanciées via l'option -D de la ligne de commande comme décrit ci-dessus, ou grâce aux méta-commandes décrites ci-dessous. En plus des commandes pré-définies par l'option de la ligne de commande -D, quelques variables sont automatiquement prédéfinies, listées sous Tableau 242. Une valeur de ces variables définie via l'option -D aura priorité sur la valeur définie automatiquement. Une fois définie, la valeur d'une variable peut être insérée dans les commandes SQL en écrivant : nom_variable. S'il y a plus d'une session par client, chaque session possède son propre jeu de variables.

Dans les fichiers de scripts, les méta-commandes commencent avec un anti- slash (\) et s'étendent jusqu'à la fin de la ligne, même si elles peuvent s'étendre sur plusieurs lignes en écrivant anti-slash puis un retour chariot. Les arguments d'une méta-commande sont séparés par des espaces vides. Les méta-commandes suivantes sont supportées :

Fonctions internes

Les fonctions listées dans Tableau 243 sont internes à pgbench et peuvent être utilisées dans des expressions apparaissant dans \set.

La fonction random génère des valeurs en utilisant une distribution uniforme ; autrement dit toutes les valeurs sont dans l'intervalle spécifiée avec une probabilité identique. Les fonctions random_exponential et random_gaussian requièrent un paramètre supplémentaire de type double qui détermine le contour précis de cette distribution.

En tant qu'exemple, la définition complète de la construction de la transaction style TPC-B est :

   \set aid random(1, 100000 * :scale)
   \set bid random(1, 1 * :scale)
   \set tid random(1, 10 * :scale)
   \set delta random(-5000, 5000)
   BEGIN;
   UPDATE pgbench_accounts SET abalance = abalance + :delta WHERE aid = :aid;
   SELECT abalance FROM pgbench_accounts WHERE aid = :aid;
   UPDATE pgbench_tellers SET tbalance = tbalance + :delta WHERE tid = :tid;
   UPDATE pgbench_branches SET bbalance = bbalance + :delta WHERE bid = :bid;
   INSERT INTO pgbench_history (tid, bid, aid, delta, mtime) VALUES (:tid, :bid, :aid, :delta, CURRENT_TIMESTAMP);
   END;
    

Ce script autorise chaque itération de la transaction à référencer des lignes différentes, sélectionnées aléatoirement. (Cet exemple montre aussi pourquoi il est important que chaque session cliente ait ses propres variables -- sinon elles n'affecteront pas les différentes lignes de façon indépendantes.

Journaux par transaction

Avec l'option -l (mais sans l'option --aggregate-interval), pgbench va écrire des informations sur chaque transaction dans un fichier journal. Il sera nommé prefix.nnn, où prefix vaut par défaut pgbench_log, et nnn est le PID du processus pgbench. Le préfixe peut être changé avec l'option --log-prefix. Si l'option -j est positionnée à 2 ou plus, créant plusieurs processus de travail (worker), chacun aura son propre fichier journal. Le premier worker utilisera le même nom pour son fichier journal que dans le cas d'un seul processus. Les fichiers journaux supplémentaires s'appelleront prefix.nnn.mmm, où mmm est un numéro de séquence, identifiant chaque worker, commençant à 1.

Le format du journal est le suivant :

id_client no_transaction temps no_script time_epoch time_us [ schedule_lag ]
    

où client_id indique la session client qui a exécuté la transaction, transaction_no compte le nombre de transactions exécutées par cette session, temps est la durée totale de la transaction en microsecondes, no_script indique quel fichier script a été utilisé (très utile lorsqu'on utilise plusieurs scripts avec l'option -f ou -b), et time_epoch/time_us est un horodatage Unix avec un décalage en microsecondes (utilisable pour créer un horodatage ISO 8601 avec des secondes fractionnées) indiquant à quel moment la transaction s'est terminée. Le champ schedule_lag est la différence entre la date de début planifiée de la transaction et sa date de début réelle, en micro secondes. Il est présent uniquement lorsque l'option --rate est utilisée. Quand les options --rate et --latency-limit sont utilisées en même temps, le champ time pour une transaction ignorée sera rapportée en tant que skipped.

Ci-dessous un extrait du fichier journal généré avec un seul client :

0 199 2241 0 1175850568 995598
0 200 2465 0 1175850568 998079
0 201 2513 0 1175850569 608
0 202 2038 0 1175850569 2663
    

Autre exemple avec les options --rate=100 et --latency-limit=5 (notez la colonne supplémentaire schedule_lag) :

0 81 4621 0 1412881037 912698 3005
0 82 6173 0 1412881037 914578 4304
0 83 skipped 0 1412881037 914578 5217
0 83 skipped 0 1412881037 914578 5099
0 83 4722 0 1412881037 916203 3108
0 84 4142 0 1412881037 918023 2333
0 85 2465 0 1412881037 919759 740
    

Dans cet exemple, la transaction 82 a été en retard, elle affiche une latence (6,173 ms) supérieure à la limite de 5 ms. Les deux transactions suivantes ont été ignorées car elles avaient déjà en retard avant même d'avoir commencé.

Dans le cas d'un test long sur du matériel qui peut supporter un grand nombre de transactions, les journaux peut devenir très volumineux. L'option --sampling-rate peut être utilisée pour journaliser seulement un extrait aléatoire des transactions effectuées.

Agrégation de la journalisation

Avec l'option --aggregate-interval, les fichiers journaux utilisent un format quelque peu différent :

début_intervalle nombre_de_transations somme_latence somme_latence_2 latence_minimum latence_maximum [ somme_retard somme_retard_2 retard_min retard_max [ transactions_ignorées ] ]
    

où début_intervalle est le début de l'intervalle (au format epoch Unix), nombre_de_transations est le nombre de transactions dans l'intervalle, somme_latence est le cumul des latences dans l'intervalle, somme_latence_2 est la somme des carrés des latences dans l'intervalle, latence_minimum est la latence minimum dans l'intervalle, et latence_maximum est la latence maximum dans l'intervalle. Les derniers champs somme_retard, somme_retard_2, retard_min, et retard_max sont présents uniquement si l'option --rate a été spécifiée. Ils fournissent des statistiques sur le temps que chaque transaction a eu à attendre la fin de la précédente, c'est-à-dire la différence entre la date de départ prévue et la date de départ réelle de chaque transaction. Le tout dernier champ, transactions_ignorées, n'est présent que si l'option --latency-limit est utilisée. Chaque transaction est comptabilisée dans l'intervalle où elle a committé.

Voici un exemple de sortie :

1345828501 5601 1542744 483552416 61 2573
1345828503 7884 1979812 565806736 60 1479
1345828505 7208 1979422 567277552 59 1391
1345828507 7685 1980268 569784714 60 1398
1345828509 7073 1979779 573489941 236 1411
    

Notez que tandis que le fichier journal brut (c'est-à-dire non agrégé) contient une référence à quel script a été utilisé pour chaque transaction, le journal agrégé n'en contient pas. De ce fait, si vous avez besoin des données par script, vous devrez agréger ces données vous-même.

Latences par requête

Avec l'option -r, pgbench collecte le temps de transaction écoulé pour chaque requête exécutée par chaque client. Une fois le test de performance terminé, il affiche une moyenne de ces valeurs, désignée comme latence de chaque requête.

Pour le script par défaut, le résultat aura la forme suivante :

starting vacuum...end.
transaction type: <builtin: TPC-B (sort of)>
 scaling factor: 1
scaling factor: 1
query mode: simple
number of clients: 10
number of threads: 1
number of transactions per client: 1000
number of transactions actually processed: 10000/10000
latency average = 15.844 ms
latency stddev = 2.715 ms
tps = 618.764555 (including connections establishing)
tps = 622.977698 (excluding connections establishing)
script statistics:
 - statement latencies in milliseconds:
        0.002  \set aid random(1, 100000 * :scale)
        0.005  \set bid random(1, 1 * :scale)
        0.002  \set tid random(1, 10 * :scale)
        0.001  \set delta random(-5000, 5000)
        0.326  BEGIN;
        0.603  UPDATE pgbench_accounts SET abalance = abalance + :delta WHERE aid = :aid;
        0.454  SELECT abalance FROM pgbench_accounts WHERE aid = :aid;
        5.528  UPDATE pgbench_tellers SET tbalance = tbalance + :delta WHERE tid = :tid;
        7.335  UPDATE pgbench_branches SET bbalance = bbalance + :delta WHERE bid = :bid;
        0.371  INSERT INTO pgbench_history (tid, bid, aid, delta, mtime) VALUES (:tid, :bid, :aid, :delta, CURRENT_TIMESTAMP);
        1.212  END;
    

Les moyennes sont rapportées séparément si plusieurs scripts sont spécifiés.

Notez que collecter des informations de chronométrage supplémentaires nécessaires pour calculer la latence par requête rajoute une certaine charge. Cela va réduire la vitesse moyenne calculée pour l'exécution des transactions et réduire le taux calculé des TPS. Le ralentissement varie de manière significative selon la plateforme et le matériel. Comparer la moyenne des valeurs de TPS avec et sans intégration de la latence est une bonne manière de se rendre compte si la surcharge induite par le chronométrage est importante ou pas.

Bonnes pratiques

Il est facile d'utiliser pgbench pour produire des résultats complètement dénués de sens ! Voici quelques conseils pour vous aider à obtenir des résultats pertinents.

Tout d'abord, ne croyez jamais en un test qui ne dure que quelques secondes. Utilisez l'option -t ou -T pour que le test dure au moins quelques minutes, de façon à lisser le bruit. Dans certains cas, il vous faudra des heures pour récupérer des valeurs reproductibles. C'est une bonne idée de lancer plusieurs fois le test pour voir si vos chiffres sont ou pas reproductibles.

Pour le scénario de test par défaut typé TPC-B, le facteur d'échelle d'initialisation (-s) devrait être au moins aussi grand que le nombre maximum de clients que vous avez l'intention de tester (-c) ; sinon vous allez principalement tester la contention induite par les mises à jour. il n'y a que -s lignes dans la table pgbench_branches, et chaque transaction veut mettre à jour l'une de ces lignes, donc si la valeur de -c est supérieure à la valeur de -s, il en résultera sûrement de nombreuses transactions bloquées en attente de la fin d'autres transactions.

Le scénario par défaut est aussi assez sensible au temps écoulé depuis l'initialisation des tables : l'accumulation des lignes et espaces morts dans les tables change les résultats. Pour comprendre ces résultats, vous devez garder une trace du nombre total de mises à jour et du moment du vacuum. Si l'autovacuum est actif, il peut en résulter des variations imprévisibles dans les performances mesurées.

Une limitation de pgbench est qu'il peut lui-même devenir le goulet d'étranglement lorsqu'on essaie de tester avec un grand nombre de sessions clientes. Cela peut être attenué en utilisant pgbench depuis une machine différente du serveur de base de données, bien qu'une faible latence sur le réseau soit dans ce cas essentielle. Il peut même être utile de lancer plusieurs instances parallèles de pgbench, depuis plusieurs machines clientes vers le même serveur de base de données.

Securité

Si des utilisateurs non dignes de confiance ont accès à une base de données qui a adopté une méthode sécurisée d'utilisation des schémas, il ne faut pas exécuter pgbench dans cette base. pgbench utilise des noms non qualifiés et ne modifie le chemin de recherche.