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.
Files changed (55) hide show
  1. {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/PKG-INFO +16 -1
  2. {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/README.md +7 -0
  3. {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/pyeztrace/__init__.py +4 -1
  4. pyeztrace-0.2.0.dev0/pyeztrace/agent_cli.py +74 -0
  5. {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/pyeztrace/cli.py +5 -0
  6. {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/pyeztrace/custom_logging.py +24 -2
  7. pyeztrace-0.2.0.dev0/pyeztrace/events.py +78 -0
  8. pyeztrace-0.2.0.dev0/pyeztrace/exceptions.py +51 -0
  9. pyeztrace-0.2.0.dev0/pyeztrace/inspection.py +158 -0
  10. pyeztrace-0.2.0.dev0/pyeztrace/integrations/__init__.py +1 -0
  11. pyeztrace-0.2.0.dev0/pyeztrace/integrations/langchain.py +99 -0
  12. pyeztrace-0.2.0.dev0/pyeztrace/integrations/sdk.py +41 -0
  13. pyeztrace-0.2.0.dev0/pyeztrace/llm.py +353 -0
  14. {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/pyeztrace/otel.py +11 -3
  15. {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/pyeztrace/tracer.py +53 -40
  16. {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/pyeztrace/viewer.py +103 -28
  17. {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/pyeztrace.egg-info/PKG-INFO +16 -1
  18. {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/pyeztrace.egg-info/SOURCES.txt +11 -0
  19. {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/pyeztrace.egg-info/requires.txt +12 -0
  20. {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/pyproject.toml +10 -2
  21. {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/tests/test_custom_logging.py +3 -0
  22. pyeztrace-0.2.0.dev0/tests/test_events.py +95 -0
  23. pyeztrace-0.2.0.dev0/tests/test_inspection.py +107 -0
  24. pyeztrace-0.2.0.dev0/tests/test_llm.py +106 -0
  25. pyeztrace-0.2.0.dev0/tests/test_llm_sdks.py +177 -0
  26. {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/tests/test_otel_bridge.py +49 -1
  27. {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/tests/test_viewer_javascript.py +17 -0
  28. {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/tests/test_viewer_live_states.py +34 -1
  29. pyeztrace-0.1.6/pyeztrace/exceptions.py +0 -23
  30. {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/LICENSE +0 -0
  31. {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/pyeztrace/_version.py +0 -0
  32. {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/pyeztrace/config.py +0 -0
  33. {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/pyeztrace/printing.py +0 -0
  34. {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/pyeztrace/setup.py +0 -0
  35. {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/pyeztrace.egg-info/dependency_links.txt +0 -0
  36. {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/pyeztrace.egg-info/entry_points.txt +0 -0
  37. {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/pyeztrace.egg-info/top_level.txt +0 -0
  38. {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/setup.cfg +0 -0
  39. {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/setup.py +0 -0
  40. {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/tests/test_advanced.py +0 -0
  41. {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/tests/test_async_task.py +0 -0
  42. {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/tests/test_cli_parser.py +0 -0
  43. {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/tests/test_cli_workflow.py +0 -0
  44. {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/tests/test_double_tracing.py +0 -0
  45. {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/tests/test_exception.py +0 -0
  46. {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/tests/test_integration.py +0 -0
  47. {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/tests/test_maintenance.py +0 -0
  48. {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/tests/test_printing.py +0 -0
  49. {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/tests/test_production_robustness.py +0 -0
  50. {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/tests/test_real_world.py +0 -0
  51. {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/tests/test_recursive_tracing.py +0 -0
  52. {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/tests/test_runtime_lifecycle.py +0 -0
  53. {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/tests/test_setup.py +0 -0
  54. {pyeztrace-0.1.6 → pyeztrace-0.2.0.dev0}/tests/test_tracer.py +0 -0
  55. {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.1.6
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 = RotatingFileHandler(
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))