{"id":2164,"library":"opentelemetry-instrumentation-pymongo","title":"OpenTelemetry PyMongo Instrumentation","description":"This library provides automatic instrumentation for the PyMongo library, enabling OpenTelemetry to collect traces from MongoDB operations. It is part of the OpenTelemetry Python Contrib project and is currently in a beta release cycle with frequent updates.","status":"active","version":"0.62b0","language":"en","source_language":"en","source_url":"https://github.com/open-telemetry/opentelemetry-python-contrib","tags":["opentelemetry","instrumentation","pymongo","mongodb","tracing","observability","database"],"install":[{"cmd":"pip install opentelemetry-instrumentation-pymongo pymongo opentelemetry-sdk opentelemetry-exporter-console","lang":"bash","label":"Install with PyMongo and Console Exporter"}],"dependencies":[{"reason":"The core library instrumented by this package.","package":"pymongo","optional":false},{"reason":"Required for configuring and exporting telemetry data.","package":"opentelemetry-sdk","optional":false},{"reason":"Required for OpenTelemetry API functionality.","package":"opentelemetry-api","optional":false}],"imports":[{"symbol":"PymongoInstrumentor","correct":"from opentelemetry.instrumentation.pymongo import PymongoInstrumentor"}],"quickstart":{"code":"import os\nimport time\nfrom pymongo import MongoClient\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.pymongo import PymongoInstrumentor\n\n# Configure OpenTelemetry SDK\nresource = Resource.create({\"service.name\": \"pymongo-example-service\"})\ntracer_provider = TracerProvider(resource=resource)\nspan_processor = SimpleSpanProcessor(ConsoleSpanExporter())\ntracer_provider.add_span_processor(span_processor)\ntrace.set_tracer_provider(tracer_provider)\n\n# Instrument PyMongo\nPymongoInstrumentor().instrument(capture_statement=True) # Set capture_statement=True to include full queries\n\n# Connect to MongoDB (ensure a local MongoDB instance is running, e.g., via Docker)\n# docker run -d -p 27017:27017 --name mongo-dev mongo:latest\nclient = MongoClient(os.environ.get('MONGO_URI', 'mongodb://localhost:27017/'))\ndb = client['testdb']\ncollection = db['testcollection']\n\nprint(\"Performing MongoDB operations...\")\n\n# Perform some operations\ncollection.insert_one({\"name\": \"Alice\", \"age\": 30})\nprint(\"Inserted one document.\")\n\ntime.sleep(0.1)\n\nresult = collection.find_one({\"name\": \"Alice\"})\nprint(f\"Found document: {result}\")\n\ntime.sleep(0.1)\n\ncollection.update_one({\"name\": \"Alice\"}, {\"$set\": {\"age\": 31}})\nprint(\"Updated one document.\")\n\ntime.sleep(0.1)\n\ncollection.delete_one({\"name\": \"Alice\"})\nprint(\"Deleted one document.\")\n\n# Cleanup (optional for demo, real applications manage connections)\nclient.close()\nprint(\"MongoDB operations complete.\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Refer to the official OpenTelemetry Python Contrib changelog for any breaking changes when upgrading to new beta or stable releases.","message":"The package version (e.g., `0.62b0`) indicates a beta release. APIs and behaviors may change in future non-beta versions.","severity":"gotcha","affected_versions":"All versions prefixed with '0.x.y bz'"},{"fix":"To enable capturing the full statement, pass `capture_statement=True` to the `instrument()` method: `PymongoInstrumentor().instrument(capture_statement=True)`.","message":"By 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure 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.","message":"For 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()`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Consider 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.","message":"When 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.","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"}