mintmory-api 0.1.0__tar.gz → 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -57,3 +57,4 @@ scripts/corpus_parts/
57
57
  *.db
58
58
  *.db-wal
59
59
  *.db-shm
60
+ .l4-out/
@@ -1,6 +1,6 @@
1
- Metadata-Version: 2.4
1
+ Metadata-Version: 2.5
2
2
  Name: mintmory-api
3
- Version: 0.1.0
3
+ Version: 0.2.0
4
4
  Summary: MintMory HTTP REST API via FastAPI
5
5
  Project-URL: Homepage, https://github.com/WeLikeCode/mint-mory
6
6
  Project-URL: Repository, https://github.com/WeLikeCode/mint-mory
@@ -18,7 +18,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
18
18
  Classifier: Typing :: Typed
19
19
  Requires-Python: >=3.12
20
20
  Requires-Dist: fastapi>=0.115
21
- Requires-Dist: mintmory-core~=0.1.0
21
+ Requires-Dist: mintmory-core~=0.2.0
22
22
  Requires-Dist: python-multipart>=0.0.12
23
23
  Requires-Dist: structlog>=24.4
24
24
  Requires-Dist: uvicorn[standard]>=0.32
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "mintmory-api"
3
- version = "0.1.0"
3
+ version = "0.2.0"
4
4
  description = "MintMory HTTP REST API via FastAPI"
5
5
  requires-python = ">=3.12"
6
6
  readme = "README.md"
@@ -19,7 +19,7 @@ classifiers = [
19
19
  ]
20
20
 
