{"id":2629,"library":"opentelemetry-instrumentation-chromadb","title":"OpenTelemetry ChromaDB Instrumentation","description":"This library provides OpenTelemetry auto-instrumentation for the ChromaDB vector database client, allowing developers to trace operations like collection creation, document addition, and queries. It's part of the OpenLLMetry project, ensuring compatibility with evolving GenAI semantic conventions. It is actively maintained with frequent releases, currently at version 0.58.0.","status":"active","version":"0.58.0","language":"en","source_language":"en","source_url":"https://github.com/traceloop/openllmetry/tree/main/packages/opentelemetry-instrumentation-chromadb","tags":["opentelemetry","observability","tracing","chromadb","llm","vector-database","ai","genai"],"install":[{"cmd":"pip install opentelemetry-instrumentation-chromadb chromadb","lang":"bash","label":"Install library and ChromaDB client"}],"dependencies":[{"reason":"The core client library being instrumented. Specific version constraints apply.","package":"chromadb","optional":false},{"reason":"Provides the necessary semantic conventions for GenAI and vector database operations.","package":"opentelemetry-semantic-conventions[gen_ai]","optional":false}],"imports":[{"symbol":"ChromaDBInstrumentor","correct":"from opentelemetry.instrumentation.chromadb import ChromaDBInstrumentor"}],"quickstart":{"code":"import os\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.chromadb import ChromaDBInstrumentor\nimport chromadb\n\n# Configure OpenTelemetry\nresource = Resource.create({\"service.name\": \"chromadb-app-instrumented\"})\nprovider = TracerProvider(resource=resource)\nprocessor = SimpleSpanProcessor(ConsoleSpanExporter())\nprovider.add_span_processor(processor)\ntrace.set_tracer_provider(provider)\n\n# Initialize ChromaDB instrumentation BEFORE using chromadb client\nChromaDBInstrumentor().instrument()\n\n# Use ChromaDB (in-memory client for quickstart)\nclient = chromadb.Client()\n\ntry:\n    collection_name = \"my_vector_collection\"\n    collection = client.create_collection(name=collection_name)\n    print(f\"Collection '{collection_name}' created.\")\n\n    collection.add(\n        documents=[\"This is a document about dogs.\", \"This is a document about cats.\"],\n        metadatas=[{\"source\": \"wiki\"}, {\"source\": \"wiki\"}],\n        ids=[\"doc1\", \"doc2\"]\n    )\n    print(\"Documents added.\")\n\n    results = collection.query(\n        query_texts=[\"What are dogs?\"],\n        n_results=1\n    )\n    print(f\"Query results: {results}\")\n\n    client.delete_collection(name=collection_name)\n    print(f\"Collection '{collection_name}' deleted.\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n\nfinally:\n    provider.shutdown()","lang":"python","description":"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."},"warnings":[{"fix":"Always 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.","message":"This 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.","severity":"breaking","affected_versions":"All versions, specific to requirements.txt"},{"fix":"Regularly 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.","message":"Semantic 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.","severity":"gotcha","affected_versions":"0.53.4+"},{"fix":"Place `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.","message":"The `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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}