OpenTelemetry Pyramid Instrumentation

0.62b0 · active · verified Sat Apr 11

The `opentelemetry-instrumentation-pyramid` library provides automatic tracing for Pyramid web applications, capturing HTTP requests, view execution, and template rendering with minimal setup. It is part of the OpenTelemetry Python Contrib project, currently at version 0.62b0, and receives monthly updates as part of the broader OpenTelemetry Python Contrib release cadence.

Warnings

breaking This library, along with other `opentelemetry-python-contrib` instrumentations, is currently in beta. It should not generally be used in production environments where API stability guarantees are required, as breaking changes may occur without major version bumps.
Fix: Monitor releases for stability announcements (e.g., 1.0.0 stable). Consider using OpenTelemetry Python SDK components that are stable (tracing API and SDK) and understand the risks of beta instrumentations.
gotcha The OpenTelemetry SDK (including `TracerProvider`) and instrumentation must be initialized *before* the Pyramid application (or any instrumented code) starts. Incorrect initialization order can lead to missing telemetry data.
Fix: Ensure `trace.set_tracer_provider()` and `PyramidInstrumentor().instrument()` are called at the very beginning of your application's entry point, before `pyramid.config.Configurator()` is used or the WSGI application is created.
gotcha If you are using `PyramidInstrumentor().instrument_config(config)` for a specific `Configurator` and also explicitly setting `pyramid.tweens` for your application, you must manually add `opentelemetry.instrumentation.pyramid.trace_tween_factory` to your tweens list.
Fix: Modify your `pyramid.tweens` setting to include `opentelemetry.instrumentation.pyramid.trace_tween_factory` alongside any other custom tweens, for example: `config.add_tween('opentelemetry.instrumentation.pyramid.trace_tween_factory')`.
gotcha As of `opentelemetry-python-contrib` version 1.32.0/0.53b0, dependency checks for instrumented libraries are performed within the `Instrumentor.instrument()` method. If the `pyramid` package is not installed or its version does not meet the instrumentation's requirements, calling `instrument()` can result in an `ImportError` or other crashes.
Fix: Always ensure that `pyramid` and its required version are installed in your environment before attempting to import and instrument it with `PyramidInstrumentor`.
gotcha To exclude specific URLs from being traced (e.g., health checks, sensitive paths), you can set the environment variable `OTEL_PYTHON_PYRAMID_EXCLUDED_URLS` or the more general `OTEL_PYTHON_EXCLUDED_URLS`. Without this, all HTTP requests to your Pyramid application will generate spans, potentially increasing noise or exposing sensitive information.
Fix: Set the environment variable `OTEL_PYTHON_PYRAMID_EXCLUDED_URLS` to a comma-delimited string of regexes matching the URLs you wish to exclude (e.g., `export OTEL_PYTHON_PYRAMID_EXCLUDED_URLS="/healthz,/metrics"`).

Install

pip install opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp opentelemetry-instrumentation-pyramid Full setup with OTLP exporter

Imports

PyramidInstrumentor

from opentelemetry.instrumentation.pyramid import PyramidInstrumentor

Quickstart

This quickstart demonstrates how to set up OpenTelemetry for a basic Pyramid application. It initializes the OpenTelemetry SDK with a `TracerProvider` and a `ConsoleSpanExporter` (for local testing), then instruments the Pyramid application using `PyramidInstrumentor().instrument()` before the WSGI app is created. Replace `ConsoleSpanExporter` with `OTLPSpanExporter` for production use, ensuring an OTLP collector is configured.

import os
from wsgiref.simple_server import make_server
from pyramid.config import Configurator
from pyramid.response import Response

from opentelemetry import trace
from opentelemetry.sdk.resources import Resource, SERVICE_NAME
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter

from opentelemetry.instrumentation.pyramid import PyramidInstrumentor

# Configure OpenTelemetry SDK
resource = Resource.create({
    SERVICE_NAME: os.environ.get('OTEL_SERVICE_NAME', 'my-pyramid-app'),
})

tracer_provider = TracerProvider(resource=resource)

# Use OTLP exporter for production, ConsoleSpanExporter for debugging
# For OTLP, ensure an OTLP collector is running or set OTEL_EXPORTER_OTLP_ENDPOINT
# otlp_exporter = OTLPSpanExporter(endpoint=os.environ.get('OTEL_EXPORTER_OTLP_ENDPOINT', 'localhost:4317'))
# tracer_provider.add_span_processor(BatchSpanProcessor(otlp_exporter))

tracer_provider.add_span_processor(BatchSpanProcessor(ConsoleSpanExporter())) # for stdout output
trace.set_tracer_provider(tracer_provider)

# Instrument Pyramid (before creating the app)
PyramidInstrumentor().instrument()

# Define a simple Pyramid view
def hello_world(request):
    return Response('Hello, OpenTelemetry Pyramid!')

def create_app():
    with Configurator() as config:
        config.add_route('hello', '/')
        config.add_view(hello_world, route_name='hello')
        app = config.make_wsgi_app()
    return app

# Run the application
if __name__ == '__main__':
    app = create_app()
    print("Serving Pyramid app on http://localhost:6543")
    server = make_server('0.0.0.0', 6543, app)
    server.serve_forever()

view raw JSON →