Skip to content

NETOBSERV-2646: help page, write examples on subcommands #473

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jotak wants to merge 1 commit into
base: main
Choose a base branch
from
Open

NETOBSERV-2646: help page, write examples on subcommands #473

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ Then, run it as a `kubectl` plugin, such as:
```bash
kubectl netobserv --version
# output example:
# Netobserv CLI version v0.0.8
# NetObserv CLI version v0.0.8
```

You can get detailed help using these commands:
Expand Down
4 changes: 2 additions & 2 deletions e2e/script_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ func TestHelpCommand(t *testing.T) {

assert.NotEmpty(t, output)
// ensure help display overall description
assert.Contains(t, output, "Netobserv allows you to capture flows, packets and metrics from your cluster.")
assert.Contains(t, output, "NetObserv allows you to capture flows, packets and metrics from your cluster.")
assert.Contains(t, output, "Find more information at: https://github.com/netobserv/network-observability-cli/")
// ensure help to display main commands
assert.Contains(t, output, "main commands:")
Expand Down Expand Up @@ -65,6 +65,6 @@ func TestVersionCommand(t *testing.T) {

assert.NotEmpty(t, output)
// ensure version display test
assert.Contains(t, output, "Netobserv CLI version test")
assert.Contains(t, output, "NetObserv CLI version test")
})
}
126 changes: 69 additions & 57 deletions scripts/help.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,67 +6,69 @@ includeList="namespace_flows_total,node_ingress_bytes_total,node_egress_bytes_to
# display main help
function help {
echo
echo "Netobserv allows you to capture flows, packets and metrics from your cluster."
echo "NetObserv allows you to capture flows, packets and metrics from your cluster."
echo "Find more information at: https://github.com/netobserv/network-observability-cli/"
echo
echo "Syntax: netobserv [flows|packets|metrics|follow|stop|copy|cleanup|version] [options]"
echo
echo "main commands:"
echo "Main commands:"
echo " flows Capture flows information in JSON format using collector pod."
echo " metrics Capture metrics information in Prometheus using a ServiceMonitor (OCP cluster only)."
echo " packets Capture packets information in pcap format using collector pod."
echo
echo "extra commands:"
echo "Extra commands:"
echo " cleanup Remove netobserv components and configurations."
echo " copy Copy collector generated files locally."
echo " follow Follow collector logs when running in background."
echo " stop Stop collection by removing agent daemonset."
echo " version Print software version."
echo
echo "basic examples:"
echo " netobserv flows --drops # Capture dropped flows on all nodes"
echo " netobserv flows --query='SrcK8S_Namespace=~\"app-.*\"' # Capture flows from any namespace starting by app-"
echo " netobserv packets --port=8080 # Capture packets on port 8080"
echo " netobserv metrics --enable_all # Capture default cluster metrics including packet drop, dns, rtt, network events packet translation and UDN mapping features informations"
echo
echo "advanced examples:"
echo " Capture flows in background and copy output locally"
echo " netobserv flows --background \ # Capture flows using background mode"
echo " --max-time=15m \ # for a maximum of 15 minutes"
echo " --protocol=TCP --port=8080 \ # either on TCP 8080"
echo " or --protocol=UDP # or UDP"
echo " netobserv follow # Display the progression of the background capture"
echo " netobserv stop # Stop the background capture by deleting eBPF agents"
echo " netobserv copy # Copy the background capture output data"
echo " netobserv cleanup # Cleanup netobserv CLI by removing the remaining collector pod"
echo
echo " Capture flows from a specific pod"
echo " netobserv flows # Capture flows"
echo " --node-selector=kubernetes.io/hostname:my-node # on node matching label 'kubernetes.io/hostname=my-node'"
echo " --query='SrcK8S_Name=~\".*my-pod.*\" # from any pod name containing 'my-pod'"
echo " or DstK8S_Name=~\".*my-pod.*\"' # or to any pod name containing 'my-pod'"
echo
echo " Capture packets on specific nodes and port"
echo " netobserv packets # Capture packets"
echo " --node-selector=netobserv:true \ # on nodes labelled with 'netobserv=true'"
echo " --port=80 \ # on port 80 only"
echo " --max-bytes=100000000 # for a maximum of 100MB"
echo
echo " Capture node and namespace drop metrics"
echo " netobserv metrics \ # Capture metrics"
echo " --drops # including drops"
echo " --include_list=node,namespace # for all metrics matching 'node' or 'namespace' keywords"
echo
echo " Capture metrics in background"
echo " netobserv metrics --background \ # Capture metrics using background mode"
echo " --max-time=24h # for a maximum of 24 hours"
echo " Then open the URL provided by the command to visualize the netobserv-cli dashboard anytime during or after the run."
echo "Flow capture examples:"
flows_examples
echo
echo "Packet capture examples:"
packets_examples
echo
echo "Metrics capture examples:"
metrics_examples
echo
}

