Collect admin observability docs into a section. (#4307)

* Collect admin observability docs into a section.

Add docs for  parameters

* Emacs snuck some tabs in. Forgot to install yaml-mode

* Lost a ':' somehow

* Fix up additional links in nav and redirects from build warnings.

* Actually _read_ the mkdocs error, realize I had a typo.

* Fix LHS nav that was using README.md

* Ah kint typo so gud.

* Fix merge oopsie

* Apparently I suck at merges

* Address @snneji feedback

config/nav.yml

@@ -53,12 +53,13 @@ nav:
           - Upgrading with kubectl: admin/upgrade/upgrade-installation.md
         # Uninstall
         - Uninstalling Knative: admin/install/uninstall.md
-        # Observability
-        - Logging: admin/collecting-logs/README.md
-        - Metrics:
-          - About metrics: admin/collecting-metrics/README.md
-          - Knative Eventing metrics: admin/collecting-metrics/eventing-metrics/metrics.md
-          - Knative Serving metrics: admin/collecting-metrics/serving-metrics/metrics.md
+        # Administrator configuration of observability tools
+        - Observability:
+          - Collecting logs: admin/observability/collecting-logs/collecting-logs.md
+          - Collecting metrics: admin/observability/collecting-metrics/collecting-metrics.md
+          - Configuring logging: admin/observability/config-logging/logging.md
+          - Knative Eventing metrics: admin/observability/collecting-metrics/eventing-metrics/metrics.md
+          - Knative Serving metrics: admin/observability/collecting-metrics/serving-metrics/metrics.md
         # Serving config
         - Knative Serving configuration:
           - Revision garbage collection: admin/serving/revision-gc.md

config/redirects.yml

@@ -24,6 +24,10 @@ plugins:
       serving/deploying-from-private-registry.md: developer/serving/deploying-from-private-registry.md
       serving/samples/blue-green-deployment.md: developer/serving/traffic-management.md
       serving/samples/traffic-splitting/README.md: developer/serving/traffic-management.md
+      admin/collecting-logs/README.md: admin/observability/collecting-logs/collecting-logs.md
+      admin/collecting-metrics/README.md: admin/observability/collecting-metrics/collecting-metrics.md
+      admin/collecting-metrics/eventing-metrics/metrics.md: admin/observability/collecting-metrics/eventing-metrics/metrics.md
+      admin/collecting-metrics/serving-metrics/metrics.md: admin/observability/collecting-metrics/serving-metrics/metrics.md
       admin/install/install-eventing-with-yaml.md: admin/install/eventing/install-eventing-with-yaml.md
       admin/install/install-serving-with-yaml.md: admin/install/serving/install-serving-with-yaml.md
       client/connecting-kn-to-your-cluster/index.md: client/README.md
@@ -34,7 +38,7 @@ plugins:
       eventing/broker/kafka-broker/kafka-configmap.md: admin/eventing/kafka-channel-configuration.md
       eventing/channels/default-channels/index.md: eventing/channels/README.md
       eventing/event-delivery.md: developer/eventing/event-delivery.md
-      eventing/metrics.md: admin/collecting-metrics/eventing-metrics/metrics.md
+      eventing/metrics.md: admin/observability/collecting-metrics/eventing-metrics/metrics.md
       eventing/parallel.md: eventing/flows/parallel.md
       eventing/samples/apache-camel-source/index.md: developer/eventing/sources/apache-camel-source/README.md
       eventing/samples/gcp-pubsub-source/README.md: eventing/samples/cloud-pubsub-source/README.md
@@ -56,8 +60,8 @@ plugins:
       help/README.md: help/contributor/README.md
       install/README.md: admin/install/README.md
       install/check-install-version.md: check-install-version.md
-      install/collecting-logs/index.md: admin/collecting-logs/README.md
-      install/collecting-metrics/index.md: admin/collecting-metrics/README.md
+      install/collecting-logs/index.md: admin/observability/collecting-logs/collecting-logs.md
+      install/collecting-metrics/index.md: admin/observability/collecting-metrics/collecting-metrics.md
       install/getting-started-knative-app/index.md: getting-started/README.md
       serving/getting-started-knative-app.md: getting-started/README.md
       install/install-eventing-with-yaml.md: admin/install/eventing/install-eventing-with-yaml.md
@@ -80,7 +84,7 @@ plugins:
       serving/configuring-autoscaling/index.md: serving/autoscaling/README.md
       serving/creating-domain-mappings.md: developer/serving/services/custom-domains.md
       serving/debugging-application-issues.md: developer/serving/troubleshooting/debugging-application-issues.md
-      serving/metrics.md: admin/collecting-metrics/serving-metrics/metrics.md
+      serving/metrics.md: admin/observability/collecting-metrics/serving-metrics/metrics.md
       serving/samples/autoscale-go/index.md: serving/autoscaling/autoscale-go/README.md
       serving/services/README.md: developer/serving/services/README.md
       serving/services/creating-services.md: developer/serving/services/creating-services.md

docs/admin/observability/collecting-logs/collecting-logs.md

@@ -3,7 +3,7 @@
 You can use [Fluent Bit](https://docs.fluentbit.io/), a log processor and forwarder, to collect
 Kubernetes logs in a central directory.
 This is not required to run Knative, but can be helpful with
-[Knative Serving](../../serving/README.md), which automatically deletes pods and associated logs when they are no longer needed.
+[Knative Serving](../../../serving/README.md), which automatically deletes pods and associated logs when they are no longer needed.
 
 Fluent Bit supports exporting to a number of other log providers. If you already have an existing log provider, for example, Splunk, Datadog, ElasticSearch, or Stackdriver, you can follow the [FluentBit documentation](https://docs.fluentbit.io/manual/pipeline/outputs) to configure log forwarders.
 
@@ -40,7 +40,7 @@ The `fluent-bit-collector.yaml` file defines a StatefulSet, as well as a Kuberne
 1. Apply the configuration by entering the command:
 
     ```bash
-    kubectl apply -f https://github.com/knative/docs/raw/main/docs/admin/install/collecting-logs/fluent-bit-collector.yaml
+    kubectl apply -f https://github.com/knative/docs/raw/main/docs/admin/observability/collecting-logs/fluent-bit-collector.yaml
     ```
     The default configuration will classify logs into:
 

docs/admin/observability/collecting-metrics/collecting-metrics.md

@@ -41,7 +41,7 @@ In the following example, you can configure a single collector instance using a
 1. Create a Deployment, Service, and ConfigMap for the collector by entering the following command:
 
        ```bash
-       kubectl apply -f https://raw.githubusercontent.com/knative/docs/main/docs/admin/collecting-metrics/collector.yaml
+       kubectl apply -f https://raw.githubusercontent.com/knative/docs/main/docs/admin/observability/collecting-metrics/collector.yaml
        ```
 
 1. Update the `config-observability` ConfigMaps in the Knative Serving and

docs/admin/observability/config-logging/logging.md

@@ -0,0 +1,25 @@
+# Configuring Log Settings
+
+Log configuration for all Knative components is managed through the `config-logging` ConfigMap in the corresponding namespace. For example, Serving components are configured through `config-logging` in the `knative-serving` namespace and Eventing components are configured through `config-logging` in the `knative-eventing` namespace, etc.
+
+Knative components use the [zap](https://github.com/uber-go/zap) logging library; options are [documented in more detail in that project](https://github.com/uber-go/zap/blob/master/config.go#L58).
+
+In addition to `zap-logger-config`, which is a general key that applies to all components in that namespace, the `config-logging` ConfigMap supports overriding the log level for individual components.
+
+| ConfigMap key                     | Description                                                                                                                                                      |
+| :-------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `zap-logger-config`               | A JSON object container for a zap logger configuration. Key fields are highlighted below.                                                                        |
+| `zap-logger-config.level`         | The default logging level for components. Messages at or above this severity level will be logged.                                                               |
+| `zap-logger-config.encoding`      | The log encoding format for component logs (defaults to JSON).                                                                                                   |
+| `zap-logger-config.encoderConfig` | A `zap` [EncoderConfig](https://github.com/uber-go/zap/blob/10d89a76cc8b9787e408aee8882e40a8bd29c585/zapcore/encoder.go#L312) used to customize record contents. |
+| `loglevel.<component>`            | Overrides logging level for the given component only. Messages at or above this severity level will be logged.                                                   |
+
+Log levels supported by Zap are:
+
+- `debug` - fine-grained debugging
+- `info` - normal logging
+- `warn` - unexpected but non-critical errors
+- `error` - critical errors; unexpected during normal operation
+- `dpanic` - in debug mode, trigger a panic (crash)
+- `panic` - trigger a panic (crash)
+- `fatal` - immediately exit with exit status 1 (failure)

docs/serving/README.md

@@ -71,7 +71,7 @@ For more information on the resources and their interactions, see the [Resource
 
 ## Observability
 
-- [Serving Metrics API](../admin/collecting-metrics/serving-metrics/metrics.md)
+- [Serving Metrics API](../admin/observability/collecting-metrics/serving-metrics/metrics.md)
 
 ## Known Issues