Registry / observability / opentelemetry-instrumentation-marqo

opentelemetry-instrumentation-marqo

JSON →
library0.62.3pypypi✓ verified 23d ago

This library provides OpenTelemetry instrumentation for the Marqo vector database Python client. It enables automatic tracing of client-side calls to Marqo, helping developers gain observability into their LLM and vector search applications. Part of the larger OpenLLMetry project, it adheres to OpenTelemetry semantic conventions for LLM and vector DB operations. The library is actively maintained, with frequent releases (multiple per month) to keep up with updates to semantic conventions and the instrumented libraries.

pip install opentelemetry-instrumentation-marqo marqo
INSTALL
IMPORT
SIG · OPENTELEMETRY-INST
O
opentelemetry-instrumentation-marqo
observabilitypythonv0.62.3
Install
5.4s avg
Import
1063ms
Disk
36MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
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
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 1.118s · 37.3MB
glibc
py 3.103.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]
fix
Regularly 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.
fix
Ensure `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.
fix
Review 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.
fix
Consider 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.
Agent activity
50 hits · last 30 days
node
46
OpenAI (training)
1
Resources