Marqo | Respan Docs

Marqo is an end-to-end tensor search engine that combines vector search with traditional keyword search. It handles embedding generation, storage, and retrieval in a single platform, supporting text, images, and multimodal search. Respan gives you full observability over every index operation, search query, and embedding step.

Set up Respan

Create an account at platform.respan.ai and grab an API key.

Run npx @respan/cli setup to set up with your coding agent.

Example projects

Python examples

Tracing

Setup

Install packages

$ pip install respan-ai opentelemetry-instrumentation-marqo marqo

Set environment variables

$ export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"

RESPAN_API_KEY is used to export traces to Respan.

Initialize and run

1 import marqo
2 from respan import Respan
3 from opentelemetry.instrumentation.marqo import MarqoInstrumentor
4 
5 respan = Respan(instrumentations=[MarqoInstrumentor()])
6 
7 client = marqo.Client(url="http://localhost:8882")
8 
9 client.create_index("documents", model="hf/e5-base-v2")
10 
11 client.index("documents").add_documents(
12     [
13         {"title": "AI Observability", "description": "Respan provides tracing for AI applications."},
14         {"title": "Tensor Search", "description": "Marqo combines vector and keyword search."},
15         {"title": "Embeddings", "description": "Embeddings capture semantic meaning as vectors."},
16     ],
17     tensor_fields=["title", "description"],
18 )
19 
20 results = client.index("documents").search("How does AI tracing work?")
21 for hit in results["hits"]:
22     print(f"{hit['title']} (score: {hit['_score']:.4f})")
23 
24 respan.flush()

View your trace

Open the Traces page to see your Marqo operation spans with index operations, queries, and embeddings.

Configuration

Parameter	Type	Default	Description
`api_key`	`str \| None`	`None`	Falls back to `RESPAN_API_KEY` env var.
`base_url`	`str \| None`	`None`	Falls back to `RESPAN_BASE_URL` env var.
`instrumentations`	`list`	`[]`	Plugin instrumentations to activate (e.g. `MarqoInstrumentor()`).
`customer_identifier`	`str \| None`	`None`	Default customer identifier for all spans.
`metadata`	`dict \| None`	`None`	Default metadata attached to all spans.
`environment`	`str \| None`	`None`	Environment tag (e.g. `"production"`).

Attributes

In Respan()

1 from respan import Respan
2 from opentelemetry.instrumentation.marqo import MarqoInstrumentor
3 
4 respan = Respan(
5     instrumentations=[MarqoInstrumentor()],
6     customer_identifier="user_123",
7     metadata={"service": "search-api", "version": "1.0.0"},
8 )

With propagate_attributes

1 from respan import Respan, propagate_attributes
2 from opentelemetry.instrumentation.marqo import MarqoInstrumentor
3 
4 respan = Respan(instrumentations=[MarqoInstrumentor()])
5 
6 def search(user_id: str, query: str):
7     with propagate_attributes(
8         customer_identifier=user_id,
9         thread_identifier="conv_abc_123",
10         metadata={"plan": "pro"},
11     ):
12         return client.index("documents").search(query)

Attribute	Type	Description
`customer_identifier`	`str`	Identifies the end user in Respan analytics.
`thread_identifier`	`str`	Groups related messages into a conversation.
`metadata`	`dict`	Custom key-value pairs. Merged with default metadata.