Stream mendalam

Topik ini membahas stream pada tingkat lanjutan setelah dasar penambahan dan pembacaan entri diperkenalkan pada topik pengantar stream. Lingkupnya mencakup aturan urutan ID yang menjamin keutuhan log, pemeriksaan keadaan stream dengan XINFO, pembacaan berkelanjutan dengan XREAD BLOCK, serta pemangkasan isi stream dengan XTRIM dan MAXLEN. Setelah mengikuti contoh pada topik ini, log peristiwa yang tumbuh terus dapat dijaga panjangnya dan dibaca secara berkelanjutan tanpa membaca ulang seluruh isi.

ID stream dan aturan urutannya#

ID stream terdiri atas dua bilangan yang dipisahkan tanda hubung, yaitu milidetik dan nomor sekuens, contohnya 1730123456789-0. Aturan yang menjamin urutan hanya satu, yaitu ID entri baru wajib lebih besar daripada ID entri terakhir pada stream tersebut. Aturan yang sama berlaku untuk penambahan dengan ID eksplisit, sehingga nomor kecil seperti 1-1 dan 2-1 sah digunakan selama urutannya menaik. Contoh pada topik ini memilih ID eksplisit agar keluarannya tetap sama pada setiap eksekusi, sedangkan produksi lazim menggunakan tanda bintang agar Redis menentukan ID dari waktu server.

# menghapus stream lama agar contoh selalu dimulai dari keadaan yang sama, keluarannya diabaikan
redis-cli del stream:pinjam >/dev/null
# ID eksplisit dipilih agar keluaran tetap, produksi lazim menggunakan tanda bintang untuk ID otomatis
redis-cli xadd stream:pinjam 1-1 peristiwa pinjam rak rak-a
redis-cli xadd stream:pinjam 1-2 peristiwa pinjam rak rak-b
redis-cli xadd stream:pinjam 2-1 peristiwa kembali rak rak-a

1-1
1-2
2-1

Nilai kembalian XADD persis sama dengan ID yang diminta, sehingga ID pada keluaran dapat langsung digunakan sebagai posisi baca. Aturan menaik ditegakkan ketat, dan percobaan berikut menunjukkan penolakan atas ID yang melanggarnya.

# ID 1-3 lebih kecil daripada entri terakhir 2-1
redis-cli xadd stream:pinjam 1-3 peristiwa pinjam rak rak-c

ERR The ID specified in XADD is equal or smaller than the target stream top item

Pesan error di atas muncul karena ID 1-3 lebih kecil daripada ID entri terakhir 2-1, sehingga penambahannya ditolak dan isi stream tidak berubah. Penolakan serupa menimpa ID yang sama dengan entri terakhir, sehingga penomoran manual wajib memperhatikan ID terakhir yang berlaku. Bila kebijakan penomoran sulit dijaga, tanda bintang menghilangkan beban tersebut karena Redis menjamin ID yang dihasilkan selalu lebih besar.

Memeriksa keadaan stream dengan XINFO#

XINFO STREAM menampilkan ringkasan keadaan sebuah stream tanpa membaca seluruh entrinya. Keluarannya memuat panjang log, ID terakhir yang dihasilkan, catatan ID entri terbesar yang pernah dihapus, serta entri pertama dan terakhir. Perintah ini berguna untuk memeriksa keadaan log sebelum menentukan kebijakan pemangkasan atau posisi awal pembacaan.

# ringkasan keadaan stream setelah tiga penambahan
redis-cli xinfo stream stream:pinjam

length
3
radix-tree-keys
1
radix-tree-nodes
2
last-generated-id
2-1
max-deleted-entry-id
0-0
entries-added
3
recorded-first-entry-id
1-1
groups
0
first-entry
1-1
peristiwa
pinjam
rak
rak-a
last-entry
2-1
peristiwa
kembali
rak
rak-a

Field length berisi jumlah entri yang tersimpan, sedangkan last-generated-id berisi ID terakhir yang pernah digunakan, baik melalui ID eksplisit maupun tanda bintang. Field max-deleted-entry-id bernilai 0-0 karena belum ada entri yang dihapus, dan nilai ini turut menjadi batas bawah penolakan ID baru. Field entries-added menghitung total penambahan sejak key dibuat, sedangkan first-entry dan last-entry menampilkan entri ujung beserta field-nilainya. Field recorded-first-entry-id menandai ID entri pertama yang masih tersimpan, dan nilainya bergeser seiring pemangkasan membuang entri terlama. Field groups berisi jumlah consumer group, yaitu kelompok pembaca yang berbagi posisi baca pada satu stream yang sama, dan nilainya 0 karena contoh pada topik ini belum membuat group.

