{"id":16701566,"url":"https://github.com/vitorenesduarte/tricks","last_synced_at":"2025-03-23T14:31:49.451Z","repository":{"id":27961429,"uuid":"115716151","full_name":"vitorenesduarte/tricks","owner":"vitorenesduarte","description":"Run experiments effortlessly on top of Kubernetes","archived":false,"fork":false,"pushed_at":"2022-05-20T20:52:07.000Z","size":2287,"stargazers_count":23,"open_issues_count":3,"forks_count":2,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-18T21:50:49.132Z","etag":null,"topics":["experiments","kubernetes","kubernetes-deployment","tricks"],"latest_commit_sha":null,"homepage":"","language":"Erlang","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/vitorenesduarte.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-12-29T11:15:41.000Z","updated_at":"2023-09-08T17:34:30.000Z","dependencies_parsed_at":"2022-08-31T16:44:32.801Z","dependency_job_id":null,"html_url":"https://github.com/vitorenesduarte/tricks","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/vitorenesduarte%2Ftricks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vitorenesduarte%2Ftricks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vitorenesduarte%2Ftricks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vitorenesduarte%2Ftricks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vitorenesduarte","download_url":"https://codeload.github.com/vitorenesduarte/tricks/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245116013,"owners_count":20563265,"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":["experiments","kubernetes","kubernetes-deployment","tricks"],"created_at":"2024-10-12T18:44:33.823Z","updated_at":"2025-03-23T14:31:48.828Z","avatar_url":"https://github.com/vitorenesduarte.png","language":"Erlang","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://img.shields.io/travis/vitorenesduarte/tricks/master.svg)](https://travis-ci.org/vitorenesduarte/tricks)\n[![Coverage Status](https://img.shields.io/coveralls/github/vitorenesduarte/tricks/master.svg?maxAge=60)](https://coveralls.io/github/vitorenesduarte/tricks?branch=master)\n\n\n\n# Tricks \n\n__Running an experiment should be as easy as describing it in an YAML file.__\n\n----------\n\n### Tricks presentation\n\n[Here](https://docs.google.com/presentation/d/1uP6eM9eA7_g_B6Ap_1SLPsBOAPypLmLIX-TPf7GbOX4/edit#slide=id.gc6f980f91_0_0)'s a presentation about Tricks.\n\n### About Tricks \n\nA Tricks entry (TE) is a set of replicas/pods.\nAn experiment is one or more TE's.\n\n#### Features\n- [x] Register occurrence of events. Each event has a counter associated.\n- [x] Implicit events (`start` and `stop` of each pod in a TE)\n- [x] Subscribe to events\n  - can be used to implement synchronization barrier\n    (e.g. make sure all clients start at the same time)\n- [x] Workflow (e.g. only start a given TE once event X counter is Y)\n- [ ] Sequences of experiments\n- [x] Pod discovery\n- [ ] Log aggregation\n- [ ] Plotting from logs (e.g. latency/throughput, CDF, bar, line)\n- [ ] Detect coordination omission from logs\n- [ ] Fault injection\n  - (when) could be defined in the same way workflow is\n  - (what) maybe provide some sort of pod selector for process faults,\n    and link selector for network faults\n- [ ] Federation support (run across multiple Kubernetes clusters)\n- [ ] Spot/preemptible instances support (if an instance is killed, the experiment is restarted)\n\n### Example\n\nIn this example, event `client1_stop` and `client2_stop`\nare implicit events,\nwhile `server-ready` is an event registered by replicas\nin the `server` TE.\n\n```yaml\napiVersion: v1\nexperiment:\n- tag: server\n  image: vitorenesduarte/tricks-example\n  replicas: 3\n  env:\n  - name: TYPE\n    value: loop\n  workflow:\n    stop:\n      name: client2_stop\n      value: 6\n- tag: client1\n  image: vitorenesduarte/tricks-example\n  replicas: 3\n  env:\n  - name: TYPE\n    value: loop\n  - name: SECONDS \n    value: 5\n  workflow:\n    start:\n      name: server-ready\n      value: 3\n- tag: client2\n  image: vitorenesduarte/tricks-example\n  replicas: 6\n  env:\n  - name: TYPE\n    value: loop\n  - name: SECONDS\n    value: 10\n  workflow:\n    start:\n      name: client1_stop\n      value: 3\n```\n\n\n#### Other examples\n\n- [examples/hello-world.yaml](examples/hello-world.yaml)\n- [examples/implicit-events.yaml](examples/implicit-events.yaml)\n- [examples/explicit-events.yaml](examples/explicit-events.yaml)\n\n### Running Tricks\n\nAssuming there's a Kubernetes cluster running:\n\n```bash\n$ tricks start\n$ tricks logs\n```\n\nAnd then in another terminal, run one of the examples:\n```bash\n$ tricks exp examples/explicit-events.yaml\n```\n\n### Environment variables\n\nConfiguration of pods is achieved through environment variables.\nSome variable names are reserved and always defined in every pod:\n- [x] `TAG`: from configuration file\n- [x] `REPLICAS`: from configuration file\n- [x] `EXP_ID`: an experiment identifier generated by Tricks\n- [x] `POD_ID`: unique (no other pod with the same `TAG` and `EXP_ID`\nhas the same id)\n- [x] `POD_IP`: pod IP from Kubernetes\n- [x] `TRICKS_IP`: pod IP of Tricks\n- [x] `TRICKS_PORT`: port of Tricks\n\n### Drivers API\n\nReplicas in experiments can be written in any language,\nas long as there's a driver available.\nDrivers open a socket (`TRICKS_IP` and `TRICKS_PORT`)\nand talk with Tricks using the following API\n(__[DT]__ is used if it's a message from a Driver to Tricks,\nor with __[TD]__ otherwise).\n\n- [x] Register events __[DT]__\n```json\n{\n  \"expId\": \"123456\",\n  \"type\": \"event\",\n  \"eventName\": \"connected\",\n}\n```\n\n- [x] Subscription of events __[DT]__\n```json\n{\n  \"expId\": \"123456\",\n  \"type\": \"subscription\",\n  \"eventName\": \"connected\",\n  \"value\": 10\n}\n```\n\n- [x] Notification of events __[TD]__\n```json\n{\n  \"expId\": \"123456\",\n  \"type\": \"notification\",\n  \"eventName\": \"connected\",\n  \"value\": 10\n}\n```\n\n- [x] Pod discovery __[DT]__\n```json\n{\n  \"expId\": \"123456\",\n  \"type\": \"discovery\",\n  \"tag\": \"server\",\n  \"min\": 2\n}\n```\n\nThe argument `min` in the previous\nmessage is optional\n(default value is 0).\nTricks will only reply when\nit has at least `min` pods\n(sending all, even if more than `min`).\n\n- [x] Pod discovery __[TD]__\n```json\n{\n  \"expId\": \"123456\",\n  \"type\": \"pods\",\n  \"tag\": \"server\",\n  \"pods\": [\n    {\n      \"id\": 1,\n      \"ip\": \"10.12.13.15\"\n    },\n    {\n      \"id\": 2,\n      \"ip\": \"10.12.13.16\"\n    },\n    {\n      \"id\": 3,\n      \"ip\": \"10.12.13.17\"\n    }\n  ]\n}\n```\n\n### Sequences of experiments\n\nTypically we want, not to run a single experiment,\nbut several, and in the end compare metrics\ncollected.\n\nIn order to support sequences of experiments,\nconfiguration values in the YAML file\ncan be replaced by variables\n(e.g. `$var`),\nthat are defined in a list of\nconfigurations.\nEach configuration will be used\nto create an experiment.\n\nAn example\nwith two variables (`$op_number` and `$client_number`)\nthat \nare used to define number of replicas,\nworkflow configuration and\nenvironment variables:\n\n```bash\napiVersion: v1\nconfig:\n  - $op_number: 100\n    $client_number: 3\n  - $op_number: 200\n    $client_number: 3\n  - $op_number: 100\n    $client_number: 6\n  - $op_number: 200\n    $client_number: 6\nexperiment:\n  - tag: server\n    image: vitorenesduarte/tricks-example\n    replicas: 3\n    env:\n    - name: TYPE\n      value: server\n    workflow:\n      stop:\n        name: client_stop\n        value: $client_number\n  - tag: client\n    image: vitorenesduarte/tricks-example\n    replicas: $client_number\n    env:\n    - name: TYPE\n      value: client\n    - name: OP_NUMBER\n      value: $op_number\n    workflow:\n      start:\n        name: server_start\n        value: 3\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvitorenesduarte%2Ftricks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvitorenesduarte%2Ftricks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvitorenesduarte%2Ftricks/lists"}