Skip to content

Commit e7887bf

Browse files
JSticklerJStickler
authored
Merge pull request #40729 from JStickler/OSSMDOC-94
OSSMDOC-94: Document OTEL Collector configuration for Tech Preview.
2 parents c12b643 + 8c53caf commit e7887bf

21 files changed

+161
-72
lines changed

‎_topic_maps/_topic_map.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2839,7 +2839,7 @@ Topics:
28392839
- Name: Installing distributed tracing
28402840
File: distr-tracing-installing
28412841
- Name: Configuring the distributed tracing platform
2842-
File: distr-tracing-deploying
2842+
File: distr-tracing-deploying-jaeger
28432843
- Name: Configuring distributed tracing data collection
28442844
File: distr-tracing-deploying-otel
28452845
- Name: Upgrading distributed tracing

distr_tracing/distr_tracing_install/distr-tracing-deploying.adoc renamed to distr_tracing/distr_tracing_install/distr-tracing-deploying-jaeger.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
[id="distr-tracing-deploying"]
33
= Configuring and deploying distributed tracing
44
include::modules/distr-tracing-document-attributes.adoc[]
5-
:context: deploying-distributed-tracing
5+
:context: deploying-distr-tracing-platform
66

77
toc::[]
88

‎distr_tracing/distr_tracing_install/distr-tracing-deploying-otel.adoc‎

Lines changed: 3 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -2,19 +2,12 @@
22
[id="distr-tracing-deploying-otel"]
33
= Configuring and deploying distributed tracing data collection
44
include::modules/distr-tracing-document-attributes.adoc[]
5-
:context: deploying-data-collection
5+
:context: deploying-distr-tracing-data-collection
66

77
toc::[]
88

9-
The {OTELName} Operator uses a custom resource definition (CRD) file that defines the architecture and configuration settings to use when creating and deploying the {OTELShortName} resources. You can either install the default configuration or modify the file to better suit your business requirements.
10-
11-
[IMPORTANT]
12-
====
13-
The {OTELName} Operator is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production.
14-
These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.
15-
For more information about the support scope of Red Hat Technology Preview features, see https://access.redhat.com/support/offerings/techpreview/.
16-
====
9+
The {OTELName} Operator uses a custom resource definition (CRD) file that defines the architecture and configuration settings to be used when creating and deploying the {OTELName} resources. You can either install the default configuration or modify the file to better suit your business requirements.
1710

1811
// The following include statements pull in the module files that comprise the assembly.
1912

20-
include::modules/distr-tracing-deploy-otel-collector.adoc[leveloffset=+1]
13+
include::modules/distr-tracing-config-otel-collector.adoc[leveloffset=+1]

‎modules/distr-tracing-architecture.adoc‎

Lines changed: 14 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -3,22 +3,28 @@ This module included in the following assemblies:
33
-service_mesh/v2x/ossm-architecture.adoc
44
-dist_tracing_arch/distr-tracing-architecture.adoc
55
////
6-
6+
:_content-type: CONCEPT
77
[id="distributed-tracing-architecture_{context}"]
88
= {DTProductName} architecture
99

1010
{DTProductName} is made up of several components that work together to collect, store, and display tracing data.
1111

12-
* *Client* (Jaeger client, Tracer, Reporter, instrumented application, client libraries)- The {JaegerShortName} clients are language-specific implementations of the OpenTracing API. They can be used to instrument applications for distributed tracing either manually or with a variety of existing open source frameworks, such as Camel (Fuse), Spring Boot (RHOAR), MicroProfile (RHOAR/Thorntail), Wildfly (EAP), and many more, that are already integrated with OpenTracing.
12+
* *{JaegerName}* - This component is based on the open source link:https://www.jaegertracing.io/[Jaeger project].
13+
14+
** *Client* (Jaeger client, Tracer, Reporter, instrumented application, client libraries)- The {JaegerShortName} clients are language-specific implementations of the OpenTracing API. They can be used to instrument applications for distributed tracing either manually or with a variety of existing open source frameworks, such as Camel (Fuse), Spring Boot (RHOAR), MicroProfile (RHOAR/Thorntail), Wildfly (EAP), and many more, that are already integrated with OpenTracing.
15+
16+
** *Agent* (Jaeger agent, Server Queue, Processor Workers) - The {JaegerShortName} agent is a network daemon that listens for spans sent over User Datagram Protocol (UDP), which it batches and sends to the Collector. The agent is meant to be placed on the same host as the instrumented application. This is typically accomplished by having a sidecar in container environments such as Kubernetes.
17+
18+
** *Jaeger Collector* (Collector, Queue, Workers) - Similar to the Jaeger agent, the Jaeger Collector receives spans and places them in an internal queue for processing. This allows the Jaeger Collector to return immediately to the client/agent instead of waiting for the span to make its way to the storage.
1319

