OTEL Auto-Instrumentation Link

Automatically configures OpenTelemetry auto-instrumentation for your application pods.

What This Link Does

When you link an external_source_code or image_base component to an OTEL component, Stacktic automatically:

Adds the auto-instrumentation annotation to the pod
Configures OTEL exporter environment variables
Handles Python PYTHONPATH requirements for Django/Flask/FastAPI

Link Attributes

Attribute	Required	Description
otel_language	Yes	Language for auto-instrumentation: `java`, `python`, `nodejs`, `dotnet`, `go`
pythonpath	For Python	Required for Python apps. The working directory of your app (e.g., `/usr/src/app`)
otel_language_custom	No	Custom annotation key (overrides default `instrumentation.opentelemetry.io/inject-{language}`)

Auto-Generated Configuration

1. Pod Annotation

metadata:
  annotations:
    instrumentation.opentelemetry.io/inject-python: "otel/otel-instrumentation"

2. Environment Variables (cloud.env)

OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector-collector.otel.svc.cluster.local:4318
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://otel-collector-collector.otel.svc.cluster.local:4318/v1/traces
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://otel-collector-collector.otel.svc.cluster.local:4318/v1/metrics
OTEL_SERVICE_NAME=my-app
PYTHONPATH=/usr/src/app  # Only for Python

3. Deployment env: section (Python only)

containers:
  - name: app
    env:
      - name: PYTHONPATH
        value: "/usr/src/app"
    envFrom:
      - secretRef:
          name: my-app-external-source-secrets

Why PYTHONPATH is Required for Python

The OTEL operator's Python auto-instrumentation has a known issue (GitHub #2495):

The operator's sitecustomize.py runs before your app starts
It doesn't add the current working directory to sys.path
Django/Flask/FastAPI can't find their settings module
Django falls back to global_settings which has DEBUG=False
Result: CommandError: You must set settings.ALLOWED_HOSTS if DEBUG is False

Solution: Set pythonpath attribute to your app's working directory (must match Dockerfile WORKDIR)

Why PYTHONPATH Must Be in env: (Not Secret)

The OTEL operator init container behavior:

envFrom: (secrets/configmaps) - OTEL operator overwrites these values
env: (explicit) - OTEL operator appends to these values

That's why Stacktic generates PYTHONPATH in both places:

cloud.env (secret) - For non-OTEL scenarios
source_code.yaml (deployment env:) - For OTEL to work correctly

Supported Languages

otel_language	Annotation	Extra Config
java	instrumentation.opentelemetry.io/inject-java	None
python	instrumentation.opentelemetry.io/inject-python	Requires pythonpath attribute
nodejs	instrumentation.opentelemetry.io/inject-nodejs	None
dotnet	instrumentation.opentelemetry.io/inject-dotnet	None
go	instrumentation.opentelemetry.io/inject-go	None

Example Link Configuration

Python (Django/Flask/FastAPI)

Link: django -> otel
Attributes:
  otel_language: "python"
  pythonpath: "/usr/src/app"

Java (Spring Boot)

Link: backend -> otel
Attributes:
  otel_language: "java"

Node.js (Express/NestJS)

Link: api -> otel
Attributes:
  otel_language: "nodejs"

How to Find Your pythonpath Value

Check your Dockerfile for the WORKDIR directive:

# Dockerfile
FROM python:3.12-slim
WORKDIR /usr/src/app  # <-- This is your pythonpath
COPY . .
CMD ["python", "manage.py", "runserver"]

Common values:

/usr/src/app - Django default
/app - Generic Python apps
/code - Some Docker Compose setups

Troubleshooting

"ALLOWED_HOSTS if DEBUG is False" - Missing or wrong pythonpath
"ModuleNotFoundError: No module named 'myapp'" - Wrong pythonpath value
Pod stuck in Init - OTEL Instrumentation CR may not exist in target namespace
No traces appearing - Check OTEL collector is running and reachable