Skip to content

Commit 92ef1fd

Browse files
skrthomasskrthomas
authored
Merge pull request #84861 from smunje1/OBSDOCS-1463-differentiate
OBSDOCS-1439_Differentiate
2 parents 0c803ed + 6d60d3e commit 92ef1fd

20 files changed

+1266
-6
lines changed

‎_topic_maps/_topic_map.yml‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2907,6 +2907,23 @@ Topics:
29072907
File: log6x-visual
29082908
# - Name: API reference 6.0
29092909
# File: log6x-api-reference
2910+
- Name: Logging 6.1
2911+
Dir: logging-6.1
2912+
Topics:
2913+
- Name: Release notes
2914+
File: log6x-release-notes-6.1
2915+
- Name: About logging 6.1
2916+
File: log6x-about-6.1
2917+
- Name: Configuring log forwarding
2918+
File: log6x-clf-6.1
2919+
- Name: Configuring LokiStack storage
2920+
File: log6x-loki-6.1
2921+
- Name: Configuring LokiStack for OTLP
2922+
File: log6x-configuring-lokistack-otlp-6.1
2923+
- Name: OpenTelemetry data model
2924+
File: log6x-opentelemetry-data-model-6.1
2925+
- Name: Visualization for logging
2926+
File: log6x-visual-6.1
29102927
- Name: Support
29112928
File: cluster-logging-support
29122929
- Name: Troubleshooting logging

‎modules/log6x-configuring-lokistack-otlp-data-ingestion.adoc‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * observability/logging/logging-6.0/log6x-configuring-lokistack-otlp.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="log6x-configuring-lokistack-otlp-data-ingestion_{context}"]
7+
= Configuring LokiStack for OTLP data ingestion
8+
9+
:FeatureName: The OpenTelemetry Protocol (OTLP) output log forwarder
10+
include::snippets/technology-preview.adoc[]
11+
12+
To configure a `LokiStack` custom resource (CR) for OTLP ingestion, follow these steps:
13+
14+
.Prerequisites
15+
16+
* Ensure that your Loki setup supports structured metadata, introduced in schema version 13 to enable OTLP log ingestion.
17+
18+
.Procedure
19+
20+
. Set the schema version:
21+
+
22+
** When creating a new `LokiStack` CR, set `version: v13` in the storage schema configuration.
23+
+
24+
[NOTE]
25+
====
26+
For existing configurations, add a new schema entry with `version: v13` and an `effectiveDate` in the future. For more information on updating schema versions, see link:https://grafana.com/docs/loki/latest/configure/storage/#upgrading-schemas[Upgrading Schemas] (Grafana documentation).
27+
====
28+
29+
. Configure the storage schema as follows:
30+
+
31+
.Example configure storage schema
32+
[source,yaml]
33+
----
34+
# ...
35+
spec:
36+
storage:
37+
schemas:
38+
- version: v13
39+
effectiveDate: 2024-10-25
40+
----
41+
+
42+
Once the `effectiveDate` has passed, the v13 schema takes effect, enabling your `LokiStack` to store structured metadata.

