Alauda Build of OpenTelemetry v2
  • English

    • 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.