Merge pull request #75257 from max-cx/otel-journald

OBSDOCS-953/TRACING-4062 Write documentation and technical enablement for journald component

Author: skopacz1

modules/otel-collector-components.adoc

@@ -14,7 +14,7 @@ Receivers get data into the Collector.
 [id="otlp-receiver_{context}"]
 === OTLP Receiver
 
-The OTLP receiver ingests traces and metrics using the OpenTelemetry protocol (OTLP).
+The OTLP receiver ingests traces, metrics, and logs by using the OpenTelemetry Protocol (OTLP).
 
 .OpenTelemetry Collector custom resource with an enabled OTLP receiver
 [source,yaml]
@@ -43,9 +43,9 @@ The OTLP receiver ingests traces and metrics using the OpenTelemetry protocol (O
           receivers: [otlp]
 ----
 <1> The OTLP gRPC endpoint. If omitted, the default `+0.0.0.0:4317+` is used.
-<2> The server-side TLS configuration. Defines paths to TLS certificates. If omitted, TLS is disabled.
+<2> The server-side TLS configuration. Defines paths to TLS certificates. If omitted, the TLS is disabled.
 <3> The path to the TLS certificate at which the server verifies a client certificate. This sets the value of `ClientCAs` and `ClientAuth` to `RequireAndVerifyClientCert` in the `TLSConfig`. For more information, see the link:https://godoc.org/crypto/tls#Config[`Config` of the Golang TLS package].
-<4> Specifies the time interval at which the certificate is reloaded. If the value is not set, the certificate is never reloaded. The `reload_interval` accepts a string containing valid units of time such as `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`.
+<4> Specifies the time interval at which the certificate is reloaded. If the value is not set, the certificate is never reloaded. The `reload_interval` field accepts a string containing valid units of time such as `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`.
 <5> The OTLP HTTP endpoint. The default value is `+0.0.0.0:4318+`.
 <6> The server-side TLS configuration. For more information, see the `grpc` protocol configuration section.
 
@@ -590,6 +590,120 @@ receivers:
 <1> A list of file glob patterns that match the file paths to be read.
 <2> An array of Operators. Each Operator performs a simple task such as parsing a timestamp or JSON. To process logs into a desired format, chain the Operators together.
 
+[id="journald-receiver_{context}"]
+=== Journald Receiver
+
+:FeatureName: The Journald Receiver
+include::snippets/technology-preview.adoc[]
+
+The Journald Receiver parses *journald* events from the *systemd* journal and sends them as logs.
+
+.OpenTelemetry Collector custom resource with the enabled Journald Receiver
+[source,yaml]
+----
+kubectl apply -f - <<EOF
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: otel-journald
+  labels:
+    security.openshift.io/scc.podSecurityLabelSync: "false"
+    pod-security.kubernetes.io/enforce: "privileged"
+    pod-security.kubernetes.io/audit: "privileged"
+    pod-security.kubernetes.io/warn: "privileged"
+---
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: privileged-sa
+  namespace: otel-journald
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  name: otel-journald-binding
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: ClusterRole
+  name: system:openshift:scc:privileged
+subjects:
+- kind: ServiceAccount
+  name: privileged-sa
+  namespace: otel-journald
+---
+apiVersion: opentelemetry.io/v1alpha1
+kind: OpenTelemetryCollector
+metadata:
+  name: otel-journald-logs
+  namespace: otel-journald
+spec:
+  mode: daemonset
+  serviceAccount: privileged-sa
+  securityContext:
+    allowPrivilegeEscalation: false
+    capabilities:
+      drop:
+      - CHOWN
+      - DAC_OVERRIDE
+      - FOWNER
+      - FSETID
+      - KILL
+      - NET_BIND_SERVICE
+      - SETGID
+      - SETPCAP
+      - SETUID
+    readOnlyRootFilesystem: true
+    seLinuxOptions:
+      type: spc_t
+    seccompProfile:
+      type: RuntimeDefault
+  config: |
+    receivers:
+      journald:
+        files: /var/log/journal/*/*
+        priority: info # <1>
+        units: # <2>
+          - kubelet
+          - crio
+          - init.scope
+          - dnsmasq
+        all: true # <3>
+        retry_on_failure:
+          enabled: true # <4>
+          initial_interval: 1s # <5>
+          max_interval: 30s # <6>
+          max_elapsed_time: 5m # <7>
+    processors:
+    exporters:
+      debug:
+        verbosity: detailed
+    service:
+      pipelines:
+        logs:
+          receivers: [journald]
+          exporters: [debug]
+  volumeMounts:
+  - name: journal-logs
+    mountPath: /var/log/journal/
+    readOnly: true
+  volumes:
+  - name: journal-logs
+    hostPath:
+      path: /var/log/journal
+  tolerations:
+  - key: node-role.kubernetes.io/master
+    operator: Exists
+    effect: NoSchedule
+EOF
+----
+<1> Filters output by message priorities or priority ranges. The default value is `info`.
+<2> Lists the units to read entries from. If empty, entries are read from all units.
+<3> Includes very long logs and logs with unprintable characters. The default value is `false`.
+<4> If set to `true`, the receiver pauses reading a file and attempts to resend the current batch of logs when encountering an error from downstream components. The default value is `false`.
+<5> The time interval to wait after the first failure before retrying. The default value is `1s`. The units are `ms`, `s`, `m`, `h`.
+<6> The upper bound for the retry backoff interval. When this value is reached, the time interval between consecutive retry attempts remains constant at this value. The default value is `30s`. The supported units are `ms`, `s`, `m`, `h`.
+<7> The maximum time interval, including retry attempts, for attempting to send a logs batch to a downstream consumer. When this value is reached, the data are discarded. If the set value is `0`, retrying never stops. The default value is `5m`. The supported units are `ms`, `s`, `m`, `h`.
+
 [id="processors_{context}"]
 == Processors