Panduan untuk Penjaga Buku Apache

Pengaturcaraan

1. Gambaran keseluruhan

Dalam artikel ini, kami akan memaparkan BookKeeper, sebuah perkhidmatan yang menerapkan sistem penyimpanan rekod yang diedarkan dan bertolak ansur .

2. Apa itu Penjaga Buku ?

BookKeeper pada awalnya dikembangkan oleh Yahoo sebagai subproyek ZooKeeper dan lulus untuk menjadi projek peringkat tertinggi pada tahun 2015. Pada terasnya, BookKeeper bertujuan untuk menjadi sistem yang boleh dipercayai dan berprestasi tinggi yang menyimpan urutan Entri Log (aka Rekod ) dalam struktur data dipanggil Ledgers .

Ciri penting lejar adalah hakikat bahawa mereka hanya boleh ditambah dan tidak berubah . Ini menjadikan BookKeeper calon yang baik untuk aplikasi tertentu, seperti sistem pembalakan diedarkan, aplikasi pesanan Pub-Sub, dan pemprosesan aliran masa nyata.

3. Konsep Penjaga Buku

3.1. Log Penyertaan

Entri log mengandungi unit data yang tidak dapat dipisahkan yang disimpan atau dibaca oleh aplikasi pelanggan dari BookKeeper. Apabila disimpan dalam lejar, setiap entri mengandungi data yang disediakan dan beberapa medan metadata.

Medan metadata tersebut merangkumi entryId, yang mesti unik dalam lejar tertentu. Terdapat juga kod pengesahan yang digunakan oleh BookKeeper untuk mengesan kapan entri rosak atau diubah.

BookKeeper tidak menawarkan ciri-ciri serialisasi dengan sendirinya, oleh itu pelanggan mesti merangka kaedah mereka sendiri untuk menukar konstruk peringkat lebih tinggi ke / dari susunan bait .

3.2. Lejar

Lejar adalah unit simpanan asas yang diuruskan oleh BookKeeper, menyimpan urutan entri log yang disusun. Seperti yang telah disebutkan sebelumnya, buku besar memiliki semantik hanya tambahan, yang bermaksud bahawa rekod tidak dapat diubah setelah ditambahkan padanya.

Juga, apabila pelanggan berhenti bertulis kepada lejar dan menutup ia, pemegang buku anjing laut dan kami tidak lagi boleh menambah data kepadanya, walaupun pada masa yang lain . Ini adalah perkara penting yang perlu diingat semasa merancang aplikasi di sekitar BookKeeper. Buku besar bukanlah calon yang baik untuk secara langsung melaksanakan konstruksi peringkat lebih tinggi , seperti barisan. Sebagai gantinya, kita melihat lejar digunakan lebih kerap untuk membuat struktur data yang lebih asas yang menyokong konsep peringkat tinggi tersebut.

Sebagai contoh, projek Log Terdistribusi Apache menggunakan lejar sebagai segmen log. Segmen tersebut digabungkan ke dalam log diedarkan, tetapi lejar yang mendasari telus kepada pengguna biasa.

BookKeeper mencapai ketahanan lejar dengan mereplikasi entri log di pelbagai contoh pelayan. Tiga parameter mengawal berapa banyak pelayan dan salinan yang disimpan:

  • Ukuran ensemble: bilangan pelayan yang digunakan untuk menulis data lejar
  • Tulis ukuran kuorum: bilangan pelayan yang digunakan untuk meniru entri log yang diberikan
  • Saiz korum ack: bilangan pelayan yang mesti mengetahui operasi menulis entri log yang diberikan

Dengan menyesuaikan parameter tersebut, kita dapat menyesuaikan ciri-ciri prestasi dan ketahanan dari lejar tertentu. Semasa menulis kepada lejar, BookKeeper hanya akan menganggap operasi itu berjaya apabila sekumpulan minimum anggota kluster mengakuinya.

Sebagai tambahan kepada metadata dalamannya, BookKeeper juga menyokong penambahan metadata tersuai ke lejar. Itu adalah peta pasangan kunci / nilai yang dilalui oleh pelanggan pada waktu penciptaan dan kedai BookKeeper di ZooKeeper di samping miliknya.

3.3. Bookies