Membaca berkelanjutan dengan XREAD BLOCK#

XREAD tanpa argumen tambahan mengembalikan keluaran kosong apabila tidak ada entri yang lebih baru daripada posisi baca, sehingga aplikasi pemantau log terpaksa memanggilnya berulang dalam selang waktu singkat. Argumen BLOCK mengubah perilaku tersebut, yaitu perintah menunggu sampai batas waktu tertentu, dan kembali lebih awal apabila entri baru datang. Posisi khusus $ meminta Redis menggunakan ID entri terakhir pada saat perintah dipanggil, sehingga hasilnya hanya memuat penambahan yang datang sesudahnya. Diagram berikut merangkum pola kursor ini, yaitu klien memegang ID terakhir yang diterima dan server hanya mengembalikan entri dengan ID lebih besar.

# menyiapkan ulang stream sensor suhu, keluaran penyiapannya diabaikan
redis-cli del stream:suhu >/dev/null
redis-cli xadd stream:suhu 1-1 ruang lab-a suhu 26.5 >/dev/null
redis-cli xadd stream:suhu 2-1 ruang lab-a suhu 27.0 >/dev/null
redis-cli xadd stream:suhu 3-1 ruang lab-b suhu 26.8 >/dev/null
# entri lebih baru daripada 2-1 sudah ada sehingga perintah langsung kembali
redis-cli xread block 1000 streams stream:suhu 2-1
# posisi $ menunggu entri yang ditambahkan setelah perintah dipanggil, tidak ada sehingga kosong setelah 1000 ms
redis-cli xread block 1000 streams stream:suhu '$'

stream:suhu
3-1
ruang
lab-b
suhu
26.8

Pemanggilan pertama langsung mengembalikan entri 3-1 karena ID-nya lebih besar daripada kursor 2-1. Pemanggilan kedua menggunakan posisi $, menunggu selama 1000 milidetik, dan berakhir tanpa keluaran apa pun karena tidak ada penambahan baru pada selang itu. Pola penggunaannya berupa perulangan, yaitu aplikasi menyimpan ID terakhir yang diterima sebagai kursor, memanggil XREAD BLOCK dengan kursor tersebut, lalu memperbarui kursor dari hasilnya. Kursor dapat disimpan di luar Redis agar proses lain melanjutkan pembacaan dari posisi yang sama.

Memangkas stream dengan XTRIM dan MAXLEN#

Stream yang digunakan sebagai log produksi tumbuh tanpa henti, sehingga kebijakan retensi perlu ditegakkan agar penggunaan memorinya terkendali. XTRIM membuang entri dari awal log menurut dua strategi, yaitu MAXLEN yang menyimpan sejumlah entri terakhir dan MINID yang menyimpan entri dengan ID di atas ambang tertentu. XADD juga menerima opsi MAXLEN pada penambahannya, sehingga penambahan dan pemangkasan terjadi dalam satu perintah. Tanpa pemangkasan, panjang log hanya berhenti apabila key-nya dihapus.

# menyiapkan ulang stream dengan lima entri, keluaran penyiapannya diabaikan
redis-cli del stream:suhu >/dev/null
redis-cli xadd stream:suhu 1-1 ruang lab-a suhu 26.5 >/dev/null
redis-cli xadd stream:suhu 1-2 ruang lab-b suhu 26.8 >/dev/null
redis-cli xadd stream:suhu 1-3 ruang lab-a suhu 27.0 >/dev/null
redis-cli xadd stream:suhu 2-1 ruang lab-b suhu 27.2 >/dev/null
redis-cli xadd stream:suhu 2-2 ruang lab-a suhu 26.9 >/dev/null
# panjang sebelum dipangkas
redis-cli xlen stream:suhu
# menyimpan tiga entri terakhir, keluarannya jumlah entri yang dibuang
redis-cli xtrim stream:suhu maxlen 3
# sisa isi setelah pemangkasan
redis-cli xrange stream:suhu - +

5
2
1-3
ruang
lab-a
suhu
27.0
2-1
ruang
lab-b
suhu
27.2
2-2
ruang
lab-a
suhu
26.9

