Skip to main content

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)

Source distribution for respan-instrumentation-chroma 0.2.0
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)

Table of built distributions (wheels) for respan-instrumentation-chroma 0.2.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page