Metadata-Version: 2.4
Name: respan-instrumentation-marqo
Version: 0.2.0
Summary: Respan instrumentation plugin for Marqo
License: Apache 2.0
Author: Respan
Author-email: team@respan.ai
Requires-Python: >=3.11,<3.14
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: marqo (>=3.5.1,<4.0.0)
Requires-Dist: opentelemetry-semantic-conventions-ai (>=0.4.1,<0.6)
Requires-Dist: respan-sdk (>=2.6.26)
Requires-Dist: respan-tracing (>=2.17.0,<3.0.0)
Requires-Dist: wrapt (>=1.16.0)
Description-Content-Type: text/markdown

# Respan instrumentation for Marqo

Native OpenTelemetry instrumentation for the official Marqo Python client,
validated against Marqo 3.18.2 and the declared minimum 3.5.1.

```python
import os

import marqo
from opentelemetry.sdk.trace import TracerProvider

from respan_instrumentation_marqo import MarqoInstrumentor

provider = TracerProvider()  # Add your application's processors/exporters.
instrumentor = MarqoInstrumentor(tracer_provider=provider)
instrumentor.activate()
try:
    client = marqo.Client(url=os.environ["MARQO_URL"])
    result = client.index("documents").search(q="native tracing")
    print(result)
finally:
    instrumentor.deactivate()
    provider.shutdown()
```

The paired examples use actual released Marqo clients against a local controlled
HTTP server, with no Marqo credentials. Respan trace export requires an explicit
opt-in. These controlled examples do not establish hosted-service acceptance.

## Coverage

Client operations include `create_index`, `delete_index`, `get_indexes`, and
`bulk_search`. Index operations include create/delete, document add/update/get/
get-many/delete, search, recommend, embed, settings/stats/status/health, and model
ejection where available in the installed SDK. Native convenience aliases
produce one operation span. `index` and `get_index` retain their native handle
factory behavior and do not invent database-operation spans. Native minimum
model ejection requires its original `model_device` argument; the adapter does
not rewrite SDK signatures or parameters.

Database operations are task spans with standard database attributes and full
sanitized public inputs, observed serialized requests, and native results.
Actual `Index.embed` calls are embedding spans: complete returned vectors appear
in canonical entity output; nonvector response fields remain separately in
capture-gated metadata. Model and HTTP status fields are emitted only when
observed. No token usage, totals, response, error output, or HTTP status is
invented. A final observed HTTP status describes an actual request and does not
claim an aggregate batch status. Native worker requests may execute outside the
call context, leaving transport metadata unobserved while public batch inputs
and aggregate native results remain complete.

The released upstream instrumentor wraps only add/search/delete-documents and
does not provide this broader native API coverage or canonical payload/privacy
behavior. This adapter retains its existing native boundary. Native results,
exceptions, warnings, request serialization, callbacks, and SDK session ownership
are preserved. Instrumentation does not drain responses, repeat provider calls,
or close Marqo's module-owned HTTP session.

## Content and lifecycle

Sampling and general/LLM suppression are checked before telemetry content
inspection. Constructor `capture_content=False`, canonical Respan content flags,
legacy `trace_content`/`override_enable_content_tracing`, and both content
environment switches disable bodies. Initial and observed active/finished
ancestor denial cannot widen; unknown local parents fail closed. Later vetoes
clear owned input/output, native request buffers, metadata, diagnostics, SDK
events, and readable span snapshots before export.

Known native JSON and typed storage retain full records, 5001-value vectors,
schemas and false/zero/empty fields. Credentials in fields, quoted authentication
text and URLs are redacted; schema property names remain intact while sensitive
defaults/examples are redacted. Unknown user conversion, getter, equality, hash,
iterator, string and representation hooks are not invoked solely for telemetry.

Compatible owners share patches until the last deactivation. Configuration
conflicts raise `ValueError`, and restoration removes only owned descriptors and
processors. Observer startup, serialization, setter, attach/detach and end faults
preserve native outcomes and caller context. The supported runtime floors are
validated separately from current companions and a clean wheel built from the
sdist. Stored Respan trace fidelity remains a separate acceptance gate.

