mirror of
https://github.com/openshift/openshift-docs.git
synced 2026-02-05 12:46:18 +01:00
564 lines
15 KiB
Plaintext
564 lines
15 KiB
Plaintext
// Module included in the following assemblies:
|
|
//
|
|
// * observability/otel/otel-configuration-of-instrumentation.adoc
|
|
|
|
:_mod-docs-content-type: REFERENCE
|
|
[id="otel-instrumentation-config_{context}"]
|
|
= OpenTelemetry instrumentation configuration options
|
|
|
|
The {OTELName} injects and configures the OpenTelemetry auto-instrumentation libraries into your workloads. Currently, the {OTELName} supports injecting instrumentation libraries for Go, Java, Node.js, Python, .NET, and the Apache HTTP Server (`httpd`).
|
|
|
|
[IMPORTANT]
|
|
====
|
|
The {OTELOperator} only supports the injection mechanism of the instrumentation libraries but does not support instrumentation libraries or upstream images. Customers can build their own instrumentation images or use community images.
|
|
====
|
|
|
|
[id="otel-instrumentation-options_{context}"]
|
|
== Instrumentation options
|
|
|
|
Instrumentation options are specified in an `Instrumentation` custom resource (CR).
|
|
|
|
.Sample `Instrumentation` CR
|
|
[source,yaml]
|
|
----
|
|
apiVersion: opentelemetry.io/v1alpha1
|
|
kind: Instrumentation
|
|
metadata:
|
|
name: instrumentation
|
|
spec:
|
|
env:
|
|
- name: OTEL_EXPORTER_OTLP_TIMEOUT
|
|
value: "20"
|
|
exporter:
|
|
endpoint: http://production-collector.observability.svc.cluster.local:4317
|
|
propagators:
|
|
- tracecontext
|
|
- baggage
|
|
sampler:
|
|
type: parentbased_traceidratio
|
|
argument: "1"
|
|
python: # <1>
|
|
env: # <2>
|
|
- name: OTEL_EXPORTER_OTLP_ENDPOINT
|
|
value: http://production-collector.observability.svc.cluster.local:4318
|
|
dotnet: # <3>
|
|
env: # <4>
|
|
- name: OTEL_EXPORTER_OTLP_ENDPOINT
|
|
value: http://production-collector.observability.svc.cluster.local:4318
|
|
go: # <5>
|
|
env: # <6>
|
|
- name: OTEL_EXPORTER_OTLP_ENDPOINT
|
|
value: http://production-collector.observability.svc.cluster.local:4318
|
|
----
|
|
<1> Python auto-instrumentation uses protocol buffers over HTTP (HTTP/proto or HTTP/protobuf) by default.
|
|
<2> Required if endpoint is set to `:4317`.
|
|
<3> .NET auto-instrumentation uses protocol buffers over HTTP (HTTP/proto or HTTP/protobuf) by default.
|
|
<4> Required if endpoint is set to `:4317`.
|
|
<5> Go auto-instrumentation uses protocol buffers over HTTP (HTTP/proto or HTTP/protobuf) by default.
|
|
<6> Required if endpoint is set to `:4317`.
|
|
+
|
|
For more information about procol buffers, see link:https://protobuf.dev/overview/[Overview] (Protocol Buffers Documentation).
|
|
|
|
//[cols=",,",options="header",]
|
|
|
|
.Parameters used by the Operator to define the instrumentation
|
|
[options="header"]
|
|
[cols="a, a, a"]
|
|
|===
|
|
|Parameter |Description |Values
|
|
|
|
|`env`
|
|
|Definition of common environment variables for all instrumentation types.
|
|
|
|
|
|
|
|`exporter`
|
|
|Exporter configuration.
|
|
|
|
|
|
|
|`propagators`
|
|
|Propagators defines inter-process context propagation configuration.
|
|
|`tracecontext`, `baggage`, `b3`, `b3multi`, `jaeger`, `ottrace`, `none`
|
|
|
|
|`resource`
|
|
|Resource attributes configuration.
|
|
|
|
|
|
|
|`sampler`
|
|
|Sampling configuration.
|
|
|
|
|
|
|
|`apacheHttpd`
|
|
|Configuration for the Apache HTTP Server instrumentation.
|
|
|
|
|
|
|
|`dotnet`
|
|
|Configuration for the .NET instrumentation.
|
|
|
|
|
|
|
|`go`
|
|
|Configuration for the Go instrumentation.
|
|
|
|
|
|
|
|`java`
|
|
|Configuration for the Java instrumentation.
|
|
|
|
|
|
|
|`nodejs`
|
|
|Configuration for the Node.js instrumentation.
|
|
|
|
|
|
|
|`python`
|
|
|Configuration for the Python instrumentation.
|
|
|
|
|
|
|
Depending on the programming language, environment variables might not work for configuring telemetry. For the SDKs that do not support environment variable configuration, you must add a similar configuration directly in the code. For more information, see link:https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/[Environment Variable Specification] (OpenTelemetry Documentation).
|
|
|
|
|===
|
|
|
|
.Default protocol for auto-instrumentation
|
|
[options="header"]
|
|
[cols="a, a"]
|
|
|===
|
|
|Auto-instrumentation | Default protocol
|
|
|
|
|Java 1.x
|
|
|`otlp/grpc`
|
|
|
|
|Java 2.x
|
|
|`otlp/http`
|
|
|
|
|Python
|
|
|`otlp/http`
|
|
|
|
|+.NET+
|
|
|`otlp/http`
|
|
|
|
|Go
|
|
|`otlp/http`
|
|
|
|
|Apache HTTP Server
|
|
|`otlp/grpc`
|
|
|
|
|===
|
|
|
|
[id="otel-configuration-of-opentelemetry-sdk-variables_{context}"]
|
|
== Configuration of the OpenTelemetry SDK variables
|
|
|
|
You can use the `instrumentation.opentelemetry.io/inject-sdk` annotation in the OpenTelemetry Collector custom resource to instruct the {OTELName} Operator to inject some of the following OpenTelemetry SDK environment variables, depending on the `Instrumentation` CR, into your pod:
|
|
|
|
* `OTEL_SERVICE_NAME`
|
|
* `OTEL_TRACES_SAMPLER`
|
|
* `OTEL_TRACES_SAMPLER_ARG`
|
|
* `OTEL_PROPAGATORS`
|
|
* `OTEL_RESOURCE_ATTRIBUTES`
|
|
* `OTEL_EXPORTER_OTLP_ENDPOINT`
|
|
* `OTEL_EXPORTER_OTLP_CERTIFICATE`
|
|
* `OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE`
|
|
* `OTEL_EXPORTER_OTLP_CLIENT_KEY`
|
|
|
|
.Values for the `instrumentation.opentelemetry.io/inject-sdk` annotation
|
|
[cols="a, a"]
|
|
|===
|
|
| Value | Description
|
|
|
|
|`"true"`
|
|
|Injects the `+Instrumentation+` resource with the default name from the current namespace.
|
|
|
|
|`"false"`
|
|
|Injects no `+Instrumentation+` resource.
|
|
|
|
|`"<instrumentation_name>"`
|
|
|Specifies the name of the `+Instrumentation+` resource to inject from the current namespace.
|
|
|
|
|`"<namespace>/<instrumentation_name>"`
|
|
|Specifies the name of the `+Instrumentation+` resource to inject from another namespace.
|
|
|
|
|===
|
|
|
|
[id="otel-instrumentation-options_exporter_{context}"]
|
|
== Exporter configuration
|
|
|
|
Although the `Instrumentation` custom resource supports setting up one or more exporters per signal, auto-instrumentation configures only the OTLP Exporter. So you must configure the endpoint to point to the OTLP Receiver on the Collector.
|
|
|
|
.Sample exporter TLS CA configuration using a config map
|
|
[source,yaml]
|
|
----
|
|
apiVersion: opentelemetry.io/v1alpha1
|
|
kind: Instrumentation
|
|
# ...
|
|
spec
|
|
# ...
|
|
exporter:
|
|
endpoint: https://production-collector.observability.svc.cluster.local:4317 # <1>
|
|
tls:
|
|
configMapName: ca-bundle # <2>
|
|
ca_file: service-ca.crt # <3>
|
|
# ...
|
|
----
|
|
<1> Specifies the OTLP endpoint using the HTTPS scheme and TLS.
|
|
<2> Specifies the name of the config map. The config map must already exist in the namespace of the pod injecting the auto-instrumentation.
|
|
<3> Points to the CA certificate in the config map or the absolute path to the certificate if the certificate is already present in the workload file system.
|
|
|
|
.Sample exporter mTLS configuration using a Secret
|
|
[source,yaml]
|
|
----
|
|
apiVersion: opentelemetry.io/v1alpha1
|
|
kind: Instrumentation
|
|
# ...
|
|
spec
|
|
# ...
|
|
exporter:
|
|
endpoint: https://production-collector.observability.svc.cluster.local:4317 # <1>
|
|
tls:
|
|
secretName: serving-certs # <2>
|
|
ca_file: service-ca.crt # <3>
|
|
cert_file: tls.crt # <4>
|
|
key_file: tls.key # <5>
|
|
# ...
|
|
----
|
|
<1> Specifies the OTLP endpoint using the HTTPS scheme and TLS.
|
|
<2> Specifies the name of the Secret for the `ca_file`, `cert_file`, and `key_file` values. The Secret must already exist in the namespace of the pod injecting the auto-instrumentation.
|
|
<3> Points to the CA certificate in the Secret or the absolute path to the certificate if the certificate is already present in the workload file system.
|
|
<4> Points to the client certificate in the Secret or the absolute path to the certificate if the certificate is already present in the workload file system.
|
|
<5> Points to the client key in the Secret or the absolute path to a key if the key is already present in the workload file system.
|
|
|
|
[NOTE]
|
|
====
|
|
You can provide the CA certificate in a config map or Secret. If you provide it in both, the config map takes higher precedence than the Secret.
|
|
====
|
|
|
|
.Example configuration for CA bundle injection by using a config map and `Instrumentation` CR
|
|
[source,yaml]
|
|
----
|
|
apiVersion: v1
|
|
kind: ConfigMap
|
|
metadata:
|
|
name: otelcol-cabundle
|
|
namespace: tutorial-application
|
|
annotations:
|
|
service.beta.openshift.io/inject-cabundle: "true"
|
|
# ...
|
|
---
|
|
apiVersion: opentelemetry.io/v1alpha1
|
|
kind: Instrumentation
|
|
metadata:
|
|
name: my-instrumentation
|
|
spec:
|
|
exporter:
|
|
endpoint: https://simplest-collector.tracing-system.svc.cluster.local:4317
|
|
tls:
|
|
configMapName: otelcol-cabundle
|
|
ca: service-ca.crt
|
|
# ...
|
|
----
|
|
|
|
[id="otel-configuration-of-apache-http-server-auto-instrumentation_{context}"]
|
|
== Configuration of the Apache HTTP Server auto-instrumentation
|
|
|
|
:FeatureName: The Apache HTTP Server auto-instrumentation
|
|
include::snippets/technology-preview.adoc[leveloffset=+1]
|
|
|
|
.Parameters for the `+.spec.apacheHttpd+` field
|
|
[options="header"]
|
|
[cols="a, a, a"]
|
|
|===
|
|
|Name |Description |Default
|
|
|
|
|`attrs`
|
|
|Attributes specific to the Apache HTTP Server.
|
|
|
|
|
|
|
|`configPath`
|
|
|Location of the Apache HTTP Server configuration.
|
|
|`/usr/local/apache2/conf`
|
|
|
|
|`env`
|
|
|Environment variables specific to the Apache HTTP Server.
|
|
|
|
|
|
|
|`image`
|
|
|Container image with the Apache SDK and auto-instrumentation.
|
|
|
|
|
|
|
|`resourceRequirements`
|
|
|The compute resource requirements.
|
|
|
|
|
|
|
|`version`
|
|
|Apache HTTP Server version.
|
|
|`2.4`
|
|
|
|
|===
|
|
|
|
.The `PodSpec` annotation to enable injection
|
|
[source,yaml]
|
|
----
|
|
instrumentation.opentelemetry.io/inject-apache-httpd: "true"
|
|
----
|
|
|
|
[id="otel-configuration-of-dotnet-auto-instrumentation_{context}"]
|
|
== Configuration of the .NET auto-instrumentation
|
|
|
|
:FeatureName: The .NET auto-instrumentation
|
|
include::snippets/technology-preview.adoc[leveloffset=+1]
|
|
|
|
[IMPORTANT]
|
|
====
|
|
By default, this feature injects unsupported, upstream instrumentation libraries.
|
|
====
|
|
|
|
[options="header"]
|
|
[cols="a, a"]
|
|
|===
|
|
|Name |Description
|
|
|
|
|`env`
|
|
|Environment variables specific to .NET.
|
|
|
|
|`image`
|
|
|Container image with the .NET SDK and auto-instrumentation.
|
|
|
|
|`resourceRequirements`
|
|
|The compute resource requirements.
|
|
|
|
|===
|
|
|
|
For the .NET auto-instrumentation, the required `OTEL_EXPORTER_OTLP_ENDPOINT` environment variable must be set if the endpoint of the exporters is set to `4317`. The .NET autoinstrumentation uses `http/proto` by default, and the telemetry data must be set to the `4318` port.
|
|
|
|
.The `PodSpec` annotation to enable injection
|
|
[source,yaml]
|
|
----
|
|
instrumentation.opentelemetry.io/inject-dotnet: "true"
|
|
----
|
|
|
|
[id="otel-configuration-of-go-auto-instrumentation_{context}"]
|
|
== Configuration of the Go auto-instrumentation
|
|
|
|
:FeatureName: The Go auto-instrumentation
|
|
include::snippets/technology-preview.adoc[leveloffset=+1]
|
|
|
|
[IMPORTANT]
|
|
====
|
|
By default, this feature injects unsupported, upstream instrumentation libraries.
|
|
====
|
|
|
|
[options="header"]
|
|
[cols="a, a"]
|
|
|===
|
|
|Name |Description
|
|
|
|
|`env`
|
|
|Environment variables specific to Go.
|
|
|
|
|`image`
|
|
|Container image with the Go SDK and auto-instrumentation.
|
|
|
|
|`resourceRequirements`
|
|
|The compute resource requirements.
|
|
|
|
|===
|
|
|
|
.The `PodSpec` annotation to enable injection
|
|
[source,yaml]
|
|
----
|
|
instrumentation.opentelemetry.io/inject-go: "true"
|
|
instrumentation.opentelemetry.io/otel-go-auto-target-exe: "/<path>/<to>/<container>/<executable>" # <1>
|
|
----
|
|
<1> Sets the value for the required `OTEL_GO_AUTO_TARGET_EXE` environment variable.
|
|
|
|
.Permissions required for the Go auto-instrumentation in the OpenShift cluster
|
|
[source,yaml]
|
|
----
|
|
apiVersion: security.openshift.io/v1
|
|
kind: SecurityContextConstraints
|
|
metadata:
|
|
name: otel-go-instrumentation-scc
|
|
allowHostDirVolumePlugin: true
|
|
allowPrivilegeEscalation: true
|
|
allowPrivilegedContainer: true
|
|
allowedCapabilities:
|
|
- "SYS_PTRACE"
|
|
fsGroup:
|
|
type: RunAsAny
|
|
runAsUser:
|
|
type: RunAsAny
|
|
seLinuxContext:
|
|
type: RunAsAny
|
|
seccompProfiles:
|
|
- '*'
|
|
supplementalGroups:
|
|
type: RunAsAny
|
|
----
|
|
|
|
[TIP]
|
|
====
|
|
The CLI command for applying the permissions for the Go auto-instrumentation in the OpenShift cluster is as follows:
|
|
[source,terminal]
|
|
----
|
|
$ oc adm policy add-scc-to-user otel-go-instrumentation-scc -z <service_account>
|
|
----
|
|
====
|
|
|
|
[id="otel-configuration-of-java-auto-instrumentation_{context}"]
|
|
== Configuration of the Java auto-instrumentation
|
|
|
|
:FeatureName: The Java auto-instrumentation
|
|
include::snippets/technology-preview.adoc[leveloffset=+1]
|
|
|
|
[IMPORTANT]
|
|
====
|
|
By default, this feature injects unsupported, upstream instrumentation libraries.
|
|
====
|
|
|
|
[options="header"]
|
|
[cols="a, a"]
|
|
|===
|
|
|Name |Description
|
|
|
|
|`env`
|
|
|Environment variables specific to Java.
|
|
|
|
|`image`
|
|
|Container image with the Java SDK and auto-instrumentation.
|
|
|
|
|`resourceRequirements`
|
|
|The compute resource requirements.
|
|
|
|
|===
|
|
|
|
.The `PodSpec` annotation to enable injection
|
|
[source,yaml]
|
|
----
|
|
instrumentation.opentelemetry.io/inject-java: "true"
|
|
----
|
|
|
|
[id="otel-configuration-of-nodejs-auto-instrumentation_{context}"]
|
|
== Configuration of the Node.js auto-instrumentation
|
|
|
|
:FeatureName: The Node.js auto-instrumentation
|
|
include::snippets/technology-preview.adoc[leveloffset=+1]
|
|
|
|
[IMPORTANT]
|
|
====
|
|
By default, this feature injects unsupported, upstream instrumentation libraries.
|
|
====
|
|
|
|
[options="header"]
|
|
[cols="a, a"]
|
|
|===
|
|
|Name |Description
|
|
|
|
|`env`
|
|
|Environment variables specific to Node.js.
|
|
|
|
|`image`
|
|
|Container image with the Node.js SDK and auto-instrumentation.
|
|
|
|
|`resourceRequirements`
|
|
|The compute resource requirements.
|
|
|
|
|===
|
|
|
|
.The `PodSpec` annotations to enable injection
|
|
[source,yaml]
|
|
----
|
|
instrumentation.opentelemetry.io/inject-nodejs: "true"
|
|
----
|
|
|
|
[id="otel-configuration-of-python-auto-instrumentation_{context}"]
|
|
== Configuration of the Python auto-instrumentation
|
|
|
|
:FeatureName: The Python auto-instrumentation
|
|
include::snippets/technology-preview.adoc[leveloffset=+1]
|
|
|
|
[IMPORTANT]
|
|
====
|
|
By default, this feature injects unsupported, upstream instrumentation libraries.
|
|
====
|
|
|
|
[options="header"]
|
|
[cols="a, a"]
|
|
|===
|
|
|Name |Description
|
|
|
|
|`env`
|
|
|Environment variables specific to Python.
|
|
|
|
|`image`
|
|
|Container image with the Python SDK and auto-instrumentation.
|
|
|
|
|`resourceRequirements`
|
|
|The compute resource requirements.
|
|
|
|
|===
|
|
|
|
For Python auto-instrumentation, the `OTEL_EXPORTER_OTLP_ENDPOINT` environment variable must be set if the endpoint of the exporters is set to `4317`. Python auto-instrumentation uses `http/proto` by default, and the telemetry data must be set to the `4318` port.
|
|
|
|
.The `PodSpec` annotation to enable injection
|
|
[source,yaml]
|
|
----
|
|
instrumentation.opentelemetry.io/inject-python: "true"
|
|
----
|
|
|
|
[id="otel-multi-container-pods_{context}"]
|
|
== Multi-container pods
|
|
|
|
The instrumentation is injected to the first container that is available by default according to the pod specification. You can also specify the target container names for injection.
|
|
|
|
.Pod annotation
|
|
[source,yaml]
|
|
----
|
|
instrumentation.opentelemetry.io/container-names: "<container_1>,<container_2>" # <1>
|
|
----
|
|
<1> Use this annotation when you want to inject a single instrumentation in multiple containers.
|
|
|
|
[NOTE]
|
|
====
|
|
The Go auto-instrumentation does not support multi-container auto-instrumentation injection.
|
|
====
|
|
|
|
[id="otel-multi-container-pods-multi-instrumentations_{context}"]
|
|
== Multi-container pods with multiple instrumentations
|
|
|
|
Injecting instrumentation for an application language to one or more containers in a multi-container pod requires the following annotation:
|
|
|
|
[source,yaml]
|
|
----
|
|
instrumentation.opentelemetry.io/<application_language>-container-names: "<container_1>,<container_2>" # <1>
|
|
----
|
|
<1> You can inject instrumentation for only one language per container. For the list of supported `<application_language>` values, see the following table.
|
|
|
|
.Supported values for the `<application_language>`
|
|
[options="header"]
|
|
[cols="a, a"]
|
|
|===
|
|
|Language |Value for `<application_language>`
|
|
|
|
|ApacheHTTPD
|
|
|`apache-httpd`
|
|
|
|
|DotNet
|
|
|`dotnet`
|
|
|
|
|Java
|
|
|`java`
|
|
|
|
|NGINX
|
|
|`inject-nginx`
|
|
|
|
|NodeJS
|
|
|`nodejs`
|
|
|
|
|Python
|
|
|`python`
|
|
|
|
|SDK
|
|
|`sdk`
|
|
|
|
|===
|
|
|
|
[id="otel-using-instrumentation-cr-with-service-mesh_{context}"]
|
|
== Using the instrumentation CR with Service Mesh
|
|
|
|
When using the `Instrumentation` custom resource (CR) with {SMProductName}, you must use the `b3multi` propagator.
|