respan-instrumentation-chroma
Trace native Chroma Python collection and client operations as Respan task spans. Requests and responses retain full records, metadata, query results and vectors, including numpy arrays. Database queries and writes do not invent embedding model names or token usage. A native None return is captured as JSON null.
pip install respan-instrumentation-chroma chromadb
This plugin supports Chroma >=0.5.0,<2.0.0 on Python 3.11–3.13. Chroma 0.5 requires a compatible numpy release (numpy>=1.26.4,<2); install that constraint when using the minimum Chroma release. The plugin requires respan-sdk>=2.6.26, which exposes the canonical span constants, and released upstream Chroma instrumentation >=0.54.0 with its OTel 1.38 and AI semantic convention 0.5.1 dependency floor.
Local recording
import tempfile
import chromadb
from chromadb.config import Settings
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor
from respan_instrumentation_chroma import ChromaInstrumentor
provider = TracerProvider()
provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))
owner = ChromaInstrumentor(tracer_provider=provider)
owner.activate()
try:
with tempfile.TemporaryDirectory() as directory:
client = chromadb.PersistentClient(
path=directory, settings=Settings(anonymized_telemetry=False)
)
collection = client.create_collection("native_docs", embedding_function=None)
collection.add(
ids=["doc-1"], documents=["Native Chroma"], embeddings=[[0.0, 1.0]]
)
result = collection.query(query_embeddings=[[0.0, 1.0]], n_results=1)
print(result["ids"])
if hasattr(client, "close"):
client.close()
else:
client._system.stop()
finally:
owner.deactivate()
provider.shutdown()
To export these spans, add the released Respan exporter to your provider before activating the plugin:
import os
from opentelemetry.sdk.trace.export import SimpleSpanProcessor
from respan_tracing.exporters.respan import RespanSpanExporter
provider.add_span_processor(
SimpleSpanProcessor(
RespanSpanExporter(
endpoint="https://api.respan.ai/api/v2/traces",
api_key=os.environ["RESPAN_API_KEY"],
)
)
)
The plugin is also registered under the chroma entry point in respan.instrumentations for Respan discovery.
Native API coverage
The plugin retains the released upstream synchronous delegate for Collection.add/get/peek/query/modify/update/upsert/delete and the upstream SegmentAPI._query boundary where the native SDK uses it. It replaces lossy upstream summaries and unsafe exception coercion with complete capture-gated canonical input and output on those spans. This can produce a nested SegmentAPI query span on older Chroma engines.
Additional spans cover client collection creation, lookup, listing/counting/deletion and reset; collection count, indexing status, fork/fork count, search and attached-function operations; and released async client/collection operations. A method is installed only when the selected Chroma release actually exposes it. Chroma 0.5 has no async client API. New cloud-only operations such as fork/search retain their native local-engine capability errors; instrumentation does not enable unsupported server features. Client construction, embedding function calls and handle cleanup keep their native behavior.
Each database span uses respan.entity.log_type=task, standard database fields and JSON traceloop.entity.input/output. The input contains the bound native arguments and collection model when available. Return values, exceptions, callback invocation counts and resource lifetimes remain those of Chroma. Native embedding callbacks may compute vectors during a database operation; that database span still represents database work.
Content controls
Use ChromaInstrumentor(capture_content=False, tracer_provider=provider) to disable bodies. The canonical respan_enable_content_tracing=False, supported legacy context flags, RESPAN_TRACE_CONTENT and TRACELOOP_TRACE_CONTENT off values (false, 0, no, off) also disable content. The initial choice cannot widen later. Supplied context and ambient context both bound capture, and observed local ancestors retain vetoes through span end. Unknown local ancestors fail closed; valid remote parents remain usable.
Native OTel sampling and general/LLM suppression are checked before content extraction. Later vetoes remove captured bodies, error messages/descriptions and events before export, including the SDK ReadableSpan end snapshot. Credential values are redacted while schema property names and complete native data shapes remain available. Unknown object conversion/getter/iterator hooks are not invoked solely for tracing. OTel's configured span attribute count remains its native limit; complete canonical bodies are written last.
Multiple owners can share identical provider/context/capture/callback configuration. Conflicting configurations fail clearly. Deactivation restores only instrumentation-owned wrappers and context hooks, and preserves foreign replacements. Telemetry start, context, serialization, attribute and end failures do not replace native results or errors.
Runnable local persistent-engine and native HTTP examples live in python/tracing/chroma.
Metadata
Release files for respan-instrumentation-chroma 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| respan_instrumentation_chroma-0.2.0.tar.gz | 15.1 kB | With provenance | Details for respan_instrumentation_chroma-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| respan_instrumentation_chroma-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for respan_instrumentation_chroma-0.2.0-py3-none-any.whl |
Total release size: 30.6 kB
Release files / respan_instrumentation_chroma-0.2.0.tar.gz
| Download URL | respan_instrumentation_chroma-0.2.0.tar.gz |
|---|---|
| Size | 15.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
813e21c8dba638d58e02f436164dcc407ff634bab697091ff66a53bf251f21e0
|
|
BLAKE2b-256 checksum How to use checksums |
4bfe8d32ae63c74409b44f9dddfe78f9dca9efb890372ec3194e75c202768915
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 13, 2026.
Transparency logRelease files / respan_instrumentation_chroma-0.2.0-py3-none-any.whl
| Download URL | respan_instrumentation_chroma-0.2.0-py3-none-any.whl |
|---|---|
| Size | 15.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
756c93843444809c5d05b7559154b3f104a03ff21e2da24217aeb21655a25c71
|
|
BLAKE2b-256 checksum How to use checksums |
ce08b9905288a2f9ee0b8edc29554ed33b4935ef6203a70033bee7afb57a2308
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 13, 2026.
Transparency logSecurity for respan-instrumentation-chroma 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for respan_instrumentation_chroma-0.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 13, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.