This is an automated email from the ASF dual-hosted git repository.
orpiske pushed a commit to branch camel-main
in repository https://gitbox.apache.org/repos/asf/camel-k.git
commit 1d6e6ce6013325f094b519e15a9eb6dfc8c6cf97
Author: Antonin Stefanutti <anto...@stefanutti.fr>
AuthorDate: Thu Jun 10 10:06:02 2021 +0200
chore(doc): Tidy observability documentation
---
.../pages/observability/integration-logging.adoc | 36 ----------------
docs/modules/ROOT/pages/observability/logging.adoc | 8 ++--
.../pages/observability/logging/integration.adoc | 48 ++++++++++++++++++++++
.../ROOT/pages/observability/logging/operator.adoc | 15 +++++++
.../ROOT/pages/observability/monitoring.adoc | 8 ++--
.../{ => monitoring}/integration.adoc | 13 +++---
.../observability/{ => monitoring}/operator.adoc | 4 +-
.../ROOT/pages/observability/operator-logging.adoc | 16 --------
docs/modules/ROOT/pages/scaling/integration.adoc | 2 +-
.../ROOT/pages/troubleshooting/debugging.adoc | 36 ++++++++--------
.../ROOT/pages/troubleshooting/known-issues.adoc | 8 ++--
.../ROOT/pages/troubleshooting/operating.adoc | 22 +++++-----
12 files changed, 115 insertions(+), 101 deletions(-)
diff --git a/docs/modules/ROOT/pages/observability/integration-logging.adoc
b/docs/modules/ROOT/pages/observability/integration-logging.adoc
deleted file mode 100644
index 2efc753..0000000
--- a/docs/modules/ROOT/pages/observability/integration-logging.adoc
+++ /dev/null
@@ -1,36 +0,0 @@
-[[integration-logging]]
-= Camel K Integration Logging
-
-Starting with link:/blog/2021/05/new-camel-k-logging-features/[Camel K 1.5],
we introduced a new
-xref:traits:logging.adoc[logging trait] that simplifies access to the logging
configuration available on the runtime.
-
-
-[[integration-logging-level]]
-== Logging Level
-
-To configure the log level, pass one of the supported log levels to the trait.
For example:
-
-```
---trait logging.level=DEBUG
-```
-
-
-[[integration-logging-format]]
-== Logging Format
-
-The format of the logging message can also be configured using one of the
supported log format options from
-https://quarkus.io/guides/logging[Quarkus] (which provides the logging
framework for Camel Quarkus which is leveraged by
-Camel K).
-
-A sample custom configuration would look like this:
-
-```
---trait logging.format='%d{HH:mm:ss} %-5p (%t) %s%e%n'.
-```
-
-[[integration-logging-structured]]
-== Structured Logs in Json Format
-
-Like the operator, the integrations will use structured logs to facilitate
collection and parsing. This can be turned on
-or off using the `--trait logging.json` trait. Subsequently, it can also be
customized to output pretty json logs by
-setting the `logging.json.pretty-print` trait.
diff --git a/docs/modules/ROOT/pages/observability/logging.adoc
b/docs/modules/ROOT/pages/observability/logging.adoc
index ee2cd22..29ca049 100644
--- a/docs/modules/ROOT/pages/observability/logging.adoc
+++ b/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.
\ No newline at end of file
+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]
diff --git a/docs/modules/ROOT/pages/observability/logging/integration.adoc
b/docs/modules/ROOT/pages/observability/logging/integration.adoc
new file mode 100644
index 0000000..14069aa
--- /dev/null
+++ b/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
+----
diff --git a/docs/modules/ROOT/pages/observability/logging/operator.adoc
b/docs/modules/ROOT/pages/observability/logging/operator.adoc
new file mode 100644
index 0000000..8378462
--- /dev/null
+++ b/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.
diff --git a/docs/modules/ROOT/pages/observability/monitoring.adoc
b/docs/modules/ROOT/pages/observability/monitoring.adoc
index e8cafab..a7bdc1e 100644
--- a/docs/modules/ROOT/pages/observability/monitoring.adoc
+++ b/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]
diff --git a/docs/modules/ROOT/pages/observability/integration.adoc
b/docs/modules/ROOT/pages/observability/monitoring/integration.adoc
similarity index 97%
rename from docs/modules/ROOT/pages/observability/integration.adoc
rename to docs/modules/ROOT/pages/observability/monitoring/integration.adoc
index 4f5ce6a..5a123b6 100644
--- a/docs/modules/ROOT/pages/observability/integration.adoc
+++ b/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
diff --git a/docs/modules/ROOT/pages/observability/operator.adoc
b/docs/modules/ROOT/pages/observability/monitoring/operator.adoc
similarity index 99%
rename from docs/modules/ROOT/pages/observability/operator.adoc
rename to docs/modules/ROOT/pages/observability/monitoring/operator.adoc
index e405077..c9076c3 100644
--- a/docs/modules/ROOT/pages/observability/operator.adoc
+++ b/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
----
diff --git a/docs/modules/ROOT/pages/observability/operator-logging.adoc
b/docs/modules/ROOT/pages/observability/operator-logging.adoc
deleted file mode 100644
index 172f87f..0000000
--- a/docs/modules/ROOT/pages/observability/operator-logging.adoc
+++ /dev/null
@@ -1,16 +0,0 @@
-[[logging]]
-= Camel K Operator Logging
-
-The Camel K Operator logging is mostly managed by the Kubernetes
infrastructure, with some specific aspects managed by
-Camel K itself. The operator uses
https://kubernetes.io/blog/2020/09/04/kubernetes-1-19-introducing-structured-logs/[structured
logs]
-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 build.
-For example, the maven build logs should be displayed like this:
-
-
-```
-{"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"}
-```
-
-There are some exceptions to this, though, and they are mostly related to
running the operator for development purposes.
\ No newline at end of file
diff --git a/docs/modules/ROOT/pages/scaling/integration.adoc
b/docs/modules/ROOT/pages/scaling/integration.adoc
index b0ca3a0..9fbbd3f 100644
--- a/docs/modules/ROOT/pages/scaling/integration.adoc
+++ b/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.
diff --git a/docs/modules/ROOT/pages/troubleshooting/debugging.adoc
b/docs/modules/ROOT/pages/troubleshooting/debugging.adoc
index 6d08b42..755800d 100644
--- a/docs/modules/ROOT/pages/troubleshooting/debugging.adoc
+++ b/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.
diff --git a/docs/modules/ROOT/pages/troubleshooting/known-issues.adoc
b/docs/modules/ROOT/pages/troubleshooting/known-issues.adoc
index 846ec5f..7b03302 100644
--- a/docs/modules/ROOT/pages/troubleshooting/known-issues.adoc
+++ b/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"}}}'
----
diff --git a/docs/modules/ROOT/pages/troubleshooting/operating.adoc
b/docs/modules/ROOT/pages/troubleshooting/operating.adoc
index 011ac44..a59af67 100644
--- a/docs/modules/ROOT/pages/troubleshooting/operating.adoc
+++ b/docs/modules/ROOT/pages/troubleshooting/operating.adoc
@@ -3,17 +3,17 @@
NOTE: The following guide uses the terminology from the
https://sre.google/sre-book/service-level-objectives/[Site Reliability
Engineer] book.
-The Camel K operator exposes a monitoring endpoint, that publishes
xref:observability/operator.adoc#metrics[metrics] indicating the _level of
service_ provided to its users.
+The Camel K operator exposes a monitoring endpoint, that publishes
xref:observability/monitoring/operator.adoc#metrics[metrics] indicating the
_level of service_ provided to its users.
These metrics materialize the Service Level Indicators (SLIs) for the Camel K
operator.
Service Level Objectives (SLOs) can be defined based on these SLIs.
-The xref:observability/operator.adoc#alerting[default alerts] created for the
Camel K operator query the SLIs corresponding metrics, and match the SLOs for
the Camel K operator, so that they fire up as soon as the _level of service_ is
not met, and preemptive measures can be taken before beaching the Service Level
Agreement (SLA) for the Camel K operator.
+The xref:observability/monitoring/operator.adoc#alerting[default alerts]
created for the Camel K operator query the SLIs corresponding metrics, and
match the SLOs for the Camel K operator, so that they fire up as soon as the
_level of service_ is not met, and preemptive measures can be taken before
beaching the Service Level Agreement (SLA) for the Camel K operator.
[[operator-sops]]
== Operator SOPs
-The following section lists the Standard Operating Procedures (SOPs),
corresponding to the xref:observability/operator.adoc#alerting[default alerts],
created for the Camel K operator.
-It assumes the operator has been installed according to the
xref:observability/operator.adoc#installation[installation] section from the
operator monitoring documentation.
+The following section lists the Standard Operating Procedures (SOPs),
corresponding to the
xref:observability/monitoring/operator.adoc#alerting[default alerts], created
for the Camel K operator.
+It assumes the operator has been installed according to the
xref:observability/monitoring/operator.adoc#installation[installation] section
from the operator monitoring documentation.
It documents the recommended troubleshooting actions, to be performed when a
particular alert fires.
It is meant to be a living document, to be improved iteratively over time, as
users face problematic situations, and actions to troubleshoot and solve them
are perfected.
@@ -46,7 +46,7 @@ It's firing when some reconciliation requests have failed.
* Search the operator logs for errors, e.g.:
+
-[source,sh]
+[source,console]
----
$ kubectl logs deployment/camel-k-operator --since=1h \
| jq -R 'fromjson?
@@ -56,7 +56,7 @@ Check the `error`, `errorVerbose` and `stacktrace` fields.
* Inspect the resources corresponding to the errors, e.g.:
+
-[source,sh]
+[source,console]
----
$ kubectl logs deployment/camel-k-operator --since=1h \
| jq -rR 'fromjson?
@@ -82,7 +82,7 @@ It's firing when more than 10% of the successful builds have
their duration abov
* Inspect the successful Builds whose duration is longer than 2 minutes, e.g.:
+
-[source,sh]
+[source,console]
----
$ kubectl get builds.camel.apache.org -o json \
| jq -r '.items[]
@@ -108,7 +108,7 @@ It's firing when more than 1% of the successful builds have
their duration above
* Inspect the successful Builds whose duration is longer than 5 minutes, e.g.:
+
-[source,sh]
+[source,console]
----
$ kubectl get builds.camel.apache.org -o json \
| jq -r '.items[]
@@ -134,7 +134,7 @@ It's firing when more than 1% of the builds have errored
over at least 10 min.
* Inspect the errored Builds, e.g.:
+
-[source,sh]
+[source,console]
----
$ kubectl get builds.camel.apache.org -o json \
| jq -r '.items[]
@@ -157,7 +157,7 @@ It's firing when more than 1% of the builds have been
queued for more than 1 min
* Inspect the Builds that have been queued for more than 1 minutes, e.g.:
+
-[source,sh]
+[source,console]
----
$ kubectl get builds.camel.apache.org -o json \
| jq -r '.items[]
@@ -183,7 +183,7 @@ It's firing when more than 1% of the builds have been
queued for more than 5 min
* Inspect the Builds that have been queued for more than 5 minutes, e.g.:
+
-[source,sh]
+[source,console]
----
$ kubectl get builds.camel.apache.org -o json \
| jq -r '.items[]