‎modules/log6x-quickstart-opentelemetry.adoc‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * observability/logging/logging-6.0/log6x-about.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="quick-start-opentelemetry_{context}"]
7+
= Quick start with OpenTelemetry
8+
9+
:FeatureName: The OpenTelemetry Protocol (OTLP) output log forwarder
10+
include::snippets/technology-preview.adoc[]
11+
12+
To configure OTLP ingestion and enable the OpenTelemetry data model, follow these steps:
13+
14+
.Prerequisites
15+
* Cluster administrator permissions
16+
17+
.Procedure
18+
19+
. Install the {clo}, {loki-op}, and {coo-first} from OperatorHub.
20+
21+
. Create a `LokiStack` custom resource (CR) in the `openshift-logging` namespace:
22+
+
23+
[source,yaml]
24+
----
25+
apiVersion: loki.grafana.com/v1
26+
kind: LokiStack
27+
metadata:
28+
name: logging-loki
29+
namespace: openshift-logging
30+
spec:
31+
managementState: Managed
32+
size: 1x.extra-small
33+
storage:
34+
schemas:
35+
- effectiveDate: '2024-10-01'
36+
version: v13
37+
secret:
38+
name: logging-loki-s3
39+
type: s3
40+
storageClassName: gp3-csi
41+
tenants:
42+
mode: openshift-logging
43+
----
44+
+
45+
[NOTE]
46+
====
47+
Ensure that the `logging-loki-s3` secret is created beforehand. The contents of this secret vary depending on the object storage in use. For more information, see "Secrets and TLS Configuration".
48+
====
49+
50+
. Create a service account for the collector:
51+
+
52+
[source,terminal]
53+
----
54+
$ oc create sa collector -n openshift-logging
55+
----
56+
57+
. Allow the collector's service account to write data to the `LokiStack` CR:
58+
+
59+
[source,terminal]
60+
----
61+
$ oc adm policy add-cluster-role-to-user logging-collector-logs-writer -z collector
62+
----
63+
+
64+
[NOTE]
65+
====
66+
The `ClusterRole` resource is created automatically during the Cluster Logging Operator installation and does not need to be created manually.
67+
====
68+
69+
. Allow the collector's service account to collect logs:
70+
+
71+
[source,terminal]
72+
----
73+
$ oc project openshift-logging
74+
----
75+
+
76+
[source,terminal]
77+
----
78+
$ oc adm policy add-cluster-role-to-user collect-application-logs -z collector
79+
----
80+
+
81+
[source,terminal]
82+
----
83+
$ oc adm policy add-cluster-role-to-user collect-audit-logs -z collector
84+
----
85+
+
86+
[source,terminal]
87+
----
88+
$ oc adm policy add-cluster-role-to-user collect-infrastructure-logs -z collector
89+
----
90+
+
91+
[NOTE]
92+
====
93+
The example binds the collector to all three roles (application, infrastructure, and audit). By default, only application and infrastructure logs are collected. To collect audit logs, update your `ClusterLogForwarder` configuration to include them. Assign roles based on the specific log types required for your environment.
94+
====
95+
96+
. Create a `UIPlugin` CR to enable the *Log* section in the *Observe* tab:
97+
+
98+
[source,yaml]
99+
----
100+
apiVersion: observability.openshift.io/v1alpha1
101+
kind: UIPlugin
102+
metadata:
103+
name: logging
104+
spec:
105+
type: Logging
106+
logging:
107+
lokiStack:
108+
name: logging-loki
109+
----
110+
111+
. Create a `ClusterLogForwarder` CR to configure log forwarding:
112+
+
113+
[source,yaml]
114+
----
115+
apiVersion: observability.openshift.io/v1
116+
kind: ClusterLogForwarder
117+
metadata:
118+
name: collector
119+
namespace: openshift-logging
120+
annotations:
121+
observability.openshift.io/tech-preview-otlp-output: "enabled" # <1>
122+
spec:
123+
serviceAccount:
124+
name: collector
125+
outputs:
126+
- name: loki-otlp
127+
type: lokiStack # <2>
128+
lokiStack:
129+
target:
130+
name: logging-loki
131+
namespace: openshift-logging
132+
dataModel: Otel # <3>
133+
authentication:
134+
token:
135+
from: serviceAccount
136+
tls:
137+
ca:
138+
key: service-ca.crt
139+
configMapName: openshift-service-ca.crt
140+
pipelines:
141+
- name: my-pipeline
142+
inputRefs:
143+
- application
144+
- infrastructure
145+
outputRefs:
146+
- loki-otlp
147+
----
148+
<1> Use the annotation to enable the `Otel` data model, which is a Technology Preview feature.
149+
<2> Define the output type as `lokiStack`.
150+
<3> Specifies the OpenTelemetry data model.
151+
+
152+
[NOTE]
153+
====
154+
You cannot use `lokiStack.labelKeys` when `dataModel` is `Otel`. To achieve similar functionality when `dataModel` is `Otel`, refer to "Configuring LokiStack for OTLP data ingestion".
155+
====
156+
157+
.Verification
158+
* Verify that OTLP is functioning correctly by going to *Observe* -> *OpenShift Logging* -> *LokiStack* -> *Writes* in the OpenShift web console, and checking *Distributor - Structured Metadata*.

