{"id":26063230,"url":"https://github.com/edgio/edgio_caching_emulator","last_synced_at":"2025-04-11T11:50:27.333Z","repository":{"id":38243776,"uuid":"145043845","full_name":"Edgio/edgio_caching_emulator","owner":"Edgio","description":"A web-caching policy emulator from Edgio.","archived":false,"fork":false,"pushed_at":"2022-06-23T02:58:38.000Z","size":20417,"stargazers_count":10,"open_issues_count":1,"forks_count":6,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-03-25T08:11:10.323Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Edgio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"Contributing.md","funding":null,"license":"LICENSE","code_of_conduct":"Code-of-Conduct.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-08-16T22:09:41.000Z","updated_at":"2023-11-11T03:45:25.000Z","dependencies_parsed_at":"2022-09-13T19:21:47.406Z","dependency_job_id":null,"html_url":"https://github.com/Edgio/edgio_caching_emulator","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Edgio%2Fedgio_caching_emulator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Edgio%2Fedgio_caching_emulator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Edgio%2Fedgio_caching_emulator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Edgio%2Fedgio_caching_emulator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Edgio","download_url":"https://codeload.github.com/Edgio/edgio_caching_emulator/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248389769,"owners_count":21095654,"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":[],"created_at":"2025-03-08T16:34:18.715Z","updated_at":"2025-04-11T11:50:27.314Z","avatar_url":"https://github.com/Edgio.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Edgio Caching Emulator\nA web-caching policy emulator.\n\n[![standard-readme\ncompliant](https://img.shields.io/badge/readme%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme)\n\nThe Edgio Caching Emulator (ECE) is a tool for comparing the impacts of\narbitrary caching policies on cache performance for fixed workloads. In\nparticular, it is intended to consume log data from production caching servers\nand provide insight into how the cache would behave, both in terms of\ntraditional cache metrics (hit rate, eviction rate, etc.) and more tangential\nmetrics (disk writes, origin pulls, etc.).\n\n## Table of Contents\n\n- [Background](#background)\n- [Install](#install)\n- [Usage](#usage)\n- [Contribute](#contribute)\n- [License](#license)\n\n## Background\n\nThis project was developed to allow for the easy implementation and comparison\nof arbitrary caching policies. Doing this in an isolated environment allows one to\navoid having to implement each potential policy in production, which can be both\ntime consuming and risky. Furthermore, the system is log-driven, and is designed to\nbe driven by production traffic traces. Since it uses these production\nworkloads, we dubbed this system an _emulator_, rather than a simulator.\n\nThe Edgio Caching Emulator includes the following features.\n* **Cache Admission**\n * **N-hit caching**: items are cached on the n-th request\n * **Probabilistic caching**: items are cached based on a pre-defined probability value\n* **Cache Eviction**\n * **FIFO**: Items are purged in first-in-first-out order\n * **Regular LRU**: items are purged in a least recently used/requested fashion\n * **Size-based LRU**: during each purge, the largest sized item from a list of X least recently used items is deleted\n\nThe emulator provides data from various metrics to show the performance of such\ntechniques over time, including hit and byte-hit ratios (overall and per customer), cache reads and writes, and reads from origin\n\n## Install\n\nTo install the ECE, first clone the repo:\n\n```git clone https://github.com/edgioinc/edgio_caching_emulator.git ```\n\nSimply hop into the directory and run make:\n\n``` cd edgio_caching_emulator ```\n\n``` make ```\n\nThe Makefile will use clang++ by default, but you can override the default with another compiler of your choice:\n\n``` CPP=g++ make ```\n\n## Usage\n\nThe ECE comes with a ready made set of cache admission (probabilistic,\nsecond-hit caching) and eviction (LRU, FIFO, S4LRU) policies. To run a ready\nmade example script will perform an example using Second-Hit Caching and LRU:\n\n``` ./run_em.sh \u003clog directory\u003e 2hc_lru ```\n\nWhere `\u003clog directory\u003e` is a directory containing logs of the appropriate\nformat.  Sample logs are provided in the directory `input_request_sequence`.\n\nOutput will be placed in `out/\u003ctimestamp\u003e`.\n\nA script is included that provides a simple plot of the hit rates, along with\nexamples of how to parse the output format. Please note, this script requires matplotlib and numpy - they are not required for the emulator itself. Run this script with the following command:\n\n`python analysis/parse.py out/\u003ctimestamp\u003e/`\n\n### Data\n\n* Input to the emulator is a list of individual asset request entries. Each entry is a new line, with the following columns:\n\n1. Timestamp\n2. Size\n3. Destination port (e.g. 80 or 443) - unused column\n4. Cache status code (e.g.: TCP_HIT/200, TCP_HIT/206 TCP_MISS/200, TCP_PARTIAL_HIT/200, etc.)\n5. Bytes out (bytes served from the requested file, could be smaller in case of range requests)\n6. URL (asset requested)\n\n* Output is stored in a .dat file (e.g. `out/29_Nov_17-18_54/lru_2hc.dat`).\n\nBelow is an example of the dat file entry:\n`Emulator_periodic_reporting 1503625504  32720333373821  213587  |      ghr 0.623736  0.998646   0.720994  0.999307  |  cache 0.623736 0.998646 133222 80365 32676017633906 44315739915 63820417982 42267494 0 44315739915  : 2hc_r    ot 0.252592  : lru 229997792359 0.0311111`\n\nIn the above sample output log entry, each line is an aggregate of 15 minutes of requests processed.\nEach line begins with `emulator_periodic_reporting` key word.\nThis line can then be parsed by any plotting script to generate figures. In this repo one such script is `analysis/parse.py`.\n\nBelow is the definition of each column in the output line above.\n\n1.  emulator_periodic_reporting - static keyword\n2.  1503625504 - timestamp of the output (once very 15 mins)\n3.  32720333373821 - Total traffic seen in the last timestamp (in bytes)\n4.  213587 - Total numer of URLs/files seen in last chunk\n5.  | - delimiter (below we have global stats)\n6.  ghr - global stats (hit rate and byte-hit rate)\n7.  0.623736 - total hit rate\n8.  0.998646 - total byte hit rate\n9.  0.720994 - total hit rate - perfect cache (admission on first hit, no eviction)\n10. 0.999307 - total byte hit rate - perfect cache\n11. | delimiter (below we have cache specific stats; followed by two colons (:))\n12. cache - has cache specific stats (next 10 columns, i.e. 13 through 22.)  Each new cache/storage tier we add begins with keyword 'cache'. The output here is ordered how they were tied together in the emulator. Legend for the next 10 columns can be found here: `analysis/parse.py#L79`\n23. : - delimiter (below have the cache admission specific stats)\n24. 2hc_rot - cache admission scheme name\n25. 0.252592 - bloom filter (used for keeping track of hit count) fill rate\n26. : - delimiter (below we have the cache eviction specific stats)\n27. lru - cache eviction scheme name\n28. 229997792359 - size of all content on disk\n29. 0.0311111 - oldest file age\n\n* Sample input logs can be found in directory: `input_request_sequence`\n* Sample emulator output can be found in directory: `out`\n\n\n### Adding Additional Experiments\n\n\nAdditional experiments can be written and placed in the src/ directory. The idea\nis similar to NS-3, where individual experiments can be written as stand alone\nmain() functions that instantiate an emulator object, add caches, and then\nconsume stdin.\n\nThe `run_em.sh` script can then be called with a list of binaries, i.e.\n\n`./run_sum.sh \u003clog directory\u003e lru_2hc my_experimet1 my_experiment2`\n\n### Adding Policies\n\nAdditional policies can be added to `lib/` (and headers to\n`include/`, as needed) and can inherit from the appropriate class in\n`cache_policy.cc` (i.e. admission or eviction). `cache_policy.cc` defines two\nclasses that provide the necessary framework for creating a cache policy. In particular, mimicking the definitions of the following components would be a good place to start: \n* size admission (`include/size_admission.h` and `lib/size_admission.cc`) for admission policies.\n* fifo (`include/fifo.h` and `lib/fifo.cc`) for eviction policies.\n\nNew policies that implement custom `periodic_output` functions will also need\nnew parsing functions; these can be implemented at the top of parse.py.\n\n## Contribute\n\nPlease refer to [the contributing.md file](Contributing.md) for information\nabout how to get involved. We welcome issues, questions, and pull requests. Pull\nRequests are welcome. We are particularly interested in implementations of\nadditional caching policies.\n\n## License\n\nThis project is licensed under the terms of the Apache 2.0 open source license.\nPlease refer to [LICENSE](LICENSE) for the full terms.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedgio%2Fedgio_caching_emulator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fedgio%2Fedgio_caching_emulator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedgio%2Fedgio_caching_emulator/lists"}