{"library":"opentelemetry-instrumentation-marqo","title":"OpenTelemetry Marqo Instrumentation","description":"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.","language":"python","status":"active","last_verified":"Thu May 14","install":{"commands":["pip install opentelemetry-instrumentation-marqo marqo"],"cli":null},"imports":["from opentelemetry.instrumentation.marqo import MarqoInstrumentor"],"auth":{"required":false,"env_vars":[]},"quickstart":{"code":"import os\nfrom opentelemetry import trace\nfrom opentelemetry.sdk.resources import Resource\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.trace.export import ConsoleSpanExporter, BatchSpanProcessor\nfrom opentelemetry.trace import set_tracer_provider\n\n# Import the Marqo instrumentation\nfrom opentelemetry.instrumentation.marqo import MarqoInstrumentor\n\n# --- OpenTelemetry Setup (Typical for any OTel Python app) ---\n# Set up a TracerProvider\nresource = Resource.create({\"service.name\": \"my-marqo-app\"})\ntracer_provider = TracerProvider(resource=resource)\n\n# Configure a SpanProcessor to export spans to the console\n# In a real application, you would use an OTLPSpanExporter, JaegerExporter, etc.\nconsole_exporter = ConsoleSpanExporter()\nspan_processor = BatchSpanProcessor(console_exporter)\ntracer_provider.add_span_processor(span_processor)\n\n# Set the global TracerProvider\nset_tracer_provider(tracer_provider)\n\n# Get a tracer for manual spans if needed\ntracer = trace.get_tracer(__name__)\n\n# --- Marqo Instrumentation Setup ---\n# Instrument Marqo. This should ideally happen before 'marqo' is imported\n# or its client is instantiated if MarqoInstrumentor().instrument() is called.\n# For this example, we mock Marqo to ensure it's runnable without a live instance.\n\n# Mock Marqo client for demonstration purposes\nclass MockMarqoClient:\n    def index(self, index_name):\n        return MockMarqoIndex(index_name)\n\nclass MockMarqoIndex:\n    def __init__(self, index_name):\n        self.index_name = index_name\n\n    def add_documents(self, documents, tensor_fields, client_batch_size=50):\n        with tracer.start_as_current_span(f\"marqo.index.add_documents: {self.index_name}\"):\n            print(f\"Mock Marqo: Adding {len(documents)} documents to index '{self.index_name}'\")\n            # Simulate Marqo client operation\n            return {\"items\": [{\"_id\": f\"doc{i}\"} for i in range(len(documents))]}\n\n    def search(self, q, searchable_attributes=None, limit=5):\n        with tracer.start_as_current_span(f\"marqo.index.search: {self.index_name}\"):\n            print(f\"Mock Marqo: Searching for '{q}' in index '{self.index_name}'\")\n            # Simulate Marqo client operation\n            return {\"hits\": [{\"_id\": \"mock_doc_1\", \"_score\": 0.9}, {\"_id\": \"mock_doc_2\", \"_score\": 0.8}]}}\n\n# Enable Marqo instrumentation\n# Note: In a real app, MarqoInstrumentor().instrument() should be called\n# before you import the actual 'marqo' client if using programmatically.\nMarqoInstrumentor().instrument()\n\n# Simulate using the Marqo client\n# If Marqo client was imported before instrumentation, you might need to re-import or defer client creation.\nmarqo_client = MockMarqoClient() # In a real app: mq.Client(url=\"http://localhost:8882\")\n\n# Perform Marqo operations\nmy_index = marqo_client.index(\"my_test_index\")\nmy_index.add_documents(\n    documents=[\n        {\"text\": \"hello world\"},\n        {\"text\": \"another document\"}\n    ],\n    tensor_fields=[\"text\"]\n)\n\nmy_index.search(q=\"world\")\n\nprint(\"Marqo operations simulated with OpenTelemetry instrumentation.\")\n\n# Ensure all spans are processed before exiting\ntracer_provider.shutdown()","lang":"python","description":"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`.","tag":null,"tag_description":null,"last_tested":"2026-04-25","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]},"compatibility":{"tag":null,"tag_description":null,"last_tested":"2026-05-14","installed_version":"0.50.1","pypi_latest":"0.60.0","is_stale":true,"summary":{"python_range":"3.10–3.9","success_rate":100,"avg_install_s":4.9,"avg_import_s":1.33,"wheel_type":"wheel"},"results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"opentelemetry-instrumentation-marqo","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":1.18,"mem_mb":18.9,"disk_size":"37.7M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"opentelemetry-instrumentation-marqo","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.23,"mem_mb":18.9,"disk_size":"37.6M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"opentelemetry-instrumentation-marqo","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":5.5,"import_time_s":0.84,"mem_mb":18.9,"disk_size":"37M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"opentelemetry-instrumentation-marqo","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.93,"mem_mb":18.9,"disk_size":"37M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"opentelemetry-instrumentation-marqo","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":1.55,"mem_mb":21.5,"disk_size":"41.1M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"opentelemetry-instrumentation-marqo","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.81,"mem_mb":21.4,"disk_size":"41.1M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"opentelemetry-instrumentation-marqo","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":4.7,"import_time_s":1.4,"mem_mb":21.5,"disk_size":"41M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"opentelemetry-instrumentation-marqo","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.37,"mem_mb":21.4,"disk_size":"41M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"opentelemetry-instrumentation-marqo","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":1.57,"mem_mb":20.6,"disk_size":"32.6M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"opentelemetry-instrumentation-marqo","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.79,"mem_mb":20.5,"disk_size":"32.6M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"opentelemetry-instrumentation-marqo","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":3.8,"import_time_s":1.62,"mem_mb":20.6,"disk_size":"32M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"opentelemetry-instrumentation-marqo","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.78,"mem_mb":20.5,"disk_size":"32M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"opentelemetry-instrumentation-marqo","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":1.25,"mem_mb":19.9,"disk_size":"32.4M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"opentelemetry-instrumentation-marqo","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.3,"mem_mb":19.8,"disk_size":"32.2M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"opentelemetry-instrumentation-marqo","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":3.9,"import_time_s":1.2,"mem_mb":19.9,"disk_size":"32M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"opentelemetry-instrumentation-marqo","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.35,"mem_mb":19.8,"disk_size":"32M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"opentelemetry-instrumentation-marqo","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":1.05,"mem_mb":18.7,"disk_size":"36.8M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"opentelemetry-instrumentation-marqo","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.14,"mem_mb":18.7,"disk_size":"36.8M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"opentelemetry-instrumentation-marqo","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":6.4,"import_time_s":1.05,"mem_mb":18.7,"disk_size":"37M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"opentelemetry-instrumentation-marqo","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.22,"mem_mb":18.7,"disk_size":"37M"}]}}