pytest-otel 2.1.0

OpenTelemetry plugin for Pytest

pytest_otel

Features

pytest-otel plugin for reporting OpenTelemetry spans of tests executed.

OpenTelemetry

Requirements

• opentelemetry-api
• opentelemetry-exporter-otlp
• opentelemetry-sdk
• pytest

Installation

You can install "pytest-otel" via pip or using the setup.py script.

pip install pytest-otel

Usage

pytest_otel is configured by adding some parameters to the pytest command line. Below are the descriptions:

• --otel-endpoint: URL for the OpenTelemetry server. (Required). Env variable: OTEL_EXPORTER_OTLP_ENDPOINT
• --otel-headers: Additional headers to send (i.e.: key1=value1,key2=value2). Env variable: OTEL_EXPORTER_OTLP_HEADERS
• --otel-service-name: Name of the service. Env variable: OTEL_SERVICE_NAME
• --otel-session-name: Name for the main span.
• --otel-traceparent: Trace parent ID. Env variable: TRACEPARENT. See https://www.w3.org/TR/trace-context-1/#trace-context-http-headers-format
• --otel-insecure: Disables TLS. Env variable: OTEL_EXPORTER_OTLP_INSECURE
• --otel-exporter-protocol: OTLP exporter protocol to use: 'grpc' or 'http/protobuf'. Default is 'grpc'. Env variable: OTEL_EXPORTER_OTLP_PROTOCOL
• --otel-dotenv-path: Path to a dotenv file to load environment variables from.

pytest --otel-endpoint https://otelcollector.example.com:4317 \
       --otel-headers "authorization=Bearer ASWDCcCRFfr" \
       --otel-service-name pytest_otel \
       --otel-session-name='My_Test_cases' \
       --otel-traceparent=00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01 \
       --otel-insecure=False \
       --otel-exporter-protocol=grpc

IMPORTANT: If you use --otel-headers the transaction metadata might expose those arguments with their values. In order to avoid any credentials to be exposed, it's recommended to use the environment variables. For instance, given the above example, a similar one with environment variables can be seen below:

OTEL_EXPORTER_OTLP_ENDPOINT=https://apm.example.com:8200 \
OTEL_EXPORTER_OTLP_HEADERS="authorization=Bearer ASWDCcCRFfr" \
OTEL_SERVICE_NAME=pytest_otel \
TRACEPARENT=00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01 \
OTEL_EXPORTER_OTLP_INSECURE=False \
OTEL_EXPORTER_OTLP_PROTOCOL=grpc \
pytest --otel-session-name='My_Test_cases'

Using a Dotenv File

To avoid setting environment variables manually, you can use a dotenv file with the --otel-dotenv-path option:

# Install with dotenv support
pip install pytest-otel[dotenv]

# Create a dotenv file (e.g., otel.env)
cat > otel.env << EOF
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
OTEL_RESOURCE_ATTRIBUTES=service.version=1.0.0,deployment.environment=test
OTEL_METRIC_EXPORT_INTERVAL=100
OTEL_BSP_SCHEDULE_DELAY=100
EOF

# Run tests with dotenv file
pytest --otel-dotenv-path=otel.env --otel-service-name=my_service --otel-session-name='My_Test_cases'

Note: CLI options (including defaults) always take precedence over dotenv and environment variables. The dotenv file is useful for:

• Setting OpenTelemetry SDK environment variables like OTEL_RESOURCE_ATTRIBUTES, OTEL_METRIC_EXPORT_INTERVAL, OTEL_BSP_SCHEDULE_DELAY
• Setting OTEL_EXPORTER_OTLP_ENDPOINT when not using the --otel-endpoint flag
• Other OpenTelemetry configuration that the plugin doesn't explicitly manage via CLI flags

For CLI-managed options like --otel-service-name and --otel-exporter-protocol, you must pass them explicitly on the command line if you want to override the defaults. 3. Default values

To use the HTTP exporter instead of gRPC:

# Note: Using port 4318 (standard OTLP HTTP port) instead of 4317 (standard OTLP gRPC port)
pytest --otel-endpoint https://otelcollector.example.com:4318 \
       --otel-service-name pytest_otel \
       --otel-session-name='My_Test_cases' \
       --otel-exporter-protocol=http/protobuf

Demos

• Jaeger
• Elastic Stack

License

Distributed under the terms of the Apache License Version 2.0_ license, "pytest-otel" is free and open source software