OpenTelemetry ChromaDB Instrumentation

Warnings

• breaking 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• pip install opentelemetry-instrumentation-chromadb chromadb Install library and ChromaDB client

Imports

• ChromaDBInstrumentor

  from opentelemetry.instrumentation.chromadb import ChromaDBInstrumentor

Quickstart

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()