chore(doc): Tidy observability documentation

docs/modules/ROOT/nav.adoc

@@ -28,9 +28,12 @@
 ** xref:configuration/dependencies.adoc[Dependencies]
 ** xref:configuration/configmap-secret.adoc[ConfigMap/Secret]
 * Observability
+** xref:observability/logging.adoc[Logging]
+*** xref:observability/logging/operator.adoc[Operator]
+*** xref:observability/logging/integration.adoc[Integration]
 ** xref:observability/monitoring.adoc[Monitoring]
-*** xref:observability/operator.adoc[Operator]
-*** xref:observability/integration.adoc[Integration]
+*** xref:observability/monitoring/operator.adoc[Operator]
+*** xref:observability/monitoring/integration.adoc[Integration]
 * Scaling
 ** xref:scaling/integration.adoc[Integration]
 * xref:traits:traits.adoc[Traits]

docs/modules/ROOT/pages/observability/logging.adoc

@@ -1,6 +1,8 @@
 [[logging]]
 = Camel K Logging
 
-The Camel K logging has two major areas. The first one is related to the logging provided by the
-xref:observability/operator-logging.adoc[operator itself], whereas the second is related to the
-xref:observability/integration-logging.adoc[integrations] ran by Camel K.
+Logs are an essential aspect of observability, and traditionally used to check nominal operation, or for troubleshooting.
+The following pages contain some details on the logging provided by the various Camel K components:
+
+- xref:observability/logging/operator.adoc[Camel K operator logging]
+- xref:observability/logging/integration.adoc[Camel K integration logging]

docs/modules/ROOT/pages/observability/logging/integration.adoc

@@ -0,0 +1,48 @@
+[[integration-logging]]
+= Camel K Integration Logging
+
+The xref:traits:logging.adoc[Logging trait] simplifies the logging configuration of the Integration runtime.
+
+NOTE: The Logging trait has been introduced in Camel K version 1.5.0. See the link:/blog/2021/05/new-camel-k-logging-features/[introductory blog post].
+
+[[integration-logging-level]]
+== Logging Level
+
+To configure the log level, the `level` option from the Logging trait can be used, e.g.:
+
+[source,console]
+----
+$ kamel run -t logging.level=DEBUG
+----
+
+[[integration-logging-format]]
+== Logging Format
+
+The format of the log messages can be configured using the `format` option, e.g.:
+
+[source,console]
+----
+$ kamel run -t logging.format='%d{HH:mm:ss} %-5p (%t) %s%e%n'
+----
+
+The supported values are those of
+https://quarkus.io/guides/logging[Quarkus logging] configuration, as it provides the logging framework, for Camel Quarkus which is leveraged by
+Camel K.
+
+[[integration-logging-structured]]
+== Structured Logs
+
+The Integration Pods can provide structured logs, to facilitate processing and parsing.
+This can be turned on or off, using the `json` option from the Logging trait, e.g.:
+
+[source,console]
+----
+$ kamel run -t logging.json=true
+----
+
+Subsequently, pretty JSON logs can be enabled with:
+
+[source,console]
+----
+$ kamel run -t logging.json=true -t logging.json-pretty-print=true
+----

docs/modules/ROOT/pages/observability/logging/operator.adoc

@@ -0,0 +1,15 @@
+[[logging]]
+= Camel K Operator Logging
+
+The operator provides https://kubernetes.io/blog/2020/09/04/kubernetes-1-19-introducing-structured-logs/[structured logging], so that the logs are more easily parseable.
+
+This includes the output of components managed by the operator, such as the Maven build, and the Integration container image build.
+
+For example, the Maven build logs display like this:
+
+[source,json]
+----
+{"level":"info","ts":1620393185.321101,"logger":"camel-k.maven.build","msg":"Downloading from repository-000: http://my.repository.com:8081/artifactory/fuse-brno/org/jboss/shrinkwrap/resolver/shrinkwrap-resolver-bom/2.2.4/shrinkwrap-resolver-bom-2.2.4.pom"}
+----
+
+This may differ when running the operator locally, for development purposes, in which case the local Maven installation that is used may provide a different output.

docs/modules/ROOT/pages/observability/monitoring.adoc

@@ -15,7 +15,7 @@ To take full advantage of the Camel K monitoring capabilities, it is recommended
 
 You can deploy the Prometheus operator by running:
 
-[source,sh]
+[source,console]
 ----
 $ kubectl apply -f https://raw.githubusercontent.com/coreos/prometheus-operator/v0.38.0/bundle.yaml
 ----
@@ -24,7 +24,7 @@ WARNING: Beware this installs the operator in the `default` namespace. You must
 
 Then, you can create a `Prometheus` resource, that the operator will use as configuration to deploy a managed Prometheus instance:
 
