{"id":2158,"library":"opentelemetry-instrumentation-jinja2","title":"OpenTelemetry Jinja2 Instrumentation","description":"The `opentelemetry-instrumentation-jinja2` library provides OpenTelemetry instrumentation for Jinja2, automatically tracing template loading, compilation, and rendering operations. It is part of the `opentelemetry-python-contrib` repository, which typically follows a monthly release cadence. As of the current version, many instrumentations within this contrib repository are still in a beta state, indicating ongoing development and potential for API changes.","status":"active","version":"0.62b0","language":"en","source_language":"en","source_url":"https://github.com/open-telemetry/opentelemetry-python-contrib","tags":["opentelemetry","tracing","instrumentation","jinja2","observability","templates"],"install":[{"cmd":"pip install opentelemetry-instrumentation-jinja2","lang":"bash","label":"Install package"}],"dependencies":[{"reason":"The library instruments Jinja2 templating engine.","package":"jinja2","optional":false},{"reason":"Core OpenTelemetry API for defining telemetry.","package":"opentelemetry-api","optional":false},{"reason":"Core OpenTelemetry SDK for processing and exporting telemetry. Often used with a configured exporter.","package":"opentelemetry-sdk","optional":false}],"imports":[{"note":"Primary class to enable Jinja2 instrumentation.","symbol":"Jinja2Instrumentor","correct":"from opentelemetry.instrumentation.jinja2 import Jinja2Instrumentor"}],"quickstart":{"code":"import os\nfrom jinja2 import Environment, FileSystemLoader\nfrom opentelemetry import trace\nfrom opentelemetry.sdk.resources import Resource\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor\nfrom opentelemetry.instrumentation.jinja2 import Jinja2Instrumentor\n\n# 1. Setup OpenTelemetry Tracer Provider and Exporter\n# For simplicity, we use ConsoleSpanExporter to print traces to console\nresource = Resource.create({\"service.name\": \"jinja2-example\"})\nprovider = TracerProvider(resource=resource)\nprocessor = SimpleSpanProcessor(ConsoleSpanExporter())\nprovider.add_span_processor(processor)\ntrace.set_tracer_provider(provider)\n\n# 2. Instrument Jinja2\nJinja2Instrumentor().instrument()\n\n# 3. Create a dummy template file for demonstration\n# In a real application, you'd have a 'templates' directory.\nif not os.path.exists('templates'):\n    os.makedirs('templates')\nwith open('templates/hello.html', 'w') as f:\n    f.write('<h1>Hello, {{ name }}!</h1><p>Today is {{ date }}.</p>')\n\n# 4. Use Jinja2 as usual\nenv = Environment(loader=FileSystemLoader(\"templates\"))\ntracer = trace.get_tracer(__name__)\n\nwith tracer.start_as_current_span(\"render-page\"):\n    template = env.get_template(\"hello.html\")\n    output = template.render(name=\"World\", date=\"April 9, 2026\")\n    print(f\"\\nRendered Output:\\n{output}\")\n\nprint(\"\\nJinja2 instrumentation complete. Check console for traces.\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All `b` (beta) versions"},{"message":"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.","severity":"gotcha"},{"message":"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.","severity":"gotcha"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}