Guide d'Apache BookKeeper

1. Vue d'ensemble

Dans cet article, nous présenterons BookKeeper, un service qui implémente un système de stockage d'enregistrements distribué et tolérant aux pannes .

2. Qu'est-ce que BookKeeper ?

BookKeeper a été initialement développé par Yahoo en tant que sous-projet ZooKeeper et a été diplômé pour devenir un projet de haut niveau en 2015. À la base, BookKeeper vise à être un système fiable et haute performance qui stocke des séquences d' entrées de journal (aka Records ) dans des structures de données appelé Ledgers .

Une caractéristique importante des registres est le fait qu'ils sont uniquement ajoutés et immuables . Cela fait de BookKeeper un bon candidat pour certaines applications, telles que les systèmes de journalisation distribués, les applications de messagerie Pub-Sub et le traitement de flux en temps réel.

3. Concepts de BookKeeper

3.1. Entrées de journal

Une entrée de journal contient une unité indivisible de données qu'une application client stocke ou lit à partir de BookKeeper. Lorsqu'elle est stockée dans un grand livre, chaque entrée contient les données fournies et quelques champs de métadonnées.

Ces champs de métadonnées incluent un entryId, qui doit être unique dans un grand livre donné. Il existe également un code d'authentification que BookKeeper utilise pour détecter lorsqu'une entrée est corrompue ou a été falsifiée.

BookKeeper n'offre aucune fonctionnalité de sérialisation en soi, donc les clients doivent concevoir leur propre méthode pour convertir des constructions de niveau supérieur vers / à partir de tableaux d' octets .

3.2. Grands livres

Un grand livre est l'unité de stockage de base gérée par BookKeeper, qui stocke une séquence ordonnée d'entrées de journal. Comme mentionné précédemment, les registres ont une sémantique d'ajout uniquement, ce qui signifie que les enregistrements ne peuvent pas être modifiés une fois ajoutés.

De plus, une fois qu'un client arrête d'écrire dans un grand livre et le ferme, BookKeeper le scelle et nous ne pouvons plus y ajouter de données, même plus tard . C'est un point important à garder à l'esprit lors de la conception d'une application autour de BookKeeper. Les grands livres ne sont pas un bon candidat pour implémenter directement des constructions de niveau supérieur , comme une file d'attente. Au lieu de cela, nous voyons des registres utilisés plus souvent pour créer des structures de données plus basiques qui prennent en charge ces concepts de niveau supérieur.

Par exemple, le projet Distributed Log d'Apache utilise des registres comme segments de journal. Ces segments sont agrégés dans des journaux distribués, mais les registres sous-jacents sont transparents pour les utilisateurs réguliers.

BookKeeper atteint la résilience du grand livre en répliquant les entrées de journal sur plusieurs instances de serveur. Trois paramètres contrôlent le nombre de serveurs et de copies conservés:

  • Taille de l'ensemble: le nombre de serveurs utilisés pour écrire les données du grand livre
  • Taille du quorum d'écriture: le nombre de serveurs utilisés pour répliquer une entrée de journal donnée
  • Ack quorum size: le nombre de serveurs qui doivent accuser réception d'une opération d'écriture d'entrée de journal donnée

En ajustant ces paramètres, nous pouvons ajuster les caractéristiques de performance et de résilience d'un grand livre donné. Lors de l'écriture dans un registre, BookKeeper ne considérera l'opération comme réussie que lorsqu'un quorum minimum de membres du cluster la reconnaît.

En plus de ses métadonnées internes, BookKeeper prend également en charge l'ajout de métadonnées personnalisées à un registre. Il s'agit d'une carte des paires clé / valeur que les clients transmettent au moment de la création et que BookKeeper stocke dans ZooKeeper à côté du sien.

3.3. Bookmakers

Les bookmakers sont des serveurs qui détiennent un ou des registres de mode. Un cluster BookKeeper se compose d'un certain nombre de bookmakers s'exécutant dans un environnement donné, fournissant des services aux clients via des connexions TCP ou TLS simples.

Les bookmakers coordonnent les actions à l'aide des services de cluster fournis par ZooKeeper. Cela implique que, si nous voulons obtenir un système totalement tolérant aux pannes, nous avons besoin d'au moins un ZooKeeper à 3 instances et une configuration BookKeeper à 3 instances. Une telle configuration serait capable de tolérer une perte si une seule instance échouait et serait toujours capable de fonctionner normalement, au moins pour la configuration du grand livre par défaut: taille d'ensemble à 3 nœuds, quorum d'écriture à 2 nœuds et quorum d'acquittement à 2 nœuds.

4. Configuration locale

