OpenTelemetry PyMongo Instrumentation

Warnings

• gotcha The package version (e.g., `0.62b0`) indicates a beta release. APIs and behaviors may change in future non-beta versions.
  Fix: Refer to the official OpenTelemetry Python Contrib changelog for any breaking changes when upgrading to new beta or stable releases.
• gotcha 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.
  Fix: To enable capturing the full statement, pass `capture_statement=True` to the `instrument()` method: `PymongoInstrumentor().instrument(capture_statement=True)`.
• gotcha 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()`.
  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.
• gotcha 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.
  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.

Install

• pip install opentelemetry-instrumentation-pymongo pymongo opentelemetry-sdk opentelemetry-exporter-console Install with PyMongo and Console Exporter

Imports

• PymongoInstrumentor

  from opentelemetry.instrumentation.pymongo import PymongoInstrumentor

Quickstart

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