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.
- {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/PKG-INFO +27 -6
- {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/README.md +18 -5
- {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/pyeztrace/__init__.py +7 -1
- pyeztrace-0.2.0.dev0/pyeztrace/agent_cli.py +74 -0
- {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/pyeztrace/cli.py +5 -0
- {pyeztrace-0.1.5 → 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.5 → pyeztrace-0.2.0.dev0}/pyeztrace/otel.py +22 -3
- {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/pyeztrace/tracer.py +53 -40
- {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/pyeztrace/viewer.py +114 -29
- {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/pyeztrace.egg-info/PKG-INFO +27 -6
- {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/pyeztrace.egg-info/SOURCES.txt +12 -0
- {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/pyeztrace.egg-info/requires.txt +12 -0
- {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/pyproject.toml +17 -2
- {pyeztrace-0.1.5 → 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.2.0.dev0/tests/test_maintenance.py +45 -0
- {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/tests/test_otel_bridge.py +75 -1
- {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/tests/test_viewer_javascript.py +17 -0
- {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/tests/test_viewer_live_states.py +34 -1
- pyeztrace-0.1.5/pyeztrace/exceptions.py +0 -23
- {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/LICENSE +0 -0
- {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/pyeztrace/_version.py +0 -0
- {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/pyeztrace/config.py +0 -0
- {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/pyeztrace/printing.py +0 -0
- {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/pyeztrace/setup.py +0 -0
- {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/pyeztrace.egg-info/dependency_links.txt +0 -0
- {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/pyeztrace.egg-info/entry_points.txt +0 -0
- {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/pyeztrace.egg-info/top_level.txt +0 -0
- {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/setup.cfg +0 -0
- {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/setup.py +0 -0
- {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/tests/test_advanced.py +0 -0
- {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/tests/test_async_task.py +0 -0
- {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/tests/test_cli_parser.py +0 -0
- {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/tests/test_cli_workflow.py +0 -0
- {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/tests/test_double_tracing.py +0 -0
- {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/tests/test_exception.py +0 -0
- {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/tests/test_integration.py +0 -0
- {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/tests/test_printing.py +0 -0
- {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/tests/test_production_robustness.py +0 -0
- {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/tests/test_real_world.py +0 -0
- {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/tests/test_recursive_tracing.py +0 -0
- {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/tests/test_runtime_lifecycle.py +0 -0
- {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/tests/test_setup.py +0 -0
- {pyeztrace-0.1.5 → pyeztrace-0.2.0.dev0}/tests/test_tracer.py +0 -0
- {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.
|
|
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
|
|
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
|
|
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 =
|
|
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."""
|