Skip to content

Commit 94aa5b6

Browse files
max-cxmax-cx
authored
Merge pull request #101769 from max-cx/OBSDOCS-2751
OBSDOCS-2751: Modularize otel-collector-extensions.adoc
2 parents 6d74e80 + 48471cf commit 94aa5b6

9 files changed

+477
-341
lines changed

‎modules/otel-extensions-bearertokenauth-extension.adoc‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * observability/otel/otel-collector/otel-collector-extensions.adoc
4+
5+
:_mod-docs-content-type: REFERENCE
6+
[id="otel-extensions-bearertokenauth-extension_{context}"]
7+
= BearerTokenAuth Extension
8+
9+
[role="_abstract"]
10+
The BearerTokenAuth Extension is an authenticator for receivers and exporters that are based on the HTTP and the gRPC protocol.
11+
You can use the OpenTelemetry Collector custom resource to configure client authentication and server authentication for the BearerTokenAuth Extension on the receiver and exporter side.
12+
This extension supports traces, metrics, and logs.
13+
14+
.OpenTelemetry Collector custom resource with client and server authentication configured for the BearerTokenAuth Extension
15+
[source,yaml]
16+
----
17+
# ...
18+
config:
19+
extensions:
20+
bearertokenauth:
21+
scheme: "Bearer" # <1>
22+
token: "<token>" # <2>
23+
filename: "<token_file>" # <3>
24+
25+
receivers:
26+
otlp:
27+
protocols:
28+
http:
29+
auth:
30+
authenticator: bearertokenauth # <4>
31+
exporters:
32+
otlp:
33+
auth:
34+
authenticator: bearertokenauth # <5>
35+
36+
service:
37+
extensions: [bearertokenauth]
38+
pipelines:
39+
traces:
40+
receivers: [otlp]
41+
exporters: [otlp]
42+
# ...
43+
----
44+
<1> You can configure the BearerTokenAuth Extension to send a custom `scheme`. The default is `Bearer`.
45+
<2> You can add the BearerTokenAuth Extension token as metadata to identify a message.
46+
<3> Path to a file that contains an authorization token that is transmitted with every message.
47+
<4> You can assign the authenticator configuration to an OTLP Receiver.
48+
<5> You can assign the authenticator configuration to an OTLP Exporter.

‎modules/otel-extensions-filestorage-extension.adoc‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * observability/otel/otel-collector/otel-collector-extensions.adoc
4+
5+
:_mod-docs-content-type: REFERENCE
6+
[id="otel-extensions-filestorage-extension_{context}"]
7+
= File Storage Extension
8+
9+
[role="_abstract"]
10+
The File Storage Extension supports traces, metrics, and logs. This extension can persist the state to the local file system. This extension persists the sending queue for the OpenTelemetry Protocol (OTLP) exporters that are based on the HTTP and the gRPC protocols. This extension requires the read and write access to a directory. This extension can use a default directory, but the default directory must already exist.
11+
12+
:FeatureName: The File Storage Extension
13+
include::snippets/technology-preview.adoc[]
14+
15+
.OpenTelemetry Collector custom resource with a configured File Storage Extension that persists an OTLP sending queue
16+
[source,yaml]
17+
----
18+
# ...
19+
config:
20+
extensions:
21+
file_storage/all_settings:
22+
directory: /var/lib/otelcol/mydir # <1>
23+
timeout: 1s # <2>
24+
compaction:
25+
on_start: true # <3>
26+
directory: /tmp/ # <4>
27+
max_transaction_size: 65_536 # <5>
28+
fsync: false # <6>
29+
30+
exporters:
31+
otlp:
32+
sending_queue:
33+
storage: file_storage/all_settings # <7>
34+
35+
service:
36+
extensions: [file_storage/all_settings] # <8>
37+
pipelines:
38+
traces:
39+
receivers: [otlp]
40+
exporters: [otlp]
41+
# ...
42+
----
43+
<1> Specifies the directory in which the telemetry data is stored.
44+
<2> Specifies the timeout time interval for opening the stored files.
45+
<3> Starts compaction when the Collector starts. If omitted, the default is `+false+`.
46+
<4> Specifies the directory in which the compactor stores the telemetry data.
47+
<5> Defines the maximum size of the compaction transaction. To ignore the transaction size, set to zero. If omitted, the default is `+65536+` bytes.
48+
<6> When set, forces the database to perform an `fsync` call after each write operation. This helps to ensure database integrity if there is an interruption to the database process, but at the cost of performance.
49+
<7> Buffers the OTLP Exporter data on the local file system.
50+
<8> Starts the File Storage Extension by the Collector.

