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.
- {mintmory_api-0.1.0 → mintmory_api-0.2.0}/.gitignore +1 -0
- {mintmory_api-0.1.0 → mintmory_api-0.2.0}/PKG-INFO +3 -3
- {mintmory_api-0.1.0 → mintmory_api-0.2.0}/pyproject.toml +2 -2
- {mintmory_api-0.1.0 → mintmory_api-0.2.0}/src/mintmory/api/app.py +60 -10
- mintmory_api-0.2.0/src/mintmory/api/telemetry_middleware.py +169 -0
- mintmory_api-0.2.0/tests/test_api_telemetry_gate.py +122 -0
- {mintmory_api-0.1.0 → mintmory_api-0.2.0}/tests/test_health_and_otel.py +110 -2
- mintmory_api-0.2.0/tests/test_health_and_otel_runtime.py +140 -0
- mintmory_api-0.2.0/tests/test_telemetry_deployment_entry_point.py +126 -0
- mintmory_api-0.2.0/tests/test_telemetry_http.py +622 -0
- mintmory_api-0.2.0/tests/test_telemetry_http_middleware.py +719 -0
- mintmory_api-0.2.0/tests/test_telemetry_http_middleware_specific_failures.py +126 -0
- mintmory_api-0.2.0/tests/test_tenancy_api_errors.py +141 -0
- mintmory_api-0.2.0/tests/test_tenancy_dreaming_api_transport.py +191 -0
- mintmory_api-0.2.0/tests/test_version.py +10 -0
- {mintmory_api-0.1.0 → mintmory_api-0.2.0}/LICENSE +0 -0
- {mintmory_api-0.1.0 → mintmory_api-0.2.0}/README.md +0 -0
- {mintmory_api-0.1.0 → mintmory_api-0.2.0}/src/mintmory/api/__init__.py +0 -0
- {mintmory_api-0.1.0 → mintmory_api-0.2.0}/src/mintmory/api/py.typed +0 -0
- {mintmory_api-0.1.0 → mintmory_api-0.2.0}/src/mintmory/api/schemas.py +0 -0
- {mintmory_api-0.1.0 → mintmory_api-0.2.0}/tests/test_routes.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
Metadata-Version: 2.
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
2
|
Name: mintmory-api
|
|
3
|
-
Version: 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.
|
|
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.
|
|
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.
|
|
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
|
-
|
|
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=
|
|
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
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
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"]
|