14-
* *Agent* (Jaeger agent, Server Queue, Processor Workers) - The {JaegerShortName} agent is a network daemon that listens for spans sent over User Datagram Protocol (UDP), which it batches and sends to the Collector. The agent is meant to be placed on the same host as the instrumented application. This is typically accomplished by having a sidecar in container environments such as Kubernetes.
20+
** *Storage* (Data Store) - Collectors require a persistent storage backend. {JaegerName} has a pluggable mechanism for span storage. Note that for this release, the only supported storage is Elasticsearch.
1521

16-
* *Collector* (Jaeger Collector, Queue, Workers) - Similar to the agent, the Collector receives spans and places them in an internal queue for processing. This allows the Collector to return immediately to the client/agent instead of waiting for the span to make its way to the storage.
22+
** *Query* (Query Service) - Query is a service that retrieves traces from storage.
1723

18-
* *Storage* (Data Store) - Collectors require a persistent storage backend. {JaegerName} has a pluggable mechanism for span storage. Note that for this release, the only supported storage is Elasticsearch.
24+
** *Ingester* (Ingester Service) - {DTProductName} can use Apache Kafka as a buffer between the Collector and the actual Elasticsearch backing storage. Ingester is a service that reads data from Kafka and writes to the Elasticsearch storage backend.
1925

20-
* *Query* (Query Service) - Query is a service that retrieves traces from storage.
26+
** *Jaeger Console* – With the {JaegerName} user interface, you can visualize your distributed tracing data. On the Search page, you can find traces and explore details of the spans that make up an individual trace.
2127

22-
* *Ingester* (Ingester Service) - {DTProductName} can use Apache Kafka as a buffer between the Collector and the actual Elasticsearch backing storage. Ingester is a service that reads data from Kafka and writes to the Elasticsearch storage backend.
28+
* *{OTELName}* - This component is based on the open source link:https://opentelemetry.io/[OpenTelemetry project].
2329
24-
* *Jaeger Console* – With the {JaegerName} user interface, you can visualize your distributed tracing data. On the Search page, you can find traces and explore details of the spans that make up an individual trace.
30+
** *OpenTelemetry Collector* - The OpenTelemetry Collector is a vendor-agnostic way to receive, process, and export telemetry data. The OpenTelemetry Collector supports open-source observability data formats, for example, Jaeger and Prometheus, sending to one or more open-source or commercial back-ends. The Collector is the default location instrumentation libraries export their telemetry data.

‎modules/distr-tracing-config-default.adoc‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
////
22
This module included in the following assemblies:
3-
- distr_tracing_install/distr-tracing-deploying.adoc
3+
- distr_tracing_install/distr-tracing-deploying-jaeger.adoc
44
////
5-
5+
:_content-type: REFERENCE
66
[id="distr-tracing-config-default_{context}"]
77
= Distributed tracing default configuration options
88

@@ -109,10 +109,8 @@ spec:
109109
|Configuration options that define the Ingester service.
110110
|
111111
|
112-
113112
|===
114113

115-
116114
The following example YAML is the minimum required to create a {JaegerName} deployment using the default settings.
117115

118116
.Example minimum required dist-tracing-all-in-one.yaml