# flows examples
function flows_examples {
echo " Capture dropped flows on all nodes:"
echo " netobserv flows --drops"
echo " Capture flows in the background, for maximum 15 minutes, TCP on 8080 or UDP, and copy output locally:"
echo " netobserv flows --background --max-time=15m --protocol=TCP --port=8080 or --protocol=UDP"
echo " Capture flows from any namespace starting with 'app-': (for --query doc, see also: https://github.com/netobserv/flowlogs-pipeline/blob/main/docs/filtering.md)"
echo " netobserv flows --query='SrcK8S_Namespace=~\"app-.*\"'"
echo " Capture flows from/to a specific pod pattern on a specific node:"
echo " netobserv flows --node-selector=kubernetes.io/hostname:my-node --query='SrcK8S_Name=~\".*my-pod.*\" or DstK8S_Name=~\".*my-pod.*\"'"
}

# packets examples
function packets_examples {
echo " Capture packets on port 8080:"
echo " netobserv packets --port=8080"
echo " Capture packets on specific nodes (labeled with 'netobserv=true') and port, for a maximum of 100MB:"
echo " netobserv packets --node-selector=netobserv:true --port=80 --max-bytes=100000000"
}

# metrics examples
function metrics_examples {
echo " Capture default cluster metrics including packet drop, dns, rtt, network events packet translation and UDN mapping features:"
echo " netobserv metrics --enable_all"
echo " Capture node and namespace drop metrics, based on keywords include list:"
echo " netobserv metrics --drops --include_list=node,namespace"
echo " Capture metrics in the background for 1 day:"
echo " netobserv metrics --background --max-time=24h"
echo " Then open the URL provided by the command to visualize the netobserv-cli dashboard anytime during or after the run."
echo
}

# display version
function version {
echo "Netobserv CLI version $1"
echo "NetObserv CLI version $1"
}

# agent / flp features
Expand Down Expand Up @@ -143,62 +145,72 @@ function metrics_options {

function flows_usage {
echo
echo "Netobserv allows you to capture flows from your cluster."
echo "NetObserv allows you to capture flows from your cluster."
echo "Find more information at: https://github.com/netobserv/network-observability-cli/"
echo
echo "Syntax: netobserv flows [options]"
echo
echo "features:"
echo "Features:"
features_usage
echo
echo "filters:"
echo "Filters:"
filters_usage
flowsAndMetrics_filters_usage
echo
echo "options:"
echo "Options:"
flowsAndPackets_collector_usage
script_usage
echo
echo "Examples:"
flows_examples
}

function packets_usage {
echo
echo "Netobserv allows you to capture packets from your cluster."
echo "NetObserv allows you to capture packets from your cluster."
echo "Find more information at: https://github.com/netobserv/network-observability-cli/"
echo
echo "Syntax: netobserv packets [options]"
echo
echo "filters:"
echo "Filters:"
filters_usage
echo
echo "options:"
echo "Options:"
flowsAndPackets_collector_usage
script_usage
echo
echo "Examples:"
packets_examples
}

function metrics_usage {
echo
echo "Netobserv allows you to capture metrics on your OCP cluster."
echo "NetObserv allows you to capture metrics on your OCP cluster."
echo "Find more information at: https://github.com/netobserv/network-observability-cli/"
echo
echo "Syntax: netobserv metrics [options]"
echo
echo "features:"
echo "Features:"
features_usage
echo
echo "filters:"
echo "Filters:"
filters_usage
flowsAndMetrics_filters_usage
echo "options:"
echo
echo "Options:"
metrics_collector_usage
script_usage
metrics_options
echo
echo "Examples:"
metrics_examples
echo
echo "More information, with full list of available metrics: https://github.com/netobserv/network-observability-operator/blob/main/docs/Metrics.md"
}

function follow_usage {
echo
echo "Netobserv allows you to capture flows and packets asyncronously using the --background option."
echo "NetObserv allows you to capture flows and packets asyncronously using the --background option."
echo "While the capture is running in background, you can connect to the collector pod to see the progression using the follow command."
echo "Find more information at: https://github.com/netobserv/network-observability-cli/"
echo
Expand All @@ -208,7 +220,7 @@ function follow_usage {

function stop_usage {
echo
echo "Netobserv allows you stop the collection and keep collector or dashboard for post analysis."
echo "NetObserv allows you stop the collection and keep collector or dashboard for post analysis."
echo "While the capture is running, use the stop command to remove the eBPF agents."
echo "Find more information at: https://github.com/netobserv/network-observability-cli/"
echo
Expand All @@ -218,7 +230,7 @@ function stop_usage {

function copy_usage {
echo
echo "Netobserv allows you copy locally the captured flows or packets from the collector pod."
echo "NetObserv allows you copy locally the captured flows or packets from the collector pod."
echo "While the collector is running, use the copy command to copy the output file(s)."
echo "To avoid modifications during the copy, it's recommended to stop the capture"
echo "Find more information at: https://github.com/netobserv/network-observability-cli/"
Expand All @@ -229,7 +241,7 @@ function copy_usage {

function cleanup_usage {
echo
echo "Netobserv may require manual cleanup in some cases such as after a background run or in case of failure."
echo "NetObserv may require manual cleanup in some cases such as after a background run or in case of failure."
echo "Use the cleanup command to remove all the netobserv CLI components."
echo "Find more information at: https://github.com/netobserv/network-observability-cli/"
echo
Expand Down
Loading