{"id":13821293,"url":"https://github.com/eslam-gomaa/kptop","last_synced_at":"2026-01-17T10:02:07.583Z","repository":{"id":64917312,"uuid":"577192494","full_name":"eslam-gomaa/kptop","owner":"eslam-gomaa","description":"A Python tool that offers beautiful CLI monitoring based on Prometheus metrics, with Kubernetes integration through PodPortForward","archived":false,"fork":false,"pushed_at":"2024-07-04T07:28:09.000Z","size":19632,"stargazers_count":280,"open_issues_count":4,"forks_count":11,"subscribers_count":3,"default_branch":"develop","last_synced_at":"2025-10-28T00:01:30.379Z","etag":null,"topics":["cli","containers","kubernetes","metrics","monitoring","pod","prometheus","python"],"latest_commit_sha":null,"homepage":"https://eslam-gomaa.github.io/kptop/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eslam-gomaa.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,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-12-12T07:22:43.000Z","updated_at":"2025-04-16T23:16:59.000Z","dependencies_parsed_at":"2024-05-29T12:13:32.864Z","dependency_job_id":"3c8dba04-fa37-489e-a712-35861419ba74","html_url":"https://github.com/eslam-gomaa/kptop","commit_stats":{"total_commits":105,"total_committers":4,"mean_commits":26.25,"dds":0.4476190476190476,"last_synced_commit":"130b020ef0afa63c367a528a0265ca2072ae463b"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/eslam-gomaa/kptop","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eslam-gomaa%2Fkptop","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eslam-gomaa%2Fkptop/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eslam-gomaa%2Fkptop/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eslam-gomaa%2Fkptop/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eslam-gomaa","download_url":"https://codeload.github.com/eslam-gomaa/kptop/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eslam-gomaa%2Fkptop/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28505570,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T06:57:29.758Z","status":"ssl_error","status_checked_at":"2026-01-17T06:56:03.931Z","response_time":85,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["cli","containers","kubernetes","metrics","monitoring","pod","prometheus","python"],"created_at":"2024-08-04T08:01:19.348Z","updated_at":"2026-01-17T10:02:07.553Z","avatar_url":"https://github.com/eslam-gomaa.png","language":"Python","funding_links":[],"categories":["python"],"sub_categories":[],"readme":"\u003c!-- # Kube-Prometheus-Top [ kptop ] --\u003e\n\n\u003c!-- A Python tool that provides Monitoring for Kubernetes Nodes, Pods, Containers, and PVCs resources on the terminal through Prometheus metircs --\u003e\n\n\n\u003c!-- https://user-images.githubusercontent.com/33789516/208325820-27111e21-81cb-446d-a5a4-0d73a615ea70.mp4 --\u003e\n\n\n\n# Kube-Prometheus-Top [ KPtop ]\n\n\u003cbr\u003e\n\nA Python tool that offers beautiful CLI monitoring based on Prometheus metrics, with Kubernetes integration through PodPortForward\n\nAllowing you to create your own custom CLI dashboards \u0026 CLI commands with custom layouts, variables, CLI arguments !\n\n**KPtop has been refactored to work as a general CLI monitoring tool, deprecating all hardcoded metrics \u0026 dashboards. 🚀**\n\n\n\u003cbr\u003e\n\n# Motivation\nPrometheus is widely used with different kinds of metrics - Let's make CLI monitoring more powerful with Prometheus data. ✊\n\n\u003cbr\u003e\n\n\n## [KPtop Documentation](https://eslam-gomaa.github.io/kptop) 🍉\n\n\u003cbr\u003e\n\n\n---\n\n\n## Environment Variables\n\u003ca id=env\u003e\u003c/a\u003e\n\n| ENV | Description                                                                          | Default | Required |\n| ----- | -------------------------------------------------------------------------------------- | --------- | ---------- |\n| `KPTOP_CONNECTION_METHOD`    | The way to connect to Prometheus server\u003cbr\u003e|**options:** [`prometheus_endpoint`, `pod_portForward`] | True  |\n\n\u003e There are 2 options to connect KPtop to Prometheus:\n1. With a Prometheus server endpoint\n    - Suitable if Prometheus is exposed (with an ingress for example)\n2. With 'K8s pod port-forward' (Through K8s API-Server)\n    - Suitable if Prometheus is Not exposed (Only rechable with K8s cluster access)\n\n\n### `prometheus_endpoint` ENVs\n\n| ENV | Description                                                     | Default | Required |\n| ----- | ----------------------------------------------------------------- | --------- | ---------- |\n| `KPTOP_PROMETHEUS_SERVER`    | Prometheus server URL                                           |         | Yes      |\n| `KPTOP_BASIC_AUTH_ENABLED`    | Whether basic authentication is needed to connect to Prometheus | False   | No       |\n| `KPTOP_PROMETHEUS_USERNAME`    | Prometheus username                                             |         | No       |\n| `KPTOP_PROMETHEUS_PASSWORD`    | Prometheus password                                             |         | No       |\n| `KPTOP_INSECURE`    | Verify SSL certificate                                          | False   | No       |\n\n\n\u003cbr\u003e\n\n### `pod_portForward` ENVs\n\n| ENV | Description                                            | Default | Required |\n| ----- | -------------------------------------------------------- | --------- | ---------- |\n| `KPTOP_PROMETHEUS_POD_NAME`    | Prometheus pod name                                    |         | Yes      |\n| `KPTOP_PROMETHEUS_POD_PORT`    | Prometheus port number                                 | 9090    | No       |\n| `KPTOP_PROMETHEUS_POD_NAMESPACE`    | The name space in which the Prometheus pod is deployed | default | No       |\n| `KUBECONFIG`    | custom K8s kube config file                            | *default path*        | No       |\n\n\n\u003cbr\u003e\n\n### General ENVs\n\n| ENV                                  | Description                                                  | Default               | Required |\n| ------------------------------------ | ------------------------------------------------------------ | --------------------- | -------- |\n| `KPTOP_START_GRAPHS_WITH_ZERO`       | By default graphs begin with '0'  to let the graph take its full hight | True                  | NO       |\n| `KPTOP_LOGGING_DIR`                  | Choose a different logging directory                         | /tmp/                 | NO       |\n| `KPTOP_DEFAULT_DASHBOARDS_DIRECTORY` | Default directory contains the dashboards yaml files         | /var/kptop/dashboards | NO       |\n| `KPTOP_DEFAULT_COMMANDS_DIRECTORY`   | Default directory contains the commands yaml files           | /var/kptop/commands   | NO       |\n\n\n\n\u003cbr\u003e\n\n---\n\n# CLI Arguments\n\u003ca id=cli\u003e\u003c/a\u003e\n\n\n| ENV                         | Description                                                  |\n| --------------------------- | ------------------------------------------------------------ |\n| `--dashboard` , `-D`        | Specify a dashboard YAML file                                |\n| `--command` , `-C`          | Specify a command YAML file                                  |\n| `--list-dashboards` , `-ld` | List all the available dashboards                            |\n| `--list-commands` , `-lc`   | List all the available commands                              |\n| `--debug`,  `-d`            | Enable debugging logging mode                                |\n| `--version`,  `-V`          | Show kptop version                                           |\n| `--print-layout`,  `-pl`    | Print the dashboard empty layout                             |\n| `--vhelp` ,  `-vh`          | Print the arguments including \"the variables arguments defined in your command yaml file\" |\n\n\n\u003cbr\u003e\n\n---\n\n\n# Usage\n\n\n## [1] Add the Prometheus connection Environment Variables\n\n## Example\n\n\u003cbr\u003e\n\n\n_**Example**_\n\n```bash\nexport KPTOP_CONNECTION_METHOD=\"pod_portForward\"\nexport KPTOP_PROMETHEUS_POD_NAME=\"my-prometheus-server-0\"\nexport KPTOP_PROMETHEUS_POD_PORT=\"9090\"\nexport KPTOP_PROMETHEUS_POD_NAMESPACE=\"monitoring\"\n```\n\n| Or\n\n```bash\nexport KPTOP_CONNECTION_METHOD=\"prometheus_endpoint\"\nexport KPTOP_PROMETHEUS_SERVER=\"http://prometheus.home-lab.com\"\n```\n\n\n\u003cbr\u003e\n\n## [2] Configure the location of your dashboards \u0026 commands\n\n\nExample:\n\n```bash\nexport KPTOP_DEFAULT_DASHBOARDS_DIRECTORY=\"/Users/YOU/kptop/examples/dashboards\"\nexport KPTOP_DEFAULT_COMMANDS_DIRECTORY=\"/Users/YOU/kptop/examples/dashboards\"\n```\n\n\n\n## Run dashboards / commands !\n\n### [Dashboards Doc](https://eslam-gomaa.github.io/kptop/dashboards)\n### [Commands Doc](https://eslam-gomaa.github.io/kptop/commands)\n\n\n```bash\nkptop --list-dashboards\n```\n\n```\nDASHBOARD      CREATION TIME        UPDATE TIME\npods           29-06-2024 19:43:19  29-06-2024 19:43:19\ntest           29-06-2024 19:27:04  29-06-2024 19:27:04\npvcs           29-06-2024 12:33:02  29-06-2024 12:33:02\nstrimzi-kafka  29-06-2024 12:33:02  29-06-2024 12:33:02\n```\n\n[**Example dashboard \u003e pods.yml**](https://github.com/eslam-gomaa/kptop/blob/v0.0.11/examples/dashboards/pods.yml)\n\n\n```bash\nkptop --dashboard pods\n```\n\n![alt text](./docs/images/dashboard-pods.png)\n\n\u003cbr\u003e\n\n[**Example dashboard \u003e pvcs.yml**](https://github.com/eslam-gomaa/kptop/blob/v0.0.11/examples/dashboards/pvcs.yml)\n\n```bash\nkptop --dashboard pvcs\n```\n\n![alt text](./docs/images/dashboard-pvcs.png)\n\n\n\u003cbr\u003e\n\n[**Example dashboard \u003e strimzi-kafka-test.yml**](https://github.com/eslam-gomaa/kptop/blob/v0.0.11/examples/dashboards/strimzi-kafka-test.yml)\n\n```bash\nkptop --dashboard strimzi-kafka-test -n kafka\n```\n\n\n![alt text](./docs/images/dashboard-strimzi-kafka-test.png)\n\n\n---\n\n\n```bash\nkptop --list-commands\n```\n\n```\nCOMMAND    CREATION TIME        UPDATE TIME\npods       29-06-2024 12:33:02  29-06-2024 12:33:02\npvcs       29-06-2024 12:33:02  29-06-2024 12:33:02\npods-wide  29-06-2024 12:33:02  29-06-2024 12:33:02\n```\n\n\n[**Example command \u003e pods-wide.yml**](https://github.com/eslam-gomaa/kptop/blob/v0.0.11/examples/commands/pods-wide.yml)\n\n```bash\nkptop --command pods-wide -n kafka\n```\n\n```\nNAME                                               MEMORY REQUESTS    MEMORY LIMITS    CPU REQUESTS    CPU LIMITS    NODE                                       ARCH    INSTANCE TYPE    AWS AZ      CAPACITY TYPE\nkafka-test-entity-operator-798859b74d-5jh58        1.0 gb             2.0 gb           0.4             2.0           ip-0-0-16-205.eu-west-1.compute.internal   amd64   m5.xlarge        eu-west-1a  on-demand\nkafka-test-cp-schema-registry-546f5f8b5d-2j48f     6.0 gb             8.0 gb           0.5             1.0           ip-0-0-16-205.eu-west-1.compute.internal   amd64   m5.xlarge        eu-west-1a  on-demand\nkafka-test-cruise-control-5c4cf6749-ss7l2          512.0 mb           2.0 gb           1.0             2.0           ip-0-0-16-205.eu-west-1.compute.internal   amd64   m5.xlarge        eu-west-1a  on-demand\nkafka-test-strimzi-canary-8686978cb7-dbrf4         64.0 mb            64.0 mb          0.1             0.1           ip-0-0-16-205.eu-west-1.compute.internal   amd64   m5.xlarge        eu-west-1a  on-demand\nkafka-test-brokers-az-c-300                        5.0 gb             8.0 gb           1.0             2.0           ip-0-0-184-231.eu-west-1.compute.internal  arm64   m7g.large        eu-west-1c  on-demand\nkafka-test-brokers-az-a-100                        5.0 gb             8.0 gb           1.0             2.0           ip-0-0-60-93.eu-west-1.compute.internal    arm64   m7g.large        eu-west-1a  on-demand\nkafka-test-cp-schema-registry-546f5f8b5d-486b9     6.0 gb             8.0 gb           0.5             1.0           ip-0-0-30-147.eu-west-1.compute.internal   amd64   m5.xlarge        eu-west-1a  on-demand\nkafka-test-testing-kafka-k8s-exporter-6fb7c6dqknnl 512.0 mb           1.0 gb           0.1             0.3           ip-0-0-16-205.eu-west-1.compute.internal   amd64   m5.xlarge        eu-west-1a  on-demand\nkafka-test-kafka-exporter-c58966cd6-r2tsj          256.0 mb           512.0 mb         0.1             0.5           ip-0-0-16-205.eu-west-1.compute.internal   amd64   m5.xlarge        eu-west-1a  on-demand\nkafka-test-kafdrop-67ff5d5b4-77khq                 256.0 mb           1.0 gb           0.2             0.5           ip-0-0-16-205.eu-west-1.compute.internal   amd64   m5.xlarge        eu-west-1a  on-demand\nkafka-test-brokers-az-b-200                        5.0 gb             8.0 gb           1.0             2.0           ip-0-0-100-105.eu-west-1.compute.internal  arm64   m7g.large        eu-west-1b  on-demand\nkafka-test-kafka-ui-55fcf964d7-n5j7r               256.0 mb           1.0 gb           0.2             0.5           ip-0-0-16-205.eu-west-1.compute.internal   amd64   m5.xlarge        eu-west-1a  on-demand\nkafka-test-zookeeper-0                             2.0 gb             4.0 gb           1.0             2.0           ip-0-0-30-147.eu-west-1.compute.internal   amd64   m5.xlarge        eu-west-1a  on-demand\nkafka-test-zookeeper-2                             2.0 gb             4.0 gb           1.0             2.0           ip-0-0-155-163.eu-west-1.compute.internal  amd64   m5.xlarge        eu-west-1c  on-demand\nkafka-test-cp-schema-registry-546f5f8b5d-pwlzk     6.0 gb             8.0 gb           0.5             1.0           ip-0-0-155-163.eu-west-1.compute.internal  amd64   m5.xlarge        eu-west-1c  on-demand\nburrow-release-kafka-burrow-79c657bfff-q4lx7       128.0 mb           256.0 mb         0.1             0.1           ip-0-0-30-147.eu-west-1.compute.internal   amd64   m5.xlarge        eu-west-1a  on-demand\nkafka-test-zookeeper-1                             2.0 gb             4.0 gb           1.0             2.0           ip-0-0-71-148.eu-west-1.compute.internal   amd64   c5.large         eu-west-1b  on-demand\nkafka-test-cruise-control-ui-569ccc5897-8jqdq      ?                  ?                ?               ?             ip-0-0-33-177.eu-west-1.compute.internal   amd64   c5.large         eu-west-1a  on-demand\nkafka-test-cruise-control-ui-569ccc5897-zl987      ?                  ?                ?               ?             ip-0-0-33-177.eu-west-1.compute.internal   amd64   c5.large         eu-west-1a  on-demand\n```\n\n\u003cbr\u003e\n\n---\n\n# Logging\n\nDefault log file location is \"`/tmp/kptop.log`\"\n\n\n\u003cbr\u003e\n\n\nReach me anytime on [Linkedin](https://www.linkedin.com/in/eslam-gomaa/)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feslam-gomaa%2Fkptop","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feslam-gomaa%2Fkptop","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feslam-gomaa%2Fkptop/lists"}