Bookie adalah pelayan yang memegang satu atau lejar mod. Kluster BookKeeper terdiri dari sejumlah bookie yang berjalan di lingkungan tertentu, menyediakan perkhidmatan kepada klien melalui sambungan TCP atau TLS biasa.

Bookie menyelaraskan tindakan menggunakan perkhidmatan kluster yang disediakan oleh ZooKeeper. Ini menunjukkan bahawa, jika kita ingin mencapai sistem toleransi kesalahan sepenuhnya, kita memerlukan sekurang-kurangnya penyediaan ZooKeeper 3-instance dan BookKeeper 3-instance. Penyediaan sedemikian akan dapat menanggung kerugian jika ada satu contoh yang gagal dan masih dapat beroperasi seperti biasa, sekurang-kurangnya untuk penyediaan lejar lalai: ukuran ensemble 3-nod, kuorum penulisan 2-nod, dan korum ack 2-node.

4. Persediaan Setempat

Keperluan asas untuk menjalankan BookKeeper secara tempatan agak sederhana. Pertama, kita memerlukan contoh ZooKeeper dan berjalan, yang menyediakan penyimpanan metadata lejar untuk BookKeeper. Seterusnya, kami menggunakan bookie, yang memberikan perkhidmatan sebenar kepada pelanggan.

Walaupun mungkin untuk melakukan langkah-langkah itu secara manual, di sini kita akan menggunakan fail penggubah dok yang menggunakan gambar Apache rasmi untuk mempermudah tugas ini:

$ cd  $ docker-compose up

Ini buruh pelabuhan-karang mewujudkan tiga bookies dan contoh ZooKeeper. Oleh kerana semua bookie dijalankan pada mesin yang sama, ia hanya berguna untuk tujuan ujian. Dokumentasi rasmi mengandungi langkah-langkah yang diperlukan untuk mengkonfigurasi kelompok toleransi sepenuhnya.

Mari buat ujian asas untuk memastikan bahawa ia berfungsi seperti yang diharapkan, dengan menggunakan senarai buku arahan shell 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

Hasilnya menunjukkan senarai bookie yang ada , yang terdiri daripada tiga bookie. Harap maklum bahawa alamat IP yang ditunjukkan akan berubah bergantung pada spesifikasi pemasangan Docker tempatan.

5. Menggunakan API Ledger

The Ledger API adalah kaedah paling asas untuk berinteraksi dengan BookKeeper . Ini membolehkan kita berinteraksi secara langsung dengan objek Ledger tetapi, di sisi lain, tidak mempunyai sokongan langsung untuk abstraksi tahap tinggi seperti aliran. Untuk kes penggunaan tersebut, projek BookKeeper menawarkan perpustakaan lain, DistributedLog, yang menyokong ciri tersebut.

Menggunakan API Ledger memerlukan penambahan kebergantungan pelayan buku ke projek kami:

 org.apache.bookkeeper bookkeeper-server 4.10.0

CATATAN: Seperti yang dinyatakan dalam dokumentasi, penggunaan kebergantungan ini juga akan merangkumi kebergantungan untuk perpustakaan protobuf dan jambu. Sekiranya projek kami juga memerlukan perpustakaan tersebut, tetapi pada versi yang berbeza daripada yang digunakan oleh BookKeeper, kami dapat menggunakan pergantungan alternatif yang membudayakan perpustakaan tersebut:

 org.apache.bookkeeper bookkeeper-server-shaded 4.10.0

5.1. Menyambung ke 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.

Panggilan balik kedua dipanggil apabila semua lejar telah dihantar ke panggilan balik pemproses atau apabila terdapat kegagalan. Dalam kes kami, kami telah menghilangkan pengendalian ralat. Sebagai gantinya, kami hanya mengurangkan CountDownLatch , yang pada gilirannya, akan menyelesaikan operasi menunggu dan membolehkan kaedah itu kembali dengan senarai semua lejar yang tersedia.

6. Kesimpulannya

Dalam artikel ini kita telah membahas projek Apache BookKeeper, melihat konsep terasnya dan menggunakan API tahap rendah untuk mengakses Ledger dan melakukan operasi membaca / menulis.

Seperti biasa, semua kod boleh didapati di GitHub.