-[source,sh]
+[source,console]
 ----
 $ cat <<EOF | kubectl apply -f -
 apiVersion: monitoring.coreos.com/v1
@@ -93,5 +93,5 @@ On OpenShift versions prior to 4.3, or if you do not want to change your cluster
 
 === What's Next
 
-- xref:observability/operator.adoc[Camel K operator monitoring]
-- xref:observability/integration.adoc[Camel K integration monitoring]
+- xref:observability/monitoring/operator.adoc[Camel K operator monitoring]
+- xref:observability/monitoring/integration.adoc[Camel K integration monitoring]

docs/modules/ROOT/pages/observability/integration.adoc → docs/modules/ROOT/pages/observability/monitoring/integration.adoc

@@ -10,19 +10,20 @@ The xref:traits:prometheus.adoc[Prometheus trait] automates the configuration of
 
 The Prometheus trait can be enabled when running an integration, e.g.:
 
-[source,sh]
+[source,console]
 ----
-$ kamel run -t prometheus.enabled=true ...
+$ kamel run -t prometheus.enabled=true
 ----
 
 Alternatively, the Prometheus trait can be enabled globally once, by updating the integration platform, e.g.:
 
-[source,sh]
+[source,console]
 ----
 $ kubectl patch ip camel-k --type=merge -p '{"spec":{"traits":{"prometheus":{"configuration":{"enabled":true}}}}}'
 ----
 
 Or by directly editing the `IntegrationPlatform` resource, e.g.:
+
 [source, yaml]
 ----
 apiVersion: camel.apache.org/v1
@@ -58,14 +59,14 @@ The Prometheus trait automatically configures the resources necessary for the Pr
 By default, the Prometheus trait creates a `PodMonitor` resource, with the `camel.apache.org/integration` label, which must match the `podMonitorSelector` field from the `Prometheus` resource.
 Additional labels can be specified with the `pod-monitor-labels` parameter from the Prometheus trait, e.g.:
 
-[source,sh]
+[source,console]
 ----
 $ kamel run -t prometheus.pod-monitor-labels="label_to_be_match_by=prometheus_selector" ...
 ----
 
 The creation of the `PodMonitor` resource can be disabled using the `pod-monitor` parameter, e.g.:
 
-[source,sh]
+[source,console]
 ----
 $ kamel run -t prometheus.pod-monitor=false ...
 ----
@@ -82,7 +83,7 @@ The Prometheus Operator declares the `AlertManager` resource that can be used to
 
 Assuming an `AlertManager` resource already exists in your cluster, you can register a `PrometheusRule` resource that is used by Prometheus to trigger alerts, e.g.:
 
-[source,sh]
+[source,console]
 ----
 $ cat <<EOF | kubectl apply -f -
 apiVersion: monitoring.coreos.com/v1

docs/modules/ROOT/pages/observability/operator.adoc → docs/modules/ROOT/pages/observability/monitoring/operator.adoc

@@ -8,7 +8,7 @@ NOTE: The Camel K monitoring architecture relies on https://prometheus.io[Promet
 
 The `kamel install` command provides the `--monitoring` option flag, that can be used to automatically creates the default resources required to monitor the Camel K operator, e.g.:
 
-[source,sh]
+[source,console]
 ----
 $ kamel install --monitoring=true
 ----
@@ -20,7 +20,7 @@ This creates:
 
 The `kamel install` command also provides the `--monitoring-port` option, that can be used to change the port of the operator monitoring endpoint, e.g.:
 
-[source,sh]
+[source,console]
 ----
 $ kamel install --monitoring=true --monitoring-port=8888
 ----

docs/modules/ROOT/pages/scaling/integration.adoc

@@ -86,7 +86,7 @@ For example, executing the following command creates an _autoscaler_ for the Int
 $ kubectl autoscale it <integration_name> --min=2 --max=5 --cpu-percent=80
 ----
 
-xref:observability/integration.adoc[Integration metrics] can also be exported for horizontal pod autoscaling (HPA), using the https://github.com/DirectXMan12/k8s-prometheus-adapter[custom metrics Prometheus adapter], so that the Integration can scale automatically based on its own metrics.
+xref:observability/monitoring/integration.adoc[Integration metrics] can also be exported for horizontal pod autoscaling (HPA), using the https://github.com/DirectXMan12/k8s-prometheus-adapter[custom metrics Prometheus adapter], so that the Integration can scale automatically based on its own metrics.
 
 If you have an OpenShift cluster, you can follow https://docs.openshift.com/container-platform/4.4/monitoring/exposing-custom-application-metrics-for-autoscaling.html[Exposing custom application metrics for autoscaling] to set it up.
 

docs/modules/ROOT/pages/troubleshooting/debugging.adoc