Les exigences de base pour exécuter BookKeeper localement sont assez modestes. Tout d'abord, nous avons besoin d'une instance ZooKeeper opérationnelle, qui fournit un stockage de métadonnées de grand livre pour BookKeeper. Ensuite, nous déployons un bookmaker, qui fournit les services réels aux clients.

Bien qu'il soit certainement possible de faire ces étapes manuellement, nous utiliserons ici un fichier docker-compose qui utilise des images Apache officielles pour simplifier cette tâche:

$ cd  $ docker-compose up

Ce docker-compose crée trois bookies et une instance ZooKeeper. Puisque tous les bookmakers fonctionnent sur la même machine, cela n'est utile qu'à des fins de test. La documentation officielle contient les étapes nécessaires pour configurer un cluster entièrement tolérant aux pannes.

Faisons un test de base pour vérifier qu'il fonctionne comme prévu, à l'aide de la commande shell listbookies de bookkeeper :

$ docker exec -it apache-bookkeeper_bookie_1 /opt/bookkeeper/bin/bookkeeper \ shell listbookies -readwrite ReadWrite Bookies : 192.168.99.101(192.168.99.101):4181 192.168.99.101(192.168.99.101):4182 192.168.99.101(192.168.99.101):3181 

La sortie affiche la liste des bookmakers disponibles , composée de trois bookmakers. Veuillez noter que les adresses IP affichées changeront en fonction des spécificités de l'installation locale de Docker.

5. Utilisation de l'API Ledger

L'API Ledger est le moyen le plus simple de s'interfacer avec BookKeeper . Il nous permet d'interagir directement avec les objets Ledger mais, d'un autre côté, ne prend pas directement en charge les abstractions de niveau supérieur telles que les flux. Pour ces cas d'utilisation, le projet BookKeeper propose une autre bibliothèque, DistributedLog, qui prend en charge ces fonctionnalités.

L'utilisation de l'API Ledger nécessite l'ajout de la dépendance comptable-serveur à notre projet:

 org.apache.bookkeeper bookkeeper-server 4.10.0 

REMARQUE: Comme indiqué dans la documentation, l'utilisation de cette dépendance inclura également des dépendances pour les bibliothèques protobuf et guava. Si notre projet a également besoin de ces bibliothèques, mais dans une version différente de celles utilisées par BookKeeper, nous pourrions utiliser une dépendance alternative qui ombrage ces bibliothèques:

 org.apache.bookkeeper bookkeeper-server-shaded 4.10.0  

5.1. Connexion aux bookmakers

The BookKeeper class is the main entry point of the Ledger API, providing a few methods to connect to our BookKeeper service. In its simplest form, all we need to do is create a new instance of this class, passing the address of one of the ZooKeeper servers used by BookKeeper:

BookKeeper client = new BookKeeper("zookeeper-host:2131"); 

Here, zookeeper-host should be set to the IP address or hostname of the ZooKeeper server that holds BookKeeper's cluster configuration. In our case, that's usually “localhost” or the host that the DOCKER_HOST environment variable points to.

If we need more control over the several parameters available to fine-tune our client, we can use a ClientConfiguration instance and use it to create our client:

ClientConfiguration cfg = new ClientConfiguration(); cfg.setMetadataServiceUri("zk+null://zookeeper-host:2131"); // ... set other properties BookKeeper.forConfig(cfg).build();

5.2. Creating a Ledger

Once we have a BookKeeper instance, creating a new ledger is straightforward:

LedgerHandle lh = bk.createLedger(BookKeeper.DigestType.MAC,"password".getBytes());

Here, we've used the simplest variant of this method. It will create a new ledger with default settings, using the MAC digest type to ensure entry integrity.

If we want to add custom metadata to our ledger, we need to use a variant that takes all parameters:

LedgerHandle lh = bk.createLedger( 3, 2, 2, DigestType.MAC, "password".getBytes(), Collections.singletonMap("name", "my-ledger".getBytes()));

This time, we've used the full version of the createLedger() method. The three first arguments are the ensemble size, write quorum, and ack quorum values, respectively. Next, we have the same digest parameters as before. Finally, we pass a Map with our custom metadata.

In both cases above, createLedger is a synchronous operation. BookKeeper also offers asynchronous ledger creation using a callback:

