{"id":17423012,"url":"https://github.com/netobserv/network-observability-cli","last_synced_at":"2025-04-16T00:07:08.368Z","repository":{"id":227097720,"uuid":"719985264","full_name":"netobserv/network-observability-cli","owner":"netobserv","description":"An OpenShift / Kubernetes CLI tool for network observability","archived":false,"fork":false,"pushed_at":"2025-04-14T15:22:58.000Z","size":22604,"stargazers_count":18,"open_issues_count":34,"forks_count":12,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-04-16T00:06:38.618Z","etag":null,"topics":["cli","kubernetes","observability","openshift"],"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/netobserv.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":"2023-11-17T10:27:36.000Z","updated_at":"2025-04-08T15:41:47.000Z","dependencies_parsed_at":"2024-04-23T15:52:53.518Z","dependency_job_id":"fdd54b61-687e-4887-b1eb-bed775d3189f","html_url":"https://github.com/netobserv/network-observability-cli","commit_stats":null,"previous_names":["netobserv/network-observability-cli"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netobserv%2Fnetwork-observability-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netobserv%2Fnetwork-observability-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netobserv%2Fnetwork-observability-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netobserv%2Fnetwork-observability-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/netobserv","download_url":"https://codeload.github.com/netobserv/network-observability-cli/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249173084,"owners_count":21224483,"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":["cli","kubernetes","observability","openshift"],"created_at":"2024-10-17T04:04:15.715Z","updated_at":"2025-04-16T00:07:08.361Z","avatar_url":"https://github.com/netobserv.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Network Observability CLI\n\nnetwork-observability-cli is a lightweight Flow, Packet and Metrics visualization tool.\nIt deploys [NetObserv eBPF agent](https://github.com/netobserv/netobserv-ebpf-agent) on your k8s cluster to collect flows or packets from nodes network interfaces\nand streams data to a local collector for analysis and visualization.\nOutput files are generated under `output/flow` and `output/pcap` directories per host name.\n\nOn Openshift environments, you can also capture metrics in your monitoring stack and display a fully configured dashboard.\n\n## Prerequisites\n\nTo run this CLI, you will need:\n- A running kubernetes / OpenShift cluster\n- either `oc` or `kubectl` command installed and connected to your cluster\n- Cluster admin rights\n\n## Getting started with Krew\n\nThe CLI is available as a [Krew](https://krew.sigs.k8s.io/) plugin, which is the fastest way to get it up and running if you already use Krew.\nIf not, please refer to its [installation guide](https://krew.sigs.k8s.io/docs/user-guide/setup/install/).\n\nTo install the NetObserv CLI, run:\n\n```bash\nkubectl krew install netobserv\n```\n\nOr if you had an older version, to update it:\n\n```bash\nkubectl krew update netobserv\n```\n\nThen, run it as a `kubectl` plugin, such as:\n\n```bash\nkubectl netobserv --version\n# output example: \n# Netobserv CLI version v0.0.8\n```\n\nYou can get detailed help using these commands:\n\n```bash\nkubectl netobserv --help\nkubectl netobserv flows --help\nkubectl netobserv packets --help\nkubectl netobserv metrics --help\n```\n\n## Run\n\n### Flow Capture\n\nFor instance, to capture all flows on the cluster that go through the `br-ex` network interface:\n\n- As a `kubectl` plugin:\n\n  ```bash\n  kubectl netobserv flows --interfaces=br-ex\n  ```\n\n- Or from the repository `Makefile`:\n\n  Run the following command to start capturing flows, replacing `USER`, `VERSION` and `COMMAND_ARGS` accordingly:\n\n  ```bash\n  USER=netobserv VERSION=dev COMMAND_ARGS=--interfaces=br-ex make flows\n  ```\n\n![flows](./img/flow-table.png)\n\nIt will display a table view with latest flows collected and write data under output/flow directory.\nTo stop capturing press Ctrl-C.\n\nThis will write data into two separate files:\n- `./output/flow/\u003cCAPTURE_DATE_TIME\u003e.json` containing json array of received data such as:\n```json\n{\n  \"AgentIP\": \"10.0.1.76\",\n  \"Bytes\": 561,\n  \"DnsErrno\": 0,\n  \"Dscp\": 20,\n  \"DstAddr\": \"f904:ece9:ba63:6ac7:8018:1e5:7130:0\",\n  \"DstMac\": \"0A:58:0A:80:00:37\",\n  \"DstPort\": 9999,\n  \"Duplicate\": false,\n  \"Etype\": 2048,\n  \"Flags\": 16,\n  \"FlowDirection\": 0,\n  \"IfDirection\": 0,\n  \"Interface\": \"ens5\",\n  \"K8S_FlowLayer\": \"infra\",\n  \"Packets\": 1,\n  \"Proto\": 6,\n  \"SrcAddr\": \"3e06:6c10:6440:2:a80:37:b756:270f\",\n  \"SrcMac\": \"0A:58:0A:80:00:01\",\n  \"SrcPort\": 46934,\n  \"TimeFlowEndMs\": 1709741962111,\n  \"TimeFlowRttNs\": 121000,\n  \"TimeFlowStartMs\": 1709741962111,\n  \"TimeReceived\": 1709741964\n}\n```\n- `./output/flow/\u003cCAPTURE_DATE_TIME\u003e.db` database that can be inspected using `sqlite3` for example: \n```bash\nbash-5.1$ sqlite3 ./output/flow/\u003cCAPTURE_DATE_TIME\u003e.db \nSQLite version 3.34.1 2021-01-20 14:10:07\nEnter \".help\" for usage hints.\nsqlite\u003e SELECT DnsLatencyMs, DnsFlagsResponseCode, DnsId, DstAddr, DstPort, Interface, Proto, SrcAddr, SrcPort, Bytes, Packets FROM flow WHERE DnsLatencyMs \u003e10 LIMIT 10;\n12|NoError|58747|10.128.0.63|57856||17|172.30.0.10|53|284|1\n11|NoError|20486|10.128.0.52|56575||17|169.254.169.254|53|225|1\n11|NoError|59544|10.128.0.103|51089||17|172.30.0.10|53|307|1\n13|NoError|32519|10.128.0.52|55241||17|169.254.169.254|53|254|1\n12|NoError|32519|10.0.0.3|55241||17|169.254.169.254|53|254|1\n15|NoError|57673|10.128.0.19|59051||17|172.30.0.10|53|313|1\n13|NoError|35652|10.0.0.3|46532||17|169.254.169.254|53|183|1\n32|NoError|37326|10.0.0.3|52718||17|169.254.169.254|53|169|1\n14|NoError|14530|10.0.0.3|58203||17|169.254.169.254|53|246|1\n15|NoError|40548|10.0.0.3|45933||17|169.254.169.254|53|174|1\n```\nor `dbeaver`:\n![dbeaver](./img/dbeaver.png)\n\n\n### Packet Capture\n\nFor instance, to capture all TCP packets on the cluster that go through port 80:\n\n- As a `kubectl` plugin:\n\n  ```bash\n  kubectl netobserv packets --protocol=TCP --port=80\n  ```\n\n- Or from the repository `Makefile`:\n\n  Run the following command to start capturing packets, replacing `USER`, `VERSION` and `COMMAND_ARGS` accordingly:\n\n  ```bash\n  USER=netobserv VERSION=dev COMMAND_ARGS=\"--protocol=TCP --port=80\" make packets\n  ```\n\nSimilarly to flow capture, it will display a table view with latest flows. However, it will collect packets and write data under output/pcap directory.\nTo stop capturing press Ctrl-C.\n\nThis will write [pcapng](https://wiki.wireshark.org/Development/PcapNg) into a single file located in `./output/pcap/\u003cCAPTURE_DATE_TIME\u003e.pcapng` that can be opened with Wireshark for example:\n\n![wireshark](./img/wireshark.png)\n\nWe use the pcapng format to add contextual metadata, such as the k8s pods and service names.\n\n### Metrics dashboard (OpenShift only)\n\nFor instance, to capture many available metrics, including Packet drops, DNS stats and latenties:\n\n- As a `kubectl` plugin:\n\n  ```bash\n  kubectl netobserv metrics --enable_pkt_drop --enable_dns --enable_rtt\n  ```\n\n- Or from the repository `Makefile`:\n\n  Run the following command to start capturing metrics, replacing `USER`, `VERSION` and `COMMAND_ARGS` accordingly:\n\n  ```bash\n  USER=netobserv VERSION=dev COMMAND_ARGS='--enable_pkt_drop --enable_dns --enable_rtt' make metrics\n  ```\n\n![metrics](./img/metrics-dashboard.png)\n\nIt will generate a monitoring dashboard called \"NetObserv / On Demand\" in your Openshift cluster.\nThe url to access it is automatically generated from the CLI. Simply click on the link to open the page.\n\n### Cleanup\n\nThe `cleanup` function will automatically remove the eBPF programs when the CLI exits. However you may need to run it manually if running in background or an error occurs.\n\n- As a `kubectl` plugin:\n\n  ```bash\n  kubectl netobserv cleanup\n  ```\n\n- Or from the repository `Makefile`:\n\n  ```bash\n  USER=netobserv VERSION=dev make cleanup\n  ```\n\n## Build\n\nTo build the project locally:\n\n### Install `shellcheck` package\n\n```bash\nsudo dnf install -y shellcheck\n```\n\n### Build the project\n\n```bash\nmake build\n```\n\nThis will also copy resources and commands to the `build` directory.\n\n### Images\n\nTo build your own images of CLI, run the following command replacing `USER` and `VERSION` accordingly:\n```bash\nUSER=netobserv VERSION=dev make images\n```\n\n## Extending OpenShift or Kubernetes CLI with plugins\n\nYou can add this plugin to your favorite `oc` or `kubectl` commands using the following steps:\n\n```bash\nK8S_CLI_BIN=oc make install-commands\n```\nOR \n```bash\nK8S_CLI_BIN=kubectl make install-commands\n```\n\nThis will add `netobserv` commands to your CLI.\nYou can verify the commands are available using:\n\n```bash\noc plugin list\n```\nOR\n```bash\nkubectl plugin list\n```\n\nIt will display as result:\n\n```bash\nThe following compatible plugins are available:\n...\n/usr/bin/\u003coc|kubectl\u003e-netobserv\n```\n\nMore info [on official OpenShift documentation](https://docs.openshift.com/container-platform/4.14/cli_reference/openshift_cli/extending-cli-plugins.html).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetobserv%2Fnetwork-observability-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnetobserv%2Fnetwork-observability-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetobserv%2Fnetwork-observability-cli/lists"}