‎modules/otel-extensions-healthcheck-extension.adoc‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * observability/otel/otel-collector/otel-collector-extensions.adoc
4+
5+
:_mod-docs-content-type: REFERENCE
6+
[id="otel-extensions-healthcheck-extension_{context}"]
7+
= Health Check Extension
8+
9+
[role="_abstract"]
10+
The Health Check Extension provides an HTTP URL for checking the status of the OpenTelemetry Collector. You can use this extension as a liveness and readiness probe on OpenShift.
11+
12+
:FeatureName: The Health Check Extension
13+
include::snippets/technology-preview.adoc[]
14+
15+
.OpenTelemetry Collector custom resource with the configured Health Check Extension
16+
[source,yaml]
17+
----
18+
# ...
19+
config:
20+
extensions:
21+
health_check:
22+
endpoint: "0.0.0.0:13133" # <1>
23+
tls: # <2>
24+
ca_file: "/path/to/ca.crt"
25+
cert_file: "/path/to/cert.crt"
26+
key_file: "/path/to/key.key"
27+
path: "/health/status" # <3>
28+
check_collector_pipeline: # <4>
29+
enabled: true # <5>
30+
interval: "5m" # <6>
31+
exporter_failure_threshold: 5 # <7>
32+
33+
receivers:
34+
otlp:
35+
protocols:
36+
http: {}
37+
38+
exporters:
39+
debug: {}
40+
41+
service:
42+
extensions: [health_check]
43+
pipelines:
44+
traces:
45+
receivers: [otlp]
46+
exporters: [debug]
47+
# ...
48+
----
49+
<1> The target IP address for publishing the health check status. The default is `0.0.0.0:13133`.
50+
<2> The TLS server-side configuration. Defines paths to TLS certificates. If omitted, the TLS is disabled.
51+
<3> The path for the health check server. The default is `/`.
52+
<4> Settings for the Collector pipeline health check.
53+
<5> Enables the Collector pipeline health check. The default is `false`.
54+
<6> The time interval for checking the number of failures. The default is `5m`.
55+
<7> The threshold of multiple failures until which a container is still marked as healthy. The default is `5`.

‎modules/otel-extensions-jaegerremotesampling-extension.adoc‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * observability/otel/otel-collector/otel-collector-extensions.adoc
4+
5+
:_mod-docs-content-type: REFERENCE
6+
[id="otel-extensions-jaegerremotesampling-extension_{context}"]
7+
= Jaeger Remote Sampling Extension
8+
9+
[role="_abstract"]
10+
The Jaeger Remote Sampling Extension enables serving sampling strategies after Jaeger's remote sampling API. You can configure this extension to proxy requests to a backing remote sampling server such as a Jaeger collector down the pipeline or to a static JSON file from the local file system.
11+
12+
:FeatureName: The Jaeger Remote Sampling Extension
13+
include::snippets/technology-preview.adoc[]
14+
15+
.OpenTelemetry Collector custom resource with a configured Jaeger Remote Sampling Extension
16+
[source,yaml]
17+
----
18+
# ...
19+
config:
20+
extensions:
21+
jaegerremotesampling:
22+
source:
23+
reload_interval: 30s # <1>
24+
remote:
25+
endpoint: jaeger-collector:14250 # <2>
26+
file: /etc/otelcol/sampling_strategies.json # <3>
27+
28+
receivers:
29+
otlp:
30+
protocols:
31+
http: {}
32+
33+
exporters:
34+
debug: {}
35+
36+
service:
37+
extensions: [jaegerremotesampling]
38+
pipelines:
39+
traces:
40+
receivers: [otlp]
41+
exporters: [debug]
42+
# ...
43+
----
44+
<1> The time interval at which the sampling configuration is updated.
45+
<2> The endpoint for reaching the Jaeger remote sampling strategy provider.
46+
<3> The path to a local file that contains a sampling strategy configuration in the JSON format.
47+
48+
.Example of a Jaeger Remote Sampling strategy file
49+
[source,json]
50+
----
51+
{
52+
"service_strategies": [
53+
{
54+
"service": "foo",
55+
"type": "probabilistic",
56+
"param": 0.8,
57+
"operation_strategies": [
58+
{
59+
"operation": "op1",
60+
"type": "probabilistic",
61+
"param": 0.2
62+
},
63+
{
64+
"operation": "op2",
65+
"type": "probabilistic",
66+
"param": 0.4
67+
}
68+
]
69+
},
70+
{
71+
"service": "bar",
72+
"type": "ratelimiting",
73+
"param": 5
74+
}
75+
],
76+
"default_strategy": {
77+
"type": "probabilistic",
78+
"param": 0.5,
79+
"operation_strategies": [
80+
{
81+
"operation": "/health",
82+
"type": "probabilistic",
83+
"param": 0.0
84+
},
85+
{
86+
"operation": "/metrics",
87+
"type": "probabilistic",
88+
"param": 0.0
89+
}
90+
]
91+
}
92+
}
93+
----