@@ -1,32 +1,34 @@
 = Debugging Camel K Integrations
 
-Sometimes integrations can fail or behave unexpectedly for unknown reasons and a developer needs to investigate the cause of such behavior.
+Sometimes an Integration can fail or behave unexpectedly for unknown reasons, and a developer needs to investigate the cause of such behavior.
 Attaching a Java debugger to an integration is a common way to start the investigation.
 
-Even if Camel K integrations run on a Kubernetes cluster, it's very easy to attach a Java debugger to the remote integration using the CLI.
+Even if the Integration Pods run on a Kubernetes cluster, it's very easy to attach a Java debugger to the remote Integration container using the CLI.
+
+== Debugging with VS Code
 
 If you're a VS Code user, you can watch this link:https://www.youtube.com/watch?v=cFPuxd1Je3c[video].
 
-Find below a more generic explanation using IntelliJ.
+== Debugging with IntelliJ IDEA
 
-Suppose you just launched an integration using the following command:
+Suppose you've started an Integration using the following command:
 
-[source,shell]
+[source,console]
 ----
-kamel run examples/Sample.java
+$ kamel run examples/Sample.java
 ----
 
-An integration named `sample` should be running in the cluster.
-You can use the `kamel debug` command to put it in "debug mode".
+An Integration named `sample` should be running in the cluster.
+You can use the `kamel debug` command to put it in _debug_ mode:
 
-[source,shell]
+[source,console]
 ----
-kamel debug sample
+$ kamel debug sample
 ----
 
 A possible output that you may find is the following:
 
-[source,shell]
+[source,console]
 ----
 $ kamel debug sample
 Enabling debug mode on integration "sample"...
@@ -37,18 +39,16 @@ Forwarding from 127.0.0.1:5005 -> 5005
 Forwarding from [::1]:5005 -> 5005
 ----
 
-As you can see in the logs, the CLI has configured the integration in debug mode (see option `-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=*:5005`)
-and started forwarding the local port 5005 on the workstation machine (local port can be changed using the `--port` option) to the container port 5005, where the JVM is waiting for a debugger.
+As you can see in the logs, the CLI has configured the integration in debug mode (see option `-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=*:5005`) and started forwarding the local port 5005 on the workstation machine (local port can be changed using the `--port` option) to the container port 5005, where the JVM is waiting for a debugger.
 
 The JVM is suspended and waits for a debugger to attach by default: this behavior can be turned off using the `--suspend=false` option.
 
-Last thing to do is, with your IDE opened on the **integration file (if using Java, Groovy or Kotlin), the Apache Camel project or the Camel K Runtime project**,
-to start a remote debugger on `localhost:5005`.
+Last thing to do is, with your IDE opened on the **integration file (if using Java, Groovy or Kotlin), the Apache Camel project, or the Camel K Runtime project**, to start a remote debugger on `localhost:5005`.
 
-The following picture shows the configuration of a remote debugger in IntelliJ Idea.
+The following picture shows the configuration of a remote debugger in IntelliJ IDEA:
 
-image::debugging/remote-debugger.png[Configuration of the remote debugger in IntelliJ Idea]
+image::debugging/remote-debugger.png[Configuration of the remote debugger in IntelliJ IDEA]
 
 Once you configure a debugger, you can **add breakpoints** to various part of the code, then connect the debugger to trigger the JVM startup.
 
-When the debugging session is finished, hitting *ctrl+c* on the terminal where the kamel CLI is running will restore the integration to its original status.
+When the debugging session is done, hitting kbd:[Ctrl+c] on the terminal where the kamel CLI is running will restore the integration to its original status.

docs/modules/ROOT/pages/troubleshooting/known-issues.adoc

@@ -10,23 +10,23 @@ From https://github.com/containers/buildah/issues/1901[containers/buildah#1901],
 
 The only option is to change the Docker container runtime to use a different _seccomp_ profile, e.g.:
 
-[source,sh]
+[source,console]
 ----
 $ docker run --security-opt seccomp=/usr/share/containers/seccomp.json
 ----
 
 However, that requires being able to configure your cluster container runtime.
 
-A work-around is to use another builder strategy, like Kaniko or Spectrum, e.g. when installing Camel K:
+A work-around is to use another builder strategy, like Kaniko or Spectrum, e.g., when installing Camel K:
 
-[source,sh]
+[source,console]
 ----
 $ kamel install --build-publish-strategy=kaniko
 ----
 
 Or by patching your `IntegrationPlatform` resource directly if you have Camel K already installed, e.g.:
 
-[source,sh]
+[source,console]
 ----
 $ kubectl patch ip camel-k --type='merge' -p '{"spec":{"build":{"publishStrategy":"kaniko"}}}'
 ----