pgbench.xml

<?xml version="1.0" encoding="ISO-8859-15"?>
<!-- Dernière modification
     le       $Date$
     par      $Author$
     révision $Revision$ -->

<sect1 id="pgbench">
 <title>pgbench</title>

 <indexterm zone="pgbench">
  <primary>pgbench</primary>
 </indexterm>

 <para>
  <application>pgbench</application> est un programme simple qui exécute un
  test de performances (<foreignphrase>benchmark</foreignphrase> en
  anglais) sur <productname>PostgreSQL</productname>. Il exécute la même
  séquence de commandes SQL de nombreuses fois, si possible dans plusieurs
  sessions en prarallèle, puis calcule le taux de transaction moyen
  (transactions par seconde). Par défaut, <application>pgbench</application>
  teste un scénario vaguement basé sur TPC-B, impliquant cinq
  <command>SELECT</command>, <command>UPDATE</command> et
  <command>INSERT</command> par transaction. Néanmoins il est facile de tester
  d'autres cas en écrivant ses propres fichiers de transaction.
 </para>

 <para>
  Voici un exemple d'affichage de pgbench&nbsp;:

 <programlisting>
transaction type: TPC-B (sort of)
scaling factor: 10
query mode: simple
number of clients: 10
number of transactions per client: 1000
number of transactions actually processed: 10000/10000
tps = 85.184871 (including connections establishing)
tps = 85.296346 (excluding connections establishing)
 </programlisting>

  Les cinq premières lignes indiquent simplement certains des paramètres
  les plus importants. La ligne suivant rapporte le nombre de transactions
  terminées et souhaitées (le dernier étant juste le produit du nombre
  de clients avec le nombre de transactions par client)&nbsp;; ils doivent être égaux
  sauf si un échec est arrivé avant la fin. Les deux dernières lignes
  précisent le taux de transactions, avec et sans le temps de lancement
  de la session.
 </para>

 <sect2>
  <title>Aperçu</title>

  <para>
   Le test de transaction par défaut, ressemblant à TPC-B, nécessite des tables
   particulières qu'il faut créer. <application>pgbench</application> doit
   être appelé avec l'option <literal>-i</literal> (initialisation) pour les
   créer et les peupler. (Cette étape n'est pas nécessaire dans le cas de script
   personnalisé, mais la base doit être configurée en conséquence.)
   L'initialisation ressemble à&nbsp;:

   <programlisting>
pgbench -i <optional> <replaceable>autres-options</replaceable> </optional> <replaceable>nom_base</replaceable>
   </programlisting>

   où <replaceable>dbname</replaceable> est le nom d'une base de données déjà
   créée et à utiliser pour les tests. (Les
   options <literal>-h</literal>, <literal>-p</literal>, et/ou
   <literal>-U</literal> peuvent être utilisées pour indiquer la façon
   de se connecter au serveur de bases de données.)
  </para>

  <caution>
   <para>
    <literal>pgbench -i</literal> crée quatre tables&nbsp;:
    <structname>pgbench_accounts</structname>, <structname>pgbench_branches</structname>,
    <structname>pgbench_history</structname> et <structname>pgbench_tellers</structname>,
    détruisant toute table existante de ce nom. Il convient d'y être attentif
    s'il existe des tables de même nom&nbsp;!
   </para>
  </caution>

  <para>
   Avec un <quote>facteur d'échelle</quote> de 1, les tables contiennent
   initialement ce nombre de lignes&nbsp;:
  </para>
  <programlisting>