‎modules/distr-tracing-config-ingester.adoc‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
////
22
This module included in the following assemblies:
3-
- distr_tracing_install/distr-tracing-deploying.adoc
3+
- distr_tracing_install/distr-tracing-deploying-jaeger.adoc
44
////
5-
5+
:_content-type: REFERENCE
66
[id="distr-tracing-config-ingester_{context}"]
77
= Ingester configuration options
88

‎modules/distr-tracing-config-jaeger-collector.adoc‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
////
22
This module included in the following assemblies:
3-
- distr_tracing_install/distr-tracing-deploying.adoc
3+
- distr_tracing_install/distr-tracing-deploying-jaeger.adoc
44
////
5-
5+
:_content-type: REFERENCE
66
[id="distr-tracing-config-jaeger-collector_{context}"]
77
= Jaeger Collector configuration options
88

‎modules/distr-tracing-config-otel-collector.adoc‎

Lines changed: 112 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,39 +1,132 @@
11
////
22
This module included in the following assemblies:
3-
-distr_tracing_install/distributed-tracing-deploying.adoc
4-
5-
STUB TOPIC for documenting OTEL collector options (Duplicated from Jaeger Collector)
3+
-distr_tracing_install/distributed-tracing-deploying-otel.adoc
64
////
7-
5+
:_content-type: REFERENCE
86
[id="distributed-tracing-config-otel-collector_{context}"]
97
= OpenTelemetry Collector configuration options
108

11-
#TECH PREVIEW BOILERPLATE HERE#
12-
#What is the actual Operator name?#
9+
[IMPORTANT]
10+
====
11+
The {OTELName} Operator is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production.
12+
These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.
13+
For more information about the support scope of Red Hat Technology Preview features, see https://access.redhat.com/support/offerings/techpreview/.
14+
====
15+
16+
The OpenTelemetry Collector consists of three components that access telemetry data:
17+
18+
* *Receivers* - A receiver, which can be push or pull based, is how data gets into the Collector. Generally, a receiver accepts data in a specified format, translates it into the internal format and passes it to processors and exporters defined in the applicable pipelines. By default, no receivers are configured. One or more receivers must be configured. Receivers may support one or more data sources.
19+
20+
* *Processors* - (Optional) Processors are run on data between being received and being exported. By default, no processors are enabled. Processors must be enabled for every data source. Not all processors support all data sources. Depending on the data source, it may be recommended that multiple processors be enabled. In addition, it is important to note that the order of processors matters.
21+
22+
* *Exporters* - An exporter, which can be push or pull based, is how you send data to one or more backends/destinations. By default, no exporters are configured. One or more exporters must be configured. Exporters may support one or more data sources. Exporters may come with default settings, but many require configuration to specify at least the destination and security settings.
23+
24+
You can define multiple instances of components in a custom resource YAML file. Once configured, these components must be enabled through pipelines defined in the `spec.config.service` section of the YAML file. As a best practice you should only enable the components that you need.
1325

14-
The OpenTelemetry Collector is the component responsible for receiving the spans that were captured by the tracer and writing them to an Elasticsearch persistent storage when using the `production` strategy, or to AMQ Streams when using the `streaming` strategy.
26+
.sample OpenTelemetry collector custom resource file
27+
[source,yaml]
28+
----
29+
apiVersion: opentelemetry.io/v1alpha1
30+
kind: OpenTelemetryCollector
31+
metadata:
32+
name: cluster-collector
33+
namespace: tracing-system
34+
spec:
35+
mode: deployment
36+
config: |
37+
receivers:
38+
otlp:
39+
protocols:
40+
grpc:
41+
http:
42+
processors:
43+
exporters:
44+
jaeger:
45+
endpoint: jaeger-production-collector-headless.tracing-system.svc:14250
46+
tls:
47+
ca_file: "/var/run/secrets/kubernetes.io/serviceaccount/service-ca.crt"
48+
service:
49+
pipelines:
50+
traces:
51+
receivers: [otlp]
52+
processors: []
53+
exporters: [jaeger]
54+
----
1555

