{"id":13676444,"url":"https://github.com/ricardomaraschini/oomhero","last_synced_at":"2025-08-03T03:42:08.240Z","repository":{"id":57845983,"uuid":"213355231","full_name":"ricardomaraschini/oomhero","owner":"ricardomaraschini","description":"Kubernetes sidecar for memory usage tracking","archived":false,"fork":false,"pushed_at":"2023-04-28T08:28:01.000Z","size":58,"stargazers_count":110,"open_issues_count":3,"forks_count":10,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-07-14T03:01:35.294Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","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/ricardomaraschini.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,"governance":null,"roadmap":null,"authors":null}},"created_at":"2019-10-07T10:32:58.000Z","updated_at":"2025-03-11T09:41:54.000Z","dependencies_parsed_at":"2024-01-14T14:31:14.750Z","dependency_job_id":"452c66e2-9df9-4fe3-b850-a145c913e3e4","html_url":"https://github.com/ricardomaraschini/oomhero","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ricardomaraschini/oomhero","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ricardomaraschini%2Foomhero","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ricardomaraschini%2Foomhero/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ricardomaraschini%2Foomhero/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ricardomaraschini%2Foomhero/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ricardomaraschini","download_url":"https://codeload.github.com/ricardomaraschini/oomhero/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ricardomaraschini%2Foomhero/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268491737,"owners_count":24258735,"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","status":"online","status_checked_at":"2025-08-03T02:00:12.545Z","response_time":2577,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":"2024-08-02T13:00:27.176Z","updated_at":"2025-08-03T03:42:08.171Z","avatar_url":"https://github.com/ricardomaraschini.png","language":"Go","funding_links":[],"categories":["Go","Rust","OPS"],"sub_categories":[],"readme":"# OOMHero\n\nOOMHero is a sidecar that helps you to keep track of your containers memory\nusage. By implementing it two signals are going to be send to your container\nas the memory usage grows: a _warning_ and a _critical_ signals. By leveraging\nthese signals you might be able to defeat the deadly `OOMKiller`.\n\n### How it works\n\nThis sidecar will send your container two signals: when memory usage crosses\nso called _warning_(**SIGUSR1** by default) and _critical_(**SIGUSR2** by default) thresholds. \nIt is possible to use different signals by specifying appropriate environment variables.\nYour application must be able to deal with these signals by implementing\nsignal handlers.\n\nYou an see [here](https://github.com/ricardomaraschini/oomhero/blob/master/cmd/bloat/main.go)\nan example of how to capture the signals in Go.\n\n### On limits\n\nIf only `requests` are specified during the pod Deployment no signal will be\nsent, this sidecar operates only on `limits`.\n\n### Deployment example\n\nThe Pod below is composed by two distinct containers, the first one is called\n`bloat` and its purpose is(as the name implies) to simulate a memory leak by\nconstantly allocating in a global variable. The sidecar is an `OOMHero` \nconfigured to send a `SIGUSR1`(warning) when `bloat` reaches 65% and a `SIGUSR2`\n(critical) on 90%. The only pre-requisite is that both containers share the same\nprocess namespace, hence `shareProcessNamespace` is set to `true`.\n\n\n```yaml\napiVersion: v1\nkind: Pod\nmetadata:\n  name: oomhero\nspec:\n  shareProcessNamespace: true\n  containers:\n    - name: bloat\n      image: quay.io/rmarasch/bloat:latest\n      imagePullPolicy: Always\n      livenessProbe:\n        periodSeconds: 3\n        failureThreshold: 1\n        httpGet:\n          path: /healthz\n          port: 8080\n      resources:\n        requests:\n          memory: \"256Mi\"\n          cpu: \"250m\"\n        limits:\n          memory: \"256Mi\"\n          cpu: \"250m\"\n    - name: oomhero\n      image: quay.io/rmarasch/oomhero:latest\n      imagePullPolicy: Always\n      securityContext:\n        privileged: true\n      env:\n      - name: WARNING\n        value: \"65\"\n      - name: CRITICAL\n        value: \"90\" \n```\n\nSaving the above yaml into a file you just need to deploy it:\n\n```bash\n$ kubectl create -f ./pod.yaml\n```\n\nThat will create a Pod with two containers, you may follow the memory consumption\nand signals being sent by inspecting all pod logs.\n\n```bash\n$ # for bloat container log\n$ kubectl logs -f oomhero --container bloat\n$ # for oomhero container log\n$ kubectl logs -f oomhero --container oomhero \n```\n\n### Configuring signals\nSignals supported by `OOMHero` are:\n- SIGABRT\n- SIGCONT\n- SIGHUP\n- SIGINT\n- SIGIOT\n- SIGKILL\n- SIGQUIT\n- SIGSTOP\n- SIGTERM\n- SIGTSTP\n- SIGUSR1\n- SIGUSR2\n\nTo use any of those signals instead of default ones, set `WARNING_SIGNAL` and `CRITICAL_SIGNAL`\nenvironment variable to specify _warning_ and _critical_ signals respectively.\nIf those environment variables are not set, `OOMHero` will use default values (SIGUSR1 and SIGUSR2).\n\nFor instance to send `SIGTERM` when critical threshold is reached put following in pod or deployment definition:\n\n```yaml\ncontainers:\n  # other containers omitted for brevity\n  - name: oomhero\n    image: quay.io/rmarasch/oomhero\n    imagePullPolicy: Always\n    env:\n    - name: WARNING\n      value: \"65\"\n    - name: CRITICAL\n      value: \"90\"\n    - name: CRITICAL_SIGNAL\n      value: \"SIGTERM\"\n```\n\n### Cooldown\n\nBy default `OOMHero` sends one signal per second to other processes once they reach warning or critical threshold.\nThis might be undesireable behavior in some circumstances, therefore cooldown can be configured.\nOnce set, signal will be sent no more often than once in `cooldown` for each signal type separately.\nIn other words other processes would not receive more than one warning and one ciritcal signal more often than once in `cooldown`.\n\nTo configure cooldown set `COOLDOWN` environment variable in deployment definition to a value conforming to [time.ParseDuartion](https://pkg.go.dev/time#ParseDuration):\n```yaml\ncontainers:\n  # other containers omitted for brevity\n  - name: oomhero\n    image: quay.io/rmarasch/oomhero\n    imagePullPolicy: Always\n    env:\n    - name: COOLDOWN\n      value: \"1m30s\"\n```\n\n### Help needed\n\n[Official documentation](https://kubernetes.io/docs/tasks/configure-pod-container/share-process-namespace/)\nstates that `SYS_PTRACE` capability is mandatory when signaling between containers\non the same Pod. I could not validate if this is true as it works without it on my\nK8S cluster. If to make it work you had to add this capability please let me know.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fricardomaraschini%2Foomhero","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fricardomaraschini%2Foomhero","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fricardomaraschini%2Foomhero/lists"}