Skip to content

OSDOCS-10730: NetObserv 1.8 CLI reference #86824

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

Merged
jeana-redhat merged 1 commit into from
Feb 12, 2025
Merged

OSDOCS-10730: NetObserv 1.8 CLI reference #86824

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
33 changes: 33 additions & 0 deletions modules/network-observability-cli-capturing-metrics.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
// Module included in the following assemblies:
//
// * observability/network_observability/netobserv_cli/netobserv-cli-using.adoc

:_mod-docs-content-type: PROCEDURE
[id="network-observability-cli-capturing-metrics_{context}"]
= Capturing metrics
You can generate on-demand dashboards in Prometheus by using a service monitor for Network Observability.

.Prerequisites
* Install the {oc-first}.
* Install the Network Observability CLI (`oc netobserv`) plugin.

.Procedure
. Capture metrics with filters enabled by running the following command:
+
.Example output
[source,terminal]
----
$ oc netobserv metrics --enable_filter=true --cidr=0.0.0.0/0 --protocol=TCP --port=49051
----
. Open the link provided in the terminal to view the *NetObserv / On-Demand* dashboard:
+
.Example URL
[source,terminal]
----
https://console-openshift-console.apps.rosa...openshiftapps.com/monitoring/dashboards/netobserv-cli
----
+
[NOTE]
====
Features that are not enabled present as empty graphs.
Copy link
Contributor

@jeana-redhat jeana-redhat Feb 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not sure what this means but I am guessing it makes sense to the intended audience :)

Copy link
Contributor Author

@skrthomas skrthomas Feb 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I think it should make sense. Network Observability has some features that are widely known in the docs and use-case-wise, but optional to turn on/off. So if you have any of these features off, then you get empty graphs.

====
177 changes: 124 additions & 53 deletions modules/network-observability-netobserv-cli-reference.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,14 @@
// Automatically generated by './scripts/generate-doc.sh'. Do not edit, or make the NETOBSERV team aware of the editions.
:_mod-docs-content-type: REFERENCE

[id="network-observability-netobserv-cli-reference_{context}"]
= Network Observability CLI usage

You can use the Network Observability CLI (`oc netobserv`) to pass command line arguments to capture flow data and packet data for further analysis, enable Network Observability Operator features, or pass configuration options to the eBPF agent and `flowlogs-pipeline`.
You can use the Network Observability CLI (`oc netobserv`) to pass command line arguments to capture flows data, packets data, and metrics for further analysis and enable features supported by the Network Observability Operator.

[id="cli-syntax_{context}"]
== Syntax
The basic syntax for `oc netobserv` commands is as follows:
The basic syntax for `oc netobserv` commands:

