pyeztrace 0.1.5__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.5 → pyeztrace-0.2.0.dev0}/PKG-INFO +27 -6
  2. {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/README.md +18 -5
  3. {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/pyeztrace/__init__.py +7 -1
  4. pyeztrace-0.2.0.dev0/pyeztrace/agent_cli.py +74 -0
  5. {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/pyeztrace/cli.py +5 -0
  6. {pyeztrace-0.1.5 → 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.5 → pyeztrace-0.2.0.dev0}/pyeztrace/otel.py +22 -3
  15. {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/pyeztrace/tracer.py +53 -40
  16. {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/pyeztrace/viewer.py +114 -29
  17. {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/pyeztrace.egg-info/PKG-INFO +27 -6
  18. {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/pyeztrace.egg-info/SOURCES.txt +12 -0
  19. {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/pyeztrace.egg-info/requires.txt +12 -0
  20. {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/pyproject.toml +17 -2
  21. {pyeztrace-0.1.5 → 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.2.0.dev0/tests/test_maintenance.py +45 -0
  27. {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/tests/test_otel_bridge.py +75 -1
  28. {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/tests/test_viewer_javascript.py +17 -0
  29. {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/tests/test_viewer_live_states.py +34 -1
  30. pyeztrace-0.1.5/pyeztrace/exceptions.py +0 -23
  31. {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/LICENSE +0 -0
  32. {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/pyeztrace/_version.py +0 -0
  33. {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/pyeztrace/config.py +0 -0
  34. {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/pyeztrace/printing.py +0 -0
  35. {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/pyeztrace/setup.py +0 -0
  36. {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/pyeztrace.egg-info/dependency_links.txt +0 -0
  37. {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/pyeztrace.egg-info/entry_points.txt +0 -0
  38. {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/pyeztrace.egg-info/top_level.txt +0 -0
  39. {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/setup.cfg +0 -0
  40. {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/setup.py +0 -0
  41. {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/tests/test_advanced.py +0 -0
  42. {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/tests/test_async_task.py +0 -0
  43. {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/tests/test_cli_parser.py +0 -0
  44. {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/tests/test_cli_workflow.py +0 -0
  45. {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/tests/test_double_tracing.py +0 -0
  46. {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/tests/test_exception.py +0 -0
  47. {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/tests/test_integration.py +0 -0
  48. {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/tests/test_printing.py +0 -0
  49. {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/tests/test_production_robustness.py +0 -0
  50. {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/tests/test_real_world.py +0 -0
  51. {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/tests/test_recursive_tracing.py +0 -0
  52. {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/tests/test_runtime_lifecycle.py +0 -0
  53. {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/tests/test_setup.py +0 -0
  54. {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/tests/test_tracer.py +0 -0
  55. {pyeztrace-0.1.5 → 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.5
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"
@@ -47,6 +55,12 @@ A dependency-free, lightweight Python tracing and logging library with hierarchi
47
55
 
48
56
  Requires Python 3.9 or newer.
49
57
 
58
+ ## Is PyEzTrace right for this task?
59
+
60
+ - [Standard logging and PyEzTrace](https://jeffersonaaron25.github.io/PyEzTrace/standard-logging/): messages, call trees, and how they fit together.
61
+ - [When to use OpenTelemetry](https://jeffersonaaron25.github.io/PyEzTrace/opentelemetry/): local inspection or optional span export.
62
+ - [Report a bug or suggest a feature](https://github.com/jeffersonaaron25/PyEzTrace/issues/new/choose).
63
+
50
64
  ## Features
51
65
 
52
66
  - **Hierarchical Logging**: Visualize nested operations with tree-style output
@@ -78,10 +92,10 @@ pip install "pyeztrace[otel]"
78
92
  pip install "pyeztrace[otel,gcp]"
79
93
 
80
94
  # S3 exporter
81
- pip install "pyeztrace[s3]"
95
+ pip install "pyeztrace[otel,s3]"
82
96
 
83
97
  # Azure Blob exporter
84
- pip install "pyeztrace[azure]"
98
+ pip install "pyeztrace[otel,azure]"
85
99
 
86
100
  # Everything
87
101
  pip install "pyeztrace[all]"
@@ -493,7 +507,7 @@ export EZTRACE_OTEL_EXPORTER=console
493
507
  Export span batches to S3 as JSONL (gzipped by default) without a collector:
494
508
 
495
509
  ```bash
496
- pip install "pyeztrace[s3]"
510
+ pip install "pyeztrace[otel,s3]"
497
511
  export EZTRACE_OTEL_ENABLED=true
498
512
  export EZTRACE_OTEL_EXPORTER=s3
499
513
  export EZTRACE_S3_BUCKET="my-trace-bucket"
@@ -505,7 +519,7 @@ export EZTRACE_COMPRESS=true # optional, default true
505
519
  Export span batches to Azure Blob Storage:
506
520
 
507
521
  ```bash
508
- pip install "pyeztrace[azure]"
522
+ pip install "pyeztrace[otel,azure]"
509
523
  export EZTRACE_OTEL_ENABLED=true
510
524
  export EZTRACE_OTEL_EXPORTER=azure
511
525
  export EZTRACE_AZURE_CONTAINER="trace-container"
@@ -522,7 +536,7 @@ Notes:
522
536
  - Exceptions are recorded on the active span when OTEL is enabled.
523
537
  - Set `EZTRACE_OTEL_DEBUG=true` to emit one-time OTEL diagnostics to stderr (startup status and no-op reasons).
524
538
  - Remote exporter initialization fails closed by default. Set `EZTRACE_OTEL_FALLBACK_TO_CONSOLE=true` only when stdout fallback is intentional.
525
- - Inspect runtime OTEL state with `from pyeztrace import otel; print(otel.get_otel_status())` (available in newer builds after `0.1.1`).
539
+ - Inspect runtime OTEL state with `from pyeztrace import get_otel_status; print(get_otel_status())` (top-level export available since `0.1.6`).
526
540
 
527
541
  ## Advanced Usage
528
542
 
@@ -625,3 +639,10 @@ Contributions are welcome! Please read our [Contributing Guidelines](CONTRIBUTIN
625
639
  ## License
626
640
 
627
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.
@@ -10,6 +10,12 @@ A dependency-free, lightweight Python tracing and logging library with hierarchi
10
10
 
11
11
  Requires Python 3.9 or newer.
12
12
 
13
+ ## Is PyEzTrace right for this task?
14
+
15
+ - [Standard logging and PyEzTrace](https://jeffersonaaron25.github.io/PyEzTrace/standard-logging/): messages, call trees, and how they fit together.
16
+ - [When to use OpenTelemetry](https://jeffersonaaron25.github.io/PyEzTrace/opentelemetry/): local inspection or optional span export.
17
+ - [Report a bug or suggest a feature](https://github.com/jeffersonaaron25/PyEzTrace/issues/new/choose).
18
+
13
19
  ## Features
14
20
 
15
21
  - **Hierarchical Logging**: Visualize nested operations with tree-style output
@@ -41,10 +47,10 @@ pip install "pyeztrace[otel]"
41
47
  pip install "pyeztrace[otel,gcp]"
42
48
 
43
49
  # S3 exporter
44
- pip install "pyeztrace[s3]"
50
+ pip install "pyeztrace[otel,s3]"
45
51
 
46
52
  # Azure Blob exporter
47
- pip install "pyeztrace[azure]"
53
+ pip install "pyeztrace[otel,azure]"
48
54
 
49
55
  # Everything
50
56
  pip install "pyeztrace[all]"
@@ -456,7 +462,7 @@ export EZTRACE_OTEL_EXPORTER=console
456
462
  Export span batches to S3 as JSONL (gzipped by default) without a collector:
457
463
 
458
464
  ```bash
459
- pip install "pyeztrace[s3]"
465
+ pip install "pyeztrace[otel,s3]"
460
466
  export EZTRACE_OTEL_ENABLED=true
461
467
  export EZTRACE_OTEL_EXPORTER=s3
462
468
  export EZTRACE_S3_BUCKET="my-trace-bucket"
@@ -468,7 +474,7 @@ export EZTRACE_COMPRESS=true # optional, default true
468
474
  Export span batches to Azure Blob Storage:
469
475
 
470
476
  ```bash
471
- pip install "pyeztrace[azure]"
477
+ pip install "pyeztrace[otel,azure]"
472
478
  export EZTRACE_OTEL_ENABLED=true
473
479
  export EZTRACE_OTEL_EXPORTER=azure
474
480
  export EZTRACE_AZURE_CONTAINER="trace-container"
@@ -485,7 +491,7 @@ Notes:
485
491
  - Exceptions are recorded on the active span when OTEL is enabled.
486
492
  - Set `EZTRACE_OTEL_DEBUG=true` to emit one-time OTEL diagnostics to stderr (startup status and no-op reasons).
487
493
  - Remote exporter initialization fails closed by default. Set `EZTRACE_OTEL_FALLBACK_TO_CONSOLE=true` only when stdout fallback is intentional.
488
- - Inspect runtime OTEL state with `from pyeztrace import otel; print(otel.get_otel_status())` (available in newer builds after `0.1.1`).
494
+ - Inspect runtime OTEL state with `from pyeztrace import get_otel_status; print(get_otel_status())` (top-level export available since `0.1.6`).
489
495
 
490
496
  ## Advanced Usage
491
497
 
@@ -588,3 +594,10 @@ Contributions are welcome! Please read our [Contributing Guidelines](CONTRIBUTIN
588
594
  ## License
589
595
 
590
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"]
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
@@ -13,6 +16,9 @@ def __getattr__(name):
13
16
  if name == "set_global_redaction":
14
17
  from .tracer import set_global_redaction
15
18
  return set_global_redaction
19
+ if name == "get_otel_status":
20
+ from .otel import get_otel_status
21
+ return get_otel_status
16
22
  if name == "print":
17
23
  from .printing import print as pyeztrace_print # noqa: A001
18
24
  return pyeztrace_print
@@ -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."""