The Red Hat build of OpenTelemetry can inject and configure the OpenTelemetry auto-instrumentation libraries into your workloads. Currently, the project supports injection of the instrumentation libraries from Go, Java, Node.js, Python, .NET, and the Apache HTTP Server (httpd
).
Auto-instrumentation in OpenTelemetry refers to the capability where the framework automatically instruments an application without manual code changes. This enables developers and administrators to get observability into their applications with minimal effort and changes to the existing codebase.
|
The Red Hat build of OpenTelemetry Operator 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.
|
Instrumentation options
Instrumentation options are specified in an Instrumentation
custom resource (CR).
Sample Instrumentation
CR
apiVersion: opentelemetry.io/v1alpha1
kind: Instrumentation
metadata:
name: java-instrumentation
spec:
env:
- name: OTEL_EXPORTER_OTLP_TIMEOUT
value: "20"
exporter:
endpoint: http://production-collector.observability.svc.cluster.local:4317
propagators:
- w3c
sampler:
type: parentbased_traceidratio
argument: "0.25"
java:
env:
- name: OTEL_JAVAAGENT_DEBUG
value: "true"
Table 1. Parameters used by the Operator to define the Instrumentation
Parameter |
Description |
Values |
|
Common environment variables to define across all the instrumentations.
|
|
|
|
|
|
Propagators defines inter-process context propagation configuration.
|
tracecontext , baggage , b3 , b3multi , jaeger , ottrace , none
|
|
Resource attributes configuration.
|
|
|
|
|
|
Configuration for the Apache HTTP Server instrumentation.
|
|
|
Configuration for the .NET instrumentation.
|
|
|
Configuration for the Go instrumentation.
|
|
|
Configuration for the Java instrumentation.
|
|
|
Configuration for the Node.js instrumentation.
|
|
|
Configuration for the Python instrumentation.
|
|
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 Red Hat build of OpenTelemetry 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
Table 2. Values for the instrumentation.opentelemetry.io/inject-sdk
annotation
Value |
Description |
|
Injects the Instrumentation resource with the default name from the current namespace.
|
|
Injects no Instrumentation resource.
|
|
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.
|
Configuration of the Apache HTTP Server auto-instrumentation
|
The Apache HTTP Server auto-instrumentation 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. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.
|
Table 3. Parameters for the .spec.apacheHttpd
field
Name |
Description |
Default |
|
Attributes specific to the Apache HTTP Server.
|
|
|
Location of the Apache HTTP Server configuration.
|
|
|
Environment variables specific to the Apache HTTP Server.
|
|
|
Container image with the Apache SDK and auto-instrumentation.
|
|
|
The compute resource requirements.
|
|
|
Apache HTTP Server version.
|
|
The PodSpec
annotation to enable injection
instrumentation.opentelemetry.io/inject-apache-httpd: "true"
Configuration of the .NET auto-instrumentation
|
The .NET auto-instrumentation 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. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.
|
|
By default, this feature injects unsupported, upstream instrumentation libraries.
|
Name |
Description |
|
Environment variables specific to .NET.
|
|
Container image with the .NET SDK and auto-instrumentation.
|
|
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
instrumentation.opentelemetry.io/inject-dotnet: "true"
Configuration of the Go auto-instrumentation
|
The Go auto-instrumentation 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. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.
|
|
By default, this feature injects unsupported, upstream instrumentation libraries.
|
Name |
Description |
|
Environment variables specific to Go.
|
|
Container image with the Go SDK and auto-instrumentation.
|
|
The compute resource requirements.
|
The PodSpec
annotation to enable injection
instrumentation.opentelemetry.io/inject-go: "true"
Additional permissions required for the Go auto-instrumentation in the OpenShift cluster
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
|
The CLI command for applying the permissions for the Go auto-instrumentation in the OpenShift cluster is as follows:
$ oc adm policy add-scc-to-user otel-go-instrumentation-scc -z <service_account>
|
Configuration of the Java auto-instrumentation
|
The Java auto-instrumentation 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. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.
|
|
By default, this feature injects unsupported, upstream instrumentation libraries.
|
Name |
Description |
|
Environment variables specific to Java.
|
|
Container image with the Java SDK and auto-instrumentation.
|
|
The compute resource requirements.
|
The PodSpec
annotation to enable injection
instrumentation.opentelemetry.io/inject-java: "true"
Configuration of the Node.js auto-instrumentation
|
The Node.js auto-instrumentation 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. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.
|
|
By default, this feature injects unsupported, upstream instrumentation libraries.
|
Name |
Description |
|
Environment variables specific to Node.js.
|
|
Container image with the Node.js SDK and auto-instrumentation.
|
|
The compute resource requirements.
|
The PodSpec
annotations to enable injection
instrumentation.opentelemetry.io/inject-nodejs: "true"
instrumentation.opentelemetry.io/otel-go-auto-target-exe: "/path/to/container/executable"
The instrumentation.opentelemetry.io/otel-go-auto-target-exe
annotation sets the value for the required OTEL_GO_AUTO_TARGET_EXE
environment variable.
Configuration of the Python auto-instrumentation
|
The Python auto-instrumentation 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. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.
|
|
By default, this feature injects unsupported, upstream instrumentation libraries.
|
Name |
Description |
|
Environment variables specific to Python.
|
|
Container image with the Python SDK and auto-instrumentation.
|
|
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
instrumentation.opentelemetry.io/inject-python: "true"
Multi-container pods
The instrumentation is run on the first container that is available by default according to the pod specification. In some cases, you can also specify target containers for injection.
Pod annotation
instrumentation.opentelemetry.io/container-names: "<container_1>,<container_2>"
|
The Go auto-instrumentation does not support multi-container auto-instrumentation injection.
|
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:
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. |
Table 4. Supported values for the <application_language>
Language |
Value for <application_language> |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Using the instrumentation CR with Service Mesh
When using the instrumentation custom resource (CR) with Red Hat OpenShift Service Mesh, you must use the b3multi
propagator.