Registry /
observability / opentelemetry-instrumentation-marqo
Install & Compatibility
Where this runs
tested against v0.62.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 1.118s · 37.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 5.4s · import 1.008s · 37MB
36MB installed
● package 36MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
MarqoInstrumentor
✓ from opentelemetry.instrumentation.marqo import MarqoInstrumentor
This quickstart demonstrates how to set up OpenTelemetry with the Marqo instrumentation. It configures a console exporter to print trace data directly to the terminal, enables the Marqo instrumentor, and then simulates basic Marqo client operations. The Marqo client is mocked to make the example runnable without requiring a live Marqo instance. In a production environment, you would replace `ConsoleSpanExporter` with an appropriate exporter (e.g., `OTLPSpanExporter`) and use the actual `marqo.Client`.
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, BatchSpanProcessor
from opentelemetry.trace import set_tracer_provider
# Import the Marqo instrumentation
from opentelemetry.instrumentation.marqo import MarqoInstrumentor
# --- OpenTelemetry Setup (Typical for any OTel Python app) ---
# Set up a TracerProvider
resource = Resource.create({"service.name": "my-marqo-app"})
tracer_provider = TracerProvider(resource=resource)
# Configure a SpanProcessor to export spans to the console
# In a real application, you would use an OTLPSpanExporter, JaegerExporter, etc.
console_exporter = ConsoleSpanExporter()
span_processor = BatchSpanProcessor(console_exporter)
tracer_provider.add_span_processor(span_processor)
# Set the global TracerProvider
set_tracer_provider(tracer_provider)
# Get a tracer for manual spans if needed
tracer = trace.get_tracer(__name__)
# --- Marqo Instrumentation Setup ---
# Instrument Marqo. This should ideally happen before 'marqo' is imported
# or its client is instantiated if MarqoInstrumentor().instrument() is called.
# For this example, we mock Marqo to ensure it's runnable without a live instance.
# Mock Marqo client for demonstration purposes
class MockMarqoClient:
def index(self, index_name):
return MockMarqoIndex(index_name)
class MockMarqoIndex:
def __init__(self, index_name):
self.index_name = index_name
def add_documents(self, documents, tensor_fields, client_batch_size=50):
with tracer.start_as_current_span(f"marqo.index.add_documents: {self.index_name}"):
print(f"Mock Marqo: Adding {len(documents)} documents to index '{self.index_name}'")
# Simulate Marqo client operation
return {"items": [{"_id": f"doc{i}"} for i in range(len(documents))]}
def search(self, q, searchable_attributes=None, limit=5):
with tracer.start_as_current_span(f"marqo.index.search: {self.index_name}"):
print(f"Mock Marqo: Searching for '{q}' in index '{self.index_name}'")
# Simulate Marqo client operation
return {"hits": [{"_id": "mock_doc_1", "_score": 0.9}, {"_id": "mock_doc_2", "_score": 0.8}]}}
# Enable Marqo instrumentation
# Note: In a real app, MarqoInstrumentor().instrument() should be called
# before you import the actual 'marqo' client if using programmatically.
MarqoInstrumentor().instrument()
# Simulate using the Marqo client
# If Marqo client was imported before instrumentation, you might need to re-import or defer client creation.
marqo_client = MockMarqoClient() # In a real app: mq.Client(url="http://localhost:8882")
# Perform Marqo operations
my_index = marqo_client.index("my_test_index")
my_index.add_documents(
documents=[
{"text": "hello world"},
{"text": "another document"}
],
tensor_fields=["text"]
)
my_index.search(q="world")
print("Marqo operations simulated with OpenTelemetry instrumentation.")
# Ensure all spans are processed before exiting
tracer_provider.shutdown()
Debug
Known issues
breakingThe OpenTelemetry GenAI semantic conventions are actively evolving. Recent versions (e.g., 0.53.4 to 0.58.0) have seen significant updates to attribute names and structures for LLM-related telemetry, including vector DB interactions. While changes are additive and backward-compatible at the API level, the actual telemetry data (span attributes) may change, requiring adjustments in your observability backend queries or dashboards. [cite: 0.58.0 release, 0.57.0 release, 0.55.0 release, 0.54.0 release, 0.53.4 release, 8, 31]fixRegularly review the OpenTelemetry GenAI semantic conventions documentation and `opentelemetry-instrumentation-marqo` release notes. Update dashboards and alert queries in your observability backend to reflect new attribute names or structures. Consider using OpenTelemetry Collector processors to normalize attributes if frequent changes are disruptive.
affects: 0.53.x - 0.58.x (and potentially future versions)
gotchaFor programmatic instrumentation, the `MarqoInstrumentor().instrument()` call must be made *before* the `marqo` library or its client is imported or instantiated in your application code. If `marqo` is imported first, the instrumentation might not apply correctly.fixEnsure `from opentelemetry.instrumentation.marqo import MarqoInstrumentor; MarqoInstrumentor().instrument()` is placed at the very beginning of your application's entry point, before any `import marqo` statements or `marqo.Client` instantiations.
affects: All versions
gotchaLike many LLM/VectorDB instrumentations, `opentelemetry-instrumentation-marqo` (especially when used with the broader Traceloop SDK) may capture prompts, responses, or document content by default. This data could contain sensitive or personally identifiable information (PII). While the `openllmetry` repository states telemetry is only collected in the SDK, specific instrumentations can still log content to spans.fixReview the specific implementation details or environment variables (e.g., `TRACELOOP_TRACE_CONTENT=false` for the Traceloop SDK, or `OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT`) to determine how to disable or redact sensitive content logging. Implement appropriate data redaction strategies at the OpenTelemetry Collector level or within your application if necessary. Always be aware of what data your observability pipeline is collecting.
affects: All versions
gotchaWhen deploying Python applications with multi-process web servers (e.g., Gunicorn with `workers > 1`), OpenTelemetry Python's automatic instrumentation (especially for metrics) can exhibit issues due to the forking model. This can lead to incomplete or incorrect telemetry data.fixConsider running Gunicorn with a single worker (`--workers 1`) or using `uvicorn` with `UvicornWorker` for multi-process environments. If using multiple workers is essential, explore programmatic instrumentation setup within each worker process or rely on `opentelemetry-instrument` wrapper, and verify metric correctness in your observability backend.
affects: All versions
Upgrade
Version history
0.62.3latest on PyPI · released Aug 10, 2026
Audit
Dependencies
marqorequiredThis package instruments the 'marqo' client library; 'marqo' must be installed for instrumentation to function.
opentelemetry-sdkrequiredCore OpenTelemetry SDK components are required for trace creation and export.
opentelemetry-apirequiredCore OpenTelemetry API components are required.