table                   # de lignes
-----------------------------------
pgbench_branches        1
pgbench_tellers         10
pgbench_accounts        100000
pgbench_history         0
  </programlisting>
  <para>
   Le nombre de lignes peut être augmenté en utilisant l'option
   <literal>-s</literal> (facteur d'échelle). L'option
   <literal>-F</literal> (facteur de remplissage) peut aussi être utilisée
   à ce moment.
  </para>

  <para>
   Une fois la configuration exécutée, le
   test de performance peut être lancé avec une commande qui n'inclut pas l'option
   <literal>-i</literal>, c'est-à-dire&nbsp;:

   <programlisting>
pgbench <optional> <replaceable>options</replaceable> </optional> <replaceable>nom_base</replaceable>
   </programlisting>

   Dans la plupart des cas, vous aurez besoin de quelques options pour que
   ce test soit réellement intéressant. Les options les plus importantes
   sont <literal>-c</literal> (nombre de clients), <literal>-t</literal>
   (nombre de transactions), <literal>-T</literal> (limite de temps) et
   <literal>-f</literal> (pour spécifier un script personnalisé). Voir
   ci-dessous pour une liste complète.
  </para>

  <para>
   <xref linkend="pgbench-init-options"/> affiche les options qui sont
   utiles lors de l'initialisation de la base de données, alors que
   <xref linkend="pgbench-run-options"/> affiche celles qui sont utiles
   lors de l'exécution des tests de performance et
   <xref linkend="pgbench-common-options"/> affiches les options utiles dans
   les deux cas.
  </para>

  <table id="pgbench-init-options">
   <title>Options d'initialisation de <application>pgbench</application></title>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>Option</entry>
      <entry>Description</entry>
     </row>
    </thead>

    <tbody>
     <row>
      <entry><literal>-i</literal></entry>
      <entry>
       Requis pour le mode initialisation.
      </entry>
     </row>
     <row>
      <entry><literal>-s</literal> <replaceable>facteur_echelle</replaceable></entry>
      <entry>
       Multiplie le nombre de lignes générées par le facteur d'échelle. Par
       exemple, <literal>-s 100</literal> ajoute 10 millions de lignes dans
       la table <structname>pgbench_accounts</structname>. La valeur par défaut est 1.
      </entry>
     </row>
     <row>
      <entry><literal>-F</literal> <replaceable>fecteur_remplissage</replaceable></entry>
      <entry>
       Crée les tables <structname>pgbench_accounts</structname>,
       <structname>pgbench_tellers</structname> et
       <structname>pgbench_branches</structname> avec le facteur de remplissage
       indiqué. La valeur par défaut est 100.
      </entry>
     </row>
    </tbody>
   </tgroup>
  </table>

  <table id="pgbench-run-options">
   <title>Options pour les tests de <application>pgbench</application></title>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>Option</entry>
      <entry>Description</entry>
     </row>
    </thead>

    <tbody>
     <row>
      <entry><literal>-c</literal> <replaceable>clients</replaceable></entry>
      <entry>
       Nombre de clients simultanés, autrement dit le nombre de sessions en
       parallèle. Par défaut, 1.
      </entry>
     </row>
     <row>
      <entry><literal>-t</literal> <replaceable>transactions</replaceable></entry>
      <entry>
       Nombre de transactions exécutées par chaque client. Par défaut, 10.
      </entry>
     </row>
     <row>
      <entry><literal>-T</literal> <replaceable>secondes</replaceable></entry>
      <entry>
       Exécute le test pendant ce nombre de secondes, plutôt que pour un certain
       nombre de transactions par client. <literal>-t</literal> et
       <literal>-T</literal> sont mutuellement exclusifs.
      </entry>
     </row>
     <row>
      <entry><literal>-M</literal> <replaceable>querymode</replaceable></entry>
      <entry>
       Protocole à utiliser pour soumettre des requêtes au serveur&nbsp;:
         <itemizedlist>
          <listitem>
           <para><literal>simple</literal>&nbsp;: utilise le protocole de
	     requêtes simple.</para>
          </listitem>
          <listitem>
           <para><literal>extended</literal>&nbsp;: utilise le protocole de
	     requêtes étendu.</para>
          </listitem>
          <listitem>
           <para><literal>prepared</literal>&nbsp;: utilise le protocole de
	     requêtes étendu avec des requêtes préparées.</para>
          </listitem>
         </itemizedlist>
       Par défaut, le protocole simple est utilisé. Voir <xref linkend="protocol"/>
       pour plus d'informations.
      </entry>
     </row>
     <row>
      <entry><literal>-N</literal></entry>
      <entry>
       Ne met pas à jour les tables <structname>pgbench_tellers</structname> et
       <structname>pgbench_branches</structname>. Ceci évitera les contentions des
       mises à jour sur ces tables mais du coup pgbench ne supporte pas les
       transactions du style TPC-B.
      </entry>
     </row>
     <row>
      <entry><literal>-S</literal></entry>
      <entry>
       Réalise uniquement des transactions de sélection au lieu du TPC-B.
      </entry>
     </row>
     <row>
      <entry><literal>-f</literal> <replaceable>nom_fichier</replaceable></entry>
      <entry>
       Lit le script de transaction à partir de
       <replaceable>nom_fichier</replaceable>. Des explications
       détaillées apparaîtront plus tard.
       <literal>-N</literal>, <literal>-S</literal> et <literal>-f</literal>
       ne sont pas utilisables ensemble.
      </entry>
     </row>
     <row>
      <entry><literal>-n</literal></entry>
      <entry>
       Aucun VACUUM n'est réalisé pendant l'exécution du test. Cette option
       est <emphasis>nécessaire</emphasis> si vous exécutez un scénario de tests
       personnalisé qui n'inclut pas les tables standards
       <structname>pgbench_accounts</structname>, <structname>pgbench_branches</structname>,
       <structname>pgbench_history</structname> et <structname>pgbench_tellers</structname>.
      </entry>
     </row>
     <row>
      <entry><literal>-v</literal></entry>
      <entry>
       Exécute un VACUUM sur les quatres tables avant le test. Sans
       <literal>-n</literal> et <literal>-v</literal>, pgbench exécute un
       VACUUM sur les seules tables <structname>pgbench_tellers</structname> et
       <structname>pgbench_branches</structname>, et supprimera toutes les entrées de
       <structname>history</structname>.
      </entry>
     </row>
     <row>
      <entry><literal>-D</literal> <replaceable>varname</replaceable><literal>=</literal><replaceable>value</replaceable></entry>
      <entry>
       Définit une variable utilisée par un script personnalisé (voir plus
       bas). Vous pouvez utiliser plusieurs fois l'option <literal>-D</literal>.
      </entry>
     </row>
     <row>
      <entry><literal>-C</literal></entry>
      <entry>
       Établie une connexion pour chaque transaction, plutôt que de se
       connecter une fois par client du thread. Ceci est utile pour mesurer la
       charge occasionnée par la connexion.
      </entry>
     </row>
     <row>
      <entry><literal>-l</literal></entry>
      <entry>
       Écrit le temps pris par chaque transaction dans un journal applicatif.
       Voir ci-dessous pour les détails.
      </entry>
     </row>
     <row>
      <entry><literal>-s</literal> <replaceable>facteur_echelle</replaceable></entry>
      <entry>
       Indique le facteur d'échelle spécifié en sortie de
       <application>pgbench</application>. Avec les tests internes, ce n'est
       pas nécessaire&nbsp;; le bon facteur d'échelle sera détecté en comptant
       le nombre de lignes dans la table <structname>pgbench_branches</structname>.
       Néanmoins, lors de tests de performance personnalisés
       (option <literal>-f</literal>), le facteur d'échelle sera rapporté
       valant 1 sauf si cette option est utilisée.
      </entry>
     </row>
     <row>
      <entry><literal>-d</literal></entry>
      <entry>
       Affiche des informations de débogage.
      </entry>
     </row>
    </tbody>
   </tgroup>
  </table>

  <table id="pgbench-common-options">
   <title>Options communes de <application>pgbench</application></title>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>Option</entry>
      <entry>Description</entry>
     </row>
    </thead>

    <tbody>
     <row>
      <entry><literal>-h</literal> <replaceable>hostname</replaceable></entry>
      <entry>Hôte du serveur de bases de données</entry>
     </row>
     <row>
      <entry><literal>-p</literal> <replaceable>port</replaceable></entry>
      <entry>Numéro de port</entry>
     </row>
     <row>
      <entry><literal>-U</literal> <replaceable>login</replaceable></entry>
      <entry>Nom utilisateur pour la connexion</entry>
     </row>
    </tbody>
   </tgroup>
  </table>
 </sect2>

 <sect2>
  <title>Quelle <quote>transaction</quote> est réalisée dans
  pgbench&nbsp;?</title>

  <para>
   Le script de transaction par défaut exécute sept commandes&nbsp;:
  </para>

  <orderedlist>
   <listitem><para><literal>BEGIN;</literal></para></listitem>
   <listitem><para><literal>UPDATE pgbench_accounts SET abalance = abalance + :delta WHERE aid = :aid;</literal></para></listitem>
   <listitem><para><literal>SELECT abalance FROM pgbench_accounts WHERE aid = :aid;</literal></para></listitem>
   <listitem><para><literal>UPDATE pgbench_tellers SET tbalance = tbalance + :delta WHERE tid = :tid;</literal></para></listitem>
   <listitem><para><literal>UPDATE pgbench_branches SET bbalance = bbalance + :delta WHERE bid = :bid;</literal></para></listitem>
   <listitem><para><literal>INSERT INTO pgbench_history (tid, bid, aid, delta, mtime) VALUES (:tid, :bid, :aid, :delta, CURRENT_TIMESTAMP);</literal></para></listitem>
   <listitem><para><literal>END;</literal></para></listitem>
  </orderedlist>

  <para>
   Si vous indiquez <literal>-N</literal>, les étapes 4 et 5 ne sont pas inclus
   dans la transaction. Si vous indiquez <literal>-S</literal>, seul le
   <command>SELECT</command> est exécuté.
  </para>
 </sect2>

 <sect2>
  <title>Scripts personnalisés</title>

  <para>
   <application>pgbench</application> sait exécuter des scénarios personnalisés
   en remplaçant le script de transaction par défaut (décrit ci-dessus) avec
   un script de transaction lu à partir d'un fichier (option
   <literal>-f</literal>). Dans ce cas, une <quote>transaction</quote> compte
   en tant qu'une exécution du fichier. Vous pouvez même indiquer plusieurs
   scripts (avec plusieurs options <literal>-f</literal>), auquel cas un
   script est choisi au hasard à chaque fois qu'une session client exécute
   une nouvelle transaction.
  </para>

  <para>
   Le fichier doit contenir une commande par ligne&nbsp;; les commandes SQL
   multi-lignes ne sont pas acceptées. Les lignes vides et les lignes
   commençant par <literal>--</literal> sont ignorées. Les lignes du fichier
   peuvent aussi contenir des <quote>meta commandes</quote>, qui sont
   interprétées par <application>pgbench</application> lui-même, comme
   décrit ci-dessous.
  </para>

  <para>
   Il existe une fonctionnalité de substitution de variables pour les fichiers.
   Les variables sont configurables par l'option <literal>-D</literal> en
   ligne de commande, comme expliqué ci-dessus, ou par les méta-commandes
   expliquées ci-dessous. En plus des variables pré-initialisées par les
   options <literal>-D</literal>, la variable <literal>scale</literal> est
   pré-initialisée avec le facteur d'échelle actuel. Une fois configurée,
   la valeur d'une variable peut être insérée dans une commande SQL en
   écrivant <literal>:</literal><replaceable>nom_variable</replaceable>.
   Lors de l'exécution de plusieurs sessions clients, chaque session a son
   propre ensemble de variables.
  </para>

  <para>
   Les méta-commandes du script commencent par un antislash
   (<literal>\</literal>). Les arguments d'une méta-commande sont séparés par
   des espaces blancs. Voici la liste des méta-commandes acceptées&nbsp;:
  </para>

  <variablelist>
   <varlistentry>
    <term>
     <literal>\set <replaceable>nom_variable</replaceable> <replaceable>operande1</replaceable> [ <replaceable>operateur</replaceable> <replaceable>operande2</replaceable> ]</literal>
    </term>

    <listitem>
     <para>
      Initialise la variable <replaceable>varname</replaceable> avec une
      valeur entière calculée.
      Chaque <replaceable>operande</replaceable> est soit une constante
      entière soit une référence
      <literal>:</literal><replaceable>nom_variable</replaceable> à une variable
      entière. L'<replaceable>operateur</replaceable> peut être
      <literal>+</literal>, <literal>-</literal>, <literal>*</literal> ou <literal>/</literal>.
     </para>

     <para>
      Exemple&nbsp;:
      <programlisting>
