Alauda Build of OpenTelemetry v2

Instrumentation Options

The Instrumentation custom resource provides various configuration options to control how auto-instrumentation is applied to your applications. These options allow you to customize the instrumentation behavior, specify resource requirements, and configure language-specific settings.

WARNING

Alauda build of OpenTelemetry v2 Operator provides the auto-injection mechanism for instrumentation, but does not include pre-built instrumentation libraries or container images. You need to build your own instrumentation images or use community-provided images.

TOC

Basic Instrumentation ConfigurationInstrumentation CR ParametersDefault Auto-Instrumentation ProtocolsAnnotation-based InjectionLanguage-specific InjectionSDK Variable InjectionSupported Values for Injection AnnotationsNamespace-level InstrumentationResource ConfigurationEnvironment Variable InjectionSelective InstrumentationInstrumentation Reference

Basic Instrumentation Configuration

The Instrumentation custom resource (CR) defines how telemetry data is collected from your applications. It provides settings for the exporter endpoint, context propagation, sampling, and language-specific instrumentation.

apiVersion: opentelemetry.io/v1alpha1
kind: Instrumentation
metadata:
  name: my-instrumentation
spec:
  env:
    - name: OTEL_EXPORTER_OTLP_TIMEOUT
      value: "20"
  exporter:
    endpoint: 'http://otel-collector.otel-collector.svc:4317'
  propagators:
    - tracecontext
    - baggage
    - b3multi
  sampler:
    type: parentbased_traceidratio
    argument: "0.25"
  python:
    env:
      - name: OTEL_EXPORTER_OTLP_ENDPOINT
        value: 'http://otel-collector.otel-collector.svc:4318'
  dotnet:
    env:
      - name: OTEL_EXPORTER_OTLP_ENDPOINT
        value: 'http://otel-collector.otel-collector.svc:4318'
  go:
    env:
      - name: OTEL_EXPORTER_OTLP_ENDPOINT
        value: 'http://otel-collector.otel-collector.svc:4318'
  1. The exporter endpoint where the Collector receives telemetry data. The default protocol is gRPC on port 4317.
  2. Context propagation formats. Supported values include tracecontext, baggage, b3, b3multi, jaeger, ottrace, and none.
  3. The sampler configuration to control the volume of trace data. The parentbased_traceidratio type with an argument of 0.25 means 25% of new root traces are sampled.
  4. Python auto-instrumentation uses otlp/http by default. The endpoint must point to the HTTP port 4318 of the Collector.
  5. .NET auto-instrumentation uses otlp/http by default. The endpoint must point to the HTTP port 4318 of the Collector.
  6. Go auto-instrumentation uses otlp/http by default. The endpoint must point to the HTTP port 4318 of the Collector.

Instrumentation CR Parameters

The following table describes the parameters that can be configured in the Instrumentation custom resource.

ParameterDescriptionValues
envCommon environment variables shared across all instrumentation types.
exporterExporter configuration for telemetry data delivery.
propagatorsInter-process context propagation configuration.tracecontext, baggage, b3, b3multi, jaeger, ottrace, none
resourceResource attributes configuration for telemetry identification.
samplerSampling configuration to control telemetry data volume.
apacheHttpdApache HTTP Server instrumentation settings.
dotnet.NET instrumentation settings.
goGo instrumentation settings.
javaJava instrumentation settings.
nodejsNode.js instrumentation settings.
pythonPython instrumentation settings.

Default Auto-Instrumentation Protocols

Each auto-instrumentation language uses a default protocol to export telemetry data to the Collector. The following table lists the default protocols.

Auto-instrumentationDefault Protocol
Java 1.xotlp/grpc
Java 2.xotlp/http
Pythonotlp/http
.NETotlp/http
Gootlp/http
Apache HTTP Serverotlp/grpc
NOTE

You can configure environment variables on the Instrumentation CR. However, after the Operator injects these environment variables into the application container, they cannot be removed by simply updating or deleting the Instrumentation CR. To remove injected environment variables, you must restart or redeploy the affected pods.

Annotation-based Injection

To enable auto-instrumentation for your application, add the appropriate annotation to your pod or namespace:

apiVersion: v1
kind: Pod
metadata:
  name: myapp
  annotations:
    instrumentation.opentelemetry.io/inject-java: "true"
spec:
  containers:
  - name: app
    image: myapp:latest

Language-specific Injection

The annotation format is instrumentation.opentelemetry.io/inject-<language>, where <language> can be:

  • apache-httpd - For Apache HTTP Server
  • dotnet - For .NET applications
  • go - For Go applications
  • java - For Java applications
  • nodejs - For Node.js applications
  • python - For Python applications

SDK Variable Injection

You can use the instrumentation.opentelemetry.io/inject-sdk annotation to instruct the OpenTelemetry Operator to inject SDK environment variables into your pod.

TIP

The inject-sdk annotation is useful when you want to inject SDK environment variables without enabling language-specific auto-instrumentation. This is particularly helpful for applications that already include OpenTelemetry SDK dependencies but need centralized configuration management.

Supported Values for Injection Annotations

ValueDescription
"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

Namespace-level Instrumentation

You can apply instrumentation to all pods in a namespace by annotating the namespace itself:

apiVersion: v1
kind: Namespace
metadata:
  name: production
  annotations:
    instrumentation.opentelemetry.io/inject-java: "true"
TIP

Namespace-level annotations provide a convenient way to enable instrumentation for all applications in an environment without modifying individual pod specifications.

Resource Configuration

You can specify resource requests and limits for the instrumentation init container:

spec:
  resource:
    limits:
      cpu: 500m
      memory: 128Mi
    requests:
      cpu: 100m
      memory: 64Mi

Environment Variable Injection

The Instrumentation CR allows you to inject additional environment variables into instrumented containers:

spec:
  env:
    - name: OTEL_TRACES_EXPORTER
      value: otlp
    - name: OTEL_METRICS_EXPORTER
      value: otlp
    - name: OTEL_LOGS_EXPORTER
      value: otlp

These environment variables are automatically added to the application container when instrumentation is injected.

Selective Instrumentation

You can control which containers in a multi-container pod receive instrumentation by using container-specific annotations:

metadata:
  annotations:
    instrumentation.opentelemetry.io/inject-java: "true"
    instrumentation.opentelemetry.io/container-names: "app,sidecar"

This annotation ensures that only the specified containers are instrumented, leaving other containers unmodified.

NOTE

If the container-names annotation is not specified, instrumentation is applied to the first container in the pod by default.

Instrumentation Reference

To reference a specific Instrumentation CR, you can use the full reference format in the annotation:

metadata:
  annotations:
    instrumentation.opentelemetry.io/inject-java: "namespace/instrumentation-name"

This allows you to use different instrumentation configurations for different applications within the same namespace.