{"id":13415640,"url":"https://github.com/danielealbano/cachegrand","last_synced_at":"2025-05-16T10:07:16.311Z","repository":{"id":27065782,"uuid":"125234630","full_name":"danielealbano/cachegrand","owner":"danielealbano","description":"cachegrand - a modern data ingestion, processing and serving platform built for today's hardware","archived":false,"fork":false,"pushed_at":"2024-08-18T11:39:03.000Z","size":9577,"stargazers_count":969,"open_issues_count":27,"forks_count":34,"subscribers_count":16,"default_branch":"main","last_synced_at":"2024-08-18T12:51:05.027Z","etag":null,"topics":["caching","high-performance","io-uring","kafka","kafka-streams","key-value","key-value-store","linux","low-latency","memcache","prometheus","redis","redis-cache","redis-database","redis-server","redis-streams","tcpip-stack","webassembly","xdp"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/danielealbano.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"danielealbano"}},"created_at":"2018-03-14T15:33:02.000Z","updated_at":"2024-08-15T18:24:29.000Z","dependencies_parsed_at":"2023-01-16T22:30:19.293Z","dependency_job_id":"ef6785f2-d3a6-43de-bf2b-dec4dbb9fe01","html_url":"https://github.com/danielealbano/cachegrand","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielealbano%2Fcachegrand","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielealbano%2Fcachegrand/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielealbano%2Fcachegrand/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielealbano%2Fcachegrand/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/danielealbano","download_url":"https://codeload.github.com/danielealbano/cachegrand/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254509476,"owners_count":22082891,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["caching","high-performance","io-uring","kafka","kafka-streams","key-value","key-value-store","linux","low-latency","memcache","prometheus","redis","redis-cache","redis-database","redis-server","redis-streams","tcpip-stack","webassembly","xdp"],"created_at":"2024-07-30T21:00:50.988Z","updated_at":"2025-05-16T10:07:11.295Z","avatar_url":"https://github.com/danielealbano.png","language":"C","funding_links":["https://github.com/sponsors/danielealbano"],"categories":["C","Software"],"sub_categories":[],"readme":"[![License](https://img.shields.io/github/license/danielealbano/cachegrand)](https://github.com/danielealbano/cachegrand/blob/main/LICENSE)\n[![Build \u0026 Test](https://github.com/danielealbano/cachegrand/actions/workflows/build_and_test.yml/badge.svg)](https://github.com/danielealbano/cachegrand/actions/workflows/build_and_test.yml)\n[![codecov](https://codecov.io/gh/danielealbano/cachegrand/branch/main/graph/badge.svg?token=H4W0N0F7MT)](https://codecov.io/gh/danielealbano/cachegrand)\n[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fdanielealbano%2Fcachegrand.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Fdanielealbano%2Fcachegrand?ref=badge_shield)\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://cachegrand.io\"\u003e\n    \u003cpicture\u003e\n      \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://raw.githubusercontent.com/danielealbano/cachegrand/main/docs/images/logo-dark.png\"\u003e\n      \u003cimg alt=\"cachegrand logo\" src=\"https://raw.githubusercontent.com/danielealbano/cachegrand/main/docs/images/logo-light.png\"\u003e\n    \u003c/picture\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n### Table of Content\n\n- [What is cachegrand?](#what-is-cachegrand)\n- [Benchmarks](#benchmarks)\n- [Quick Start](#quick-start)\n- [Configuration](#configuration)\n- [Running cachegrand](#running-cachegrand)\n- [License](#license)\n- [Contributing](#contributing)\n\n### What is cachegrand?\n\ncachegrand is a high-performance key-value store designed to optimize performance on modern hardware. It offers\nefficient data handling, processing, and retrieval capabilities through standard protocols and APIs. With its impressive\nscalability, cachegrand can handle millions of operations per second, all completed in less than a millisecond.\n\nUnderneath its robust architecture, cachegrand employs its own database engine that seamlessly works with various data\ntypes to to enable a versatile data ingestion and retrieval. Additionally, cachegrand supports WebAssembly, empowering\nserver-side data processing.\n\nOne of cachegrand's notable features is its compatibility with widely adopted protocols and interfaces, including Kafka,\nRedis, and Memcache. This compatibility allows developers to leverage their existing familiarity with SDKs and\nframeworks.\n\ncachegrand is still in development and some of the features are still in the works, but it's already possible to use it\nas a high-performance key-value store with the Redis protocol.\n\n#### Use cases\n\ncachegrand simplifies real-time operations by providing an integrated solution, eliminating the need for stitching\ntogether multiple technologies. It offers a streamlined approach to manage and process data, enabling efficient\nreal-time scenarios.\n\nWith cachegrand, you can:\n\n- Ingest data using familiar streaming methods like Kafka or Redis.\n- Process data using WebAssembly-compatible languages like Python or Rust.\n- Leverage the internal database to store intermediate and final results.\n- Deliver processed data using supported protocols such as Kafka, Redis, HTTP(s), or Memcached.\n\nBut it's also possible just to use single components of cachegrand, like the Key-Value store via the Redis protocol,\nor the Kafka protocol, both with or without the WebAssembly support, depending on your needs.\n\n#### Implemented Key features\n\nCurrently cachegrand supports only the Redis interface to interact with the Key-Value store, support for the Kafka\ninterface and the WebAssembly support are still in the works.\n\n- [Redis](https://github.com/danielealbano/cachegrand/blob/main/docs/architecture/modules/redis.md) protocol support\n- [Prometheus](https://github.com/danielealbano/cachegrand/blob/main/docs/architecture/modules/prometheus.md) endpoint\n  for monitoring\n- Blazing fast [hashtable](https://github.com/danielealbano/cachegrand/blob/main/docs/architecture/hashtable.md) capable\n  of digesting 2.1 billion records per second on a 1x AMD EPYC 7502\n- [Scales vertically](#benchmarks), 2x cpus means ~2x requests\n- In-memory and on-disk storage\n- Supports different collection data types (Streams, Lists, Hashsets, Sorted Sets, etc.) (WIP)\n\n#### Planned Key Features\n\n- More modules for additional platforms compatibility, e.g. Kafka, Memcache, HTTPS, AWS S3, DataDog, etc.\n- And ad-hoc UDP message-based (Homa-like) network stack based on Linux XDP (eXpress Data Path)\n- [WebAssembly](https://github.com/danielealbano/cachegrand/blob/main/docs/architecture/webassembly.md) to provide\n  [User Defined Functions](https://github.com/danielealbano/cachegrand/blob/main/docs/architecture/webassembly/user-defined-functions.md),\n  [event hooks](https://github.com/danielealbano/cachegrand/blob/main/docs/architecture/webassembly/event-hooks.md),\n  implement [modules](https://github.com/danielealbano/cachegrand/blob/main/docs/architecture/webassembly.md#modules),\n  you can use your preferred language to perform operations server side\n- Automatic load balancing, Replication groups, Eventual Consistency\n\nIt's possible to find more information in the [docs'](https://github.com/danielealbano/cachegrand/blob/main/docs/)\nfolder.\n\ncachegrand runs on Linux on x86-64 (Intel and AMD) and aarch64 (ARMv8, e.g. Raspberry PI 4, Orange PI 5, etc.), we are\nplanning to port it to more hardware (e.g. RISC) once will become more feature complete.\n\n### Benchmarks\n\n#### Internal Key-Value stor via the Redis interface\n\nThe benchmarks are regularly carried out on an **AMD EPYC 7502P** with **2 x 25Gbit** network links using\n**Ubuntu 22.04** and two other servers, with the same hardware, to generate load using memtier_benchmark.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"GET/SET latest benchmarks\" width=\"48%\" src=\"https://github.com/cachegrand/cachegrand-benchmarks/raw/main/images/latest-benchmarks-get-set.png\"\u003e\n  \u0026nbsp;\n  \u003cimg alt=\"GET/SET with batching latest benchmarks\" width=\"48%\" src=\"https://github.com/cachegrand/cachegrand-benchmarks/raw/main/images/latest-benchmarks-get-set-pipelining.png\"\u003e\n\u003c/p\u003e\n\n_[Benchmarks source](https://github.com/cachegrand/cachegrand-benchmarks)_\n\n### Quick Start\n\nSimply run\n\n```shell\ndocker run \\\n  --ulimit memlock=-1:-1 \\\n  --ulimit nofile=262144:262144 \\\n  -p 6379:6379 \\\n  -p 6380:6380 \\\n  -p 9090:9090 \\\n  -it \\\n  --rm \\\n  cachegrand/cachegrand-server:latest\n```\n\nit comes with a default config file with Redis on port 6379, TLS-enabled Redis on port 6380 and Prometheus on port 9090\nwith the metrics endpoint on `/metrics`.\n\nThe certificate will be generated on each start, to use an ad-hoc SSL certificate, instead of the auto-generated one,\nit's possible to mount the required certificate and key using the following command\n\n```shell\ndocker run \\\n  -v /path/to/certificate.pem:/etc/cachegrand/cachegrand.pem \\\n  -v /path/to/certificate.key:/etc/cachegrand/cachegrand.key \\\n  --ulimit memlock=-1:-1 \\\n  --ulimit nofile=262144:262144 \\\n  -p 6379:6379 \\\n  -p 6380:6380 \\\n  -p 9090:9090 \\\n  -it \\\n  --rm \\\n  cachegrand/cachegrand-server:latest\n```\n\nif you want to use a custom configuration, you can download the default configuration file using the following command\n\n```shell\ncurl https://raw.githubusercontent.com/danielealbano/cachegrand/main/etc/cachegrand.yaml.skel -o /path/to/cachegrand.yaml\n```\n\nEdit it and then use it with the cachegrand's docker image using the following command\n\n```shell\ndocker run \\\n  -v /path/to/cachegrand.yaml:/etc/cachegrand/cachegrand.yaml \\\n  --ulimit memlock=-1:-1 \\\n  --ulimit nofile=262144:262144 \\\n  -p 6379:6379 \\\n  -p 6380:6380 \\\n  -p 9090:9090 \\\n  -it \\\n  --rm \\\n  cachegrand/cachegrand-server:latest\n```\n\n### Configuration\n\ncachegrand comes with a default configuration but for production use please review the\n[documentation](https://github.com/danielealbano/cachegrand/blob/main/docs/configuration.md) to ensure an optimal deployment.\n\n### Running cachegrand\n\n#### Build from source\n\nInstructions on how to build cachegrand from the sources are available in the\n[documentation](https://github.com/danielealbano/cachegrand/blob/main/docs/build-from-source.md)\n\ncachegrand doesn't need to run as root but please review the configuration section to ensure that enough lockable memory\nhas been allowed, enough files can be opened and that the slab allocator has been enabled and enough huge pages have been provided\n\nBefore trying to start cachegrand, take a look to the\n[performance tips](https://github.com/danielealbano/cachegrand/blob/main/docs/performance-tips.md) available in the\ndocs' section as they might provide a valuable help!\n\n#### Help\n\n```shell\n$ ./cachegrand-server --help\nUsage: cachegrand-server [OPTION...]\n\n  -c, --config-file=FILE     Config file (default config file\n                             /usr/local/etc/cachegrand/cachegrand.conf )\n  -l, --log-level=LOG LEVEL  log level (error, warning, info, verbose, debug)\n  -?, --help                 Give this help list\n      --usage                Give a short usage message\n\nMandatory or optional arguments to long options are also mandatory or optional\nfor any corresponding short options.\n```\n\n#### Start it locally\n\nOnce cachegrand has been [built from the sources](#build-from-source), it's possible to run it with the following command\n\n```shell\n/path/to/cachegrand-server -c /path/to/cachegrand.yaml.skel\n[2023-04-08T18:25:54Z][INFO       ][program_startup_report] cachegrand-server version v0.3.0 (built on 2023-05-08T18:19:31Z)\n[2023-04-08T18:25:54Z][INFO       ][program_startup_report] \u003e Release build, compiled using gcc v11.3.0\n[2023-04-08T18:25:54Z][INFO       ][program_startup_report] \u003e Hashing algorithm in use t1ha2\n[2023-04-08T18:25:54Z][INFO       ][program_startup_report] \u003e Running on Linux bf2b94ff7fa5 5.19.0-38-generic #39-Ubuntu SMP PREEMPT_DYNAMIC Fri Mar 17 17:33:16 UTC 2023 x86_64\n[2023-04-08T18:25:54Z][INFO       ][program_startup_report] \u003e Memory: 128722 MB total, 1955 MB swap total\n[2023-04-08T18:25:54Z][INFO       ][program_startup_report] \u003e TLS: mbed TLS 2.28.0 (kernel offloading enabled)\n[2023-04-08T18:25:54Z][INFO       ][program_startup_report] \u003e Realtime clock source \u003cPOSIX\u003e, resolution \u003c4 ms\u003e\n[2023-04-08T18:25:54Z][INFO       ][program_startup_report] \u003e Monotonic clock source \u003cHardware (TSC)\u003e (estimated cpu cycles per second \u003c4.20 GHz\u003e), resolution \u003c1 ms\u003e\n[2023-04-08T18:25:54Z][INFO       ][config] Loading the configuration from /etc/cachegrand/cachegrand.yaml\n[2023-04-08T18:25:54Z][INFO       ][program] Starting \u003c32\u003e workers\n[2023-04-08T18:25:54Z][INFO       ][worker][id: 00][cpu: 00][module_redis_snapshot_load] Snapshot file \u003c/var/lib/cachegrand/dump.rdb\u003e does not exist\n[2023-04-08T18:25:55Z][INFO       ][program] Ready to accept connections\n```\n\n### License\n\ncachegrand is Open Source and licensed under the\n[BSD 3-Clause License](https://github.com/danielealbano/cachegrand/blob/main/LICENSE), all the files under the\nrepository are licensed under the same license unless otherwise specified (for example, but not limited, via a README or\na LICENSE in a sub folder or as header in the source files).\n\ncachegrand uses a number of different components all licensed under compatible licenses but if you spot any that is not\ncompatible with the BSD 3-Clause License please open an issue, we will be happy to fix it promptly!\n\n### Contributing\n\nPlease if you find any bug, malfunction or regression feel free to open an issue or to fork the repository and submit\nyour PRs! If you do open an Issue for a crash, if possible please enable sentry.io in the configuration file and try to\nreproduce the crash, a minidump will be automatically uploaded on sentry.io.\n\nAlso, if you have built cachegrand from the source, please attach the compiled binary to the issue as well as sentry.io\nknows nothing of your own compiled binaries.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanielealbano%2Fcachegrand","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdanielealbano%2Fcachegrand","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanielealbano%2Fcachegrand/lists"}