\set ntellers 10 * :scale
      </programlisting>
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>
     <literal>\setrandom <replaceable>nom_variable</replaceable> <replaceable>min</replaceable> <replaceable>max</replaceable></literal>
    </term>

    <listitem>
     <para>
      Initialise la variable <replaceable>nom_variable</replaceable> à une
      valeur entière prise au hasard entre les limites
      <replaceable>min</replaceable> et <replaceable>max</replaceable>,
      limites inclues.
      Chaque limite peut être soit une constante entière soit une référence
      <literal>:</literal><replaceable>nom_variable</replaceable> à une valeur
      entière.
     </para>

     <para>
      Exemple&nbsp;:
      <programlisting>
\setrandom aid 1 :naccounts
      </programlisting>
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>
     <literal>\sleep <replaceable>nombre</replaceable> [ us | ms | s ]</literal>
    </term>

    <listitem>
     <para>
      Provoque un endormissement de l'exécution du script pour la durée
      indiquée en microsecondes (<literal>us</literal>), millisecondes
      (<literal>ms</literal>) ou secondes (<literal>s</literal>). Si l'unité
      est omise, alors ce seront par défaut des secondes.
      <replaceable>nombre</replaceable> peut être soit un entier soit une
      référence <literal>:</literal><replaceable>nom_variable</replaceable> à
      un entier.
     </para>

     <para>
      Exemple&nbsp;:
      <programlisting>
