Options d'initialisation

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

Options Benchmark

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

Options habituelles

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 de transaction 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. De ce fait, le test ressemblera moins à TPC-B.

Si vous sélectionnez le script interne select-only (ou -S), alors seule l'instruction only the SELECT est exécutée.

Scripts personnalisés

pgbench est capable d'utiliser des scénarios de test de performances personnalisés qui remplacent le script de transactions par défaut (décrit ci-dessus) par un script de transactions lu depuis le fichier spécifié avec l'option (-f). Dans ce cas, une « transaction » est comptabilisée comme une exécution d'un 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 décrit dans la partie suivante.

Note

Avant PostgreSQL™ 9.6, les commandes SQL compris dans les fichiers scripts étaient terminées par un retour à la ligne. Elles ne pouvaient donc pas être écrites sur plusieurs lignes. Maintenant, un point-virgule est requis pour séparer des commandes SQL consécutives (bien qu'une commande SQL n'en a pas besoin si elle est suivie par une méta-comande). Si vous avez besoin de créer un fichier script qui fonctionne avec les anciennes et nouvelles versions de pgbench, assurez-vous d'écrire chaque commande SQL sur une seule ligne et en terminant avec un point-virgule.

Il est possible simplement de substituer les variables dans les fichiers scripts. Les variables peuvent être instanciées via la ligne de commande avec l'option -D 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, il y a quelques variables qui sont automatiquement prédéfinies, listées sous Tableau 239, « Variables automatiques ». Si une valeur pour l'une de ces variables a été définie via la ligne de commande avec l'option -D, elle sera prise en compte en priorité par rapport à 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. Les arguments d'une méta-commande sont séparés par des espaces vides. Les méta- commmandes suivantes sont supportées :

Fonctions internes

Les fonctions listées dans Tableau 240, « Fonctions pgbench » sont construites dans 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.

Connexion par transaction

Avec l'option -l mais sans l'option --aggregate-interval, pgbench va écrire le temps utilisé par chaque transaction dans un fichier journal. Ce fichier journal s'appellera pgbench_log.nnn où nnn est le PID du processus pgbench. 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 pgbench_log.nnn.mmm, où mmm est un numéro de séquence, identifiant chaque worker supplémentaire, en commençant à 1.

Le format du journal est le suivant :

id_client no_transaction temps no_script time_epoch time_us [schedule_lag]
    

Où temps est la durée totale de la transaction en micro secondes, no_script identifie quel fichier script est utilisé (très utile lorsqu'on utilise plusieurs scripts avec l'option -f ou -b), et time_epoch/time_us et un horodatage unix avec un décalage en micro secondes (utilisable pour créer un horodatage ISO 8601 avec des secondes fractionnées) qui montre à 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 la date de début effective de la transaction, 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 temp, le champ time pour une transaction ignorée sera rapportée en tant que skipped. Le dernier champ skipped_transactions rapporte le nombre de transactions ignorées car elles avaient trop de retard par rapport à la planification. Il est uniquement présent lorsque les deux options --rate et --latency-limit sont utilisées.

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

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

Un autre exemple avec les options --rate=100 et --latency-limit=5 (vous noterez 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 est 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à du retard avant même le début de la transaction.

Dans le cas où on lance un test long, sur du matériel qui peut supporter un grand nombre de transactions, le fichier journal 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 horodatage unix), nombre_de_transations est le nombre de transactions dans l'intervalle, somme_latence est le cumul des latences (ce qui vous permet de déduire facilement la latence moyenne). Les deux champs suivants sont très utiles pour calculer la variance. En effet, somme_latence est la somme des latences, alors que somme_latence_2 est la somme des latences au carré. Les deux derniers champs sont latence_min, la latence minimum dans l'intervalle, et latence_max, la latence maximum dans l'intervalle. Une transaction est comptée dans un intervalle à partir du moment où elle a été validée. 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. Le tout dernier champ, transactions_ignorées, est présent uniquement si l'option --latency-limit a aussi été utilisée. Ils sont calculés sur le delta entre le moment où la transaction a pu commencer par rapport au moment la dernière s'est terminée, précisément la différence pour chaque transaction entre le moment où il était prévu qu'elle commence et le moment où elle a effectivement pu commencer.

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, tant que le fichier journal est brut (c'est-à-dire non agrégé), il contient une référence des fichiers scripts personnalisés que le fichier journal agrégé ne contient pas. De ce fait, si vous avez besoin des données de vos scripts, 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 que le test de performance est terminé, il rapporte une moyenne de ces valeurs, référencée comme la 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 seront rapportées séparément si plusieurs scripts ont été spécifiés.

Notez que la collecte supplémentaire des informations de chronométrage nécessaires pour la récupération de la latence par transaction induit une certaine surcharge. En effet, 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 qui est utilisé pour le test. Comparer la moyenne des valeurs de TPS avec et sans l'intégration de la latence dans le test est une bonne manière de se rendre compte si la surcharge induite par le chronométrage est importante ou pas.

Bonnes pratiques

Il facile de se retrouver à utiliser pgbench et ne produire finalement que des résultats complètement insignifiants ! Voici quelques conseils pour vous aider à récupérer des résultats pertinents.

Tout d'abord, ne pensez jamais qu'un test ne peut durer que quelques secondes. Utilisez l'option -t ou -T pour vous assurer 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. Une bonne idée, lancez plusieurs fois votre test, de manière à vous rendre compte si les chiffres que vous obtenez sont ou pas reproductibles.

Pour le scénario de test par défaut typé TPC-B, l'initialisation du facteur d'échelle (-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, indubitablement, il en résultera de nombreuses transactions bloquées en attente de la fin d'autres transactions.

Le moment où les tables ont été créées va sensiblement influencer le résultat du scénario de test par défaut, compte tenu de l'accumulation des lignes et espaces morts dans les tables lors du test. Pour comprendre les résultats, vous devriez garder une trace du nombre total de mises à jour ainsi que le moment où l'opération de VACUUM a lieu. Si la tâche autovacuum est active, 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'il essaye de tester un grand nombre de sessions clientes. Cela peut être attenué en utilisant pgbench depuis une machine différente de la machine où se trouve la 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 fois pgbench de manière concurrente, 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 peut pas manipuler le chemin de recherche.