XTRIM MAXLEN 3 membuang dua entri terlama dan menyisakan 1-3, 2-1, serta 2-2. Nilai kembalian XTRIM berupa jumlah entri yang dibuang. Bentuk pemangkasan pada contoh sebelumnya membuang entri sampai panjang log benar-benar memenuhi batas, sedangkan bentuk perkiraan dengan tanda tilde, ditulis maxlen ~ 3, memperbolehkan simpangan kecil di atas batas demi mempercepat operasinya dan menjadi pilihan lazim pada produksi.

# menyimpan hanya entri dengan ID di atas ambang 2-1
redis-cli xtrim stream:suhu minid 2-1
# sisa isi setelah pemangkasan MINID
redis-cli xrange stream:suhu - +
# penambahan sekaligus pemangkasan dalam satu perintah
redis-cli xadd stream:suhu maxlen 2 3-1 ruang lab-c suhu 27.4
# panjang setelah penambahan dengan MAXLEN
redis-cli xlen stream:suhu
# isi akhir stream setelah kedua pemangkasan
redis-cli xrange stream:suhu - +

1
2-1
ruang
lab-b
suhu
27.2
2-2
ruang
lab-a
suhu
26.9
3-1
2
2-2
ruang
lab-a
suhu
26.9
3-1
ruang
lab-c
suhu
27.4

XTRIM MINID 2-1 membuang entri 1-3 karena ID-nya lebih kecil daripada ambang. Penambahan dengan MAXLEN 2 mengembalikan ID 3-1 sebagaimana biasa, tetapi sekaligus membuang entri terlama sehingga panjang akhirnya tetap dua. Kedua strategi ini saling melengkapi, yaitu MAXLEN menjaga jumlah entri, sedangkan MINID menjaga jendela waktu log.

Kesalahan umum#

Kesalahan pada penggunaan stream tingkat lanjut umumnya menyentuh posisi baca dan kebijakan retensi. Daftar berikut memuat kesalahan yang paling sering muncul beserta perbaikannya.

• Memulai pembacaan dari $ padahal entri lama dibutuhkan. Posisi $ hanya melihat penambahan setelah perintah dipanggil, sehingga seluruh isi yang sudah ada terlewat. Gunakan ID 0 sebagai posisi awal bila log perlu dibaca dari awal.
• Memangkas dengan ambang yang lebih kecil daripada kecepatan konsumsi. Entri yang terbuang sebelum consumer membacanya hilang untuk selamanya. Selaraskan MAXLEN dengan laju konsumsi, atau tetapkan MINID menurut umur entri yang masih dibutuhkan.
• Memanggil XREAD BLOCK 0 di dalam perulangan tanpa penanganan pemutusan. Perintah tersebut menunggu tanpa batas sehingga proses pemantau menggantung apabila tidak ada entri baru. Gunakan nilai BLOCK terbatas dan perlakukan keluaran kosong sebagai tanda untuk memeriksa ulang kondisi.
• Mengira ID eksplisit bebas digunakan ulang setelah entrinya terhapus. Penolakan tetap berlaku terhadap ID yang lebih kecil daripada max-deleted-entry-id, sehingga ID lama tidak dapat hidup kembali. Periksa field tersebut melalui XINFO STREAM apabila penomoran manual menemui penolakan.

Ringkasan#

• ID stream tersusun atas milidetik dan nomor sekuens, dan XADD menolak ID yang sama dengan atau lebih kecil daripada entri terakhir maupun ID terbesar yang pernah dihapus.
• XINFO STREAM merangkum panjang log, ID terakhir, ID terbesar yang pernah dihapus, dan entri pertama serta terakhir tanpa membaca seluruh isi.
• XREAD BLOCK menunggu entri baru sampai batas waktu tertentu, sedangkan posisi $ memulai dari entri terakhir pada saat perintah dipanggil.
• XTRIM dengan MAXLEN atau MINID membuang entri terlama secara permanen, dan XADD menerima MAXLEN agar pemangkasan menyertai penambahan.

Referensi#

• XADD — Redis — Dokumentasi XADD beserta aturan ID eksplisit dan opsi MAXLEN pada penambahan.
• XREAD — Redis — Dokumentasi XREAD beserta semantik BLOCK dan posisi khusus $.
• XTRIM — Redis — Dokumentasi XTRIM dengan strategi MAXLEN dan MINID beserta bentuk perkiraannya.
• XINFO STREAM — Redis — Dokumentasi XINFO STREAM beserta arti setiap field ringkasannya.
• Streams — Redis — Ikhtisar tipe data stream beserta pola pembacaan berkelanjutan dan pemangkasannya.