‎modules/otel-extensions-oauth2client-extension.adoc‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * observability/otel/otel-collector/otel-collector-extensions.adoc
4+
5+
:_mod-docs-content-type: REFERENCE
6+
[id="otel-extensions-oauth2client-extension_{context}"]
7+
= OAuth2Client Extension
8+
9+
[role="_abstract"]
10+
The OAuth2Client Extension is an authenticator for exporters that are based on the HTTP and the gRPC protocol.
11+
Client authentication for the OAuth2Client Extension is configured in a separate section in the OpenTelemetry Collector custom resource.
12+
This extension supports traces, metrics, and logs.
13+
14+
:FeatureName: The OAuth2Client Extension
15+
include::snippets/technology-preview.adoc[]
16+
17+
.OpenTelemetry Collector custom resource with client authentication configured for the OAuth2Client Extension
18+
[source,yaml]
19+
----
20+
# ...
21+
config:
22+
extensions:
23+
oauth2client:
24+
client_id: <client_id> # <1>
25+
client_secret: <client_secret> # <2>
26+
endpoint_params: # <3>
27+
audience: <audience>
28+
token_url: https://example.com/oauth2/default/v1/token # <4>
29+
scopes: ["api.metrics"] # <5>
30+
# tls settings for the token client
31+
tls: # <6>
32+
insecure: true # <7>
33+
ca_file: /var/lib/mycert.pem # <8>
34+
cert_file: <cert_file> # <9>
35+
key_file: <key_file> # <10>
36+
timeout: 2s # <11>
37+
38+
receivers:
39+
otlp:
40+
protocols:
41+
http: {}
42+
43+
exporters:
44+
otlp:
45+
auth:
46+
authenticator: oauth2client # <12>
47+
48+
service:
49+
extensions: [oauth2client]
50+
pipelines:
51+
traces:
52+
receivers: [otlp]
53+
exporters: [otlp]
54+
# ...
55+
----
56+
<1> Client identifier, which is provided by the identity provider.
57+
<2> Confidential key used to authenticate the client to the identity provider.
58+
<3> Further metadata, in the key-value pair format, which is transferred during authentication. For example, `audience` specifies the intended audience for the access token, indicating the recipient of the token.
59+
<4> The URL of the OAuth2 token endpoint, where the Collector requests access tokens.
60+
<5> The scopes define the specific permissions or access levels requested by the client.
61+
<6> The Transport Layer Security (TLS) settings for the token client, which is used to establish a secure connection when requesting tokens.
62+
<7> When set to `true`, configures the Collector to use an insecure or non-verified TLS connection to call the configured token endpoint.
63+
<8> The path to a Certificate Authority (CA) file that is used to verify the server's certificate during the TLS handshake.
64+
<9> The path to the client certificate file that the client must use to authenticate itself to the OAuth2 server if required.
65+
<10> The path to the client's private key file that is used with the client certificate if needed for authentication.
66+
<11> Sets a timeout for the token client's request.
67+
<12> You can assign the authenticator configuration to an OTLP exporter.

‎modules/otel-extensions-oidcauth-extension.adoc‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * observability/otel/otel-collector/otel-collector-extensions.adoc
4+
5+
:_mod-docs-content-type: REFERENCE
6+
[id="otel-extensions-oidcauth-extension_{context}"]
7+
= OIDC Auth Extension
8+
9+
[role="_abstract"]
10+
The OIDC Auth Extension authenticates incoming requests to receivers by using the OpenID Connect (OIDC) protocol.
11+
It validates the ID token in the authorization header against the issuer and updates the authentication context of the incoming request.
12+
13+
:FeatureName: The OIDC Auth Extension
14+
include::snippets/technology-preview.adoc[]
15+
16+
.OpenTelemetry Collector custom resource with the configured OIDC Auth Extension
17+
[source,yaml]
18+
----
19+
# ...
20+
config:
21+
extensions:
22+
oidc:
23+
attribute: authorization # <1>
24+
issuer_url: https://example.com/auth/realms/opentelemetry # <2>
25+
issuer_ca_path: /var/run/tls/issuer.pem # <3>
26+
audience: otel-collector # <4>
27+
username_claim: email # <5>
28+
receivers:
29+
otlp:
30+
protocols:
31+
grpc:
32+
auth:
33+
authenticator: oidc
34+
exporters:
35+
debug: {}
36+
service:
37+
extensions: [oidc]
38+
pipelines:
39+
traces:
40+
receivers: [otlp]
41+
exporters: [debug]
42+
# ...
43+
----
44+
<1> The name of the header that contains the ID token. The default name is `authorization`.
45+
<2> The base URL of the OIDC provider.
46+
<3> Optional: The path to the issuer's CA certificate.
47+
<4> The audience for the token.
48+
<5> The name of the claim that contains the username. The default name is `sub`.

0 commit comments

Comments
 (0)