21
21
  dependencies = [
22
- "mintmory-core~=0.1.0",
22
+ "mintmory-core~=0.2.0",
23
23
  "fastapi>=0.115",
24
24
  "uvicorn[standard]>=0.32",
25
25
  "python-multipart>=0.0.12",
@@ -13,12 +13,15 @@ from __future__ import annotations
13
13
 
14
14
  from collections.abc import AsyncGenerator, Callable
15
15
  from contextlib import asynccontextmanager
16
+ from importlib.metadata import PackageNotFoundError
17
+ from importlib.metadata import version as _dist_version
16
18
  from typing import Annotated
17
19
 
18
20
  import anyio
19
21
  import anyio.to_thread
20
- from fastapi import FastAPI, HTTPException, Query
22
+ from fastapi import FastAPI, HTTPException, Query, Request
21
23
  from fastapi.middleware.cors import CORSMiddleware
24
+ from fastapi.responses import JSONResponse
22
25
  from mintmory.api.schemas import (
23
26
  CaptionRunRequest,
24
27
  ConceptLinkCreate,
@@ -30,31 +33,43 @@ from mintmory.api.schemas import (
30
33
  SessionFeedback,
31
34
  SummaryPut,
32
35
  )
36
+ from mintmory.api.telemetry_middleware import TelemetryMiddleware
33
37
  from mintmory.core import session as session_module
34
38
  from mintmory.core.config import load_settings
35
- from mintmory.core.dreaming import DreamingEngine
39
+ from mintmory.core.dreaming import DreamFailedError, DreamingEngine
40
+ from mintmory.core.dreaming import run_dream as run_tenant_dreams
36
41
  from mintmory.core.llm import build_dreaming_engine
37
42
  from mintmory.core.ports import StorageBackend
38
43
  from mintmory.core.storage_factory import build_storage
39
- from mintmory.core.telemetry import init_telemetry
44
+ from mintmory.core.telemetry import init_telemetry, shutdown_telemetry
40
45
  from mintmory.core.types import (
41
46
  SYMMETRIC_LINK_TYPES,
47
+ TENANT_GLOBAL,
42
48
  CaptionRunReport,
43
49
  ConceptLink,
44
50
  ConceptLinkType,
45
- DreamIntensity,
51
+ CrossTenantLinkError,
46
52
  DreamReport,
47
53
  ImageDescription,
48
54
  ImageJob,
55
+ InvalidTenantIdError,
49
56
  LinkSource,
50
57
  MemoryRecord,
51
58
  MemoryStats,
52
59
  MemorySummary,
53
60
  NoteResult,
61
+ ProtectedTenantError,
54
62
  QuerySession,
63
+ ScopeRequiredError,
55
64
  SearchRequest,
56
65
  SearchResponse,
57
66
  SummaryJob,
67
+ TenancyNotSupportedError,
68
+ TenantError,
69
+ TenantImmutableError,
70
+ TenantInactiveError,
71
+ TenantMigrationError,
72
+ TenantNotFoundError,
58
73
  )
59
74
 
60
75
  # ---------------------------------------------------------------------------
@@ -89,7 +104,7 @@ async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
89
104
  # NO embedder — API-added memories get NULL embeddings (asymmetry vs CLI).
90
105
  _store = build_storage(settings.storage)
91
106
  _store.initialise()
92
- init_telemetry(settings.otel)
107
+ init_telemetry(settings.otel, default_service_name="mintmory-api")
93
108
 
94
109
  # Startup guard (design §6.3): cap anyio's default thread-limiter to at most
95
110
  # pool_max so we never queue more DB threads than the pool can serve.
@@ -100,14 +115,20 @@ async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
100
115
  limiter.total_tokens = pool_max
101
116
 
102
117
  yield
118
+ shutdown_telemetry()
103
119
  if _store:
104
120
  _store.close()
105
121
  _store = None
106
122
 
107
123
 
124
+ try:
125
+ _VERSION = _dist_version("mintmory-api")
126
+ except PackageNotFoundError: # running from a source tree without an install
127
+ _VERSION = "0.0.0+unknown"
128
+
108
129
  app = FastAPI(
109
130
  title="MintMory Memory API",
110
- version="0.1.0",
131
+ version=_VERSION,
111
132
  description=(
112
133
  "Palantir-Ontology-inspired typed memory for LLM agents. "
113
134
  "See docs/openapi/mintmory.yaml for the full contract."
@@ -122,6 +143,31 @@ app.add_middleware(
122
143
  allow_headers=["*"],
123
144
  )
124
145
 
146
+ app.add_middleware(TelemetryMiddleware)
147
+
148
+
149
+ @app.exception_handler(DreamFailedError)
150
+ async def _dream_failed_error(_: Request, exc: DreamFailedError) -> JSONResponse:
151
+ return JSONResponse({"detail": str(exc)}, status_code=500)
152
+
153
+
154
+ _TENANT_HTTP: dict[type[TenantError], int] = {
155
+ TenantNotFoundError: 404,
156
+ TenantInactiveError: 409,
157
+ CrossTenantLinkError: 409,
158
+ TenantImmutableError: 409,
159
+ ProtectedTenantError: 403,
160
+ ScopeRequiredError: 403,
161
+ InvalidTenantIdError: 422,
162
+ TenancyNotSupportedError: 501,
163
+ TenantMigrationError: 503,
164
+ }
165
+
166
+
167
+ @app.exception_handler(TenantError)
168
+ async def _tenant_error(_: Request, exc: TenantError) -> JSONResponse:
169
+ return JSONResponse({"detail": str(exc)}, status_code=_TENANT_HTTP.get(type(exc), 400))
170
+
125
171
 
126
172
  def get_store() -> StorageBackend:
127
173
  if _store is None:
@@ -334,10 +380,12 @@ async def run_dream(body: DreamRequest) -> DreamReport:
334
380
  intensity = body.intensity
335
381
 
336
382
  def _do_dream() -> DreamReport:
337
- engine = DreamingEngine(store)
338
- if intensity is DreamIntensity.FULL:
339
- return engine.run_full()
340
- return engine.run_light()
383
+ return run_tenant_dreams(
384
+ store,
385
+ intensity=intensity,
386
+ tenant_id=None,
387
+ engine_factory=lambda tenant_id: DreamingEngine(store, tenant_id=tenant_id),
388
+ )
341
389
 
342
390
  return await _db(_do_dream)
343
391
 
@@ -417,6 +465,7 @@ async def list_summary_jobs(
417
465
  settings.llm,
418
466
  link_settings=settings.link,
419
467
  summary_settings=settings.summary,
468
+ tenant_id=TENANT_GLOBAL,
420
469
  )
421
470
  jobs = engine.collect_summary_jobs(include_all=include_all)
422
471
  return jobs[:limit] if limit > 0 else jobs
@@ -445,6 +494,7 @@ async def put_summary(concept: str, body: SummaryPut) -> MemorySummary:
445
494
  settings.llm,
446
495
  link_settings=settings.link,
447
496
  summary_settings=settings.summary,
497
+ tenant_id=TENANT_GLOBAL,
448
498
  )
449
499
  return engine.apply_summary(concept, summary_text)
450
500
 
@@ -0,0 +1,169 @@
1
+ """ASGI middleware that traces each HTTP request as a SERVER span.
2
+
3
+ Spec: observability › HTTP server spans continue the caller's trace; observability › How the
4
+ middleware ends the server span; observability › Middleware telemetry never alters a request;
5
+ observability › Excluded HTTP paths; observability › HTTP server duration metric.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import contextlib
11
+ import functools
12
+ import logging
13
+ import os
14
+ import re
15
+ import time
16
+ from collections.abc import Callable
17
+ from typing import Any
18
+
19
+ from mintmory.core import telemetry
20
+
21
+ _LOGGER = logging.getLogger("mintmory.telemetry")
22
+
23
+ _EXCLUDED_URLS_VARIABLE = "OTEL_PYTHON_EXCLUDED_URLS"
24
+ _HEALTH_PATHS = ("/healthz", "/readyz")
25
+ _DURATION_HISTOGRAM = "http.server.request.duration"
26
+ _DURATION_BUCKETS = (0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10)
27
+ _REQUEST_METHOD = "http.request.method"
28
+ _ROUTE = "http.route"
29
+ _RESPONSE_STATUS = "http.response.status_code"
30
+ _INTERNAL_ERROR_STATUS = 500
31
+
32
+
33
+ def _safe(step: Callable[..., Any], *args: Any, **kwargs: Any) -> Any:
34
+ """Run one telemetry step; drop its failure at DEBUG so the request is unaffected.
35
+
36
+ The step's result comes back unchanged. A raising step is dropped with one DEBUG record on
37
+ ``mintmory.telemetry`` naming only the exception class, and ``None`` comes back.
38
+ """
39
+ try:
40
+ return step(*args, **kwargs)
41
+ except Exception as error: # noqa: BLE001 - a telemetry step must never alter the request
42
+ _LOGGER.debug("telemetry: http middleware step failed (%s)", type(error).__name__)
43
+ return None
44
+
45
+
46
+ @functools.cache
47
+ def _compile_excluded(value: str) -> tuple[re.Pattern[str], ...]:
48
+ """Compile the comma-separated regexes of ``value``, skipping invalid items.
49
+
50
+ Items are stripped and empties ignored; an invalid regex is skipped with one WARNING
51
+ naming it. Cached on the whole value, so the warning is logged at the value's first compile.
52
+ """
53
+ patterns: list[re.Pattern[str]] = []
54
+ for item in value.split(","):
55
+ item = item.strip()
56
+ if not item:
57
+ continue
58
+ try:
59
+ patterns.append(re.compile(item))
60
+ except re.error:
61
+ _LOGGER.warning("invalid %s pattern %r skipped", _EXCLUDED_URLS_VARIABLE, item)
62
+ return tuple(patterns)
63
+
64
+
65
+ def _is_excluded(path: str) -> bool:
66
+ """Whether ``path`` is a health probe or matches an ``OTEL_PYTHON_EXCLUDED_URLS`` regex."""
67
+ if path in _HEALTH_PATHS:
68
+ return True
69
+ value = os.environ.get(_EXCLUDED_URLS_VARIABLE, "")
70
+ patterns: tuple[re.Pattern[str], ...] = _safe(_compile_excluded, value) or ()
71
+ return any(pattern.search(path) is not None for pattern in patterns)
72
+
73
+
74
+ def _decode_headers(headers: Any) -> dict[str, str]:
75
+ """ASGI header bytes as a lower-cased mapping, decoded as latin-1."""
76
+ decoded: dict[str, str] = {}
77
+ for name, value in headers:
78
+ decoded[name.decode("latin-1").lower()] = value.decode("latin-1")
79
+ return decoded
80
+
81
+
82
+ class TelemetryMiddleware:
83
+ """Outermost user middleware: one SERVER span and one duration point per traced request."""
84
+
85
+ def __init__(self, app: Any) -> None:
86
+ self.app = app
87
+
88
+ async def __call__(self, scope: Any, receive: Any, send: Any) -> None:
89
+ if scope.get("type") != "http" or _is_excluded(scope.get("path", "")):
90
+ await self.app(scope, receive, send)
91
+ return
92
+
93
+ method = scope.get("method", "")
94
+
95
+ headers = _safe(_decode_headers, scope.get("headers") or []) or {}
96
+ context = _safe(telemetry.extract_context, headers)
97
+
98
+ stack = contextlib.ExitStack()
99
+ span_cm = _safe(
100
+ telemetry.span,
101
+ method,
102
+ kind="server",
103
+ context=context,
104
+ record_exception=False,
105
+ set_status_on_exception=False,
106
+ )
107
+ span = None if span_cm is None else _safe(stack.enter_context, span_cm)
108
+ if span is None:
109
+ _safe(stack.close)
110
+ await self.app(scope, receive, send)
111
+ return
112
+
113
+ started = time.perf_counter()
114
+ sent: list[int] = []
115
+
116
+ async def wrapped_send(message: Any) -> None:
117
+ if message.get("type") == "http.response.start" and not sent:
118
+ sent.append(message.get("status"))
119
+ await send(message)
120
+
121
+ error: Exception | None = None
122
+ try:
123
+ await self.app(scope, receive, wrapped_send)
124
+ except Exception as exc:
125
+ error = exc
126
+ finally:
127
+ route = scope.get("route")
128
+ route_path = _safe(getattr, route, "path", None) if route is not None else None
129
+ if not isinstance(route_path, str):
130
+ route_path = None
131
+ if route_path is not None:
132
+ _safe(span.update_name, f"{method} {route_path}")
133
+
134
+ status = sent[0] if sent else None
135
+ if not isinstance(status, int):
136
+ status = None
137
+ if status is None and error is not None:
138
+ status = _INTERNAL_ERROR_STATUS
139
+
140
+ attributes: dict[str, Any] = {_REQUEST_METHOD: method}
141
+ if route_path is not None:
142
+ attributes[_ROUTE] = route_path
143
+ if status is not None:
144
+ attributes[_RESPONSE_STATUS] = status
145
+ _safe(span.set_attributes, attributes)
146
+
147
+ if error is not None:
148
+ _safe(telemetry.mark_error, span, type(error).__name__)
149
+ elif status is not None and status >= _INTERNAL_ERROR_STATUS:
150
+ _safe(telemetry.mark_error, span, str(status))
151
+
152
+ metric_attributes: dict[str, Any] = {_REQUEST_METHOD: method}
153
+ if route_path is not None:
154
+ metric_attributes[_ROUTE] = route_path
155
+ if status is not None:
156
+ metric_attributes[_RESPONSE_STATUS] = status
157
+ _safe(
158
+ telemetry.record_histogram,
159
+ _DURATION_HISTOGRAM,
160
+ time.perf_counter() - started,
161
+ unit="s",
162
+ boundaries=_DURATION_BUCKETS,
163
+ **metric_attributes,
164
+ )
165
+
166
+ _safe(stack.close)
167
+
168
+ if error is not None:
169
+ raise error
@@ -0,0 +1,122 @@
1
+ """Task 2.1 gate: the deployment scenarios re-pinned under fresh names.
2
+
3
+ Spec: deployment › Telemetry activation at API startup.
4
+
5
+ Task 2.1 is the unit's final check (the ruff/format/mypy/coverage gates). It adds no
6
+ behaviour of its own, so the three API scenarios of the delta are re-pinned here against
7
+ the lifespan that already satisfies them (TDD exemption: already satisfied by task 1.3).
8
+ Each test starts the real ``mintmory.api.app.app`` under ``TestClient`` and asserts a
9
+ real, non-zero answer (the recorded activator arguments, the flushed call order), so it
10
+ fails on a base without the lifespan wiring.
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ from collections.abc import Iterator
16
+ from pathlib import Path
17
+ from typing import Any
18
+
19
+ import pytest
20
+ from fastapi.testclient import TestClient
21
+ from mintmory.api import app as app_module
22
+ from mintmory.core import telemetry
23
+
24
+ _OTLP_ENDPOINT_VARIABLES = (
25
+ "OTEL_EXPORTER_OTLP_ENDPOINT",
26
+ "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT",
27
+ "OTEL_EXPORTER_OTLP_METRICS_ENDPOINT",
28
+ )
29
+
30
+
31
+ @pytest.fixture
32
+ def gate_db(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Iterator[None]:
33
+ """Point the API at a throwaway DB and reset the global store around startup."""
34
+ monkeypatch.setenv("MINTMORY_DB", str(tmp_path / "api_telemetry_gate.db"))
35
+ monkeypatch.setattr(app_module, "_store", None)
36
+ yield
37
+ monkeypatch.setattr(app_module, "_store", None)
38
+
39
+
40
+ def _record_activator(monkeypatch: pytest.MonkeyPatch) -> list[tuple[Any, dict[str, Any]]]:
41
+ """Wrap ``mintmory.api.app.init_telemetry`` with a recorder that still initialises."""
42
+ calls: list[tuple[Any, dict[str, Any]]] = []
43
+ real_init = telemetry.init_telemetry
44
+
45
+ def _record(settings: Any = None, **kwargs: Any) -> bool:
46
+ calls.append((settings, kwargs))
47
+ return real_init(settings, **kwargs)
48
+
49
+ monkeypatch.setattr(app_module, "init_telemetry", _record)
50
+ return calls
51
+
52
+
53
+ @pytest.mark.l4("C-5d7fad0c")
54
+ def test_gate_api_uses_noop_shim_without_a_collector(
55
+ gate_db: None, monkeypatch: pytest.MonkeyPatch
56
+ ) -> None:
57
+ """In ``auto`` with no collector the API stays off under ``mintmory-api``.
58
+
59
+ The off result is the zero value, so the test also asserts the recorded activator
60
+ argument (the non-zero default service name) and that the lifespan ran.
61
+ """
62
+ monkeypatch.delenv("MINTMORY_OTEL_ENABLED", raising=False)
63
+ for variable in _OTLP_ENDPOINT_VARIABLES:
64
+ monkeypatch.delenv(variable, raising=False)
65
+ monkeypatch.setattr(telemetry, "_endpoint_reachable", lambda url, timeout=0.1: False)
66
+
67
+ calls = _record_activator(monkeypatch)
68
+ with TestClient(app_module.app) as client:
69
+ assert client.get("/healthz").status_code == 200
70
+ assert telemetry.is_enabled() is False
71
+
72
+ assert calls, "the API lifespan must activate telemetry once at startup"
73
+ _settings, kwargs = calls[0]
74
+ assert kwargs.get("default_service_name") == "mintmory-api"
75
+
76
+
77
+ @pytest.mark.l4("C-59ff07c0")
78
+ def test_gate_api_enables_telemetry_when_configured(
79
+ gate_db: None, monkeypatch: pytest.MonkeyPatch, closed_port: int
80
+ ) -> None:
81
+ """``MINTMORY_OTEL_ENABLED=true`` turns the API's telemetry on under ``mintmory-api``."""
82
+ pytest.importorskip("opentelemetry.sdk")
83
+ monkeypatch.setenv("MINTMORY_OTEL_ENABLED", "true")
84
+ monkeypatch.setenv("OTEL_EXPORTER_OTLP_ENDPOINT", f"http://127.0.0.1:{closed_port}")
85
+
86
+ calls = _record_activator(monkeypatch)
87
+ with TestClient(app_module.app) as client:
88
+ assert client.get("/healthz").status_code == 200
89
+ assert telemetry.is_enabled() is True
90
+
91
+ assert calls, "the API lifespan must activate telemetry once at startup"
92
+ _settings, kwargs = calls[0]
93
+ assert kwargs.get("default_service_name") == "mintmory-api"
94
+
95
+
96
+ @pytest.mark.l4("C-5fc161bb")
97
+ def test_gate_api_shutdown_flushes_then_closes_store(
98
+ gate_db: None, monkeypatch: pytest.MonkeyPatch
99
+ ) -> None:
100
+ """At shutdown the API flushes telemetry before closing the store."""
101
+ calls: list[str] = []
102
+
103
+ class _RecordingStore:
104
+ def initialise(self) -> None:
105
+ return None
106
+
107
+ def close(self) -> None:
108
+ calls.append("close")
109
+
110
+ def _build_recording_store(*args: Any, **kwargs: Any) -> _RecordingStore:
111
+ return _RecordingStore()
112
+
113
+ def _record_shutdown(*args: Any, **kwargs: Any) -> None:
114
+ calls.append("shutdown_telemetry")
115
+
116
+ monkeypatch.setattr(app_module, "build_storage", _build_recording_store)
117
+ monkeypatch.setattr(app_module, "shutdown_telemetry", _record_shutdown)
118
+
119
+ with TestClient(app_module.app) as client:
120
+ assert client.get("/healthz").status_code == 200
121
+
122
+ assert calls == ["shutdown_telemetry", "close"]
@@ -9,11 +9,13 @@ from __future__ import annotations
9
9
 
10
10
  import sqlite3
11
11
  from collections.abc import Iterator
12
+ from pathlib import Path
12
13
  from typing import Any
13
14
 
14
15
  import pytest
15
16
  from fastapi.testclient import TestClient
16
17
  from mintmory.api import app as app_module
18
+ from mintmory.core import telemetry
17
19
 
18
20
 
19
21
  @pytest.fixture
@@ -132,10 +134,116 @@ def test_telemetry_metric_exporter_matches_configured_exporter(
132
134
  try:
133
135
  _reset()
134
136
  assert telemetry_mod.init_telemetry(OTelSettings(enabled=True, exporter="otlp")) is True
135
- assert isinstance(captured[-1], me_mod.OTLPMetricExporter)
137
+ assert isinstance(captured[-1]._inner, me_mod.OTLPMetricExporter)
136
138
 
137
139
  _reset()
138
140
  assert telemetry_mod.init_telemetry(OTelSettings(enabled=True, exporter="console")) is True
139
- assert isinstance(captured[-1], export_mod.ConsoleMetricExporter)
141
+ assert isinstance(captured[-1]._inner, export_mod.ConsoleMetricExporter)
140
142
  finally:
141
143
  _reset()
144
+
145
+
146
+ # ---------------------------------------------------------------------------
147
+ # Telemetry — API entry point (deployment › Telemetry activation at API startup)
148
+ # ---------------------------------------------------------------------------
149
+
150
+ _OTLP_ENDPOINT_VARIABLES = (
151
+ "OTEL_EXPORTER_OTLP_ENDPOINT",
152
+ "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT",
153
+ "OTEL_EXPORTER_OTLP_METRICS_ENDPOINT",
154
+ )
155
+
156
+
157
+ @pytest.fixture
158
+ def _otel_env(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Iterator[None]:
159
+ """Point the API at a throwaway DB and reset the global store before startup."""
160
+ db_file = tmp_path / "otel_entry_point.db"
161
+ monkeypatch.setenv("MINTMORY_DB", str(db_file))
162
+ monkeypatch.setattr(app_module, "_store", None)
163
+ yield
164
+ monkeypatch.setattr(app_module, "_store", None)
165
+
166
+
167
+ def _record_app_init(monkeypatch: pytest.MonkeyPatch) -> list[tuple[Any, dict[str, Any]]]:
168
+ """Wrap ``mintmory.api.app.init_telemetry`` with a recorder that still initialises."""
169
+ calls: list[tuple[Any, dict[str, Any]]] = []
170
+ real_init = telemetry.init_telemetry
171
+
172
+ def _recording_init(settings: Any = None, **kwargs: Any) -> bool:
173
+ calls.append((settings, kwargs))
174
+ return real_init(settings, **kwargs)
175
+
176
+ monkeypatch.setattr(app_module, "init_telemetry", _recording_init)
177
+ return calls
178
+
179
+
180
+ @pytest.mark.l4("C-5d7fad0c")
181
+ def test_api_startup_stays_off_by_default(_otel_env: None, monkeypatch: pytest.MonkeyPatch) -> None:
182
+ """In ``auto`` with no collector the API activates telemetry but stays a no-op shim.
183
+
184
+ The activator is passed the ``mintmory-api`` default service name (a real,
185
+ non-zero answer) alongside the off result.
186
+ """
187
+ monkeypatch.delenv("MINTMORY_OTEL_ENABLED", raising=False)
188
+ for variable in _OTLP_ENDPOINT_VARIABLES:
189
+ monkeypatch.delenv(variable, raising=False)
190
+
191
+ def _unreachable(url: str, timeout: float = 0.1) -> bool:
192
+ return False
193
+
194
+ monkeypatch.setattr(telemetry, "_endpoint_reachable", _unreachable)
195
+
196
+ calls = _record_app_init(monkeypatch)
197
+ with TestClient(app_module.app) as client:
198
+ assert client.get("/healthz").status_code == 200
199
+ assert telemetry.is_enabled() is False
200
+ assert calls, "the API lifespan must activate telemetry once at startup"
201
+ _settings, kwargs = calls[0]
202
+ assert kwargs.get("default_service_name") == "mintmory-api"
203
+
204
+
205
+ @pytest.mark.l4("C-59ff07c0")
206
+ def test_api_startup_activates_when_enabled(
207
+ _otel_env: None, monkeypatch: pytest.MonkeyPatch, closed_port: int
208
+ ) -> None:
209
+ """``MINTMORY_OTEL_ENABLED=true`` turns the API's telemetry on under ``mintmory-api``."""
210
+ pytest.importorskip("opentelemetry.sdk")
211
+ monkeypatch.setenv("MINTMORY_OTEL_ENABLED", "true")
212
+ monkeypatch.setenv("OTEL_EXPORTER_OTLP_ENDPOINT", f"http://127.0.0.1:{closed_port}")
213
+
214
+ calls = _record_app_init(monkeypatch)
215
+ with TestClient(app_module.app) as client:
216
+ assert client.get("/healthz").status_code == 200
217
+ assert telemetry.is_enabled() is True
218
+ assert calls, "the API lifespan must activate telemetry once at startup"
219
+ _settings, kwargs = calls[0]
220
+ assert kwargs.get("default_service_name") == "mintmory-api"
221
+
222
+
223
+ @pytest.mark.l4("C-5fc161bb")
224
+ def test_lifespan_flushes_telemetry_before_closing_store(
225
+ _otel_env: None, monkeypatch: pytest.MonkeyPatch
226
+ ) -> None:
227
+ """The API lifespan flushes telemetry at shutdown, before it closes the store."""
228
+ calls: list[str] = []
229
+
230
+ class _RecordingStore:
231
+ def initialise(self) -> None:
232
+ return None
233
+
234
+ def close(self) -> None:
235
+ calls.append("close")
236
+
237
+ def _build_recording_store(*args: Any, **kwargs: Any) -> _RecordingStore:
238
+ return _RecordingStore()
239
+
240
+ def _record_shutdown(*args: Any, **kwargs: Any) -> None:
241
+ calls.append("shutdown_telemetry")
242
+
243
+ monkeypatch.setattr(app_module, "build_storage", _build_recording_store)
244
+ monkeypatch.setattr(app_module, "shutdown_telemetry", _record_shutdown, raising=False)
245
+
246
+ with TestClient(app_module.app) as client:
247
+ assert client.get("/healthz").status_code == 200
248
+
249
+ assert calls == ["shutdown_telemetry", "close"]