From 33a4cea193d2182fe36a1d902ce31f50d7fa4855 Mon Sep 17 00:00:00 2001 From: Croxx Date: Wed, 18 Sep 2024 13:34:26 +0800 Subject: [PATCH] doc: update hybrid cache doc part 2 (#11) Signed-off-by: MrCroxx --- docs/02-tutorial/02-hybrid-cache.md | 87 ++++++++++++++++++- docs/02-tutorial/03-monitor.md | 3 + docs/02-tutorial/03-tail-based-tracing.md | 3 - .../02-overhead-of-the-file-system-layer.md | 3 + docs/05-design/01-architecture.md | 4 +- docusaurus.config.ts | 2 +- 6 files changed, 94 insertions(+), 8 deletions(-) create mode 100644 docs/02-tutorial/03-monitor.md delete mode 100644 docs/02-tutorial/03-tail-based-tracing.md create mode 100644 docs/03-topic/02-overhead-of-the-file-system-layer.md diff --git a/docs/02-tutorial/02-hybrid-cache.md b/docs/02-tutorial/02-hybrid-cache.md index ccf2cd2..3475a3c 100644 --- a/docs/02-tutorial/02-hybrid-cache.md +++ b/docs/02-tutorial/02-hybrid-cache.md @@ -42,7 +42,7 @@ For more details, please refer to the API document.[^hybrid-cache-builder]. :::tip dynamic tail-based tracing config -The tracing config is used for configure the dynamic tail-based tracing. It can also be modified later. To learn more, see [Tutorial - Tail-based Tracing](/docs/tutorial/tail-based-tracing). +The tracing config is used for configure the dynamic tail-based tracing. It can also be modified later. To learn more, see [Tutorial - Setup Monitor System](/docs/tutorial/monitor). ::: @@ -78,6 +78,76 @@ RisingWave[^risingwave] supports caching the LSM-tree meta and blocks in both hy To specify a device for the hybrid cache, just call `with_device_config()`[^with-device-config] and provide the device config. +Currently, the storage of the hybrid cache supports 2 kinds of devices: + +1. `DirectFsDevice`[^direct-fs-device]: Setup within a directory of a file system with direct I/O[^direct-io] files. +2. `DirectFileDevice`[^direct-file-device]: Setup with a raw block device (block file) or a direct I/O[^direct-io] file in a file system. + +Determine which kind of device to use depends on your needs. If you want to utilize the spare space of an existing file system, `DirectFsDevice` is all you need. If you want to overcome the overhead of the file system, use `DirectFileDevice` on a raw block device. And **NEVER** use a `DirectFileDevice` within a file system. The `inode` latch will make the overhead of the file system layer worse. + +:::tip + +For more details about the overhead of the file system layer, see [Topic - Overhead of the File System Layer](/docs/topic/overhead-of-the-file-system-layer) + +::: + +Let's take `DirectFsDevice` as an example: + +```rust +let hybrid: HybridCache = HybridCacheBuilder::new() + .with_name("foyer") + .memory(1024) + .storage() + .with_device_config(DirectFsDeviceOptionsBuilder::new("/data/foyer").build()) + .build() + .await + .unwrap(); +``` + +This example uses directory `/data/foyer` to store disk cache data using a device options builder. With the default configuration, ***foyer*** will take 80% of the current free space as the disk cache capacity. You can also specify the disk cache capacity and per file size with the builder. + +For more details, please refer to the API document.[^direct-fs-device-options-builder] [^direct-file-device-options-builder] + +#### 2.3.3 Restrict the throughput + +The bandwidth of the disk is much lower than the bandwidth of the memory. To avoid excessive use of the disk bandwidth, it is **HIGHLY RECOMMENDED** to setup the admission picker with a rate limiter. + +```rust +let hybrid: HybridCache = HybridCacheBuilder::new() + .with_name("foyer") + .memory(1024) + .storage() + .with_device_config(DirectFsDeviceOptionsBuilder::new("/data/foyer").build()) + .with_admission_picker(Arc::new(RateLimitPicker::new(100 * 1024 * 1024))) + .build() + .await + .unwrap(); +``` + +You can also customize the admission picker with your own admission policy. For more details, please refer to the API document.[^admission-picker] + +:::tip admission picker + +Admission means allowing an entry to be inserted into the disk cache. And a admission picker can be used to customize the admission policy. + +For more details, please refer to [Design - Architecture](/docs/design/architecture). + +::: + +#### 2.3.4 Achieve better performance + +The hybrid cache builder also provides a lot of detailed arguments for tuning. + +For example: + +- `with_indexer_shards()` can be used for mitigating hot shards of the indexer. +- `with_flushers()`, `with_reclaimers()` and `with_recover_concurrency()` can be used to tune the concurrency of the inner components. +- `with_runtime_config()` can be used to enable the dedicated runtime or further runtime splitting. + +Tuning the optimized parameters requires an understanding of ***foyer*** interior design and benchmarking with the real workload. For more details, please refer to [Design - Architecture](/docs/design/architecture). + +## 3. `HybridCache` Usage + ***TBC ... ...*** [^hybrid-cache]: https://docs.rs/foyer/latest/foyer/struct.HybridCache.html @@ -88,11 +158,22 @@ To specify a device for the hybrid cache, just call `with_device_config()`[^with [^storage]: https://docs.rs/foyer/latest/foyer/struct.HybridCacheBuilderPhaseMemory.html#method.storage - [^cache-builder]: https://docs.rs/foyer/latest/foyer/struct.CacheBuilder.html [^cache]: https://docs.rs/foyer/latest/foyer/enum.Cache.html [^risingwave]: https://github.com/risingwavelabs/risingwave -[^with-device-config]: https://docs.rs/foyer/latest/foyer/struct.HybridCacheBuilderPhaseStorage.html#method.with_device_config \ No newline at end of file +[^with-device-config]: https://docs.rs/foyer/latest/foyer/struct.HybridCacheBuilderPhaseStorage.html#method.with_device_config + +[^direct-fs-device]: https://docs.rs/foyer/latest/foyer/struct.DirectFsDevice.html + +[^direct-file-device]: https://docs.rs/foyer/latest/foyer/struct.DirectFileDevice.html + +[^direct-io]: https://linux.die.net/HOWTO/SCSI-Generic-HOWTO/dio.html + +[^direct-fs-device-options-builder]: https://docs.rs/foyer/latest/foyer/struct.DirectFsDeviceOptionsBuilder.html + +[^direct-file-device-options-builder]: https://docs.rs/foyer/latest/foyer/struct.DirectFileDeviceOptionsBuilder.html + +[^admission-picker]: https://docs.rs/foyer/latest/foyer/trait.AdmissionPicker.html diff --git a/docs/02-tutorial/03-monitor.md b/docs/02-tutorial/03-monitor.md new file mode 100644 index 0000000..de8e4ed --- /dev/null +++ b/docs/02-tutorial/03-monitor.md @@ -0,0 +1,3 @@ +# Setup Monitor System + +***TBC ... ...*** \ No newline at end of file diff --git a/docs/02-tutorial/03-tail-based-tracing.md b/docs/02-tutorial/03-tail-based-tracing.md deleted file mode 100644 index 39f40aa..0000000 --- a/docs/02-tutorial/03-tail-based-tracing.md +++ /dev/null @@ -1,3 +0,0 @@ -# Tail-based Tracing - -***TBC ... ...*** \ No newline at end of file diff --git a/docs/03-topic/02-overhead-of-the-file-system-layer.md b/docs/03-topic/02-overhead-of-the-file-system-layer.md new file mode 100644 index 0000000..e1c4b70 --- /dev/null +++ b/docs/03-topic/02-overhead-of-the-file-system-layer.md @@ -0,0 +1,3 @@ +# Overhead of the File System Layer + +***TBC ... ...*** \ No newline at end of file diff --git a/docs/05-design/01-architecture.md b/docs/05-design/01-architecture.md index f2569bf..3f0cb8e 100644 --- a/docs/05-design/01-architecture.md +++ b/docs/05-design/01-architecture.md @@ -1 +1,3 @@ -# Architecture \ No newline at end of file +# Architecture + +***TBC ... ...*** diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 3d11d19..ea91155 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -170,7 +170,7 @@ const config: Config = { markdown: { format: 'detect', remarkRehypeOptions: { - footnoteBackLabel: 'References', + footnoteLabel: 'References', } },