Guida ad Apache BookKeeper

1. Panoramica

In questo articolo presenteremo BookKeeper, un servizio che implementa un sistema di archiviazione dei record distribuito e tollerante agli errori .

2. Che cos'è BookKeeper ?

BookKeeper è stato originariamente sviluppato da Yahoo come sottoprogetto ZooKeeper e si è laureato fino a diventare un progetto di primo livello nel 2015. Fondamentalmente, BookKeeper mira ad essere un sistema affidabile e ad alte prestazioni che memorizza sequenze di voci di registro (note anche come record ) in strutture di dati chiamato Ledgers .

Una caratteristica importante dei registri è il fatto che sono di sola aggiunta e immutabili . Ciò rende BookKeeper un buon candidato per determinate applicazioni, come i sistemi di registrazione distribuiti, le applicazioni di messaggistica Pub-Sub e l'elaborazione del flusso in tempo reale.

3. Concetti di BookKeeper

3.1. Voci di registro

Una voce di registro contiene un'unità indivisibile di dati che un'applicazione client memorizza o legge da BookKeeper. Quando viene memorizzato in un libro mastro, ogni voce contiene i dati forniti e alcuni campi di metadati.

Questi campi di metadati includono un entryId, che deve essere univoco all'interno di un dato libro mastro. C'è anche un codice di autenticazione che BookKeeper utilizza per rilevare quando una voce è danneggiata o è stata manomessa.

BookKeeper non offre funzionalità di serializzazione da solo, quindi i clienti devono ideare un proprio metodo per convertire i costrutti di livello superiore in / da array di byte .

3.2. Libri mastri

Un libro mastro è l'unità di archiviazione di base gestita da BookKeeper, che memorizza una sequenza ordinata di voci di registro. Come accennato in precedenza, i registri hanno semantica di sola aggiunta, il che significa che i record non possono essere modificati una volta aggiunti a essi.

Inoltre, una volta che un cliente smette di scrivere su un libro mastro e lo chiude, BookKeeper lo sigilla e non possiamo più aggiungervi dati, anche in un secondo momento . Questo è un punto importante da tenere a mente quando si progetta un'applicazione attorno a BookKeeper. I registri non sono un buon candidato per implementare direttamente costrutti di livello superiore , come una coda. Invece, vediamo i libri mastri utilizzati più spesso per creare strutture dati più basilari che supportano quei concetti di livello superiore.

Ad esempio, il progetto Log distribuito di Apache utilizza i registri come segmenti di registro. Questi segmenti vengono aggregati in registri distribuiti, ma i registri sottostanti sono trasparenti per gli utenti regolari.

BookKeeper raggiunge la resilienza del registro replicando le voci di registro su più istanze del server. Tre parametri controllano quanti server e copie vengono conservati:

  • Dimensione dell'insieme: il numero di server utilizzati per scrivere i dati contabili
  • Dimensione quorum di scrittura: il numero di server utilizzati per replicare una determinata voce di registro
  • Ack quorum size: il numero di server che devono riconoscere una determinata operazione di scrittura della voce di log

Modificando questi parametri, possiamo ottimizzare le caratteristiche di prestazioni e resilienza di un dato libro mastro. Quando si scrive in un libro mastro, BookKeeper considererà l'operazione come riuscita solo se un quorum minimo di membri del cluster lo riconosce.

Oltre ai suoi metadati interni, BookKeeper supporta anche l'aggiunta di metadati personalizzati a un libro mastro. Si tratta di una mappa di coppie chiave / valore che i client passano al momento della creazione e che BookKeeper archivia in ZooKeeper insieme al proprio.

3.3. Bookies

I bookmaker sono server che detengono uno o i registri delle modalità. Un cluster di BookKeeper è costituito da una serie di bookmaker in esecuzione in un determinato ambiente, che forniscono servizi ai client su semplici connessioni TCP o TLS.

I bookmaker coordinano le azioni utilizzando i servizi di cluster forniti da ZooKeeper. Ciò implica che, se vogliamo ottenere un sistema completamente tollerante ai guasti, abbiamo bisogno di almeno uno ZooKeeper a 3 istanze e una configurazione BookKeeper a 3 istanze. Una tale configurazione sarebbe in grado di tollerare la perdita se una singola istanza fallisce e sarebbe ancora in grado di funzionare normalmente, almeno per la configurazione del registro di default: dimensione dell'insieme a 3 nodi, quorum di scrittura a 2 nodi e quorum di ack a 2 nodi.

4. Configurazione locale

I requisiti di base per eseguire BookKeeper in locale sono piuttosto modesti. Innanzitutto, abbiamo bisogno di un'istanza ZooKeeper attiva e funzionante, che fornisce l'archiviazione dei metadati del registro per BookKeeper. Successivamente, distribuiamo un bookmaker, che fornisce i servizi effettivi ai clienti.

Sebbene sia certamente possibile eseguire questi passaggi manualmente, qui useremo un file docker-compose che utilizza immagini Apache ufficiali per semplificare questa attività:

$ cd  $ docker-compose up

Questo docker-compose crea tre bookmaker e un'istanza di ZooKeeper. Poiché tutti gli allibratori funzionano sulla stessa macchina, è utile solo a scopo di test. La documentazione ufficiale contiene i passaggi necessari per configurare un cluster completamente a tolleranza di errore.

Facciamo un test di base per verificare che funzioni come previsto, utilizzando listbookies dei comandi della shell di 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 

L'output mostra l'elenco dei bookmaker disponibili , composto da tre bookmaker. Si noti che gli indirizzi IP visualizzati cambieranno a seconda delle specifiche dell'installazione Docker locale.

5. Using the Ledger API

The Ledger API is the most basic way to interface with BookKeeper. It allows us to interact directly with Ledger objects but, on the other hand, lacks direct support for higher-level abstractions such as streams. For those use cases, the BookKeeper project offers another library, DistributedLog, which supports those features.

Using the Ledger API requires adding the bookkeeper-server dependency to our project:

 org.apache.bookkeeper bookkeeper-server 4.10.0 

NOTE: As stated in the documentation, using this dependency will also include dependencies for the protobuf and guava libraries. Should our project also need those libraries, but at a different version than those used by BookKeeper, we could use an alternative dependency that shades those libraries:

 org.apache.bookkeeper bookkeeper-server-shaded 4.10.0  

5.1. Connecting to Bookies

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.

Il secondo callback viene chiamato quando tutti i registri sono stati inviati al callback del processore o quando si verifica un errore. Nel nostro caso, abbiamo omesso la gestione degli errori. Invece, stiamo solo diminuendo un CountDownLatch , che, a sua volta, terminerà l' operazione di attesa e consentirà al metodo di tornare con un elenco di tutti i libri mastri disponibili.

6. Conclusione

In questo articolo abbiamo trattato il progetto Apache BookKeeper, dando uno sguardo ai suoi concetti fondamentali e utilizzando la sua API di basso livello per accedere a Ledger ed eseguire operazioni di lettura / scrittura.

Come al solito, tutto il codice è disponibile su GitHub.