.`oc netobserv` syntax
[source,terminal]
Expand All @@ -26,6 +27,14 @@ $ oc netobserv [<command>] [<feature_option>] [<command_options>] <1>
| Capture flows information. For subcommands, see the "Flows capture options" table.
| packets
| Capture packets data. For subcommands, see the "Packets capture options" table.
| metrics
| Capture metrics data. For subcommands, see the "Metrics capture options" table.
| follow
| Follow collector logs when running in background.
| stop
| Stop collection by removing agent daemonset.
| copy
| Copy collector generated files locally.
| cleanup
| Remove the Network Observability CLI components.
| version
Expand All @@ -46,44 +55,52 @@ $ oc netobserv flows [<feature_option>] [<command_options>]
[cols="1,1,1",options="header"]
|===
| Option | Description | Default
|--enable_pktdrop| enable packet drop | false
|--enable_dns| enable DNS tracking | false
|--enable_rtt| enable RTT tracking | false
|--enable_network_events| enable Network events monitoring | false
|--enable_filter| enable flow filter | false
|--log-level| components logs | info
|--max-time| maximum capture time | 5m
|--max-bytes| maximum capture bytes | 50000000 = 50MB
|--copy| copy the output files locally | prompt
|--direction| filter direction | n/a
|--cidr| filter CIDR | 0.0.0.0/0
|--protocol| filter protocol | n/a
|--sport| filter source port | n/a
|--dport| filter destination port | n/a
|--port| filter port | n/a
|--sport_range| filter source port range | n/a
|--dport_range| filter destination port range | n/a
|--port_range| filter port range | n/a
|--sports| filter on either of two source ports | n/a
|--dports| filter on either of two destination ports | n/a
|--ports| filter on either of two ports | n/a
|--tcp_flags| filter TCP flags | n/a
|--action| filter action | Accept
|--icmp_type| filter ICMP type | n/a
|--icmp_code| filter ICMP code | n/a
|--peer_ip| filter peer IP | n/a
|--interfaces| interfaces to monitor | n/a
|--enable_all| enable all eBPF features | false
|--enable_dns| enable DNS tracking | false
|--enable_network_events| enable network events monitoring | false
|--enable_pkt_translation| enable packet translation | false
|--enable_pkt_drop| enable packet drop | false
|--enable_rtt| enable RTT tracking | false
|--enable_udn_mapping| enable User Defined Network mapping | false
|--get-subnets| get subnets information | false
|--background| run in background | false
|--copy| copy the output files locally | prompt
|--log-level| components logs | info
|--max-time| maximum capture time | 5m
|--max-bytes| maximum capture bytes | 50000000 = 50MB
|--action| filter action | Accept
|--cidr| filter CIDR | 0.0.0.0/0
|--direction| filter direction | –
|--dport| filter destination port | –
|--dport_range| filter destination port range | –
|--dports| filter on either of two destination ports | –
|--drops| filter flows with only dropped packets | false
|--icmp_code| filter ICMP code | –
|--icmp_type| filter ICMP type | –
|--node-selector| capture on specific nodes | –
|--peer_ip| filter peer IP | –
|--peer_cidr| filter peer CIDR | –
|--port_range| filter port range | –
|--port| filter port | –
|--ports| filter on either of two ports | –
|--protocol| filter protocol | –
|--regexes| filter flows using regular expression | –
|--sport_range| filter source port range | –
|--sport| filter source port | –
|--sports| filter on either of two source ports | –
|--tcp_flags| filter TCP flags | –
|--interfaces| interfaces to monitor | –
|===

.Example running flows capture on TCP protocol and port 49051 with PacketDrop and RTT features enabled:
[source,terminal]
----
$ oc netobserv flows --enable_pktdrop=true --enable_rtt=true --enable_filter=true --action=Accept --cidr=0.0.0.0/0 --protocol=TCP --port=49051
$ oc netobserv flows --enable_pkt_drop --enable_rtt --enable_filter --action=Accept --cidr=0.0.0.0/0 --protocol=TCP --port=49051
----

[id="cli-reference-packet-capture-options_{context}"]
== Packets capture options
You can filter on port and protocol for packet capture data.
You can filter packets capture data the as same as flows capture by using the filters.
Certain features, such as packets drop, DNS, RTT, and network events, are only available for flows and metrics capture.

