pyeztrace 0.1.6__tar.gz → 0.2.0.dev0__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.
- {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/PKG-INFO +16 -1
- {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/README.md +7 -0
- {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/pyeztrace/__init__.py +4 -1
- pyeztrace-0.2.0.dev0/pyeztrace/agent_cli.py +74 -0
- {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/pyeztrace/cli.py +5 -0
- {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/pyeztrace/custom_logging.py +24 -2
- pyeztrace-0.2.0.dev0/pyeztrace/events.py +78 -0
- pyeztrace-0.2.0.dev0/pyeztrace/exceptions.py +51 -0
- pyeztrace-0.2.0.dev0/pyeztrace/inspection.py +158 -0
- pyeztrace-0.2.0.dev0/pyeztrace/integrations/__init__.py +1 -0
- pyeztrace-0.2.0.dev0/pyeztrace/integrations/langchain.py +99 -0
- pyeztrace-0.2.0.dev0/pyeztrace/integrations/sdk.py +41 -0
- pyeztrace-0.2.0.dev0/pyeztrace/llm.py +353 -0
- {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/pyeztrace/otel.py +11 -3
- {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/pyeztrace/tracer.py +53 -40
- {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/pyeztrace/viewer.py +103 -28
- {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/pyeztrace.egg-info/PKG-INFO +16 -1
- {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/pyeztrace.egg-info/SOURCES.txt +11 -0
- {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/pyeztrace.egg-info/requires.txt +12 -0
- {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/pyproject.toml +10 -2
- {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/tests/test_custom_logging.py +3 -0
- pyeztrace-0.2.0.dev0/tests/test_events.py +95 -0
- pyeztrace-0.2.0.dev0/tests/test_inspection.py +107 -0
- pyeztrace-0.2.0.dev0/tests/test_llm.py +106 -0
- pyeztrace-0.2.0.dev0/tests/test_llm_sdks.py +177 -0
- {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/tests/test_otel_bridge.py +49 -1
- {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/tests/test_viewer_javascript.py +17 -0
- {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/tests/test_viewer_live_states.py +34 -1
- pyeztrace-0.1.6/pyeztrace/exceptions.py +0 -23
- {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/LICENSE +0 -0
- {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/pyeztrace/_version.py +0 -0
- {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/pyeztrace/config.py +0 -0
- {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/pyeztrace/printing.py +0 -0
- {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/pyeztrace/setup.py +0 -0
- {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/pyeztrace.egg-info/dependency_links.txt +0 -0
- {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/pyeztrace.egg-info/entry_points.txt +0 -0
- {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/pyeztrace.egg-info/top_level.txt +0 -0
- {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/setup.cfg +0 -0
- {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/setup.py +0 -0
- {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/tests/test_advanced.py +0 -0
- {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/tests/test_async_task.py +0 -0
- {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/tests/test_cli_parser.py +0 -0
- {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/tests/test_cli_workflow.py +0 -0
- {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/tests/test_double_tracing.py +0 -0
- {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/tests/test_exception.py +0 -0
- {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/tests/test_integration.py +0 -0
- {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/tests/test_maintenance.py +0 -0
- {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/tests/test_printing.py +0 -0
- {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/tests/test_production_robustness.py +0 -0
- {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/tests/test_real_world.py +0 -0
- {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/tests/test_recursive_tracing.py +0 -0
- {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/tests/test_runtime_lifecycle.py +0 -0
- {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/tests/test_setup.py +0 -0
- {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/tests/test_tracer.py +0 -0
- {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/tests/test_version.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: pyeztrace
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.2.0.dev0
|
|
4
4
|
Summary: A dependency-free, lightweight Python tracing and logging library
|
|
5
5
|
Author-email: Jefferson Nelsson <jefferson.nelsson@gmail.com>
|
|
6
6
|
License-Expression: MIT
|
|
@@ -21,6 +21,14 @@ Classifier: Operating System :: OS Independent
|
|
|
21
21
|
Requires-Python: >=3.9
|
|
22
22
|
Description-Content-Type: text/markdown
|
|
23
23
|
License-File: LICENSE
|
|
24
|
+
Provides-Extra: openai
|
|
25
|
+
Requires-Dist: openai>=3.13.0; extra == "openai"
|
|
26
|
+
Provides-Extra: anthropic
|
|
27
|
+
Requires-Dist: anthropic>=1.5.0; extra == "anthropic"
|
|
28
|
+
Provides-Extra: langchain
|
|
29
|
+
Requires-Dist: langchain-core>=1.6.3; extra == "langchain"
|
|
30
|
+
Provides-Extra: llm
|
|
31
|
+
Requires-Dist: pyeztrace[anthropic,langchain,openai]; extra == "llm"
|
|
24
32
|
Provides-Extra: otel
|
|
25
33
|
Requires-Dist: opentelemetry-api>=1.23.0; extra == "otel"
|
|
26
34
|
Requires-Dist: opentelemetry-sdk>=1.23.0; extra == "otel"
|
|
@@ -631,3 +639,10 @@ Contributions are welcome! Please read our [Contributing Guidelines](CONTRIBUTIN
|
|
|
631
639
|
## License
|
|
632
640
|
|
|
633
641
|
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
|
642
|
+
|
|
643
|
+
### 0.2.0 development
|
|
644
|
+
|
|
645
|
+
The development branch adds [agent inspection commands](docs/agent-cli.md) and
|
|
646
|
+
[optional local LLM tracing](docs/llm-tracing.md). SDKs remain optional; the core
|
|
647
|
+
has no required dependencies. See the [development contract](docs/design/0.2.0.md)
|
|
648
|
+
for scope and release gates. These additions are not part of published 0.1.6.
|
|
@@ -594,3 +594,10 @@ Contributions are welcome! Please read our [Contributing Guidelines](CONTRIBUTIN
|
|
|
594
594
|
## License
|
|
595
595
|
|
|
596
596
|
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
|
597
|
+
|
|
598
|
+
### 0.2.0 development
|
|
599
|
+
|
|
600
|
+
The development branch adds [agent inspection commands](docs/agent-cli.md) and
|
|
601
|
+
[optional local LLM tracing](docs/llm-tracing.md). SDKs remain optional; the core
|
|
602
|
+
has no required dependencies. See the [development contract](docs/design/0.2.0.md)
|
|
603
|
+
for scope and release gates. These additions are not part of published 0.1.6.
|
|
@@ -1,9 +1,12 @@
|
|
|
1
1
|
"""PyEzTrace package exports."""
|
|
2
2
|
|
|
3
|
-
__all__ = ["Logging", "trace", "set_global_redaction", "print", "get_otel_status"]
|
|
3
|
+
__all__ = ["Logging", "trace", "set_global_redaction", "print", "get_otel_status", "Run"]
|
|
4
4
|
|
|
5
5
|
|
|
6
6
|
def __getattr__(name):
|
|
7
|
+
if name == "Run":
|
|
8
|
+
from .events import Run
|
|
9
|
+
return Run
|
|
7
10
|
if name == "Logging":
|
|
8
11
|
from .custom_logging import Logging
|
|
9
12
|
return Logging
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
"""Versioned JSON CLI without changing the legacy print/serve contracts."""
|
|
2
|
+
import argparse
|
|
3
|
+
import json
|
|
4
|
+
import sys
|
|
5
|
+
|
|
6
|
+
from pyeztrace.inspection import InspectionError, Snapshot, encoded, MAX_OUTPUT_BYTES
|
|
7
|
+
|
|
8
|
+
COMMANDS = {'runs', 'tree', 'call', 'path', 'errors', 'payload'}
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
class Parser(argparse.ArgumentParser):
|
|
12
|
+
def error(self, message):
|
|
13
|
+
raise InspectionError('invalid_arguments', message)
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
def main(argv):
|
|
17
|
+
command = argv[0]
|
|
18
|
+
try:
|
|
19
|
+
parser = Parser(prog=f'pyeztrace {command}', allow_abbrev=False)
|
|
20
|
+
parser.add_argument('log_file')
|
|
21
|
+
if command in ('call', 'path', 'payload'):
|
|
22
|
+
parser.add_argument('call_id')
|
|
23
|
+
parser.add_argument('--run')
|
|
24
|
+
parser.add_argument('--format', choices=['json', 'text'], default='json')
|
|
25
|
+
if command in ('runs', 'tree', 'errors'):
|
|
26
|
+
parser.add_argument('--limit', type=int, default=100)
|
|
27
|
+
parser.add_argument('--cursor')
|
|
28
|
+
if command == 'payload':
|
|
29
|
+
parser.add_argument('--max-bytes', type=int, default=8192)
|
|
30
|
+
args = parser.parse_args(argv[1:])
|
|
31
|
+
if hasattr(args, 'limit') and not 1 <= args.limit <= 1000:
|
|
32
|
+
raise InspectionError('invalid_arguments', '--limit must be between 1 and 1000')
|
|
33
|
+
if hasattr(args, 'max_bytes') and not 1 <= args.max_bytes <= 65536:
|
|
34
|
+
raise InspectionError('invalid_arguments', '--max-bytes must be between 1 and 65536')
|
|
35
|
+
snapshot = Snapshot(args.log_file)
|
|
36
|
+
cursor = None
|
|
37
|
+
if command in ('call', 'path', 'payload'):
|
|
38
|
+
call = snapshot.find(args.call_id, args.run)
|
|
39
|
+
if command == 'call':
|
|
40
|
+
value = snapshot.summary(call)
|
|
41
|
+
elif command == 'path':
|
|
42
|
+
value = snapshot.ancestors(call)
|
|
43
|
+
else:
|
|
44
|
+
payload = [{'line': r['_line'], 'message': r.get('message'), 'data': r.get('data')}
|
|
45
|
+
for r in call['records']]
|
|
46
|
+
raw = encoded(payload)
|
|
47
|
+
value = {'call_id': call['call_id'], 'run_id': call['run_id'],
|
|
48
|
+
'bytes': len(raw), 'truncated': len(raw) > args.max_bytes,
|
|
49
|
+
'encoding': 'utf-8', 'content': raw[:args.max_bytes].decode('utf-8', errors='ignore')}
|
|
50
|
+
else:
|
|
51
|
+
if command == 'runs':
|
|
52
|
+
values = [r for r in snapshot.runs.values() if args.run is None or r['run_id'] == args.run]
|
|
53
|
+
else:
|
|
54
|
+
values = [snapshot.summary(c) for c in snapshot.calls.values()
|
|
55
|
+
if (args.run is None or c['run_id'] == args.run)
|
|
56
|
+
and (command != 'errors' or c['status'] == 'error')]
|
|
57
|
+
query = {'command': command, 'run': args.run}
|
|
58
|
+
value, cursor = snapshot.page(values, query, args.limit, args.cursor)
|
|
59
|
+
result = {'schema_version': 1, 'command': command, 'data': value,
|
|
60
|
+
'source': snapshot.source, 'warnings': snapshot.warnings, 'next_cursor': cursor}
|
|
61
|
+
raw = encoded(result)
|
|
62
|
+
if len(raw) > MAX_OUTPUT_BYTES:
|
|
63
|
+
raise InspectionError('output_too_large', 'Output exceeds 256 KiB; lower --limit or use payload')
|
|
64
|
+
output = raw.decode() if args.format == 'json' else json.dumps(result, ensure_ascii=False, indent=2, allow_nan=False)
|
|
65
|
+
if len(output.encode('utf-8')) > MAX_OUTPUT_BYTES:
|
|
66
|
+
raise InspectionError('output_too_large', 'Output exceeds 256 KiB; lower --limit')
|
|
67
|
+
sys.stdout.write(output + '\n')
|
|
68
|
+
return 0
|
|
69
|
+
except BrokenPipeError:
|
|
70
|
+
return 0
|
|
71
|
+
except (OSError, InspectionError, RecursionError, UnicodeError) as exc:
|
|
72
|
+
code = getattr(exc, 'code', 'io_error' if isinstance(exc, OSError) else 'invalid_record')
|
|
73
|
+
sys.stderr.write(json.dumps({'schema_version': 1, 'error': {'code': code, 'message': str(exc)}}) + '\n')
|
|
74
|
+
return 2 if code == 'invalid_arguments' else 1
|
|
@@ -280,6 +280,9 @@ def _port(value):
|
|
|
280
280
|
|
|
281
281
|
def main():
|
|
282
282
|
"""Main entry point for the pyeztrace CLI command."""
|
|
283
|
+
from pyeztrace.agent_cli import COMMANDS, main as inspect_main
|
|
284
|
+
if len(sys.argv) > 1 and sys.argv[1] in COMMANDS:
|
|
285
|
+
return inspect_main(sys.argv[1:])
|
|
283
286
|
parser = argparse.ArgumentParser(
|
|
284
287
|
description="PyEzTrace Log Analyzer and Viewer",
|
|
285
288
|
prog="pyeztrace", allow_abbrev=False
|
|
@@ -293,6 +296,8 @@ def main():
|
|
|
293
296
|
)
|
|
294
297
|
|
|
295
298
|
subparsers = parser.add_subparsers(dest='command', help='Available commands')
|
|
299
|
+
for command in sorted(COMMANDS):
|
|
300
|
+
subparsers.add_parser(command, help='Bounded JSON trace inspection (use ' + command + ' --help)')
|
|
296
301
|
|
|
297
302
|
# Analyze / print subcommand (default)
|
|
298
303
|
parser_print = subparsers.add_parser('print', help='Print or analyze logs', allow_abbrev=False)
|
|
@@ -21,6 +21,20 @@ from pyeztrace.config import config
|
|
|
21
21
|
from typing import Any, Callable, Optional, Union, Dict
|
|
22
22
|
|
|
23
23
|
|
|
24
|
+
def _open_private_file(path, flags):
|
|
25
|
+
return os.open(path, flags, 0o600)
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
class _PrivateRotatingFileHandler(RotatingFileHandler):
|
|
29
|
+
_open_with_permissions = staticmethod(open)
|
|
30
|
+
|
|
31
|
+
def _open(self):
|
|
32
|
+
return self._open_with_permissions(
|
|
33
|
+
self.baseFilename, self.mode, encoding=self.encoding, errors=self.errors,
|
|
34
|
+
opener=_open_private_file,
|
|
35
|
+
)
|
|
36
|
+
|
|
37
|
+
|
|
24
38
|
def _json_safe(value: Any, *, _seen: Optional[set] = None, _depth: int = 0) -> Any:
|
|
25
39
|
"""Return a bounded, JSON-safe representation without raising into application code."""
|
|
26
40
|
if value is None or isinstance(value, (bool, int, str)):
|
|
@@ -330,7 +344,7 @@ class Logging:
|
|
|
330
344
|
logger.removeHandler(handler)
|
|
331
345
|
|
|
332
346
|
|
|
333
|
-
file_handler =
|
|
347
|
+
file_handler = _PrivateRotatingFileHandler(
|
|
334
348
|
filename=str(log_path),
|
|
335
349
|
maxBytes=config.max_size,
|
|
336
350
|
backupCount=config.backup_count,
|
|
@@ -386,6 +400,7 @@ class Logging:
|
|
|
386
400
|
# Merge context with kwargs
|
|
387
401
|
context = LogContext.get_current_context()
|
|
388
402
|
merged_kwargs = {**context, **kwargs}
|
|
403
|
+
record_envelope = merged_kwargs.pop("_eztrace_envelope", None)
|
|
389
404
|
forced_level = merged_kwargs.pop("_eztrace_level_override", None)
|
|
390
405
|
safe_merged_kwargs = _json_safe(merged_kwargs)
|
|
391
406
|
include_data_in_output = Logging._show_data_in_cli
|
|
@@ -441,6 +456,8 @@ class Logging:
|
|
|
441
456
|
"message": message,
|
|
442
457
|
"data": safe_merged_kwargs,
|
|
443
458
|
}
|
|
459
|
+
if record_envelope is not None:
|
|
460
|
+
payload.update(record_envelope)
|
|
444
461
|
if duration is not None:
|
|
445
462
|
payload["duration"] = _json_safe(duration)
|
|
446
463
|
return json.dumps(payload, ensure_ascii=False, allow_nan=False)
|
|
@@ -500,6 +517,11 @@ class Logging:
|
|
|
500
517
|
})
|
|
501
518
|
return
|
|
502
519
|
|
|
520
|
+
from pyeztrace.events import envelope
|
|
521
|
+
event = merged_kwargs.get("event", "")
|
|
522
|
+
kind = "run" if str(event).startswith("run_") else ("call" if merged_kwargs.get("call_id") else "log")
|
|
523
|
+
merged_kwargs["_eztrace_envelope"] = envelope("llm" if merged_kwargs.get("kind") == "llm" else kind)
|
|
524
|
+
|
|
503
525
|
console_format = Logging._console_format or "color"
|
|
504
526
|
file_format = Logging._file_format or "json"
|
|
505
527
|
|
|
@@ -781,7 +803,7 @@ class Logging:
|
|
|
781
803
|
parent_dir = os.path.dirname(os.fspath(metrics_path))
|
|
782
804
|
if parent_dir:
|
|
783
805
|
os.makedirs(parent_dir, exist_ok=True)
|
|
784
|
-
with open(metrics_path, "a", encoding="utf-8") as f:
|
|
806
|
+
with open(metrics_path, "a", encoding="utf-8", opener=_open_private_file) as f:
|
|
785
807
|
f.write(json.dumps(snapshot) + "\n")
|
|
786
808
|
Logging._last_metrics_sidecar_fingerprint = fingerprint
|
|
787
809
|
except Exception:
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
"""Versioned record identities and explicit local run scopes."""
|
|
2
|
+
import contextvars
|
|
3
|
+
import os
|
|
4
|
+
import threading
|
|
5
|
+
import time
|
|
6
|
+
import uuid
|
|
7
|
+
|
|
8
|
+
SCHEMA_VERSION = 1
|
|
9
|
+
_run = contextvars.ContextVar('pyeztrace_run', default=None)
|
|
10
|
+
_process = os.getpid()
|
|
11
|
+
_process_run = uuid.uuid4().hex
|
|
12
|
+
_lock = threading.Lock()
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
def current_run_id():
|
|
16
|
+
global _process, _process_run, _lock
|
|
17
|
+
explicit = _run.get()
|
|
18
|
+
pid = os.getpid()
|
|
19
|
+
if explicit is not None and explicit[0] == pid:
|
|
20
|
+
return explicit[1]
|
|
21
|
+
# A PID check gives a forked child an independent implicit run.
|
|
22
|
+
if _process != pid:
|
|
23
|
+
# Do not acquire an inherited lock potentially held at fork.
|
|
24
|
+
_process, _process_run = pid, uuid.uuid4().hex
|
|
25
|
+
# Replace the inherited lock before acquiring it in the child.
|
|
26
|
+
_lock = threading.Lock()
|
|
27
|
+
with _lock:
|
|
28
|
+
if _process_run is None:
|
|
29
|
+
_process_run = uuid.uuid4().hex
|
|
30
|
+
return _process_run
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
def envelope(kind='log'):
|
|
34
|
+
return {'schema_version': SCHEMA_VERSION, 'event_id': uuid.uuid4().hex,
|
|
35
|
+
'run_id': current_run_id(), 'kind': kind}
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
class Run:
|
|
39
|
+
"""Group work into an explicit run; supports ``with`` in sync/async code.
|
|
40
|
+
|
|
41
|
+
A scope instance is single-use. Concurrent tasks inherit the run identity;
|
|
42
|
+
finish them before leaving the scope. Ordinary tracing works without a Run.
|
|
43
|
+
"""
|
|
44
|
+
|
|
45
|
+
def __init__(self, name='run'):
|
|
46
|
+
self.name = str(name)
|
|
47
|
+
self.id = uuid.uuid4().hex
|
|
48
|
+
self._token = None
|
|
49
|
+
self._used = False
|
|
50
|
+
|
|
51
|
+
def __enter__(self):
|
|
52
|
+
from pyeztrace.custom_logging import Logging
|
|
53
|
+
if self._used:
|
|
54
|
+
raise RuntimeError('Run scopes are single-use')
|
|
55
|
+
self._used = True
|
|
56
|
+
self._token = _run.set((os.getpid(), self.id))
|
|
57
|
+
self._start = time.monotonic()
|
|
58
|
+
try:
|
|
59
|
+
Logging.log_info('Run started', function=self.name, event='run_start')
|
|
60
|
+
except BaseException:
|
|
61
|
+
_run.reset(self._token)
|
|
62
|
+
raise
|
|
63
|
+
return self
|
|
64
|
+
|
|
65
|
+
def __exit__(self, exc_type, exc, tb):
|
|
66
|
+
from pyeztrace.custom_logging import Logging
|
|
67
|
+
current = _run.get()
|
|
68
|
+
if current != (os.getpid(), self.id):
|
|
69
|
+
raise RuntimeError('Run scopes must exit in reverse entry order')
|
|
70
|
+
_run.reset(self._token)
|
|
71
|
+
token = _run.set(current)
|
|
72
|
+
try:
|
|
73
|
+
Logging.log_info('Run ended', function=self.name,
|
|
74
|
+
event='run_error' if exc_type else 'run_end',
|
|
75
|
+
status='error' if exc_type else 'success',
|
|
76
|
+
duration=time.monotonic() - self._start)
|
|
77
|
+
finally:
|
|
78
|
+
_run.reset(token)
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
try:
|
|
2
|
+
from builtins import BaseExceptionGroup
|
|
3
|
+
except ImportError: # Python 3.9–3.10
|
|
4
|
+
BaseExceptionGroup = ()
|
|
5
|
+
|
|
6
|
+
|
|
7
|
+
def protect_exception_details(exc):
|
|
8
|
+
"""Keep the original exception while marking its details private to tracing."""
|
|
9
|
+
if isinstance(exc, BaseException):
|
|
10
|
+
BaseException.__setattr__(exc, "_pyeztrace_private_details", True)
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
def has_private_exception_details(exc):
|
|
14
|
+
pending = [exc]
|
|
15
|
+
seen = set()
|
|
16
|
+
while pending:
|
|
17
|
+
current = pending.pop()
|
|
18
|
+
if current is None or id(current) in seen:
|
|
19
|
+
continue
|
|
20
|
+
seen.add(id(current))
|
|
21
|
+
if getattr(current, "_pyeztrace_private_details", False):
|
|
22
|
+
return True
|
|
23
|
+
pending.extend((current.__cause__, current.__context__))
|
|
24
|
+
if isinstance(current, BaseExceptionGroup):
|
|
25
|
+
pending.extend(current.exceptions)
|
|
26
|
+
return False
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
class SetupNotDoneError(Exception):
|
|
30
|
+
"""
|
|
31
|
+
Exception raised when setup is not done.
|
|
32
|
+
"""
|
|
33
|
+
pass
|
|
34
|
+
|
|
35
|
+
class SetupAlreadyDoneError(Exception):
|
|
36
|
+
"""
|
|
37
|
+
Exception raised when setup is already done.
|
|
38
|
+
"""
|
|
39
|
+
pass
|
|
40
|
+
|
|
41
|
+
class SetupError(Exception):
|
|
42
|
+
"""
|
|
43
|
+
Exception raised for general setup errors.
|
|
44
|
+
"""
|
|
45
|
+
pass
|
|
46
|
+
|
|
47
|
+
class TracingError(Exception):
|
|
48
|
+
"""
|
|
49
|
+
Exception raised for errors in the tracing system.
|
|
50
|
+
"""
|
|
51
|
+
pass
|
|
@@ -0,0 +1,158 @@
|
|
|
1
|
+
"""Bounded, snapshot-based inspection shared by machine-facing consumers."""
|
|
2
|
+
import base64
|
|
3
|
+
import hashlib
|
|
4
|
+
import io
|
|
5
|
+
import json
|
|
6
|
+
import math
|
|
7
|
+
import os
|
|
8
|
+
import stat
|
|
9
|
+
from pathlib import Path
|
|
10
|
+
|
|
11
|
+
MAX_FILE_BYTES = 64 * 1024 * 1024
|
|
12
|
+
MAX_RECORD_BYTES = 1024 * 1024
|
|
13
|
+
MAX_OUTPUT_BYTES = 256 * 1024
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
class InspectionError(ValueError):
|
|
17
|
+
def __init__(self, code, message):
|
|
18
|
+
super().__init__(message)
|
|
19
|
+
self.code = code
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
def encoded(value):
|
|
23
|
+
return json.dumps(value, ensure_ascii=False, allow_nan=False, separators=(',', ':')).encode('utf-8')
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
def open_regular_file(path):
|
|
27
|
+
# Opening a FIFO in blocking mode would hang before we can check its type.
|
|
28
|
+
fd = os.open(path, os.O_RDONLY | getattr(os, 'O_NONBLOCK', 0))
|
|
29
|
+
source = os.fdopen(fd, 'rb')
|
|
30
|
+
try:
|
|
31
|
+
if not stat.S_ISREG(os.fstat(fd).st_mode):
|
|
32
|
+
raise InspectionError('invalid_source', 'Source must be a regular file')
|
|
33
|
+
except BaseException:
|
|
34
|
+
source.close()
|
|
35
|
+
raise
|
|
36
|
+
return source
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
def finite_float(value):
|
|
40
|
+
number = float(value)
|
|
41
|
+
return number if math.isfinite(number) else None
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
class Snapshot:
|
|
45
|
+
def __init__(self, path):
|
|
46
|
+
with open_regular_file(Path(path)) as source:
|
|
47
|
+
raw = source.read(MAX_FILE_BYTES + 1)
|
|
48
|
+
if len(raw) > MAX_FILE_BYTES:
|
|
49
|
+
raise InspectionError('source_too_large', 'Source exceeds 64 MiB; select a smaller log segment')
|
|
50
|
+
self.fingerprint = hashlib.sha256(raw).hexdigest()
|
|
51
|
+
self.source = {'sha256': self.fingerprint, 'bytes': len(raw)}
|
|
52
|
+
self.warnings = []
|
|
53
|
+
self.rows = []
|
|
54
|
+
self.calls = {}
|
|
55
|
+
self.runs = {}
|
|
56
|
+
malformed = 0
|
|
57
|
+
legacy_run = 'legacy'
|
|
58
|
+
for number, line in enumerate(io.BytesIO(raw), 1):
|
|
59
|
+
if number > 100000:
|
|
60
|
+
raise InspectionError("too_many_records", "Source exceeds 100,000 records")
|
|
61
|
+
if len(line.rstrip(b'\r\n')) > MAX_RECORD_BYTES:
|
|
62
|
+
raise InspectionError("record_too_large", "A record exceeds 1 MiB")
|
|
63
|
+
try:
|
|
64
|
+
row = json.loads(line, parse_constant=lambda v: None, parse_float=finite_float)
|
|
65
|
+
if not isinstance(row, dict) or not isinstance(row.get('data', {}), dict):
|
|
66
|
+
raise ValueError()
|
|
67
|
+
except (ValueError, UnicodeError, RecursionError):
|
|
68
|
+
malformed += 1
|
|
69
|
+
continue
|
|
70
|
+
version = row.get('schema_version')
|
|
71
|
+
if version is not None and (type(version) is not int or version != 1):
|
|
72
|
+
raise InspectionError('unsupported_schema', f'Unsupported record schema on line {number}')
|
|
73
|
+
data = row.get('data', {})
|
|
74
|
+
run = row.get('run_id') if version == 1 else legacy_run
|
|
75
|
+
if not isinstance(run, str) or not run:
|
|
76
|
+
malformed += 1
|
|
77
|
+
continue
|
|
78
|
+
row['_run'] = run
|
|
79
|
+
row['_line'] = number
|
|
80
|
+
self.rows.append(row)
|
|
81
|
+
summary = self.runs.setdefault(run, {'run_id': run, 'name': None,
|
|
82
|
+
'status': 'unknown', 'calls': 0})
|
|
83
|
+
event = data.get('event')
|
|
84
|
+
if event == 'run_start':
|
|
85
|
+
summary.update(name=row.get('function'), status='incomplete')
|
|
86
|
+
elif event in ('run_end', 'run_error'):
|
|
87
|
+
summary['status'] = 'error' if event == 'run_error' else 'success'
|
|
88
|
+
cid = data.get('call_id')
|
|
89
|
+
if not isinstance(cid, str) or not cid:
|
|
90
|
+
continue
|
|
91
|
+
key = (run, cid)
|
|
92
|
+
if key not in self.calls:
|
|
93
|
+
self.calls[key] = {'call_id': cid, 'run_id': run, 'parent_id': None,
|
|
94
|
+
'function': None, 'kind': data.get('kind', 'call'),
|
|
95
|
+
'status': 'unknown', 'duration': None, 'records': []}
|
|
96
|
+
summary['calls'] += 1
|
|
97
|
+
call = self.calls[key]
|
|
98
|
+
parent = data.get('parent_id')
|
|
99
|
+
if isinstance(parent, str) and parent:
|
|
100
|
+
call['parent_id'] = parent
|
|
101
|
+
call['function'] = call['function'] or row.get('function')
|
|
102
|
+
if event == 'start':
|
|
103
|
+
call['status'] = 'incomplete'
|
|
104
|
+
elif event in ('end', 'error'):
|
|
105
|
+
call['status'] = data.get('status', 'error' if event == 'error' else 'success')
|
|
106
|
+
call['duration'] = row.get('duration')
|
|
107
|
+
call['records'].append(row)
|
|
108
|
+
if malformed:
|
|
109
|
+
self.warnings.append({'code': 'malformed_records', 'count': malformed})
|
|
110
|
+
|
|
111
|
+
def find(self, cid, run=None):
|
|
112
|
+
matches = [c for (rid, identity), c in self.calls.items()
|
|
113
|
+
if identity == cid and (run is None or rid == run)]
|
|
114
|
+
if not matches:
|
|
115
|
+
raise InspectionError('not_found', 'Call was not found')
|
|
116
|
+
if len(matches) != 1:
|
|
117
|
+
raise InspectionError('ambiguous_call', 'Call ID occurs in multiple runs; specify --run')
|
|
118
|
+
return matches[0]
|
|
119
|
+
|
|
120
|
+
@staticmethod
|
|
121
|
+
def summary(call):
|
|
122
|
+
return {k: v for k, v in call.items() if k != 'records'}
|
|
123
|
+
|
|
124
|
+
def ancestors(self, call):
|
|
125
|
+
path, seen = [], set()
|
|
126
|
+
while call:
|
|
127
|
+
if call['call_id'] in seen:
|
|
128
|
+
raise InspectionError('cyclic_parent', 'Parent chain contains a cycle')
|
|
129
|
+
seen.add(call['call_id'])
|
|
130
|
+
path.append(self.summary(call))
|
|
131
|
+
parent = call['parent_id']
|
|
132
|
+
call = self.calls.get((call['run_id'], parent))
|
|
133
|
+
if parent and call is None:
|
|
134
|
+
self.warnings.append({'code': 'missing_parent', 'call_id': parent})
|
|
135
|
+
return list(reversed(path))
|
|
136
|
+
|
|
137
|
+
def page(self, values, query, limit, cursor):
|
|
138
|
+
offset = 0
|
|
139
|
+
if cursor:
|
|
140
|
+
if len(cursor) > 4096:
|
|
141
|
+
raise InspectionError("invalid_cursor", "Cursor exceeds size limit")
|
|
142
|
+
try:
|
|
143
|
+
token = json.loads(base64.urlsafe_b64decode(cursor.encode()))
|
|
144
|
+
if token['source'] != self.fingerprint or token['query'] != query:
|
|
145
|
+
raise InspectionError('stale_cursor', 'Source or query changed; restart pagination')
|
|
146
|
+
offset = token['offset']
|
|
147
|
+
if type(offset) is not int or not 0 <= offset <= len(values):
|
|
148
|
+
raise ValueError()
|
|
149
|
+
except InspectionError:
|
|
150
|
+
raise
|
|
151
|
+
except (ValueError, KeyError, TypeError, UnicodeError):
|
|
152
|
+
raise InspectionError('invalid_cursor', 'Invalid pagination cursor') from None
|
|
153
|
+
end = min(offset + limit, len(values))
|
|
154
|
+
next_cursor = None
|
|
155
|
+
if end < len(values):
|
|
156
|
+
next_cursor = base64.urlsafe_b64encode(encoded(
|
|
157
|
+
{'source': self.fingerprint, 'query': query, 'offset': end})).decode()
|
|
158
|
+
return values[offset:end], next_cursor
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""Optional integrations. Import individual adapters explicitly."""
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
"""LangChain callback integration; only this module imports langchain-core."""
|
|
2
|
+
import threading
|
|
3
|
+
|
|
4
|
+
try:
|
|
5
|
+
from langchain_core.callbacks import BaseCallbackHandler
|
|
6
|
+
except ImportError as exc:
|
|
7
|
+
raise ImportError('Install pyeztrace[langchain] to use the LangChain integration') from exc
|
|
8
|
+
|
|
9
|
+
from pyeztrace.llm import CapturePolicy, Operation, field
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
class PyEzTraceCallbackHandler(BaseCallbackHandler):
|
|
13
|
+
"""Capture local model/tool operations; do not combine with SDK wrapping.
|
|
14
|
+
|
|
15
|
+
The same handler can be shared by concurrent runs. Pending operations are
|
|
16
|
+
bounded; call close() when abandoning a framework run without end callbacks.
|
|
17
|
+
"""
|
|
18
|
+
run_inline = True
|
|
19
|
+
|
|
20
|
+
def __init__(self, *, capture_content=True, max_content_bytes=8192, redact=None):
|
|
21
|
+
self.policy = CapturePolicy(capture_content, max_content_bytes, redact)
|
|
22
|
+
self._operations = {}
|
|
23
|
+
self._lock = threading.RLock()
|
|
24
|
+
|
|
25
|
+
def _start(self, name, params, run_id, parent_run_id):
|
|
26
|
+
with self._lock:
|
|
27
|
+
if len(self._operations) >= 1024 or str(run_id) in self._operations:
|
|
28
|
+
return
|
|
29
|
+
parent = self._operations.get(str(parent_run_id))
|
|
30
|
+
operation = Operation(name, 'langchain', params, self.policy,
|
|
31
|
+
parent_id=str(parent_run_id) if parent_run_id else None,
|
|
32
|
+
identity=str(run_id), run_id=parent.run if parent else None)
|
|
33
|
+
self._operations[str(run_id)] = operation
|
|
34
|
+
|
|
35
|
+
def on_chat_model_start(self, serialized, messages, *, run_id, parent_run_id=None, **kwargs):
|
|
36
|
+
params = kwargs.get('invocation_params') or {}
|
|
37
|
+
self._start('langchain.chat', {'messages': messages, 'model': params.get('model_name', params.get('model', 'unknown'))}, run_id, parent_run_id)
|
|
38
|
+
|
|
39
|
+
def on_llm_start(self, serialized, prompts, *, run_id, parent_run_id=None, **kwargs):
|
|
40
|
+
params = kwargs.get('invocation_params') or {}
|
|
41
|
+
self._start('langchain.llm', {'prompt': prompts, 'model': params.get('model_name', params.get('model', 'unknown'))}, run_id, parent_run_id)
|
|
42
|
+
|
|
43
|
+
def on_llm_end(self, response, *, run_id, **kwargs):
|
|
44
|
+
with self._lock:
|
|
45
|
+
operation = self._operations.pop(str(run_id), None)
|
|
46
|
+
if operation:
|
|
47
|
+
generations = field(response, 'generations') or []
|
|
48
|
+
usage = (field(response, 'llm_output') or {}).get('token_usage', {})
|
|
49
|
+
if not usage:
|
|
50
|
+
# Newer chat models attach usage to the returned AIMessage.
|
|
51
|
+
# Count one candidate per batch, not each alternative generation.
|
|
52
|
+
usage = {}
|
|
53
|
+
for batch in generations[:64]:
|
|
54
|
+
if not batch:
|
|
55
|
+
continue
|
|
56
|
+
counts = field(field(batch[0], 'message'), 'usage_metadata') or {}
|
|
57
|
+
for key in ('input_tokens', 'output_tokens', 'total_tokens'):
|
|
58
|
+
count = field(counts, key)
|
|
59
|
+
if type(count) is int and count >= 0:
|
|
60
|
+
usage[key] = usage.get(key, 0) + count
|
|
61
|
+
operation.observe({'output': field(response, 'generations'),
|
|
62
|
+
'usage': usage})
|
|
63
|
+
operation.finish()
|
|
64
|
+
|
|
65
|
+
def on_llm_error(self, error, *, run_id, **kwargs):
|
|
66
|
+
with self._lock:
|
|
67
|
+
operation = self._operations.pop(str(run_id), None)
|
|
68
|
+
if operation:
|
|
69
|
+
operation.finish('error', error)
|
|
70
|
+
|
|
71
|
+
def on_tool_start(self, serialized, input_str, *, run_id, parent_run_id=None, **kwargs):
|
|
72
|
+
self._start('langchain.tool.' + str((serialized or {}).get('name', 'tool'))[:128],
|
|
73
|
+
{'input': input_str}, run_id, parent_run_id)
|
|
74
|
+
|
|
75
|
+
def on_tool_end(self, output, *, run_id, **kwargs):
|
|
76
|
+
with self._lock:
|
|
77
|
+
operation = self._operations.pop(str(run_id), None)
|
|
78
|
+
if operation:
|
|
79
|
+
operation.observe({'output': output})
|
|
80
|
+
operation.finish()
|
|
81
|
+
|
|
82
|
+
def on_tool_error(self, error, *, run_id, **kwargs):
|
|
83
|
+
self.on_llm_error(error, run_id=run_id)
|
|
84
|
+
|
|
85
|
+
def on_chain_start(self, serialized, inputs, *, run_id, parent_run_id=None, **kwargs):
|
|
86
|
+
name = kwargs.get('name') or (serialized or {}).get('name', 'chain')
|
|
87
|
+
self._start('langchain.chain.' + str(name)[:128], {'input': inputs}, run_id, parent_run_id)
|
|
88
|
+
|
|
89
|
+
def on_chain_end(self, outputs, *, run_id, **kwargs):
|
|
90
|
+
self.on_tool_end(outputs, run_id=run_id)
|
|
91
|
+
|
|
92
|
+
def on_chain_error(self, error, *, run_id, **kwargs):
|
|
93
|
+
self.on_llm_error(error, run_id=run_id)
|
|
94
|
+
|
|
95
|
+
def close(self):
|
|
96
|
+
with self._lock:
|
|
97
|
+
pending, self._operations = self._operations, {}
|
|
98
|
+
for operation in pending.values():
|
|
99
|
+
operation.finish('cancelled')
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
"""Explicit OpenAI/Anthropic client proxies; SDK imports stay in user code."""
|
|
2
|
+
from pyeztrace.llm import CapturePolicy, wrap_create
|
|
3
|
+
|
|
4
|
+
|
|
5
|
+
class _Proxy:
|
|
6
|
+
def __init__(self, target, provider, policy, path=()):
|
|
7
|
+
self._target, self._provider, self._policy, self._path = target, provider, policy, path
|
|
8
|
+
|
|
9
|
+
def __getattr__(self, name):
|
|
10
|
+
value = getattr(self._target, name)
|
|
11
|
+
path = self._path + (name,)
|
|
12
|
+
routes = {('chat', 'completions', 'create'), ('responses', 'create')} if self._provider == 'openai' else {('messages', 'create')}
|
|
13
|
+
if path in routes:
|
|
14
|
+
return wrap_create(value, self._provider, '.'.join(path), self._policy)
|
|
15
|
+
if any(route[:len(path)] == path for route in routes):
|
|
16
|
+
return _Proxy(value, self._provider, self._policy, path)
|
|
17
|
+
return value
|
|
18
|
+
|
|
19
|
+
def __enter__(self):
|
|
20
|
+
self._target.__enter__()
|
|
21
|
+
return self
|
|
22
|
+
|
|
23
|
+
def __exit__(self, *args):
|
|
24
|
+
return self._target.__exit__(*args)
|
|
25
|
+
|
|
26
|
+
async def __aenter__(self):
|
|
27
|
+
await self._target.__aenter__()
|
|
28
|
+
return self
|
|
29
|
+
|
|
30
|
+
async def __aexit__(self, *args):
|
|
31
|
+
return await self._target.__aexit__(*args)
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
def trace_openai(client, *, capture_content=True, max_content_bytes=8192, redact=None):
|
|
35
|
+
"""Return a proxy tracing Chat Completions/Responses create, including stream=True."""
|
|
36
|
+
return _Proxy(client, 'openai', CapturePolicy(capture_content, max_content_bytes, redact))
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
def trace_anthropic(client, *, capture_content=True, max_content_bytes=8192, redact=None):
|
|
40
|
+
"""Return a proxy tracing Messages create, including stream=True."""
|
|
41
|
+
return _Proxy(client, 'anthropic', CapturePolicy(capture_content, max_content_bytes, redact))
|