OpenTelemetry Jinja2 Instrumentation

Warnings

• gotcha As 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.
  Fix: Refer 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.
• gotcha The 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.
• gotcha OpenTelemetry 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.
• gotcha Incorrect 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.
  Fix: Limit 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.

Install

• pip install opentelemetry-instrumentation-jinja2 Install package

Imports

• Jinja2Instrumentor

  from opentelemetry.instrumentation.jinja2 import Jinja2Instrumentor

  Primary class to enable Jinja2 instrumentation.

Quickstart

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.")