OSDOCS-15203:CQA for associating secondary metrics

Author: JoeAldinger

modules/cnf-associating-secondary-interfaces-metrics-to-network-attachments.adoc

@@ -1,73 +1,18 @@
-// CNF-43 Associate Secondary Interfaces Metrics to Network Attachments
 // Module included in the following assemblies:
 //
 // *networking/associating-secondary-interfaces-metrics-to-network-attachments.adoc
 
+:_mod-docs-content-type: CONCEPT
 [id="cnf-associating-secondary-interfaces-metrics-to-network-attachments_{context}"]
 = Extending secondary network metrics for monitoring
 
-Secondary devices, or interfaces, are used for different purposes. It is important to have a way to classify them to be able to aggregate the metrics for secondary devices with the same classification.
+Secondary devices, or interfaces, are used for different purposes. Metrics from secondary network interfaces need to be classified to allow for effective aggregation and monitoring.
 
-Exposed metrics contain the interface but do not specify where the interface originates. This is workable when there are no additional interfaces. However, if secondary interfaces are added, it can be difficult to use the metrics since it is hard to identify interfaces using only interface names.
+Exposed metrics contain the interface but do not specify where the interface originates. This is workable when there are no additional interfaces. However, relying on interface names alone becomes problematic when secondary interfaces are added because it is difficult to identify their purpose and use their metrics effectively..
 
-When adding secondary interfaces, their names depend on the order in which they are added, and different secondary interfaces might belong to different networks and can be used for different purposes.
+When adding secondary interfaces, their names depend on the order in which they are added. Secondary interfaces can belong to distinct networks that can each serve a different purposes.
 
 With `pod_network_name_info` it is possible to extend the current metrics with additional information that identifies the interface type. In this way, it is possible to aggregate the metrics and to add specific alarms to specific interface types.
 
-The network type is generated using the name of the related `NetworkAttachmentDefinition`, that in turn is used to differentiate different classes of secondary networks. For example, different interfaces belonging to different networks or using different CNIs use different network attachment definition names.
+The network type is generated from the name of the `NetworkAttachmentDefinition` resource, which distinguishes different secondary network classes. For example, different interfaces belonging to different networks or using different CNIs use different network attachment definition names.
 
-[id="cnf-associating-secondary-interfaces-metrics-to-network-attachments-network-metrics-daemon_{context}"]
-== Network Metrics Daemon
-
-The Network Metrics Daemon is a daemon component that collects and publishes network related metrics.
-
-The kubelet is already publishing network related metrics you can observe. These metrics are:
-
-* `container_network_receive_bytes_total`
-* `container_network_receive_errors_total`
-* `container_network_receive_packets_total`
-* `container_network_receive_packets_dropped_total`
-* `container_network_transmit_bytes_total`
-* `container_network_transmit_errors_total`
-* `container_network_transmit_packets_total`
-* `container_network_transmit_packets_dropped_total`
-
-The labels in these metrics contain, among others:
-
-* Pod name
-* Pod namespace
-* Interface name (such as `eth0`)
-
-These metrics work well until new interfaces are added to the pod, for example via https://github.com/intel/multus-cni[Multus], as it is not clear what the interface names refer to.
-
-The interface label refers to the interface name, but it is not clear what that interface is meant for. In case of many different interfaces, it would be impossible to understand what network the metrics you are monitoring refer to.
-
-This is addressed by introducing the new `pod_network_name_info` described in the following section.
-
-[id="cnf-associating-secondary-interfaces-metrics-with-network-name_{context}"]
-== Metrics with network name
-
-This daemonset publishes a `pod_network_name_info` gauge metric, with a fixed value of `0`:
-
-[source,bash]
-----
-pod_network_name_info{interface="net0",namespace="namespacename",network_name="nadnamespace/firstNAD",pod="podname"} 0
-----
-
-The network name label is produced using the annotation added by Multus. It is the concatenation of the namespace the network attachment definition belongs to, plus the name of the network attachment definition.
-
-The new metric alone does not provide much value, but combined with the network related `container_network_*` metrics, it offers better support for monitoring secondary networks.
-
-Using a `promql` query like the following ones, it is possible to get a new metric containing the value and the network name retrieved from the `k8s.v1.cni.cncf.io/network-status` annotation:
-
-[source,bash]
-----
-(container_network_receive_bytes_total) + on(namespace,pod,interface) group_left(network_name) ( pod_network_name_info )
-(container_network_receive_errors_total) + on(namespace,pod,interface) group_left(network_name) ( pod_network_name_info )
-(container_network_receive_packets_total) + on(namespace,pod,interface) group_left(network_name) ( pod_network_name_info )
-(container_network_receive_packets_dropped_total) + on(namespace,pod,interface) group_left(network_name) ( pod_network_name_info )
-(container_network_transmit_bytes_total) + on(namespace,pod,interface) group_left(network_name) ( pod_network_name_info )
-(container_network_transmit_errors_total) + on(namespace,pod,interface) group_left(network_name) ( pod_network_name_info )
-(container_network_transmit_packets_total) + on(namespace,pod,interface) group_left(network_name) ( pod_network_name_info )
-(container_network_transmit_packets_dropped_total) + on(namespace,pod,interface) group_left(network_name)
-----

