Registry /
observability / opentelemetry-instrumentation-pymongo
Install & Compatibility
Where this runs
tested against v? · pip install
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
build_error
glibcpy 3.10–3.95 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
PymongoInstrumentor
✓ from opentelemetry.instrumentation.pymongo import PymongoInstrumentor
This quickstart demonstrates how to set up the OpenTelemetry SDK with a console exporter, instrument PyMongo, and perform basic database operations. It will print the generated traces to the console.
import os
import time
from pymongo import MongoClient
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.pymongo import PymongoInstrumentor
# Configure OpenTelemetry SDK
resource = Resource.create({"service.name": "pymongo-example-service"})
tracer_provider = TracerProvider(resource=resource)
span_processor = SimpleSpanProcessor(ConsoleSpanExporter())
tracer_provider.add_span_processor(span_processor)
trace.set_tracer_provider(tracer_provider)
# Instrument PyMongo
PymongoInstrumentor().instrument(capture_statement=True) # Set capture_statement=True to include full queries
# Connect to MongoDB (ensure a local MongoDB instance is running, e.g., via Docker)
# docker run -d -p 27017:27017 --name mongo-dev mongo:latest
client = MongoClient(os.environ.get('MONGO_URI', 'mongodb://localhost:27017/'))
db = client['testdb']
collection = db['testcollection']
print("Performing MongoDB operations...")
# Perform some operations
collection.insert_one({"name": "Alice", "age": 30})
print("Inserted one document.")
time.sleep(0.1)
result = collection.find_one({"name": "Alice"})
print(f"Found document: {result}")
time.sleep(0.1)
collection.update_one({"name": "Alice"}, {"$set": {"age": 31}})
print("Updated one document.")
time.sleep(0.1)
collection.delete_one({"name": "Alice"})
print("Deleted one document.")
# Cleanup (optional for demo, real applications manage connections)
client.close()
print("MongoDB operations complete.")
Debug
Known issues
gotchaThe package version (e.g., `0.62b0`) indicates a beta release. APIs and behaviors may change in future non-beta versions.fixRefer to the official OpenTelemetry Python Contrib changelog for any breaking changes when upgrading to new beta or stable releases.
affects: All versions prefixed with '0.x.y bz'
gotchaBy default, the `db.statement` attribute in spans may not capture the full MongoDB query due to potential concerns about sensitive data (PII). It often only includes the command name.fixTo enable capturing the full statement, pass `capture_statement=True` to the `instrument()` method: `PymongoInstrumentor().instrument(capture_statement=True)`.
affects: All versions
gotchaFor traces to be collected and exported, you must explicitly configure an OpenTelemetry `TracerProvider` and `SpanProcessor` with an appropriate exporter (e.g., `ConsoleSpanExporter`, `OTLPSpanExporter`) before calling `PymongoInstrumentor().instrument()`.fixEnsure that `opentelemetry.sdk.trace.TracerProvider` is initialized and `trace.set_tracer_provider()` is called, and a `SpanProcessor` is added to the provider, before using any instrumented libraries.
affects: All versions
gotchaWhen using pre-fork web servers (e.g., Gunicorn or uWSGI with multiple workers) with automatic instrumentation, metrics and traces might be inconsistent or lost due to issues with background threads and locks being forked incorrectly. This is a general issue with OpenTelemetry Python auto-instrumentation.fixConsider using programmatic auto-instrumentation in each worker process, setting `workers = 1` for Gunicorn/uWSGI, or using alternative deployment strategies like `UvicornWorker` without forking after instrumentation.
affects: All versions
Upgrade
Version history
0.65b0latest on PyPI · released Jul 16, 2026
Audit
Dependencies
pymongorequiredThe core library instrumented by this package.
opentelemetry-sdkrequiredRequired for configuring and exporting telemetry data.
opentelemetry-apirequiredRequired for OpenTelemetry API functionality.