Metadata-Version: 2.5
Name: opentelemetry-instrumentation-memorysync
Version: 1.0.0
Summary: OpenTelemetry instrumentation for the MemorySync Python SDK: memory operations as first-class spans in AgentOps, Respan, and any OTel backend.
Project-URL: Homepage, https://memorysync.io
Project-URL: Documentation, https://docs.memorysync.io/guides/agentops
Project-URL: Respan guide, https://docs.memorysync.io/guides/respan
Author-email: MemorySync <support@memorysync.io>
License: MIT
Keywords: agentops,agents,instrumentation,llm,memory,memorysync,observability,opentelemetry,respan,tracing
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: opentelemetry-api>=1.20.0
Requires-Dist: opentelemetry-instrumentation>=0.41b0
Provides-Extra: instruments
Requires-Dist: memorysync>=1.8.0; extra == 'instruments'
Provides-Extra: test
Requires-Dist: httpx<1.0,>=0.25; extra == 'test'
Requires-Dist: memorysync>=1.8.0; extra == 'test'
Requires-Dist: opentelemetry-sdk>=1.20.0; extra == 'test'
Requires-Dist: pytest>=7.0; extra == 'test'
Description-Content-Type: text/markdown

# opentelemetry-instrumentation-memorysync

OpenTelemetry instrumentation for the [MemorySync](https://memorysync.io)
Python SDK — memory operations become first-class spans in **AgentOps**,
**Respan**, and any other OpenTelemetry backend.

The first SDK-level tracing instrumentor shipped by any memory vendor.

```bash
pip install opentelemetry-instrumentation-memorysync
```

## With AgentOps

`agentops.init()` registers AgentOps as the global OpenTelemetry tracer
provider, so MemorySync spans land in your AgentOps traces automatically:

```python
import agentops
from opentelemetry.instrumentation.memorysync import instrument_memorysync
from memorysync import MemorySyncClient

agentops.init()            # before or after instrument_memorysync() — both work
instrument_memorysync()

client = MemorySyncClient(api_key="ms_...", base_url="https://api.memorysync.io")
client.add("Prefers window seats", source="chat")     # → span: memorysync.add
client.query("seating preferences", k=5)              # → span: memorysync.query
```

## With Respan (formerly Keywords AI)

Route your LLM calls through the Respan gateway and instrument MemorySync —
every step of the loop is a first-class span:

```python
from openai import OpenAI
from opentelemetry.instrumentation.memorysync import instrument_memorysync

instrument_memorysync()
llm = OpenAI(api_key=RESPAN_API_KEY, base_url="https://api.respan.ai/api/")

context = ms.recall(tenant_id=t, user_id=u, prompt=question, k=6)   # span 1
reply = llm.chat.completions.create(...)                            # gateway-traced
ms.add_turn(tenant_id=t, user_id=u, text=..., sync_embed=False)     # span 2
```

## With plain OpenTelemetry / auto-instrumentation

The package registers the standard `opentelemetry_instrumentor` entry
point, so the OTel CLI picks it up with zero code changes:

```bash
opentelemetry-instrument python app.py
```

## What gets traced

`memorysync.{operation}` CLIENT spans for both `MemorySyncClient` and
`AsyncMemorySyncClient` (full sync/async parity): `add`, `add_turn`,
`bulk_add`, `query`, `retrieve`, `recall`, `search_routed`, `get`,
`update`, `forget`, `summarize`, `history`, `feedback`, `list_memories`.

Attributes always include the operation, sync/async client kind,
server address, project/tenant/user identifiers, result counts, score
min/max/avg, `already_exists` idempotency signals, and error type +
HTTP status on failure. A `memorysync.client.operation.duration`
histogram is recorded per call.

## Privacy: content capture is OFF by default

Memory content is customer data. By default **no memory text, query
text, or recalled context is recorded** — only counts, identifiers,
scores, and latencies. Opt in explicitly:

```python
instrument_memorysync(capture_content=True)
# or: MEMORYSYNC_OTEL_CAPTURE_CONTENT=true
```

Even opted in, input is truncated to 500 characters and at most 5
result texts of 200 characters each are recorded.

## Engineering guarantees

- **Instrumentation can never break the app.** Attribute extraction is
  fully guarded; return values and exceptions pass through untouched;
  spans are always ended.
- **Zero stdout pollution** — the instrumentation never prints (the
  test suite asserts stdout stays empty during instrumented calls).
- **Idempotent** — `instrument_memorysync()` twice is safe;
  `uninstrument_memorysync()` restores the original methods.
- **Order independent** — OTel's proxy tracer late-binds, so
  instrumenting before your platform initializes still works.
- **Zero changes to the `memorysync` package** — methods are wrapped at
  runtime; nothing in the SDK itself is modified on disk.

## Docs

- AgentOps guide: https://docs.memorysync.io/guides/agentops
- Respan guide: https://docs.memorysync.io/guides/respan
