Registry /
observability / opentelemetry-instrumentation-jinja2
Install & Compatibility
Where this runs
tested against v0.65b0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 22.6MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.9s · import 0.000s · 23MB
21MB installed
● package 21MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Jinja2Instrumentor
✓ from opentelemetry.instrumentation.jinja2 import Jinja2Instrumentor
✗ from opentelemetry.instrumentation.jinja2 import Jinja2Instrumentor
This quickstart demonstrates how to set up OpenTelemetry with Jinja2 instrumentation. It configures a basic `TracerProvider` with a `ConsoleSpanExporter` to print traces to the console, then instruments Jinja2, and finally renders a simple template to generate traces for loading, compiling, and rendering.
import os
from jinja2 import Environment, FileSystemLoader
from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor
from opentelemetry.instrumentation.jinja2 import Jinja2Instrumentor
# 1. Setup OpenTelemetry Tracer Provider and Exporter
# For simplicity, we use ConsoleSpanExporter to print traces to console
resource = Resource.create({"service.name": "jinja2-example"})
provider = TracerProvider(resource=resource)
processor = SimpleSpanProcessor(ConsoleSpanExporter())
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)
# 2. Instrument Jinja2
Jinja2Instrumentor().instrument()
# 3. Create a dummy template file for demonstration
# In a real application, you'd have a 'templates' directory.
if not os.path.exists('templates'):
os.makedirs('templates')
with open('templates/hello.html', 'w') as f:
f.write('<h1>Hello, {{ name }}!</h1><p>Today is {{ date }}.</p>')
# 4. Use Jinja2 as usual
env = Environment(loader=FileSystemLoader("templates"))
tracer = trace.get_tracer(__name__)
with tracer.start_as_current_span("render-page"):
template = env.get_template("hello.html")
output = template.render(name="World", date="April 9, 2026")
print(f"\nRendered Output:\n{output}")
print("\nJinja2 instrumentation complete. Check console for traces.")
Debug
Known issues
gotchaAs a 'beta' release (`0.62b0`), the API and emitted telemetry (e.g., span names, attributes) are subject to change without strict adherence to semantic versioning. This may require updates to your code or observability backend configurations when upgrading.fixRefer to the `opentelemetry-python-contrib` changelog before upgrading and test thoroughly in non-production environments. Be prepared to adapt to API or semantic convention changes.
affects: All `b` (beta) versions
gotchaThe instrumentation automatically traces core Jinja2 operations. However, if you have complex custom logic within your templates or non-standard template loading mechanisms, you might need to add manual instrumentation using the OpenTelemetry API to gain full visibility into those specific parts.
gotchaOpenTelemetry semantic conventions, which define standard names for attributes and spans, are actively evolving. While efforts are made to ensure stability, minor changes to these conventions may occur over time, potentially impacting existing dashboards or alerts that rely on specific attribute names.
gotchaIncorrect or excessive use of high-cardinality attributes (e.g., unique IDs in every span) can lead to significant performance overhead and increased costs in your observability backend. Review and filter attributes carefully, especially in production environments.fixLimit the use of high-cardinality attributes. Utilize OpenTelemetry's sampling capabilities to reduce trace volume. Configure resource attributes for process-level metadata rather than per-span attributes where appropriate.
affects: All versions
Upgrade
Version history
0.65b0latest on PyPI · released Jul 16, 2026
Audit
Dependencies
jinja2requiredThe library instruments Jinja2 templating engine.
opentelemetry-apirequiredCore OpenTelemetry API for defining telemetry.
opentelemetry-sdkrequiredCore OpenTelemetry SDK for processing and exporting telemetry. Often used with a configured exporter.