‎modules/log6x-quickstart-viaq.adoc‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * observability/logging/logging-6.0/log6x-about.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="quick-start-viaq_{context}"]
7+
= Quick start with ViaQ
8+
9+
To use the default ViaQ data model, follow these steps:
10+
11+
.Prerequisites
12+
* Cluster administrator permissions
13+
14+
.Procedure
15+
16+
. Install the {clo}, {loki-op}, and {coo-first} from OperatorHub.
17+
18+
. Create a `LokiStack` custom resource (CR) in the `openshift-logging` namespace:
19+
+
20+
[source,yaml]
21+
----
22+
apiVersion: loki.grafana.com/v1
23+
kind: LokiStack
24+
metadata:
25+
name: logging-loki
26+
namespace: openshift-logging
27+
spec:
28+
managementState: Managed
29+
size: 1x.extra-small
30+
storage:
31+
schemas:
32+
- effectiveDate: '2024-10-01'
33+
version: v13
34+
secret:
35+
name: logging-loki-s3
36+
type: s3
37+
storageClassName: gp3-csi
38+
tenants:
39+
mode: openshift-logging
40+
----
41+
+
42+
[NOTE]
43+
====
44+
Ensure that the `logging-loki-s3` secret is created beforehand. The contents of this secret vary depending on the object storage in use. For more information, see Secrets and TLS Configuration.
45+
====
46+
47+
. Create a service account for the collector:
48+
+
49+
[source,terminal]
50+
----
51+
$ oc create sa collector -n openshift-logging
52+
----
53+
54+
. Allow the collector's service account to write data to the `LokiStack` CR:
55+
+
56+
[source,terminal]
57+
----
58+
$ oc adm policy add-cluster-role-to-user logging-collector-logs-writer -z collector
59+
----
60+
+
61+
[NOTE]
62+
====
63+
The `ClusterRole` resource is created automatically during the Cluster Logging Operator installation and does not need to be created manually.
64+
====
65+
66+
. Allow the collector's service account to collect logs:
67+
+
68+
[source,terminal]
69+
----
70+
$ oc project openshift-logging
71+
----
72+
+
73+
[source,terminal]
74+
----
75+
$ oc adm policy add-cluster-role-to-user collect-application-logs -z collector
76+
----
77+
+
78+
[source,terminal]
79+
----
80+
$ oc adm policy add-cluster-role-to-user collect-audit-logs -z collector
81+
----
82+
+
83+
[source,terminal]
84+
----
85+
$ oc adm policy add-cluster-role-to-user collect-infrastructure-logs -z collector
86+
----
87+
+
88+
[NOTE]
89+
====
90+
The example binds the collector to all three roles (application, infrastructure, and audit), but by default, only application and infrastructure logs are collected. To collect audit logs, update your `ClusterLogForwarder` configuration to include them. Assign roles based on the specific log types required for your environment.
91+
====
92+
93+
. Create a `UIPlugin` CR to enable the *Log* section in the *Observe* tab:
94+
+
95+
[source,yaml]
96+
----
97+
apiVersion: observability.openshift.io/v1alpha1
98+
kind: UIPlugin
99+
metadata:
100+
name: logging
101+
spec:
102+
type: Logging
103+
logging:
104+
lokiStack:
105+
name: logging-loki
106+
----
107+
108+
. Create a `ClusterLogForwarder` CR to configure log forwarding:
109+
+
110+
[source,yaml]
111+
----
112+
apiVersion: observability.openshift.io/v1
113+
kind: ClusterLogForwarder
114+
metadata:
115+
name: collector
116+
namespace: openshift-logging
117+
spec:
118+
serviceAccount:
119+
name: collector
120+
outputs:
121+
- name: default-lokistack
122+
type: lokiStack
123+
lokiStack:
124+
authentication:
125+
token:
126+
from: serviceAccount
127+
target:
128+
name: logging-loki
129+
namespace: openshift-logging
130+
tls:
131+
ca:
132+
key: service-ca.crt
133+
configMapName: openshift-service-ca.crt
134+
pipelines:
135+
- name: default-logstore
136+
inputRefs:
137+
- application
138+
- infrastructure
139+
outputRefs:
140+
- default-lokistack
141+
----
142+
+
143+
[NOTE]
144+
====
145+
The `dataModel` field is optional and left unset (`dataModel: ""`) by default. This allows the Cluster Logging Operator (CLO) to automatically select a data model. Currently, the CLO defaults to the ViaQ model when the field is unset, but this will change in future releases. Specifying `dataModel: ViaQ` ensures the configuration remains compatible if the default changes.
146+
====
147+
148+
.Verification
149+
* Verify that logs are visible in the *Log* section of the *Observe* tab in the OpenShift web console.

‎observability/logging/logging-6.0/log6x-about.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -164,4 +164,4 @@ spec:
164164
- default-lokistack
165165
----
166166

167-
. Verify that logs are visible in the Log section of the Observe tab in the OpenShift web console.
167+
. Verify that logs are visible in the Log section of the Observe tab in the OpenShift web console.

‎observability/logging/logging-6.0/log6x-clf.adoc‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -88,8 +88,6 @@ syslog:: Forwards logs to an external syslog server.
8888

8989
Each output type has its own configuration fields.
9090

91-
include::modules/log6x-configuring-otlp-output.adoc[leveloffset=+1]
92-
9391
=== Pipelines
9492

9593
Pipelines are configured in an array under `spec.pipelines`. Each pipeline must have a unique name and consists of:

0 commit comments

Comments
 (0)