bk.asyncCreateLedger( 3, 2, 2, BookKeeper.DigestType.MAC, "passwd".getBytes(), (rc, lh, ctx) -> { // ... use lh to access ledger operations }, null, Collections.emptyMap()); 

Newer versions of BookKeeper (>= 4.6) also support a fluent-style API and CompletableFuture to achieve the same goal:

CompletableFuture cf = bk.newCreateLedgerOp() .withDigestType(org.apache.bookkeeper.client.api.DigestType.MAC) .withPassword("password".getBytes()) .execute(); 

Note that, in this case, we get a WriteHandle instead of a LedgerHandle. As we'll see later, we can use any of them to access our ledger as LedgerHandle implements WriteHandle.

5.3. Writing Data

Once we've acquired a LedgerHandle or WriteHandle, we write data to the associated ledger using one of the append() method variants. Let's start with the synchronous variant:

for(int i = 0; i < MAX_MESSAGES; i++) { byte[] data = new String("message-" + i).getBytes(); lh.append(data); } 

Here, we're using a variant that takes a byte array. The API also supports Netty's ByteBuf and Java NIO's ByteBuffer, which allow better memory management in time-critical scenarios.

For asynchronous operations, the API differs a bit depending on the specific handle type we've acquired. WriteHandle uses CompletableFuture, whereas LedgerHandle also supports callback-based methods:

// Available in WriteHandle and LedgerHandle CompletableFuture f = lh.appendAsync(data); // Available only in LedgerHandle lh.asyncAddEntry( data, (rc,ledgerHandle,entryId,ctx) -> { // ... callback logic omitted }, null);

Which one to choose is largely a personal choice, but in general, using CompletableFuture-based APIs tends to be easier to read. Also, there's the side benefit that we can construct a Mono directly from it, making it easier to integrate BookKeeper in reactive applications.

5.4. Reading Data

Reading data from a BookKeeper ledger works in a similar way to writing. First, we use our BookKeeper instance to create a LedgerHandle:

LedgerHandle lh = bk.openLedger( ledgerId, BookKeeper.DigestType.MAC, ledgerPassword); 

Except for the ledgerId parameter, which we'll cover later, this code looks much like the createLedger() method we've seen before. There's an important difference, though; this method returns a read-only LedgerHandle instance. If we try to use any of the available append() methods, all we'll get is an exception.

Alternatively, a safer way is to use the fluent-style API:

ReadHandle rh = bk.newOpenLedgerOp() .withLedgerId(ledgerId) .withDigestType(DigestType.MAC) .withPassword("password".getBytes()) .execute() .get(); 

ReadHandle has the required methods to read data from our ledger:

long lastId = lh.readLastConfirmed(); rh.read(0, lastId).forEach((entry) -> { // ... do something });

Here, we've simply requested all available data in this ledger using the synchronous read variant. As expected, there's also an async variant:

rh.readAsync(0, lastId).thenAccept((entries) -> { entries.forEach((entry) -> { // ... process entry }); });

If we choose to use the older openLedger() method, we'll find additional methods that support the callback style for async methods:

lh.asyncReadEntries( 0, lastId, (rc,lh,entries,ctx) -> { while(entries.hasMoreElements()) { LedgerEntry e = ee.nextElement(); } }, null);

5.5. Listing Ledgers

We've seen previously that we need the ledger's id to open and read its data. So, how do we get one? One way is using the LedgerManager interface, which we can access from our BookKeeper instance. This interface basically deals with ledger metadata, but also has the asyncProcessLedgers() method. Using this method – and some help form concurrent primitives – we can enumerate all available ledgers:

public List listAllLedgers(BookKeeper bk) { List ledgers = Collections.synchronizedList(new ArrayList()); CountDownLatch processDone = new CountDownLatch(1); bk.getLedgerManager() .asyncProcessLedgers( (ledgerId, cb) -> { ledgers.add(ledgerId); cb.processResult(BKException.Code.OK, null, null); }, (rc, s, obj) -> { processDone.countDown(); }, null, BKException.Code.OK, BKException.Code.ReadException); try { processDone.await(1, TimeUnit.MINUTES); return ledgers; } catch (InterruptedException ie) { throw new RuntimeException(ie); } } 

Let's digest this code, which is a bit longer than expected for a seemingly trivial task. The asyncProcessLedgers() method requires two callbacks.

The first one collects all ledgers ids in a list. We're using a synchronized list here because this callback can be called from multiple threads. Besides the ledger id, this callback also receives a callback parameter. We must call its processResult() method to acknowledge that we've processed the data and to signal that we're ready to get more data.

Le deuxième rappel est appelé lorsque tous les registres ont été envoyés au rappel du processeur ou en cas d'échec. Dans notre cas, nous avons omis la gestion des erreurs. Au lieu de cela, nous décrémentons simplement un CountDownLatch , qui, à son tour, terminera l' opération d' attente et permettra à la méthode de revenir avec une liste de tous les registres disponibles.

6. Conclusion

Dans cet article, nous avons couvert le projet Apache BookKeeper, en examinant ses concepts de base et en utilisant son API de bas niveau pour accéder à Ledgers et effectuer des opérations de lecture / écriture.

Comme d'habitude, tout le code est disponible sur sur GitHub.