\sleep 10 ms
      </programlisting>
     </para>
    </listitem>
   </varlistentry>
  </variablelist>

  <para>
   En exemple, voici la définition complète d'une transaction style
   TPC-B&nbsp;:

   <programlisting>
\set nbranches :scale
\set ntellers 10 * :scale
\set naccounts 100000 * :scale
\setrandom aid 1 :naccounts
\setrandom bid 1 :nbranches
\setrandom tid 1 :ntellers
\setrandom delta -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;
   </programlisting>

   Ce script permet à chaque itération de la transaction de référencer des
   lignes différentes, prises au hasard. (Cet exemple montre aussi pourquoi
   il est imporant que chaque session client ait ses propres variables &mdash;
   sinon elles ne traiteraient pas des lignes différentes.)
  </para>

 </sect2>

 <sect2>
  <title>Journalisation par transaction</title>

  <para>
   Avec l'option <literal>-l</literal>, <application>pgbench</application>
   écrit le temps pris par chaque transaction dans un journal applicatif.
   Le journal sera nommé
   <filename>pgbench_log.<replaceable>nnn</replaceable></filename>, où
   <replaceable>nnn</replaceable> est le PID du processus pgbench. Le format
   de ce journal est&nbsp;:

   <programlisting>
    <replaceable>client_id</replaceable> <replaceable>transaction_no</replaceable> <replaceable>time</replaceable> <replaceable>file_no</replaceable> <replaceable>time_epoch</replaceable> <replaceable>time_us</replaceable>
   </programlisting>

   où <replaceable>time</replaceable> est le durée de la transaction en
   microsecondes, <replaceable>file_no</replaceable> identifie le script qui
   a été utilisé (utile quand plusieurs scripts sont indiqués avec
   <literal>-f</literal>) et
   <replaceable>time_epoch</replaceable>/<replaceable>time_us</replaceable> sont
   une date/heure au format epoch Unix et un décalage en microsecondes
   (convenable pour la création d'un horodatage ISO 8601 avec des secondes
   en fration) indiquant la date et heure de la fin de la transaction.
  </para>

  <para>
   Voici un exemple de journal&nbsp;:
   <programlisting>
 0 199 2241 0 1175850568 995598
 0 200 2465 0 1175850568 998079
 0 201 2513 0 1175850569 608
 0 202 2038 0 1175850569 2663
   </programlisting>
  </para>
 </sect2>

 <sect2>
  <title>Bonnes practiques</title>

  <para>
   Il est très facile d'utiliser <application>pgbench</application> pour
   produire des nombres sans signification. Voici quelques lignes de conduite
   pour vous aider à obtenir des résultats intéressants.
  </para>

  <para>
   En premier lieu, ne <emphasis>jamais</emphasis> croire tout test qui ne
   s'exécute que pendant quelques secondes. Utilisez l'option
   <literal>-t</literal> ou <literal>-T</literal>
   pour que le test dure plusieurs minutes pour rendre
   le bruit insignifiant. Dans certains cas, nous avez besoin de quelques
   heures pour obtenir des chiffres reproductibles. Exécuter le test plusieurs
   fois est une bonne idée pour savoir si vos résultats sont reproductibles.
  </para>

  <para>
   Pour le scénario par défaut, style TPC-B, le facteur d'échelle à
   l'initialisation (<literal>-s</literal>) doit être au moins aussi important
   que le plus grand nombre de clients que vous souhaitez supporter
   (<literal>-c</literal>)&nbsp;; sinon vous ne ferez que mesurer la contention
   des mises à jour. Il n'y a que <literal>-s</literal> lignes dans la table
   <structname>pgbench_branches</structname>, et chaque transaction veut en mettre une
   à jour, donc les valeurs <literal>-c</literal> supérieures à 
   <literal>-s</literal> résulteront sans doute en beaucoup de transactions
   bloquées, en attente d'autres transactions.
  </para>

  <para>
   Le scénario test par défaut est aussi assez sensible du moment où les
   tables ont été initialisées&nbsp;: une accumulation de lignes morts et
   d'espace vide dans les tables modifient les résultats. Pour comprendre
   les résultats, vous devez garder trace de nombre total de mises à jour
   et des moments où un VACUUM est exécuté. Si l'autovacuum est activé,
   cela peut causer des modifications non prévisibles dans les performances
   mesurées.
  </para>

  <para>
   Une limite de <application>pgbench</application> est qu'il peut devenir
   lui-même le goulot d'étranglement lors de tentative de tests d'un grand
   nombre de sessions clients. Ceci peut se voir allégé en exécutant
   <application>pgbench</application> sur une autre machine que le serveur
   de bases de données, bien que la latence du réseau est essentielle. Il
   pourrait même être utile d'exécuter plusieurs instances
   <application>pgbench</application> en parallèle sur plusieurs machines
   client, pour le même serveur de bases de données.
  </para>
 </sect2>

</sect1>