modules/cnf-metrics-secondary-interfaces-by-name.adoc

@@ -0,0 +1,33 @@
+// Module included in the following assemblies:
+//
+// *networking/associating-secondary-interfaces-metrics-to-network-attachments.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="cnf-metrics-secondary-interfaces-by-name_{context}"]
+= Metrics with network name
+
+The Network Metrics daemonset publishes a `pod_network_name_info` gauge metric, with a fixed value of `0`.
+
+.Example of `pod_network_name_info`
+[source,bash]
+----
+pod_network_name_info{interface="net0",namespace="namespacename",network_name="nadnamespace/firstNAD",pod="podname"} 0
+----
+
+The network name label is produced using the annotation added by Multus. It is the concatenation of the namespace the network attachment definition belongs to, plus the name of the network attachment definition.
+
+The new metric alone does not provide much value, but combined with the network related `container_network_*` metrics, it offers better support for monitoring secondary networks.
+
+Using a `promql` query like the following ones, it is possible to get a new metric containing the value and the network name retrieved from the `k8s.v1.cni.cncf.io/network-status` annotation:
+
+[source,bash]
+----
+(container_network_receive_bytes_total) + on(namespace,pod,interface) group_left(network_name) ( pod_network_name_info )
+(container_network_receive_errors_total) + on(namespace,pod,interface) group_left(network_name) ( pod_network_name_info )
+(container_network_receive_packets_total) + on(namespace,pod,interface) group_left(network_name) ( pod_network_name_info )
+(container_network_receive_packets_dropped_total) + on(namespace,pod,interface) group_left(network_name) ( pod_network_name_info )
+(container_network_transmit_bytes_total) + on(namespace,pod,interface) group_left(network_name) ( pod_network_name_info )
+(container_network_transmit_errors_total) + on(namespace,pod,interface) group_left(network_name) ( pod_network_name_info )
+(container_network_transmit_packets_total) + on(namespace,pod,interface) group_left(network_name) ( pod_network_name_info )
+(container_network_transmit_packets_dropped_total) + on(namespace,pod,interface) group_left(network_name)
+----

modules/cnf-network-metrics-daemon.adoc

@@ -0,0 +1,32 @@
+// Module included in the following assemblies:
+//
+// *networking/associating-secondary-interfaces-metrics-to-network-attachments.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="cnf-network-metrics-daemon_{context}"]
+= Network Metrics Daemon
+
+The Network Metrics Daemon is a daemon component that collects and publishes network related metrics.
+
+The kubelet is already publishing network related metrics you can observe. These metrics are:
+
+* `container_network_receive_bytes_total`
+* `container_network_receive_errors_total`
+* `container_network_receive_packets_total`
+* `container_network_receive_packets_dropped_total`
+* `container_network_transmit_bytes_total`
+* `container_network_transmit_errors_total`
+* `container_network_transmit_packets_total`
+* `container_network_transmit_packets_dropped_total`
+
+The labels in these metrics contain, among others:
+
+* Pod name
+* Pod namespace
+* Interface name (such as `eth0`)
+
+These metrics work well until new interfaces are added to the pod, for example via https://github.com/intel/multus-cni[Multus], as it is not clear what the interface names refer to.
+
+The interface label refers to the interface name, but it is not clear what that interface is meant for. In case of many different interfaces, it would be impossible to understand what network the metrics you are monitoring refer to.
+
+This is addressed by introducing the new `pod_network_name_info` described in the following section.

networking/advanced_networking/associating-secondary-interfaces-metrics-to-network-attachments.adoc

@@ -6,4 +6,10 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
+Administrators can use the `pod_network_info` metric to classify and monitor secondary network interfaces. The metric does this by adding a label that identifies the interface type, typically based on the associated `NetworkAttachmentDefinition` resource.
+
 include::modules/cnf-associating-secondary-interfaces-metrics-to-network-attachments.adoc[leveloffset=+1]
+
+include::modules/cnf-network-metrics-daemon.adoc[leveloffset=+1]
+
+include::modules/cnf-metrics-secondary-interfaces-by-name.adoc[leveloffset=+1]