Developer documentation for generating telemetry schema (#5250)

Makefile

@@ -87,6 +87,11 @@ update-crds: ## Update CRDs
 	kustomize build config/crd/app-protect-dos --load-restrictor='LoadRestrictionsNone' >deploy/crds-nap-dos.yaml
 	kustomize build config/crd/app-protect-waf --load-restrictor='LoadRestrictionsNone' >deploy/crds-nap-waf.yaml
 
+.PHONY: telemetry-schema
+telemetry-schema: ## Generate the telemetry Schema
+	go generate internal/telemetry/exporter.go
+	gofumpt -w internal/telemetry/*_generated.go
+
 .PHONY: certificate-and-key
 certificate-and-key: ## Create default cert and key
 	./build/generate_default_cert_and_key.sh

docs/content/configuration/global-configuration/command-line-arguments.md

@@ -538,7 +538,7 @@ The default value is `true`.
 
 ### -enable-telemetry-reporting
 
-Enable gathering and reporting of product related telemetry.
+Enable gathering and reporting of software telemetry.
 
 The default value is `true`.
 

docs/content/installation/installing-nic/installation-with-helm.md

@@ -22,11 +22,11 @@ h2 {
 - A [Kubernetes Version Supported by the Ingress Controller](https://docs.nginx.com/nginx-ingress-controller/technical-specifications/#supported-kubernetes-versions)
 - Helm 3.0+.
 - If you’d like to use NGINX Plus:
-    - To pull from the F5 Container registry, configure a docker registry secret using your JWT token from the MyF5 portal by following the instructions from [here](https://docs.nginx.com/nginx-ingress-controller/installation/nic-images/using-the-jwt-token-docker-secret). Make sure to specify the secret using `controller.serviceAccount.imagePullSecretName` or `controller.serviceAccount.imagePullSecretsNames` parameter.
-    - Alternatively, pull an Ingress Controller image with NGINX Plus and push it to your private registry by following the instructions from [here]({{< relref "installation/nic-images/pulling-ingress-controller-image" >}}).
-    - Alternatively, you can build an Ingress Controller image with NGINX Plus and push it to your private registry by following the instructions from [here]({{< relref "installation/building-nginx-ingress-controller.md" >}}).
-    - Update the `controller.image.repository` field of the `values-plus.yaml` accordingly.
-- If you’d like to use App Protect DoS, please install App Protect DoS Arbitrator [helm chart](https://github.com/nginxinc/nap-dos-arbitrator-helm-chart). Make sure to install in the same namespace as the NGINX Ingress Controller. Note that if you install multiple NGINX Ingress Controllers in the same namespace, they will need to share the same Arbitrator because it is not possible to install more than one Arbitrator in a single namespace.
+  - To pull from the F5 Container registry, configure a docker registry secret using your JWT token from the MyF5 portal by following the instructions from [here](https://docs.nginx.com/nginx-ingress-controller/installation/nic-images/using-the-jwt-token-docker-secret). Make sure to specify the secret using `controller.serviceAccount.imagePullSecretName` or `controller.serviceAccount.imagePullSecretsNames` parameter.
+  - Alternatively, pull an NGINX Ingress Controller image with NGINX Plus and push it to your private registry by following the instructions from [here]({{< relref "installation/nic-images/pulling-ingress-controller-image" >}}).
+  - Alternatively, you can NGINX build an Ingress Controller image with NGINX Plus and push it to your private registry by following the instructions from [here]({{< relref "installation/building-nginx-ingress-controller.md" >}}).
+  - Update the `controller.image.repository` field of the `values-plus.yaml` accordingly.
+- To use App Protect DoS, install the App Protect DoS Arbitrator [Helm Chart](https://github.com/nginxinc/nap-dos-arbitrator-helm-chart) in the same namespace as the NGINX Ingress Controller. If you install multiple NGINX Ingress Controllers in the same namespace, they will need to share the same Arbitrator because there can only be one Arbitrator in a single namespace.
 
 ## CRDs
 

docs/developer/telemetry-schema-generation.md

@@ -0,0 +1,37 @@
+# Telemetry Schema Generation
+
+This document outlines how to update the `data.avdl` schema file in `internal/telemetry`
+This document also details reasons why the schema file would need to be updated.
+
+## Updating the schema
+In the root of the project, run the below Make command
+```
+make telemetry-schema
+```
+
+Depending on what kind of update was made, different files will be updated,
+- `internal/telemetry/nicresourcecounts_attributes_generated.go`
+  This file is updated if properties in NICResourceCounts are added, updated or deleted.
+
+- `internal/telemetry/data_attributes_generated.go`
+  This file is update if properties of the Data struct in the [telemetry-exporter](https://github.com/nginxinc/telemetry-exporter) library are added, updated or deleted.
+
+- `internal/telemetry/data.avdl`
+  This file is updated if either the NICResourceCounts or the Data struct is updated.
+
+## Reasons to update the Schema file
+1. A new data point is being collected
+
+We may choose to collect a count of a new resource managed by the Ingress Controller.
+In this case, the `NICResourceCounts` struct in `internal/telemetry/exporter.go` would be updated
+```
+type NICResourceCounts struct {
+	// MyNewResources is the number of MyNewResources resources managed by the Ingress Controller.
+	MyNewResources int64
+}
+```
+
+2. An existing data point has been updated or delete
+
+This may either be a data point under `NICResourceCounts`, or a field in the common `Data` struct in [telemetry-exporter](https://github.com/nginxinc/telemetry-exporter) library.
+For example, we may change the name of, or delete, `MyNewResources` used in the first example.

internal/telemetry/data.avdl

@@ -33,13 +33,13 @@ It is the UID of the `kube-system` Namespace. */
 		/** ClusterNodeCount is the number of nodes in the cluster. */
 		long? ClusterNodeCount = null;
 
-		/** VirtualServer is the number of VirtualServer managed by the Ingress Controller. */
+		/** VirtualServers is the number of VirtualServer resources managed by the Ingress Controller. */
 		long? VirtualServers = null;
 
-		/** VirtualServerRoutes is the number of VirtualServerRoutes managed by the Ingress Controller. */
+		/** VirtualServerRoutes is the number of VirtualServerRoute resources managed by the Ingress Controller. */
 		long? VirtualServerRoutes = null;
 
-		/** TransportServers is the number of TransportServers managed by the Ingress Controller. */
+		/** TransportServers is the number of TransportServer resources  by the Ingress Controller. */
 		long? TransportServers = null;
 
 	}

internal/telemetry/exporter.go

@@ -62,11 +62,11 @@ type Data struct {
 //
 //go:generate go run -tags=generator github.com/nginxinc/telemetry-exporter/cmd/generator -type NICResourceCounts
 type NICResourceCounts struct {
-	// VirtualServer is the number of VirtualServer managed by the Ingress Controller.
+	// VirtualServers is the number of VirtualServer resources managed by the Ingress Controller.
 	VirtualServers int64
-	// VirtualServerRoutes is the number of VirtualServerRoutes managed by the Ingress Controller.
+	// VirtualServerRoutes is the number of VirtualServerRoute resources managed by the Ingress Controller.
 	VirtualServerRoutes int64
-	// TransportServers is the number of TransportServers managed by the Ingress Controller.
+	// TransportServers is the number of TransportServer resources  by the Ingress Controller.
 	TransportServers int64
 
 	// Replicas is the number of NIC replicas.