.`oc netobserv packets` syntax
[source,terminal]
Expand All @@ -93,31 +110,85 @@ $ oc netobserv packets [<option>]
[cols="1,1,1",options="header"]
|===
| Option | Description | Default
|--log-level| components logs | info
|--max-time| maximum capture time | 5m
|--max-bytes| maximum capture bytes | 50000000 = 50MB
|--copy| copy the output files locally | prompt
|--direction| filter direction | n/a
|--cidr| filter CIDR | 0.0.0.0/0
|--protocol| filter protocol | n/a
|--sport| filter source port | n/a
|--dport| filter destination port | n/a
|--port| filter port | n/a
|--sport_range| filter source port range | n/a
|--dport_range| filter destination port range | n/a
|--port_range| filter port range | n/a
|--sports| filter on either of two source ports | n/a
|--dports| filter on either of two destination ports | n/a
|--ports| filter on either of two ports | n/a
|--tcp_flags| filter TCP flags | n/a
|--action| filter action | Accept
|--icmp_type| filter ICMP type | n/a
|--icmp_code| filter ICMP code | n/a
|--peer_ip| filter peer IP | n/a
|--background| run in background | false
|--copy| copy the output files locally | prompt
|--log-level| components logs | info
|--max-time| maximum capture time | 5m
|--max-bytes| maximum capture bytes | 50000000 = 50MB
|--action| filter action | Accept
|--cidr| filter CIDR | 0.0.0.0/0
|--direction| filter direction | –
|--dport| filter destination port | –
|--dport_range| filter destination port range | –
|--dports| filter on either of two destination ports | –
|--drops| filter flows with only dropped packets | false
|--icmp_code| filter ICMP code | –
|--icmp_type| filter ICMP type | –
|--node-selector| capture on specific nodes | –
|--peer_ip| filter peer IP | –
|--peer_cidr| filter peer CIDR | –
|--port_range| filter port range | –
|--port| filter port | –
|--ports| filter on either of two ports | –
|--protocol| filter protocol | –
|--regexes| filter flows using regular expression | –
|--sport_range| filter source port range | –
|--sport| filter source port | –
|--sports| filter on either of two source ports | –
|--tcp_flags| filter TCP flags | –
|===

.Example running packets capture on TCP protocol and port 49051:
[source,terminal]
----
$ oc netobserv packets --action=Accept --cidr=0.0.0.0/0 --protocol=TCP --port=49051
----
[id="cli-reference-metrics-capture-options_{context}"]
== Metrics capture options
You can enable features and use filters on metrics capture, the same as flows capture. The generated graphs fill accordingly in the dashboard.

.`oc netobserv metrics` syntax
[source,terminal]
----
$ oc netobserv metrics [<option>]
----
[cols="1,1,1",options="header"]
|===
| Option | Description | Default
|--enable_all| enable all eBPF features | false
|--enable_dns| enable DNS tracking | false
|--enable_network_events| enable network events monitoring | false
|--enable_pkt_translation| enable packet translation | false
|--enable_pkt_drop| enable packet drop | false
|--enable_rtt| enable RTT tracking | false
|--enable_udn_mapping| enable User Defined Network mapping | false
|--get-subnets| get subnets information | false
|--action| filter action | Accept
|--cidr| filter CIDR | 0.0.0.0/0
|--direction| filter direction | –
|--dport| filter destination port | –
|--dport_range| filter destination port range | –
|--dports| filter on either of two destination ports | –
|--drops| filter flows with only dropped packets | false
|--icmp_code| filter ICMP code | –
|--icmp_type| filter ICMP type | –
|--node-selector| capture on specific nodes | –
|--peer_ip| filter peer IP | –
|--peer_cidr| filter peer CIDR | –
|--port_range| filter port range | –
|--port| filter port | –
|--ports| filter on either of two ports | –
|--protocol| filter protocol | –
|--regexes| filter flows using regular expression | –
|--sport_range| filter source port range | –
|--sport| filter source port | –
|--sports| filter on either of two source ports | –
|--tcp_flags| filter TCP flags | –
|--interfaces| interfaces to monitor | –
|===

.Example running metrics capture for TCP drops
[source,terminal]
----
$ oc netobserv metrics --enable_pkt_drop --enable_filter --protocol=TCP
----
1 change: 1 addition & 0 deletions observability/network_observability/netobserv_cli/netobserv-cli-using.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ You can visualize and filter the flows and packets data directly in the terminal

include::modules/network-observability-cli-capturing-flows.adoc[leveloffset=+1]
include::modules/network-observability-cli-capturing-packets.adoc[leveloffset=+1]
include::modules/network-observability-cli-capturing-metrics.adoc[leveloffset=+1]
include::modules/network-observability-netobserv-cli-cleaning.adoc[leveloffset=+1]

[role=_additional_resources]
Expand Down