gts-agency-python-sdk 0.0.1__py3-none-any.whl
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.
- agency_sdk/__init__.py +0 -0
- agency_sdk/auth_hooks.py +55 -0
- agency_sdk/client.py +212 -0
- agency_sdk/credentials.py +54 -0
- agency_sdk/delegates/__init__.py +0 -0
- agency_sdk/delegates/annotations_client.py +495 -0
- agency_sdk/delegates/annotations_dto.py +200 -0
- agency_sdk/delegates/base_client.py +126 -0
- agency_sdk/delegates/datasets_client.py +109 -0
- agency_sdk/delegates/datasets_dto.py +81 -0
- agency_sdk/delegates/datasource_client.py +44 -0
- agency_sdk/delegates/datasource_dto.py +107 -0
- agency_sdk/delegates/files_client.py +184 -0
- agency_sdk/delegates/files_dto.py +36 -0
- agency_sdk/delegates/gateway_client.py +81 -0
- agency_sdk/delegates/gateway_dto.py +37 -0
- agency_sdk/delegates/ontology_client.py +203 -0
- agency_sdk/delegates/ontology_dto.py +221 -0
- agency_sdk/delegates/prompts_client.py +56 -0
- agency_sdk/delegates/rules_client.py +33 -0
- agency_sdk/delegates/rules_dto.py +108 -0
- agency_sdk/delegates/session_client.py +95 -0
- agency_sdk/delegates/session_dto.py +94 -0
- agency_sdk/delegates/session_templates_client.py +23 -0
- agency_sdk/delegates/session_templates_dto.py +27 -0
- agency_sdk/delegates/session_vault_client.py +135 -0
- agency_sdk/delegates/session_vault_dto.py +75 -0
- agency_sdk/delegates/work_queue_client.py +230 -0
- agency_sdk/delegates/work_queue_dto.py +127 -0
- agency_sdk/domain.py +140 -0
- agency_sdk/observability/__init__.py +60 -0
- agency_sdk/observability/auth.py +15 -0
- agency_sdk/observability/bootstrap.py +344 -0
- agency_sdk/test/__init__.py +0 -0
- agency_sdk/test/conftest.py +106 -0
- agency_sdk/test/test_annotations_client.py +599 -0
- agency_sdk/test/test_annotations_dto.py +299 -0
- agency_sdk/test/test_base_client.py +153 -0
- agency_sdk/test/test_client_facade.py +105 -0
- agency_sdk/test/test_credentials.py +67 -0
- agency_sdk/test/test_files_client.py +264 -0
- agency_sdk/test/test_files_dto.py +93 -0
- agency_sdk/test/test_gateway_dto.py +70 -0
- agency_sdk/test/test_gateway_facade.py +229 -0
- agency_sdk/test/test_gateway_openai.py +76 -0
- agency_sdk/test/test_observability_auth.py +125 -0
- agency_sdk/test/test_observability_facade_threadsafety.py +50 -0
- agency_sdk/test/test_observability_langfuse.py +76 -0
- agency_sdk/test/test_observability_packaging.py +78 -0
- agency_sdk/test/test_observability_pipeline.py +246 -0
- agency_sdk/test/test_ontology_client.py +152 -0
- agency_sdk/test/test_ontology_dto.py +158 -0
- agency_sdk/test/test_session_client.py +128 -0
- agency_sdk/test/test_session_dto.py +75 -0
- agency_sdk/test/test_session_templates_client.py +36 -0
- agency_sdk/test/test_session_templates_dto.py +45 -0
- agency_sdk/test/test_session_vault_client.py +151 -0
- agency_sdk/test/test_session_vault_dto.py +27 -0
- agency_sdk/test/test_stub_requests.py +39 -0
- agency_sdk/test/test_work_queue_client.py +388 -0
- agency_sdk/test/test_work_queue_dto.py +233 -0
- gts_agency_python_sdk-0.0.1.dist-info/METADATA +221 -0
- gts_agency_python_sdk-0.0.1.dist-info/RECORD +66 -0
- gts_agency_python_sdk-0.0.1.dist-info/WHEEL +5 -0
- gts_agency_python_sdk-0.0.1.dist-info/licenses/LICENSE +201 -0
- gts_agency_python_sdk-0.0.1.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
"""Tests for the openai-client factory on AgencyGatewayClient.
|
|
2
|
+
|
|
3
|
+
The gateway hands back STANDARD openai clients wired to the gateway: base_url on
|
|
4
|
+
the gateway host (``/v1``), the ``x-org`` routing header as a default header, and
|
|
5
|
+
an httpx auth hook that stamps a fresh rotating bearer on every request (the
|
|
6
|
+
construction-time ``api_key`` is a placeholder — verified live 2026-07-07 that
|
|
7
|
+
the per-request Authorization override wins). ``openai`` is a core dependency, so
|
|
8
|
+
these tests import it directly (a missing core dep fails the module import).
|
|
9
|
+
"""
|
|
10
|
+
|
|
11
|
+
import builtins
|
|
12
|
+
|
|
13
|
+
import httpx
|
|
14
|
+
import openai
|
|
15
|
+
|
|
16
|
+
from agency_sdk.delegates.gateway_client import AgencyGatewayClient
|
|
17
|
+
|
|
18
|
+
import pytest
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
@pytest.fixture
|
|
22
|
+
def client(fake_credentials):
|
|
23
|
+
return AgencyGatewayClient(
|
|
24
|
+
token_supplier=fake_credentials,
|
|
25
|
+
gateway_base_url="http://gw.test:4000/",
|
|
26
|
+
org_id="2",
|
|
27
|
+
)
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
def _assert_rotating_auth(httpx_client) -> None:
|
|
31
|
+
"""The wired httpx client must stamp a fresh bearer per request via auth_flow."""
|
|
32
|
+
auth = httpx_client.auth
|
|
33
|
+
assert isinstance(auth, httpx.Auth)
|
|
34
|
+
request = httpx.Request("POST", "http://gw.test:4000/v1/chat/completions")
|
|
35
|
+
next(auth.auth_flow(request))
|
|
36
|
+
assert request.headers["Authorization"] == "Bearer test-token" # from FakeCredentials
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
def test_openai_client_is_wired_to_gateway(client):
|
|
40
|
+
oai = client.openai_client(max_retries=0)
|
|
41
|
+
|
|
42
|
+
assert isinstance(oai, openai.OpenAI)
|
|
43
|
+
assert str(oai.base_url) == "http://gw.test:4000/v1/" # gateway host, /v1 path
|
|
44
|
+
assert oai.default_headers.get("x-org") == "2"
|
|
45
|
+
assert oai.max_retries == 0 # caller kwargs pass through
|
|
46
|
+
_assert_rotating_auth(oai._client)
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
def test_async_openai_client_is_wired_to_gateway(client):
|
|
50
|
+
aoai = client.async_openai_client()
|
|
51
|
+
|
|
52
|
+
assert isinstance(aoai, openai.AsyncOpenAI)
|
|
53
|
+
assert str(aoai.base_url) == "http://gw.test:4000/v1/"
|
|
54
|
+
assert aoai.default_headers.get("x-org") == "2"
|
|
55
|
+
_assert_rotating_auth(aoai._client)
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
def test_openai_clients_are_independent_instances(client):
|
|
59
|
+
assert client.openai_client() is not client.openai_client() # no cache: caller owns lifecycle
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
def test_openai_helper_auth_does_not_import_observability(client, monkeypatch):
|
|
63
|
+
# M1: the gateway's rotating-bearer auth comes from the neutral core module
|
|
64
|
+
# agency_sdk.auth_hooks, NOT the optional observability submodule. Block that
|
|
65
|
+
# submodule entirely and the helper must still build a working auth hook.
|
|
66
|
+
real_import = builtins.__import__
|
|
67
|
+
|
|
68
|
+
def block_observability(name, *args, **kwargs):
|
|
69
|
+
if name.startswith("agency_sdk.observability"):
|
|
70
|
+
raise ImportError(f"observability blocked: {name}")
|
|
71
|
+
return real_import(name, *args, **kwargs)
|
|
72
|
+
|
|
73
|
+
monkeypatch.setattr(builtins, "__import__", block_observability)
|
|
74
|
+
|
|
75
|
+
oai = client.openai_client(max_retries=0) # must not reach into observability
|
|
76
|
+
_assert_rotating_auth(oai._client)
|
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
"""Phase 3: per-request bearer hooks, header precedence, endpoint resolution.
|
|
2
|
+
|
|
3
|
+
All offline. The auth hooks must stamp a *fresh* token on every call (so a
|
|
4
|
+
long-running export never sends an expired one), and ``build_headers`` must
|
|
5
|
+
resolve the Authorization header in the documented precedence order.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
import base64
|
|
9
|
+
|
|
10
|
+
import pytest
|
|
11
|
+
|
|
12
|
+
from agency_sdk.observability.auth import BearerTokenAuth, make_httpx_bearer_auth
|
|
13
|
+
from agency_sdk.observability.bootstrap import (
|
|
14
|
+
DEFAULT_LOGS_PATH,
|
|
15
|
+
DEFAULT_TRACES_PATH,
|
|
16
|
+
Observability,
|
|
17
|
+
TelemetryConfig,
|
|
18
|
+
)
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
class _FakeRequest:
|
|
22
|
+
def __init__(self) -> None:
|
|
23
|
+
self.headers: dict[str, str] = {}
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
class _StaticCreds:
|
|
27
|
+
"""Duck-typed CredentialsSupplier; raises to simulate an unavailable token."""
|
|
28
|
+
|
|
29
|
+
def __init__(self, token: str | None) -> None:
|
|
30
|
+
self._token = token
|
|
31
|
+
|
|
32
|
+
def bearer_token(self) -> str:
|
|
33
|
+
if self._token is None:
|
|
34
|
+
raise RuntimeError("no auth configured")
|
|
35
|
+
return self._token
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
def _obs(creds: object, **kw: object) -> Observability:
|
|
39
|
+
return Observability(creds, "gts-test", config=TelemetryConfig(**kw)) # type: ignore[arg-type]
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
# -- requests hook ------------------------------------------------------------
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def test_requests_bearer_auth_stamps_fresh_token_each_call():
|
|
46
|
+
tokens = iter(["tok-1", "tok-2"])
|
|
47
|
+
auth = BearerTokenAuth(lambda: next(tokens))
|
|
48
|
+
|
|
49
|
+
r1, r2 = _FakeRequest(), _FakeRequest()
|
|
50
|
+
auth(r1)
|
|
51
|
+
auth(r2)
|
|
52
|
+
|
|
53
|
+
assert r1.headers["Authorization"] == "Bearer tok-1"
|
|
54
|
+
assert r2.headers["Authorization"] == "Bearer tok-2"
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
def test_requests_bearer_auth_skips_when_no_token():
|
|
58
|
+
auth = BearerTokenAuth(lambda: None)
|
|
59
|
+
r = _FakeRequest()
|
|
60
|
+
|
|
61
|
+
auth(r)
|
|
62
|
+
|
|
63
|
+
assert "Authorization" not in r.headers
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
# -- httpx hook ---------------------------------------------------------------
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
def test_httpx_bearer_auth_mirrors_requests_hook():
|
|
70
|
+
auth = make_httpx_bearer_auth(lambda: "tok-x")
|
|
71
|
+
req = _FakeRequest()
|
|
72
|
+
|
|
73
|
+
yielded = list(auth.auth_flow(req))
|
|
74
|
+
|
|
75
|
+
assert len(yielded) == 1
|
|
76
|
+
assert yielded[0].headers["Authorization"] == "Bearer tok-x"
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
# -- header precedence chain --------------------------------------------------
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
def test_build_headers_uses_bearer_token():
|
|
83
|
+
headers = _obs(_StaticCreds("abc")).build_headers()
|
|
84
|
+
assert headers["Authorization"] == "Bearer abc"
|
|
85
|
+
assert headers["x-org-id"] == "2"
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
def test_build_headers_explicit_header_wins():
|
|
89
|
+
obs = _obs(_StaticCreds("abc"), extra_headers="Authorization=Bearer explicit,X-Foo=bar")
|
|
90
|
+
headers = obs.build_headers()
|
|
91
|
+
assert headers["Authorization"] == "Bearer explicit"
|
|
92
|
+
assert headers["X-Foo"] == "bar"
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
def test_build_headers_falls_back_to_langfuse_basic():
|
|
96
|
+
obs = _obs(_StaticCreds(None), langfuse_public_key="pk", langfuse_secret_key="sk")
|
|
97
|
+
headers = obs.build_headers()
|
|
98
|
+
expected = "Bearer " + base64.b64encode(b"pk:sk").decode("utf-8")
|
|
99
|
+
assert headers["Authorization"] == expected
|
|
100
|
+
|
|
101
|
+
|
|
102
|
+
def test_build_headers_org_id_always_set():
|
|
103
|
+
assert _obs(_StaticCreds("abc"), org_id="7").build_headers()["x-org-id"] == "7"
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
# -- endpoint resolution ------------------------------------------------------
|
|
107
|
+
|
|
108
|
+
|
|
109
|
+
def test_resolve_endpoint_explicit_wins():
|
|
110
|
+
obs = _obs(_StaticCreds("t"), host="http://h:1")
|
|
111
|
+
assert obs._resolve_endpoint("http://explicit/x", DEFAULT_TRACES_PATH) == "http://explicit/x"
|
|
112
|
+
|
|
113
|
+
|
|
114
|
+
def test_resolve_endpoint_host_plus_path():
|
|
115
|
+
obs = _obs(_StaticCreds("t"), host="http://h:1/")
|
|
116
|
+
assert obs._resolve_endpoint(None, DEFAULT_TRACES_PATH) == "http://h:1" + DEFAULT_TRACES_PATH
|
|
117
|
+
|
|
118
|
+
|
|
119
|
+
def test_resolve_endpoint_host_already_has_path():
|
|
120
|
+
obs = _obs(_StaticCreds("t"), host="http://h:1" + DEFAULT_LOGS_PATH)
|
|
121
|
+
assert obs._resolve_endpoint(None, DEFAULT_LOGS_PATH) == "http://h:1" + DEFAULT_LOGS_PATH
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
def test_resolve_endpoint_none_without_host():
|
|
125
|
+
assert _obs(_StaticCreds("t"), host=None)._resolve_endpoint(None, DEFAULT_TRACES_PATH) is None
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
"""Phase 9 / H1: AgencyClient.observability() must be thread-safe.
|
|
2
|
+
|
|
3
|
+
The lazy build is documented to return the same instance on repeated calls. Under
|
|
4
|
+
concurrency the unguarded check-then-set could construct several Observability
|
|
5
|
+
objects (and, once each is init()'d, attach duplicate root log handlers). This
|
|
6
|
+
test forces the race and asserts a single construction.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
import threading
|
|
10
|
+
import time
|
|
11
|
+
|
|
12
|
+
import agency_sdk.observability as obs_mod
|
|
13
|
+
from agency_sdk.client import AgencyClient
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
def test_observability_is_thread_safe(monkeypatch, fake_credentials):
|
|
17
|
+
real_cls = obs_mod.Observability
|
|
18
|
+
count = {"n": 0}
|
|
19
|
+
count_lock = threading.Lock()
|
|
20
|
+
|
|
21
|
+
def counting(*args, **kwargs):
|
|
22
|
+
with count_lock:
|
|
23
|
+
count["n"] += 1
|
|
24
|
+
time.sleep(0.01) # widen the race window so an unguarded build builds N times
|
|
25
|
+
return real_cls(*args, **kwargs)
|
|
26
|
+
|
|
27
|
+
monkeypatch.setattr(obs_mod, "Observability", counting)
|
|
28
|
+
|
|
29
|
+
client = AgencyClient(token_supplier=fake_credentials, base_url="http://cp.test")
|
|
30
|
+
|
|
31
|
+
n_threads = 8
|
|
32
|
+
results: list = []
|
|
33
|
+
results_lock = threading.Lock()
|
|
34
|
+
barrier = threading.Barrier(n_threads)
|
|
35
|
+
|
|
36
|
+
def worker():
|
|
37
|
+
barrier.wait() # release all threads together
|
|
38
|
+
instance = client.observability("gts-x")
|
|
39
|
+
with results_lock:
|
|
40
|
+
results.append(instance)
|
|
41
|
+
|
|
42
|
+
threads = [threading.Thread(target=worker) for _ in range(n_threads)]
|
|
43
|
+
for t in threads:
|
|
44
|
+
t.start()
|
|
45
|
+
for t in threads:
|
|
46
|
+
t.join()
|
|
47
|
+
|
|
48
|
+
assert count["n"] == 1 # constructed exactly once despite concurrent callers
|
|
49
|
+
assert len(results) == n_threads
|
|
50
|
+
assert all(instance is results[0] for instance in results) # all share one instance
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
"""Phase 6: the Langfuse client helper.
|
|
2
|
+
|
|
3
|
+
``langfuse_client()`` returns None when the project keys or the langfuse package
|
|
4
|
+
are absent, and otherwise builds a Langfuse client authenticated through the same
|
|
5
|
+
refreshing bearer hook and the shared OTLP span exporter. The langfuse package is
|
|
6
|
+
stubbed so the test never touches the network.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
import sys
|
|
10
|
+
import types
|
|
11
|
+
|
|
12
|
+
import httpx
|
|
13
|
+
|
|
14
|
+
from agency_sdk.observability.bootstrap import Observability, TelemetryConfig
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
class _StaticCreds:
|
|
18
|
+
def bearer_token(self) -> str:
|
|
19
|
+
return "tok"
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
def test_langfuse_client_none_without_keys():
|
|
23
|
+
obs = Observability(_StaticCreds(), "gts-x", config=TelemetryConfig(host="http://cp.test")) # no langfuse keys
|
|
24
|
+
assert obs.langfuse_client() is None
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
def test_langfuse_client_none_when_package_missing(monkeypatch):
|
|
28
|
+
monkeypatch.setitem(sys.modules, "langfuse", None) # force ImportError
|
|
29
|
+
obs = Observability(
|
|
30
|
+
_StaticCreds(),
|
|
31
|
+
"gts-x",
|
|
32
|
+
config=TelemetryConfig(
|
|
33
|
+
host="http://cp.test",
|
|
34
|
+
langfuse_public_key="pk",
|
|
35
|
+
langfuse_secret_key="sk",
|
|
36
|
+
),
|
|
37
|
+
)
|
|
38
|
+
assert obs.langfuse_client() is None
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
def test_langfuse_client_built_with_bearer_auth_and_span_exporter(monkeypatch):
|
|
42
|
+
captured: dict = {}
|
|
43
|
+
|
|
44
|
+
class FakeLangfuse:
|
|
45
|
+
def __init__(self, **kwargs):
|
|
46
|
+
captured.update(kwargs)
|
|
47
|
+
|
|
48
|
+
fake_module = types.ModuleType("langfuse")
|
|
49
|
+
fake_module.Langfuse = FakeLangfuse # type: ignore[attr-defined]
|
|
50
|
+
monkeypatch.setitem(sys.modules, "langfuse", fake_module)
|
|
51
|
+
|
|
52
|
+
obs = Observability(
|
|
53
|
+
_StaticCreds(),
|
|
54
|
+
"gts-x",
|
|
55
|
+
config=TelemetryConfig(
|
|
56
|
+
host="http://cp.test",
|
|
57
|
+
langfuse_public_key="pk",
|
|
58
|
+
langfuse_secret_key="sk",
|
|
59
|
+
),
|
|
60
|
+
)
|
|
61
|
+
|
|
62
|
+
client = obs.langfuse_client()
|
|
63
|
+
|
|
64
|
+
assert isinstance(client, FakeLangfuse)
|
|
65
|
+
assert captured["public_key"] == "pk"
|
|
66
|
+
assert captured["secret_key"] == "sk"
|
|
67
|
+
assert captured["host"] == "http://cp.test" # langfuse_host defaults to host
|
|
68
|
+
assert captured["span_exporter"] is not None
|
|
69
|
+
|
|
70
|
+
httpx_client = captured["httpx_client"]
|
|
71
|
+
assert isinstance(httpx_client, httpx.Client)
|
|
72
|
+
# The transport auth is our refreshing bearer hook routed through _safe_token.
|
|
73
|
+
request = type("R", (), {"headers": {}})()
|
|
74
|
+
list(httpx_client._auth.auth_flow(request))
|
|
75
|
+
assert request.headers["Authorization"] == "Bearer tok"
|
|
76
|
+
httpx_client.close()
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
"""Phase 2: packaging & lazy-import behaviour for the observability module.
|
|
2
|
+
|
|
3
|
+
These tests guarantee the optional ``[observability]`` extra never leaks into the
|
|
4
|
+
SDK's lean core: importing ``agency_sdk`` and constructing ``AgencyClient`` must
|
|
5
|
+
not pull OpenTelemetry, and requesting observability without the extra installed
|
|
6
|
+
must fail with a clear, actionable message naming the extra.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
import subprocess
|
|
10
|
+
import sys
|
|
11
|
+
from pathlib import Path
|
|
12
|
+
|
|
13
|
+
import pytest
|
|
14
|
+
|
|
15
|
+
from agency_sdk.client import AgencyClient
|
|
16
|
+
|
|
17
|
+
REPO_ROOT = Path(__file__).resolve().parents[2]
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
def test_import_agency_sdk_is_lazy_wrt_opentelemetry():
|
|
21
|
+
"""Importing the SDK core (in a fresh interpreter) must not import OpenTelemetry."""
|
|
22
|
+
code = (
|
|
23
|
+
"import sys, agency_sdk, agency_sdk.client\n"
|
|
24
|
+
"from agency_sdk.client import AgencyClient\n"
|
|
25
|
+
"leaked = [m for m in sys.modules if m == 'opentelemetry' or m.startswith('opentelemetry.')]\n"
|
|
26
|
+
"assert not leaked, leaked\n"
|
|
27
|
+
"print('OK')\n"
|
|
28
|
+
)
|
|
29
|
+
result = subprocess.run(
|
|
30
|
+
[sys.executable, "-c", code],
|
|
31
|
+
cwd=REPO_ROOT,
|
|
32
|
+
capture_output=True,
|
|
33
|
+
text=True,
|
|
34
|
+
)
|
|
35
|
+
assert result.returncode == 0, result.stderr
|
|
36
|
+
assert result.stdout.strip().endswith("OK")
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
def test_observability_raises_clear_error_when_extra_missing(monkeypatch, fake_credentials):
|
|
40
|
+
"""Without the extra, ``observability()`` raises an ImportError naming the extra."""
|
|
41
|
+
# Force the optional deps to look absent regardless of the dev environment.
|
|
42
|
+
monkeypatch.setitem(sys.modules, "opentelemetry", None)
|
|
43
|
+
monkeypatch.setitem(sys.modules, "opentelemetry.sdk", None)
|
|
44
|
+
|
|
45
|
+
client = AgencyClient(token_supplier=fake_credentials, base_url="http://cp.test")
|
|
46
|
+
|
|
47
|
+
with pytest.raises(ImportError) as exc_info:
|
|
48
|
+
client.observability("gts-test")
|
|
49
|
+
|
|
50
|
+
message = str(exc_info.value)
|
|
51
|
+
assert "observability" in message.lower()
|
|
52
|
+
assert "pip install" in message
|
|
53
|
+
assert "[observability]" in message
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
def test_observability_returns_bound_cached_instance(fake_credentials):
|
|
57
|
+
"""With deps present, ``observability()`` returns an instance bound to the
|
|
58
|
+
shared credentials, defaulting the host to the client ``base_url``, and caches it."""
|
|
59
|
+
from agency_sdk.observability import Observability
|
|
60
|
+
|
|
61
|
+
client = AgencyClient(token_supplier=fake_credentials, base_url="http://cp.test/")
|
|
62
|
+
|
|
63
|
+
obs = client.observability("gts-test", "1.2.3")
|
|
64
|
+
|
|
65
|
+
assert isinstance(obs, Observability)
|
|
66
|
+
assert obs.credentials is fake_credentials
|
|
67
|
+
assert obs.service_name == "gts-test"
|
|
68
|
+
assert obs.service_version == "1.2.3"
|
|
69
|
+
assert obs.host == "http://cp.test" # defaults to (rstripped) client base_url
|
|
70
|
+
assert client.observability("gts-test") is obs # idempotent / cached
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
def test_observability_host_is_overridable(fake_credentials):
|
|
74
|
+
client = AgencyClient(token_supplier=fake_credentials, base_url="http://cp.test")
|
|
75
|
+
|
|
76
|
+
obs = client.observability("gts-test", host="http://otel.other:4318")
|
|
77
|
+
|
|
78
|
+
assert obs.host == "http://otel.other:4318"
|
|
@@ -0,0 +1,246 @@
|
|
|
1
|
+
"""Phase 4: telemetry pipeline & log/trace correlation, verified offline.
|
|
2
|
+
|
|
3
|
+
Uses OpenTelemetry in-memory exporters (no network) to assert that ``init()``
|
|
4
|
+
builds real recording providers, that stdlib logs emitted inside an active span
|
|
5
|
+
carry that span's trace id, that the processor is selectable, and that exporter
|
|
6
|
+
failure degrades to ``init() -> None`` without side effects.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
import logging
|
|
10
|
+
|
|
11
|
+
import pytest
|
|
12
|
+
|
|
13
|
+
from opentelemetry.sdk._logs.export import (
|
|
14
|
+
BatchLogRecordProcessor,
|
|
15
|
+
InMemoryLogExporter,
|
|
16
|
+
SimpleLogRecordProcessor,
|
|
17
|
+
)
|
|
18
|
+
from opentelemetry.sdk.trace.export import BatchSpanProcessor, SimpleSpanProcessor
|
|
19
|
+
from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
|
|
20
|
+
|
|
21
|
+
from agency_sdk.observability.auth import BearerTokenAuth
|
|
22
|
+
from agency_sdk.observability.bootstrap import Observability, TelemetryConfig
|
|
23
|
+
|
|
24
|
+
pytestmark = pytest.mark.filterwarnings("ignore::DeprecationWarning")
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
class _StaticCreds:
|
|
28
|
+
def bearer_token(self) -> str:
|
|
29
|
+
return "tok"
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
@pytest.fixture
|
|
33
|
+
def otel_isolation():
|
|
34
|
+
"""Undo init()'s global side effects (root handler + LoggingInstrumentor)."""
|
|
35
|
+
root = logging.getLogger()
|
|
36
|
+
handlers_before = list(root.handlers)
|
|
37
|
+
level_before = root.level
|
|
38
|
+
yield
|
|
39
|
+
for handler in list(root.handlers):
|
|
40
|
+
if handler not in handlers_before:
|
|
41
|
+
root.removeHandler(handler)
|
|
42
|
+
root.setLevel(level_before)
|
|
43
|
+
try:
|
|
44
|
+
from opentelemetry.instrumentation.logging import LoggingInstrumentor
|
|
45
|
+
|
|
46
|
+
LoggingInstrumentor().uninstrument()
|
|
47
|
+
except Exception:
|
|
48
|
+
pass
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
def _obs_with_inmemory(monkeypatch, processor="simple"):
|
|
52
|
+
obs = Observability(_StaticCreds(), "gts-test", config=TelemetryConfig(host="http://cp.test", processor=processor))
|
|
53
|
+
span_exporter = InMemorySpanExporter()
|
|
54
|
+
log_exporter = InMemoryLogExporter()
|
|
55
|
+
monkeypatch.setattr(obs, "make_span_exporter", lambda: span_exporter)
|
|
56
|
+
monkeypatch.setattr(obs, "make_log_exporter", lambda: log_exporter)
|
|
57
|
+
return obs, span_exporter, log_exporter
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
def test_telemetry_config_defaults_and_unpacking():
|
|
61
|
+
# Default config: untraced-host, simple processor, org "2".
|
|
62
|
+
default = Observability(_StaticCreds(), "gts-x")
|
|
63
|
+
assert default.host is None
|
|
64
|
+
assert default.processor == "simple"
|
|
65
|
+
assert default.org_id == "2"
|
|
66
|
+
assert default.langfuse_host is None
|
|
67
|
+
|
|
68
|
+
# Supplied config is unpacked onto the instance; langfuse_host falls back to host.
|
|
69
|
+
obs = Observability(
|
|
70
|
+
_StaticCreds(),
|
|
71
|
+
"gts-x",
|
|
72
|
+
config=TelemetryConfig(host="http://h:1", processor="batch", org_id="7"),
|
|
73
|
+
)
|
|
74
|
+
assert obs.host == "http://h:1"
|
|
75
|
+
assert obs.processor == "batch"
|
|
76
|
+
assert obs.org_id == "7"
|
|
77
|
+
assert obs.langfuse_host == "http://h:1"
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
def test_init_builds_recording_providers(monkeypatch, otel_isolation):
|
|
81
|
+
obs, span_exporter, _ = _obs_with_inmemory(monkeypatch)
|
|
82
|
+
|
|
83
|
+
tracer = obs.init()
|
|
84
|
+
|
|
85
|
+
assert tracer is not None
|
|
86
|
+
with tracer.start_as_current_span("root") as span:
|
|
87
|
+
ctx = span.get_span_context()
|
|
88
|
+
assert ctx.trace_id != 0 # real recording provider, valid context
|
|
89
|
+
assert span.is_recording()
|
|
90
|
+
obs.shutdown()
|
|
91
|
+
assert any(s.name == "root" for s in span_exporter.get_finished_spans())
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
def test_logs_carry_active_span_trace_id(monkeypatch, otel_isolation):
|
|
95
|
+
obs, _, log_exporter = _obs_with_inmemory(monkeypatch)
|
|
96
|
+
tracer = obs.init()
|
|
97
|
+
logging.getLogger().setLevel(logging.DEBUG)
|
|
98
|
+
|
|
99
|
+
with tracer.start_as_current_span("root") as span:
|
|
100
|
+
trace_id = span.get_span_context().trace_id
|
|
101
|
+
logging.getLogger("obs.test.correlation").warning("correlated-line")
|
|
102
|
+
|
|
103
|
+
obs._logger_provider.force_flush()
|
|
104
|
+
matched = [r for r in log_exporter.get_finished_logs() if r.log_record.body == "correlated-line"]
|
|
105
|
+
obs.shutdown()
|
|
106
|
+
|
|
107
|
+
assert matched, "log line was not exported"
|
|
108
|
+
assert matched[0].log_record.trace_id == trace_id
|
|
109
|
+
|
|
110
|
+
|
|
111
|
+
def test_processor_choice_simple_default_and_batch():
|
|
112
|
+
span_exp = InMemorySpanExporter()
|
|
113
|
+
log_exp = InMemoryLogExporter()
|
|
114
|
+
|
|
115
|
+
simple = Observability(_StaticCreds(), "s") # default
|
|
116
|
+
batch = Observability(_StaticCreds(), "s", config=TelemetryConfig(processor="batch"))
|
|
117
|
+
|
|
118
|
+
assert isinstance(simple._make_span_processor(span_exp), SimpleSpanProcessor)
|
|
119
|
+
assert isinstance(simple._make_log_processor(log_exp), SimpleLogRecordProcessor)
|
|
120
|
+
|
|
121
|
+
batch_span = batch._make_span_processor(span_exp)
|
|
122
|
+
batch_log = batch._make_log_processor(log_exp)
|
|
123
|
+
assert isinstance(batch_span, BatchSpanProcessor)
|
|
124
|
+
assert isinstance(batch_log, BatchLogRecordProcessor)
|
|
125
|
+
batch_span.shutdown() # stop the worker threads
|
|
126
|
+
batch_log.shutdown()
|
|
127
|
+
|
|
128
|
+
|
|
129
|
+
def test_make_span_exporter_attaches_refreshing_auth():
|
|
130
|
+
obs = Observability(_StaticCreds(), "gts-test", config=TelemetryConfig(host="http://cp.test"))
|
|
131
|
+
|
|
132
|
+
exporter = obs.make_span_exporter()
|
|
133
|
+
|
|
134
|
+
assert isinstance(exporter._session.auth, BearerTokenAuth)
|
|
135
|
+
|
|
136
|
+
|
|
137
|
+
def test_make_log_exporter_attaches_refreshing_auth():
|
|
138
|
+
obs = Observability(_StaticCreds(), "gts-test", config=TelemetryConfig(host="http://cp.test"))
|
|
139
|
+
|
|
140
|
+
exporter = obs.make_log_exporter()
|
|
141
|
+
|
|
142
|
+
assert isinstance(exporter._session.auth, BearerTokenAuth)
|
|
143
|
+
|
|
144
|
+
|
|
145
|
+
def test_tracer_provider_property_reflects_lifecycle(monkeypatch, otel_isolation):
|
|
146
|
+
obs, _, _ = _obs_with_inmemory(monkeypatch)
|
|
147
|
+
|
|
148
|
+
assert obs.tracer_provider is None
|
|
149
|
+
obs.init()
|
|
150
|
+
assert obs.tracer_provider is not None
|
|
151
|
+
obs.shutdown()
|
|
152
|
+
|
|
153
|
+
|
|
154
|
+
def test_shutdown_is_idempotent(monkeypatch, otel_isolation):
|
|
155
|
+
obs, _, _ = _obs_with_inmemory(monkeypatch)
|
|
156
|
+
obs.init()
|
|
157
|
+
logger_provider, tracer_provider = obs._logger_provider, obs._tracer_provider
|
|
158
|
+
counts = {"log": 0, "trace": 0}
|
|
159
|
+
monkeypatch.setattr(logger_provider, "shutdown", lambda: counts.__setitem__("log", counts["log"] + 1))
|
|
160
|
+
monkeypatch.setattr(tracer_provider, "shutdown", lambda: counts.__setitem__("trace", counts["trace"] + 1))
|
|
161
|
+
|
|
162
|
+
obs.shutdown()
|
|
163
|
+
obs.shutdown() # a second explicit call (and the atexit path) must be a no-op
|
|
164
|
+
|
|
165
|
+
assert counts == {"log": 1, "trace": 1}
|
|
166
|
+
assert obs._logger_provider is None
|
|
167
|
+
assert obs._tracer_provider is None
|
|
168
|
+
|
|
169
|
+
|
|
170
|
+
def test_init_registers_instance_shutdown_with_atexit(monkeypatch, otel_isolation):
|
|
171
|
+
import agency_sdk.observability.bootstrap as bootstrap
|
|
172
|
+
|
|
173
|
+
registered: list = []
|
|
174
|
+
monkeypatch.setattr(bootstrap.atexit, "register", lambda fn, *a, **k: registered.append(fn))
|
|
175
|
+
|
|
176
|
+
obs, _, _ = _obs_with_inmemory(monkeypatch)
|
|
177
|
+
obs.init()
|
|
178
|
+
|
|
179
|
+
# atexit drives the instance shutdown (idempotent), not the raw providers directly.
|
|
180
|
+
assert obs.shutdown in registered
|
|
181
|
+
assert obs._logger_provider.shutdown not in registered
|
|
182
|
+
assert obs._tracer_provider.shutdown not in registered
|
|
183
|
+
obs.shutdown()
|
|
184
|
+
|
|
185
|
+
|
|
186
|
+
def test_init_returns_none_on_exporter_failure(monkeypatch, otel_isolation):
|
|
187
|
+
obs = Observability(_StaticCreds(), "gts-test", config=TelemetryConfig(host="http://cp.test"))
|
|
188
|
+
|
|
189
|
+
def boom():
|
|
190
|
+
raise RuntimeError("exporter down")
|
|
191
|
+
|
|
192
|
+
monkeypatch.setattr(obs, "make_log_exporter", boom)
|
|
193
|
+
handlers_before = list(logging.getLogger().handlers)
|
|
194
|
+
|
|
195
|
+
result = obs.init()
|
|
196
|
+
|
|
197
|
+
assert result is None # graceful degradation, no exception
|
|
198
|
+
# No global side effects when setup fails.
|
|
199
|
+
assert list(logging.getLogger().handlers) == handlers_before
|
|
200
|
+
|
|
201
|
+
|
|
202
|
+
# -- agent_run (Mechanism 5) --------------------------------------------------
|
|
203
|
+
|
|
204
|
+
|
|
205
|
+
def test_agent_run_opens_root_span_with_attributes(monkeypatch, otel_isolation):
|
|
206
|
+
obs, span_exporter, _ = _obs_with_inmemory(monkeypatch)
|
|
207
|
+
obs.init()
|
|
208
|
+
|
|
209
|
+
with obs.agent_run("agent.x", correlation_id="cid-1", team="echo") as span:
|
|
210
|
+
assert span is not None
|
|
211
|
+
assert span.is_recording()
|
|
212
|
+
|
|
213
|
+
obs.shutdown()
|
|
214
|
+
root = next(s for s in span_exporter.get_finished_spans() if s.name == "agent.x")
|
|
215
|
+
assert root.attributes["correlation_id"] == "cid-1"
|
|
216
|
+
assert root.attributes["team"] == "echo"
|
|
217
|
+
|
|
218
|
+
|
|
219
|
+
def test_agent_run_is_nullcontext_when_tracing_off():
|
|
220
|
+
obs = Observability(_StaticCreds(), "gts-x") # init() never called -> no tracer
|
|
221
|
+
|
|
222
|
+
ran = False
|
|
223
|
+
with obs.agent_run("agent.x", k="v") as span:
|
|
224
|
+
assert span is None
|
|
225
|
+
ran = True
|
|
226
|
+
|
|
227
|
+
assert ran # body still executes, untraced
|
|
228
|
+
|
|
229
|
+
|
|
230
|
+
def test_child_spans_and_logs_share_root_trace_id(monkeypatch, otel_isolation):
|
|
231
|
+
obs, _, log_exporter = _obs_with_inmemory(monkeypatch)
|
|
232
|
+
tracer = obs.init()
|
|
233
|
+
logging.getLogger().setLevel(logging.DEBUG)
|
|
234
|
+
|
|
235
|
+
with obs.agent_run("agent.x") as root:
|
|
236
|
+
root_trace_id = root.get_span_context().trace_id
|
|
237
|
+
with tracer.start_as_current_span("child") as child:
|
|
238
|
+
assert child.get_span_context().trace_id == root_trace_id
|
|
239
|
+
logging.getLogger("obs.test.nested").warning("inside-run")
|
|
240
|
+
|
|
241
|
+
obs._logger_provider.force_flush()
|
|
242
|
+
matched = [r for r in log_exporter.get_finished_logs() if r.log_record.body == "inside-run"]
|
|
243
|
+
obs.shutdown()
|
|
244
|
+
|
|
245
|
+
assert matched
|
|
246
|
+
assert matched[0].log_record.trace_id == root_trace_id
|