Registry /
observability / opentelemetry-instrumentation-chromadb
Install & Compatibility
Where this runs
tested against v0.62.3 · pip install
no network on importno background threads
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
installs and imports cleanly · install 24.5s · import 0.000s · 468MB
438MB installed
● package 438MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ChromaDBInstrumentor
✓ from opentelemetry.instrumentation.chromadb import ChromaDBInstrumentor
This quickstart demonstrates how to set up OpenTelemetry with `opentelemetry-instrumentation-chromadb`. It configures a simple console exporter, initializes the ChromaDB instrumentor, and then performs basic ChromaDB operations (create, add, query, delete collection) using an in-memory client, with traces printed to the console.
import os
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.chromadb import ChromaDBInstrumentor
import chromadb
# Configure OpenTelemetry
resource = Resource.create({"service.name": "chromadb-app-instrumented"})
provider = TracerProvider(resource=resource)
processor = SimpleSpanProcessor(ConsoleSpanExporter())
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)
# Initialize ChromaDB instrumentation BEFORE using chromadb client
ChromaDBInstrumentor().instrument()
# Use ChromaDB (in-memory client for quickstart)
client = chromadb.Client()
try:
collection_name = "my_vector_collection"
collection = client.create_collection(name=collection_name)
print(f"Collection '{collection_name}' created.")
collection.add(
documents=["This is a document about dogs.", "This is a document about cats."],
metadatas=[{"source": "wiki"}, {"source": "wiki"}],
ids=["doc1", "doc2"]
)
print("Documents added.")
results = collection.query(
query_texts=["What are dogs?"],
n_results=1
)
print(f"Query results: {results}")
client.delete_collection(name=collection_name)
print(f"Collection '{collection_name}' deleted.")
except Exception as e:
print(f"An error occurred: {e}")
finally:
provider.shutdown()
Debug
Known issues
breakingThis instrumentation has specific version requirements for `chromadb`. As of `0.58.0`, it requires `chromadb<0.6,>=0.4.15`. Using incompatible versions may lead to instrumentation failures or runtime errors.fixAlways check the `install_requires` or `pyproject.toml` of the `opentelemetry-instrumentation-chromadb` package for the exact `chromadb` version range it supports and install a compatible client version.
affects: All versions, specific to requirements.txt
gotchaSemantic conventions, especially for GenAI and vector database attributes, are under active development within the OpenTelemetry ecosystem. Span attribute names, structures, and values may change between minor versions of the instrumentation, potentially requiring updates to your OpenTelemetry collector configuration or custom processing logic.fixRegularly review the release notes for changes in semantic conventions. Consider using a robust OTel collector setup that can handle attribute renames or schema changes, or pin the instrumentation version to ensure stability if custom processing relies on specific attributes.
affects: 0.53.4+
gotchaThe `ChromaDBInstrumentor().instrument()` call must occur *before* the `chromadb` client library is first imported or initialized in your application. If `chromadb` is imported globally at the start of your script, ensure the `instrument()` call is executed early in the application lifecycle.fixPlace `ChromaDBInstrumentor().instrument()` as early as possible in your application's startup code, typically right after OpenTelemetry SDK setup and before any `import chromadb` statements that are executed at the module level.
affects: All versions
Upgrade
Version history
0.62.3latest on PyPI · released Aug 10, 2026
Audit
Dependencies
chromadbrequiredThe core client library being instrumented. Specific version constraints apply.
opentelemetry-semantic-conventions[gen_ai]requiredProvides the necessary semantic conventions for GenAI and vector database operations.