16-
The Collectors are stateless and thus many instances of OpenTelemetry Collector can be run in parallel. Collectors require almost no configuration, except for the location of the Elasticsearch cluster.
56+
[NOTE]
57+
====
58+
If a component is configured, but not defined within the `service` section then it is not enabled.
59+
====
1760

1861
.Parameters used by the Operator to define the OpenTelemetry Collector
1962
[options="header"]
20-
[cols="l, a, a"]
63+
[cols="l, a, a, a"]
2164
|===
22-
|Parameter |Description |Values
65+
|Parameter |Description |Values |Default
66+
|receivers:
67+
|A receiver is how data gets into the Collector. By default, no receivers are configured. There must be at least one enabled receiver for a configuration to be considered valid. Receivers are enabled by being added to a pipeline.
68+
|`otlp`, `jaeger`
69+
|None
70+
71+
|receivers:
72+
otlp:
73+
|The `oltp` and `jaeger` receivers come with default settings, specifying the name of the receiver is enough to configure it.
2374
|
2475
|
76+
77+
|processors:
78+
|Processors run on data between being received and being exported. By default, no processors are enabled.
2579
|
26-
|===
80+
|None
2781

82+
|exporters:
83+
|An exporter sends data to one or more backends/destinations. By default, no exporters are configured. There must be at least one enabled exporter for a configuration to be considered valid. Exporters are enabled by being added to a pipeline. Exporters may come with default settings, but many require configuration to specify at least the destination and security settings.
84+
|`logging`, `jaeger`
85+
|None
2886

29-
.Parameters passed to the Collector
30-
[options="header"]
31-
[cols="l, a, a"]
32-
|===
33-
|Parameter |Description |Values
34-
|spec:
35-
collector:
36-
options: {}
87+
|exporters:
88+
jaeger:
89+
endpoint:
90+
91+
|The `jaeger` exporter’s endpoint must be of the form `<name>-collector-headless.<namespace>.svc`, with the name and namespace of the Jaeger deployment, for a secure connection to be established.
3792
|
3893
|
94+
95+
|exporters:
96+
jaeger:
97+
tls:
98+
ca_file:
99+
|Path to the CA certificate. For a client this verifies the server certificate. For a server this verifies client certificates. If empty uses system root CA.
100+
|
101+
|
102+
103+
|service:
104+
pipelines:
105+
|Components are enabled by adding them to a pipeline under `services.pipeline`.
106+
|
107+
|
108+
109+
|service:
110+
pipelines:
111+
traces:
112+
receivers:
113+
|You enable receivers for tracing by adding them under `service.pipelines.traces`.
114+
|
115+
|None
116+
117+
|service:
118+
pipelines:
119+
traces:
120+
processors:
121+
|You enable processors for tracing by adding them under `service.pipelines.traces`.
122+
|
123+
|None
124+
125+
|service:
126+
pipelines:
127+
traces:
128+
exporters:
129+
|You enable exporters for tracing by adding them under `service.pipelines.traces`.
130+
|
131+
|None
39132
|===

‎modules/distr-tracing-config-query.adoc‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
////
22
This module included in the following assemblies:
3-
- distr_tracing_install/distr-tracing-deploying.adoc
3+
- distr_tracing_install/distr-tracing-deploying-jaeger.adoc
44
////
5-
5+
:_content-type: REFERENCE
66
[id="distr-tracing-config-query_{context}"]
77
= Query configuration options
88

@@ -20,7 +20,6 @@ Query is a service that retrieves traces from storage and hosts the user interfa
2020
|Specifies the number of Query replicas to create.
2121
|Integer, for example, `2`
2222
|
23-
2423
|===
2524

2625

‎modules/distr-tracing-config-sampling.adoc‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
////
22
This module included in the following assemblies:
3-
- distr_tracing_install/distr-tracing-deploying.adoc
3+
- distr_tracing_install/distr-tracing-deploying-jaeger.adoc
44
////
5-
5+
:_content-type: REFERENCE
66
[id="distr-tracing-config-sampling_{context}"]
77
= Distributed tracing sampling configuration options
88

0 commit comments

Comments
 (0)