OpenTelemetry Instrumentation for Marqo

OpenTelemetry Instrumentation for Marqo is part of Traceloop’s OpenLLMetry project. It automatically wraps the official Marqo Python client so that vector-database operations emit OpenTelemetry spans, giving you distributed traces of your retrieval and indexing calls without changing application code.

Install the package, call MarqoInstrumentor().instrument(), and every Marqo query, insert, and delete is captured as a span you can export to any OpenTelemetry-compatible backend such as Jaeger, Grafana Tempo, or Traceloop. It plugs directly into existing OpenTelemetry pipelines for GenAI and RAG observability.

What You Get

• Automatic span creation for Marqo client operations (add_documents, search, and delete_documents)
• A single-call instrumentor that hooks the client via wrapt with no application code changes
• Compatibility with any OpenTelemetry tracer provider and exporter

Common Use Cases

• Tracing Marqo retrieval latency inside a RAG pipeline
• Correlating vector-database calls with LLM spans in an end-to-end GenAI trace
• Monitoring Marqo indexing and query performance in production

Under The Hood

Architecture - The instrumentor subclasses OpenTelemetry’s BaseInstrumentor. On instrument() it iterates a WRAPPED_METHODS table and uses wrapt.wrap_function_wrapper to patch the target methods on marqo.index.Index (add_documents / search / delete_documents), so each call opens a span through the configured tracer before delegating to the original method. uninstrument() unwraps them.

Tech Stack - Pure Python (>=3.10), depending on opentelemetry-api, opentelemetry-instrumentation, opentelemetry-semantic-conventions, the AI semantic conventions package, and wrapt for monkey-patching. Packaged with a PEP 621 pyproject.toml and managed by uv within the OpenLLMetry monorepo.

Code Quality - The module is small and focused: an __init__.py instrumentor, a wrapper.py that builds spans and records attributes/exceptions, a config.py holding an exception logger, and a version.py. It ships pytest-based tests (including recorded cassettes for some packages) and is linted with ruff.

API Design - The public surface is a single class, MarqoInstrumentor, with .instrument() / .uninstrument() and an optional exception_logger. Getting started is one import and one call, matching the standard OpenTelemetry instrumentor contract that developers already know.