Skip to main content
  1. Sign up — Create an account at platform.respan.ai
  2. Create an API key — Generate one on the API keys page
  3. Add credits or a provider key — Add credits on the Credits page or connect your own provider key on the Integrations page
Add the Docs MCP to your AI coding tool to get help building with Respan. No API key needed.
{
  "mcpServers": {
    "respan-docs": {
      "url": "https://docs.respan.ai/mcp"
    }
  }
}

​
What is Chroma?

Chroma is an open-source embedding database designed for AI applications, with built-in document storage and automatic embedding generation. Respan auto-instruments Chroma operations so every add, query, and collection operation is captured as a traced span.

​
Setup

1

Install packages

pip install respan-ai opentelemetry-instrumentation-chromadb chromadb python-dotenv
2

Set environment variables

export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
Chroma runs locally by default, so no additional credentials are needed.
3

Initialize and run

import os
from dotenv import load_dotenv

load_dotenv()

import chromadb
from respan import Respan

# Initialize Respan with auto-instrumentation
respan = Respan(is_auto_instrument=True)

# Create a Chroma client (in-memory by default)
client = chromadb.Client()

# Create a collection
collection = client.create_collection(name="respan-demo")

# Add documents (Chroma auto-generates embeddings)
collection.add(
    ids=["doc_1", "doc_2", "doc_3"],
    documents=[
        "The quick brown fox jumps over the lazy dog.",
        "Machine learning models require large datasets.",
        "Vector databases enable similarity search at scale.",
    ],
    metadatas=[
        {"source": "literature"},
        {"source": "textbook"},
        {"source": "documentation"},
    ],
)

# Query
results = collection.query(
    query_texts=["How do vector databases work?"],
    n_results=2,
)
print(results)

respan.flush()
4

View your trace

Open the Traces page to see your Chroma spans including collection creation, add, and query operations.

​
Configuration

ParameterTypeDefaultDescription
api_keystr | NoneNoneFalls back to RESPAN_API_KEY env var.
base_urlstr | NoneNoneFalls back to RESPAN_BASE_URL env var.
is_auto_instrumentbool | NoneFalseAuto-discover installed instrumentors. Required for Traceloop instrumentors.
customer_identifierstr | NoneNoneDefault customer identifier for all spans.
metadatadict | NoneNoneDefault metadata attached to all spans.
environmentstr | NoneNoneEnvironment tag (e.g. "production").

​
Attributes

Attach customer identifiers, thread IDs, and metadata to spans.

​
In Respan()

Set defaults at initialization — these apply to all spans. 
from respan import Respan

respan = Respan(
    is_auto_instrument=True,
    customer_identifier="user_123",
    metadata={"service": "search-api", "version": "1.0.0"},
)

​
With propagate_attributes

Override per-request using a context manager. 
from respan import Respan, propagate_attributes

respan = Respan(is_auto_instrument=True)

with propagate_attributes(
    customer_identifier="user_456",
    thread_identifier="session_abc",
    metadata={"plan": "enterprise"},
):
    results = collection.query(
        query_texts=["semantic search techniques"],
        n_results=5,
    )
    print(results)
AttributeTypeDescription
customer_identifierstrIdentifies the end user in Respan analytics.
thread_identifierstrGroups related messages into a conversation.
metadatadictCustom key-value pairs. Merged with default metadata.

​
Examples

​
Create collection

import chromadb

client = chromadb.Client()

# Create with default embedding function
collection = client.create_collection(name="articles")

# Or with persistent storage
client = chromadb.PersistentClient(path="./chroma_data")
collection = client.create_collection(name="articles")

​
Add documents

# Add with auto-generated embeddings
collection.add(
    ids=["article_001", "article_002", "article_003"],
    documents=[
        "Introduction to neural networks and deep learning.",
        "Best practices for building REST APIs.",
        "Understanding vector similarity search algorithms.",
    ],
    metadatas=[
        {"topic": "ml", "author": "Alice"},
        {"topic": "engineering", "author": "Bob"},
        {"topic": "databases", "author": "Charlie"},
    ],
)

# Add with pre-computed embeddings (1536-dim)
collection.add(
    ids=["vec_001", "vec_002"],
    embeddings=[
        [0.12, 0.34, 0.56] + [0.0] * 1533,
        [0.78, 0.91, 0.23] + [0.0] * 1533,
    ],
    metadatas=[
        {"category": "electronics"},
        {"category": "clothing"},
    ],
)

​
Query

# Query by text
results = collection.query(
    query_texts=["How do neural networks learn?"],
    n_results=3,
    where={"topic": "ml"},
)

for doc, distance in zip(results["documents"][0], results["distances"][0]):
    print(f"distance={distance:.4f}: {doc[:80]}...")

# Query by embedding
results = collection.query(
    query_embeddings=[[0.12, 0.34, 0.56] + [0.0] * 1533],
    n_results=5,
)

​
Delete

# Delete by IDs
collection.delete(ids=["article_001", "article_002"])

# Delete by filter
collection.delete(where={"topic": "ml"})