pytraceflow 0.1.0__tar.gz

pytraceflow-0.1.0/MANIFEST.in

@@ -0,0 +1,9 @@
+include LICENSE
+include README.md
+exclude pft*.html
+exclude pft*.json
+exclude jaeger.zip
+recursive-exclude jaeger-bin *
+recursive-exclude __pycache__ *
+recursive-exclude .venv *
+recursive-include samples *.py

pytraceflow-0.1.0/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: pytraceflow
+Version: 0.1.0
+Summary: Post-mortem Python trace profiler that emits JSON plus an HTML viewer and OTLP exporter.
+Author: FlowTrace maintainers
+License: MIT
+Keywords: tracing,profiling,debugging,observability,otlp,jaeger
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: memory
+Requires-Dist: psutil>=5.9; extra == "memory"
+Provides-Extra: otlp
+Requires-Dist: opentelemetry-sdk>=1.22.0; extra == "otlp"
+Requires-Dist: opentelemetry-exporter-otlp>=1.22.0; extra == "otlp"
+Provides-Extra: all
+Requires-Dist: psutil>=5.9; extra == "all"
+Requires-Dist: opentelemetry-sdk>=1.22.0; extra == "all"
+Requires-Dist: opentelemetry-exporter-otlp>=1.22.0; extra == "all"
+Dynamic: license-file
+
+# PyTraceFlow.
+
+[![PyPI](https://img.shields.io/pypi/v/pytraceflow)](https://pypi.org/project/pytraceflow/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg?logo=python)](https://pypi.org/project/pytraceflow/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Status](https://img.shields.io/badge/status-alpha-orange)](#)
+[![Downloads](https://img.shields.io/pypi/dm/pytraceflow?color=blue)](https://pypi.org/project/pytraceflow/)
+
+FlowTrace is a trace visualizer designed as a "post-mortem debugger": instead of pausing and resuming, it captures calls (inputs, outputs, caller, module, duration, errors) into a hierarchical JSON so you can inspect them later without re-running.
+
+![FlowTrace overview](images/pytraceflow.jpg)
+![Call details panel](images/pytraceflow_calls.jpg)
+
+## Quick start (3 steps)
+1. Capture the complex sample to JSON: `python pytraceflow.py -s samples/complex/complex_app.py -o pft_complex.json`
+2. Render the HTML viewer: `python pytraceflow_visual.py -i pft_complex.json -o pft_complex.html`
+![Call details panel](images/pytraceflow_visual.jpg)
+3. Optional export to OTLP/Jaeger (HTTP 4318): `python export_otlp.py -i pft_complex.json --endpoint http://localhost:4318/v1/traces --service pytraceflow-complex`
+![Call details panel](images/pytraceflow_to_otlp_menu.jpg)
+![Call details panel](images/pytraceflow_to_otlp_spans.jpg)
+## Basic flow
+1. Profile a script: `python pytraceflow.py -s your_script.py -o pft.json`
+2. Generate the viewer: `python pytraceflow_visual.py -i pft.json -o pft.html`
+3. Open `pft.html` and browse:
+   - Search terms: opens the matching node in a floating panel.
+   - Expand/collapse nodes; open calls.
+   - Controls to show/hide badges, Python internals, language (es/en), and light/dark mode.
+
+### Passing script arguments
+- Any arguments unknown to `pytraceflow.py` are forwarded to the profiled script (no `--` separator required).
+- Example with options: `python pytraceflow.py -s samples/basic/basic_sample.py --customer "ana maria" --tier gold --coffee 3`
+- Example with positionals: `python pytraceflow.py -s samples/basic/basic_positional_sample.py "juan perez" silver 1 2 0 0.18`
+
+## Features
+- Captures inputs/outputs, caller, module, duration, and errors.
+- Groups instances and nested calls while preserving hierarchy.
+- Search with highlighting and floating panels; option to hide Python internals.
+- Dark mode by default, quick controls, and multi-language.
+- Performance knobs: `--flush-interval` (seconds, <=0 disables background flush), `--flush-every-call` (legacy, slower), `--log-flushes` (stderr).
+- Overhead controls: memoria desactivada por defecto; habilita con `--with-memory` (usa psutil + tracemalloc), o combina `--no-tracemalloc` / `--no-memory`. `--skip-inputs` evita serializar args/kwargs.
+- Root entry now records total runtime; STDERR line: `[FlowTrace] Profiling finished in X.XXXs (script=...)`.
+- Export existing traces to OTLP/Jaeger via `export_otlp.py`, with span names enriched by module and instance id to make nested calls distinct in Jaeger UI.
+
+## CLI options
+- `-s/--script` (required): target script path.
+- `-o/--output`: JSON output path (default `pft.json`).
+- `--flush-interval`: seconds between background flushes; `<=0` disables thread (default `1.0`).
+- `--flush-every-call`: force flush on every event (slow; legacy).
+- `--log-flushes`: log each flush to stderr.
+- `--with-memory`: enable memory snapshots (psutil + tracemalloc). Default is off; expect slower runs when enabled.
+- `--no-memory`: disable memory snapshots.
+- `--no-tracemalloc`: keep psutil but skip tracemalloc.
+- `--skip-inputs`: do not serialize call inputs/outputs.
+- OTLP export (optional, requires `opentelemetry-*`): `--export-otlp-endpoint http://localhost:4318/v1/traces`, `--export-otlp-service myapp`, repeat `--export-otlp-header key=value` for extra headers.
+- Any other args are forwarded to the profiled script.
+
+### Usage examples
+- Default fast run: `python pytraceflow.py -s samples/basic/basic_sample.py -o pft.json`
+- With memory metrics: `python pytraceflow.py -s samples/basic/basic_sample.py --with-memory --flush-interval 2.0`
+- Minimal overhead: `python pytraceflow.py -s samples/basic/basic_sample.py --flush-interval 0 --skip-inputs`
+- Legacy per-call flush with logs: `python pytraceflow.py -s samples/basic/basic_sample.py --flush-every-call --log-flushes`
+- Memory via psutil only: `python pytraceflow.py -s samples/basic/basic_sample.py --with-memory --no-tracemalloc`
+- Export to OTLP/HTTP: `python pytraceflow.py -s samples/basic/basic_sample.py --export-otlp-endpoint http://localhost:4318/v1/traces --export-otlp-service pytraceflow-sample`
+- Export a saved trace to Jaeger (OTLP/HTTP, port 4318): `python export_otlp.py -i pft.json --endpoint http://localhost:4318/v1/traces --service pytraceflow-sample`
+- Export with custom headers (auth/tenant): `python export_otlp.py -i pft.json --endpoint http://localhost:4318/v1/traces --service pytraceflow-sample --header Authorization=Bearer_TOKEN --header X-Tenant=acme`
+
+## Included examples
+- `script.py` basic example.
+- `complex_app.py` with modules `demo/...` (prices, taxes, discounts).
+- `conc_demo.py` with CPU-bound (multiprocessing) and IO-bound (threads) to view concurrent traces.
+- `basic_positional_sample.py` shows the same flow using positional arguments.
+- `error_sample.py` intentionally fails (missing config) to show the error badge.
+
+## Backlog / ideas
+- Filters by module/class/time.
+- Export filtered views.
+
+## License
+MIT License. See `LICENSE` for full text.
+
+---
+
+FlowTrace es un visualizador de trazas de ejecucion, pensado como un "debugger post-mortem": en lugar de parar y reanudar, captura las llamadas (inputs, outputs, caller, modulo, duracion, errores) en un JSON jerarquico para inspeccionarlo despues sin reejecutar.
+
+![Vista general de FlowTrace](images/pytraceflow.jpg)
+![Panel de detalle de llamadas](images/pytraceflow_calls.jpg)
+
+## Inicio rápido (3 pasos)
+1. Capturar el ejemplo complejo a JSON: `python pytraceflow.py -s samples/complex/complex_app.py -o pft_complex.json`
+2. Generar el visor HTML: `python pytraceflow_visual.py -i pft_complex.json -o pft_complex.html`
+![Panel visual de llamadas](images/pytraceflow_visual.jpg)
+3. Exportar a OTLP/Jaeger (HTTP 4318): `python export_otlp.py -i pft_complex.json --endpoint http://localhost:4318/v1/traces --service pytraceflow-complex`
+![Menu de exportacion a OTLP/Jaeger](images/pytraceflow_to_otlp_menu.jpg)
+![Spans exportados a Jaeger](images/pytraceflow_to_otlp_spans.jpg)
+
+## Flujo basico
+1. Perfilar un script: `python pytraceflow.py -s tu_script.py -o pft.json`
+2. Generar visor: `python pytraceflow_visual.py -i pft.json -o pft.html`
+3. Abrir `pft.html` y navegar:
+   - Buscar trminos: abre el nodo coincidente en panel flotante.
+   - Expandir/colapsar nodos; abrir calls.
+   - Controles para mostrar/ocultar badges, internals de Python, idioma (es/en) y modo claro/oscuro.
+
+### Pasar argumentos al script
+- Cualquier argumento que `pytraceflow.py` no reconoce se reenvia al script perfilado (no hace falta `--`).
+- Ejemplo con opciones: `python pytraceflow.py -s samples/basic/basic_sample.py --customer "ana maria" --tier gold --coffee 3`
+- Ejemplo con posicionales: `python pytraceflow.py -s samples/basic/basic_positional_sample.py "juan perez" silver 1 2 0 0.18`
+
+## Caracteristicas
+- Captura inputs/outputs, caller, modulo, duracion y errores.
+- Agrupa instancias y llamadas anidadas preservando jerarquia.
+- Buscador con resaltado y paneles flotantes; opcion para ocultar internals de Python.
+- Modo oscuro por defecto, controles rapidos y multilenguaje.
+- Ajustes de performance: `--flush-interval` (segundos, <=0 desactiva flush en background), `--flush-every-call` (modo anterior, mas lento), `--log-flushes` (stderr).
+- Controles de overhead: memoria viene desactivada por defecto; `--with-memory` la habilita (psutil + tracemalloc), combinable con `--no-tracemalloc` / `--no-memory`. `--skip-inputs` evita serializar args/kwargs.
+- La llamada raiz registra el tiempo total; se imprime en STDERR `[FlowTrace] Profiling finished in X.XXXs (script=...)`.
+- Export de trazas existentes a OTLP/Jaeger con `export_otlp.py`; los spans incluyen módulo e id de instancia para distinguir llamadas anidadas en Jaeger.
+
+## Opciones CLI
+- `-s/--script` (obligatorio): ruta del script a perfilar.
+- `-o/--output`: ruta del JSON de salida (por defecto `pft.json`).
+- `--flush-interval`: segundos entre flushes en background; `<=0` desactiva el hilo (por defecto `1.0`).
+- `--flush-every-call`: fuerza flush en cada evento (lento; legado).
+- `--log-flushes`: loguea cada flush a stderr.
+- `--with-memory`: habilita snapshots de memoria (psutil + tracemalloc). Por defecto está apagado; al activarlo las ejecuciones serán más lentas.
+- `--no-memory`: desactiva snapshots de memoria.
+- `--no-tracemalloc`: deja psutil pero omite tracemalloc.
+- `--skip-inputs`: no serializa inputs/outputs de las llamadas.
+- Export OTLP (opcional, requiere `opentelemetry-*`): `--export-otlp-endpoint http://localhost:4318/v1/traces`, `--export-otlp-service miapp`, headers extra con `--export-otlp-header clave=valor` (repetible).
+- Cualquier otro argumento se reenvía al script perfilado.
+
+### Ejemplos de uso
+- Ejecución rápida por defecto: `python pytraceflow.py -s samples/basic/basic_sample.py -o pft.json`
+- Con métricas de memoria: `python pytraceflow.py -s samples/basic/basic_sample.py --with-memory --flush-interval 2.0`
+- Overhead mínimo: `python pytraceflow.py -s samples/basic/basic_sample.py --flush-interval 0 --skip-inputs`
+- Flush por llamada con logs: `python pytraceflow.py -s samples/basic/basic_sample.py --flush-every-call --log-flushes`
+- Solo psutil (sin tracemalloc): `python pytraceflow.py -s samples/basic/basic_sample.py --with-memory --no-tracemalloc`
+- Export a OTLP/HTTP: `python pytraceflow.py -s samples/basic/basic_sample.py --export-otlp-endpoint http://localhost:4318/v1/traces --export-otlp-service pytraceflow-sample`
+- Exportar un JSON ya capturado a Jaeger (OTLP/HTTP, puerto 4318): `python export_otlp.py -i pft.json --endpoint http://localhost:4318/v1/traces --service pytraceflow-sample`
+- Exportar con cabeceras extra (auth/tenant): `python export_otlp.py -i pft.json --endpoint http://localhost:4318/v1/traces --service pytraceflow-sample --header Authorization=Bearer_TOKEN --header X-Tenant=acme`
+
+## Ejemplos incluidos
+- `script.py` ejemplo basico.
+- `complex_app.py` con modulos `demo/...` (precios, impuestos, descuentos).
+- `conc_demo.py` con CPU-bound (multiproceso) e IO-bound (hilos) para ver trazas concurrentes.
+- `basic_positional_sample.py` muestra el mismo flujo usando argumentos posicionales.
+- `error_sample.py` falla adrede (config faltante) para ver el badge de error.
+- `error_internal_sample.py` falla dentro de una llamada interna (`validate_config`) para ver errores anidados.
+
+## Pendientes / ideas
+- Filtros por mdulo/clase/tiempo.
+- Export de vistas filtradas.
+- Integracin con spans/telemetra.
+
+## Licencia
+MIT License. Ver `LICENSE` para el texto completo.
+

pytraceflow-0.1.0/README.md

@@ -0,0 +1,157 @@
+# PyTraceFlow.
+
+[![PyPI](https://img.shields.io/pypi/v/pytraceflow)](https://pypi.org/project/pytraceflow/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg?logo=python)](https://pypi.org/project/pytraceflow/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Status](https://img.shields.io/badge/status-alpha-orange)](#)
+[![Downloads](https://img.shields.io/pypi/dm/pytraceflow?color=blue)](https://pypi.org/project/pytraceflow/)
+
+FlowTrace is a trace visualizer designed as a "post-mortem debugger": instead of pausing and resuming, it captures calls (inputs, outputs, caller, module, duration, errors) into a hierarchical JSON so you can inspect them later without re-running.
+
+![FlowTrace overview](images/pytraceflow.jpg)
+![Call details panel](images/pytraceflow_calls.jpg)
+
+## Quick start (3 steps)
+1. Capture the complex sample to JSON: `python pytraceflow.py -s samples/complex/complex_app.py -o pft_complex.json`
+2. Render the HTML viewer: `python pytraceflow_visual.py -i pft_complex.json -o pft_complex.html`
+![Call details panel](images/pytraceflow_visual.jpg)
+3. Optional export to OTLP/Jaeger (HTTP 4318): `python export_otlp.py -i pft_complex.json --endpoint http://localhost:4318/v1/traces --service pytraceflow-complex`
+![Call details panel](images/pytraceflow_to_otlp_menu.jpg)
+![Call details panel](images/pytraceflow_to_otlp_spans.jpg)
+## Basic flow
+1. Profile a script: `python pytraceflow.py -s your_script.py -o pft.json`
+2. Generate the viewer: `python pytraceflow_visual.py -i pft.json -o pft.html`
+3. Open `pft.html` and browse:
+   - Search terms: opens the matching node in a floating panel.
+   - Expand/collapse nodes; open calls.
+   - Controls to show/hide badges, Python internals, language (es/en), and light/dark mode.
+
+### Passing script arguments
+- Any arguments unknown to `pytraceflow.py` are forwarded to the profiled script (no `--` separator required).
+- Example with options: `python pytraceflow.py -s samples/basic/basic_sample.py --customer "ana maria" --tier gold --coffee 3`
+- Example with positionals: `python pytraceflow.py -s samples/basic/basic_positional_sample.py "juan perez" silver 1 2 0 0.18`
+
+## Features
+- Captures inputs/outputs, caller, module, duration, and errors.
+- Groups instances and nested calls while preserving hierarchy.
+- Search with highlighting and floating panels; option to hide Python internals.
+- Dark mode by default, quick controls, and multi-language.
+- Performance knobs: `--flush-interval` (seconds, <=0 disables background flush), `--flush-every-call` (legacy, slower), `--log-flushes` (stderr).
+- Overhead controls: memoria desactivada por defecto; habilita con `--with-memory` (usa psutil + tracemalloc), o combina `--no-tracemalloc` / `--no-memory`. `--skip-inputs` evita serializar args/kwargs.
+- Root entry now records total runtime; STDERR line: `[FlowTrace] Profiling finished in X.XXXs (script=...)`.
+- Export existing traces to OTLP/Jaeger via `export_otlp.py`, with span names enriched by module and instance id to make nested calls distinct in Jaeger UI.
+
+## CLI options
+- `-s/--script` (required): target script path.
+- `-o/--output`: JSON output path (default `pft.json`).
+- `--flush-interval`: seconds between background flushes; `<=0` disables thread (default `1.0`).
+- `--flush-every-call`: force flush on every event (slow; legacy).
+- `--log-flushes`: log each flush to stderr.
+- `--with-memory`: enable memory snapshots (psutil + tracemalloc). Default is off; expect slower runs when enabled.
+- `--no-memory`: disable memory snapshots.
+- `--no-tracemalloc`: keep psutil but skip tracemalloc.
+- `--skip-inputs`: do not serialize call inputs/outputs.
+- OTLP export (optional, requires `opentelemetry-*`): `--export-otlp-endpoint http://localhost:4318/v1/traces`, `--export-otlp-service myapp`, repeat `--export-otlp-header key=value` for extra headers.
+- Any other args are forwarded to the profiled script.
+
+### Usage examples
+- Default fast run: `python pytraceflow.py -s samples/basic/basic_sample.py -o pft.json`
+- With memory metrics: `python pytraceflow.py -s samples/basic/basic_sample.py --with-memory --flush-interval 2.0`
+- Minimal overhead: `python pytraceflow.py -s samples/basic/basic_sample.py --flush-interval 0 --skip-inputs`
+- Legacy per-call flush with logs: `python pytraceflow.py -s samples/basic/basic_sample.py --flush-every-call --log-flushes`
+- Memory via psutil only: `python pytraceflow.py -s samples/basic/basic_sample.py --with-memory --no-tracemalloc`
+- Export to OTLP/HTTP: `python pytraceflow.py -s samples/basic/basic_sample.py --export-otlp-endpoint http://localhost:4318/v1/traces --export-otlp-service pytraceflow-sample`
+- Export a saved trace to Jaeger (OTLP/HTTP, port 4318): `python export_otlp.py -i pft.json --endpoint http://localhost:4318/v1/traces --service pytraceflow-sample`
+- Export with custom headers (auth/tenant): `python export_otlp.py -i pft.json --endpoint http://localhost:4318/v1/traces --service pytraceflow-sample --header Authorization=Bearer_TOKEN --header X-Tenant=acme`
+
+## Included examples
+- `script.py` basic example.
+- `complex_app.py` with modules `demo/...` (prices, taxes, discounts).
+- `conc_demo.py` with CPU-bound (multiprocessing) and IO-bound (threads) to view concurrent traces.
+- `basic_positional_sample.py` shows the same flow using positional arguments.
+- `error_sample.py` intentionally fails (missing config) to show the error badge.
+
+## Backlog / ideas
+- Filters by module/class/time.
+- Export filtered views.
+
+## License
+MIT License. See `LICENSE` for full text.
+
+---
+
+FlowTrace es un visualizador de trazas de ejecucion, pensado como un "debugger post-mortem": en lugar de parar y reanudar, captura las llamadas (inputs, outputs, caller, modulo, duracion, errores) en un JSON jerarquico para inspeccionarlo despues sin reejecutar.
+
+![Vista general de FlowTrace](images/pytraceflow.jpg)
+![Panel de detalle de llamadas](images/pytraceflow_calls.jpg)
+
+## Inicio rápido (3 pasos)
+1. Capturar el ejemplo complejo a JSON: `python pytraceflow.py -s samples/complex/complex_app.py -o pft_complex.json`
+2. Generar el visor HTML: `python pytraceflow_visual.py -i pft_complex.json -o pft_complex.html`
+![Panel visual de llamadas](images/pytraceflow_visual.jpg)
+3. Exportar a OTLP/Jaeger (HTTP 4318): `python export_otlp.py -i pft_complex.json --endpoint http://localhost:4318/v1/traces --service pytraceflow-complex`
+![Menu de exportacion a OTLP/Jaeger](images/pytraceflow_to_otlp_menu.jpg)
+![Spans exportados a Jaeger](images/pytraceflow_to_otlp_spans.jpg)
+
+## Flujo basico
+1. Perfilar un script: `python pytraceflow.py -s tu_script.py -o pft.json`
+2. Generar visor: `python pytraceflow_visual.py -i pft.json -o pft.html`
+3. Abrir `pft.html` y navegar:
+   - Buscar trminos: abre el nodo coincidente en panel flotante.
+   - Expandir/colapsar nodos; abrir calls.
+   - Controles para mostrar/ocultar badges, internals de Python, idioma (es/en) y modo claro/oscuro.
+
+### Pasar argumentos al script
+- Cualquier argumento que `pytraceflow.py` no reconoce se reenvia al script perfilado (no hace falta `--`).
+- Ejemplo con opciones: `python pytraceflow.py -s samples/basic/basic_sample.py --customer "ana maria" --tier gold --coffee 3`
+- Ejemplo con posicionales: `python pytraceflow.py -s samples/basic/basic_positional_sample.py "juan perez" silver 1 2 0 0.18`
+
+## Caracteristicas
+- Captura inputs/outputs, caller, modulo, duracion y errores.
+- Agrupa instancias y llamadas anidadas preservando jerarquia.
+- Buscador con resaltado y paneles flotantes; opcion para ocultar internals de Python.
+- Modo oscuro por defecto, controles rapidos y multilenguaje.
+- Ajustes de performance: `--flush-interval` (segundos, <=0 desactiva flush en background), `--flush-every-call` (modo anterior, mas lento), `--log-flushes` (stderr).
+- Controles de overhead: memoria viene desactivada por defecto; `--with-memory` la habilita (psutil + tracemalloc), combinable con `--no-tracemalloc` / `--no-memory`. `--skip-inputs` evita serializar args/kwargs.
+- La llamada raiz registra el tiempo total; se imprime en STDERR `[FlowTrace] Profiling finished in X.XXXs (script=...)`.
+- Export de trazas existentes a OTLP/Jaeger con `export_otlp.py`; los spans incluyen módulo e id de instancia para distinguir llamadas anidadas en Jaeger.
+
+## Opciones CLI
+- `-s/--script` (obligatorio): ruta del script a perfilar.
+- `-o/--output`: ruta del JSON de salida (por defecto `pft.json`).
+- `--flush-interval`: segundos entre flushes en background; `<=0` desactiva el hilo (por defecto `1.0`).
+- `--flush-every-call`: fuerza flush en cada evento (lento; legado).
+- `--log-flushes`: loguea cada flush a stderr.
+- `--with-memory`: habilita snapshots de memoria (psutil + tracemalloc). Por defecto está apagado; al activarlo las ejecuciones serán más lentas.
+- `--no-memory`: desactiva snapshots de memoria.
+- `--no-tracemalloc`: deja psutil pero omite tracemalloc.
+- `--skip-inputs`: no serializa inputs/outputs de las llamadas.
+- Export OTLP (opcional, requiere `opentelemetry-*`): `--export-otlp-endpoint http://localhost:4318/v1/traces`, `--export-otlp-service miapp`, headers extra con `--export-otlp-header clave=valor` (repetible).
+- Cualquier otro argumento se reenvía al script perfilado.
+
+### Ejemplos de uso
+- Ejecución rápida por defecto: `python pytraceflow.py -s samples/basic/basic_sample.py -o pft.json`
+- Con métricas de memoria: `python pytraceflow.py -s samples/basic/basic_sample.py --with-memory --flush-interval 2.0`
+- Overhead mínimo: `python pytraceflow.py -s samples/basic/basic_sample.py --flush-interval 0 --skip-inputs`
+- Flush por llamada con logs: `python pytraceflow.py -s samples/basic/basic_sample.py --flush-every-call --log-flushes`
+- Solo psutil (sin tracemalloc): `python pytraceflow.py -s samples/basic/basic_sample.py --with-memory --no-tracemalloc`
+- Export a OTLP/HTTP: `python pytraceflow.py -s samples/basic/basic_sample.py --export-otlp-endpoint http://localhost:4318/v1/traces --export-otlp-service pytraceflow-sample`
+- Exportar un JSON ya capturado a Jaeger (OTLP/HTTP, puerto 4318): `python export_otlp.py -i pft.json --endpoint http://localhost:4318/v1/traces --service pytraceflow-sample`
+- Exportar con cabeceras extra (auth/tenant): `python export_otlp.py -i pft.json --endpoint http://localhost:4318/v1/traces --service pytraceflow-sample --header Authorization=Bearer_TOKEN --header X-Tenant=acme`
+
+## Ejemplos incluidos
+- `script.py` ejemplo basico.
+- `complex_app.py` con modulos `demo/...` (precios, impuestos, descuentos).
+- `conc_demo.py` con CPU-bound (multiproceso) e IO-bound (hilos) para ver trazas concurrentes.
+- `basic_positional_sample.py` muestra el mismo flujo usando argumentos posicionales.
+- `error_sample.py` falla adrede (config faltante) para ver el badge de error.
+- `error_internal_sample.py` falla dentro de una llamada interna (`validate_config`) para ver errores anidados.
+
+## Pendientes / ideas
+- Filtros por mdulo/clase/tiempo.
+- Export de vistas filtradas.
+- Integracin con spans/telemetra.
+
+## Licencia
+MIT License. Ver `LICENSE` para el texto completo.
+

pytraceflow-0.1.0/export_otlp.py

@@ -0,0 +1,104 @@
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+
+def parse_headers(values: list[str]) -> dict[str, str]:
+    headers: dict[str, str] = {}
+    for h in values:
+        if "=" not in h:
+            sys.stderr.write(f"[export-otlp] Ignoring header '{h}' (expected key=value)\n")
+            continue
+        k, v = h.split("=", 1)
+        headers[k.strip()] = v.strip()
+    return headers
+
+
+def load_root(path: Path) -> dict[str, Any]:
+    with path.open("r", encoding="utf-8") as f:
+        data = json.load(f)
+    if not data or not isinstance(data, list):
+        raise ValueError("Invalid FlowTrace JSON: expected list with root node")
+    return data[0]
+
+
+def emit_tree(tracer, node: dict[str, Any], parent_ctx=None) -> None:
+    from opentelemetry import trace
+    from opentelemetry.trace import Status, StatusCode
+
+    callable_name = node.get("callable")
+    called_name = node.get("called")
+
+    if callable_name and called_name and callable_name != called_name:
+        span_name = f"{called_name}.{callable_name}"
+    else:
+        span_name = callable_name or called_name or "unknown"
+
+    if node.get("module"):
+        span_name = f"{node['module']}::{span_name}"
+    if node.get("instance_id") is not None:
+        span_name += f"#{node['instance_id']}"
+
+    with tracer.start_as_current_span(span_name, context=parent_ctx) as span:
+        span.set_attribute("flowtrace.module", node.get("module", ""))
+        span.set_attribute("flowtrace.called", node.get("called", ""))
+        if node.get("duration_ms") is not None:
+            span.set_attribute("flowtrace.duration_ms", node.get("duration_ms"))
+        if node.get("instance_id") is not None:
+            span.set_attribute("flowtrace.instance_id", node.get("instance_id"))
+        if node.get("inputs"):
+            span.set_attribute("flowtrace.inputs_present", True)
+        if node.get("error"):
+            span.record_exception(Exception(str(node.get("error"))))
+            span.set_status(Status(StatusCode.ERROR))
+        child_ctx = trace.set_span_in_context(span)
+        for child in node.get("calls", []):
+            emit_tree(tracer, child, child_ctx)
+
+
+def export_otlp(json_path: Path, endpoint: str, service_name: str | None, headers: dict[str, str]) -> None:
+    try:
+        from opentelemetry import trace
+        from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+        from opentelemetry.sdk.resources import Resource
+        from opentelemetry.sdk.trace import TracerProvider
+        from opentelemetry.sdk.trace.export import BatchSpanProcessor
+    except Exception as exc:  # pragma: no cover
+        sys.stderr.write(f"[export-otlp] Missing dependency opentelemetry-* ({exc})\n")
+        sys.exit(1)
+
+    root = load_root(json_path)
+    resource = Resource.create({"service.name": service_name or json_path.stem})
+    provider = TracerProvider(resource=resource)
+    exporter = OTLPSpanExporter(endpoint=endpoint, headers=headers)
+    provider.add_span_processor(BatchSpanProcessor(exporter))
+    trace.set_tracer_provider(provider)
+    tracer = trace.get_tracer("flowtrace.exporter")
+
+    try:
+        emit_tree(tracer, root)
+    finally:
+        provider.shutdown()
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Export FlowTrace JSON to OTLP/HTTP")
+    parser.add_argument("-i", "--input", default="flowtrace.json", help="Path to FlowTrace JSON")
+    parser.add_argument("--endpoint", required=True, help="OTLP/HTTP endpoint (e.g. http://localhost:4318/v1/traces)")
+    parser.add_argument("--service", default=None, help="service.name value (defaults to JSON filename)")
+    parser.add_argument(
+        "--header",
+        action="append",
+        default=[],
+        help="Extra OTLP header key=value (repeatable)",
+    )
+    args = parser.parse_args()
+
+    headers = parse_headers(args.header)
+    export_otlp(Path(args.input), args.endpoint, args.service, headers)
+
+
+if __name__ == "__main__":
+    main()

pytraceflow-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pytraceflow"
+version = "0.1.0"
+description = "Post-mortem Python trace profiler that emits JSON plus an HTML viewer and OTLP exporter."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "FlowTrace maintainers" }]
+keywords = ["tracing", "profiling", "debugging", "observability", "otlp", "jaeger"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Debuggers",
+  "Topic :: System :: Monitoring"
+]
+dependencies = []
+
+[project.optional-dependencies]
+memory = ["psutil>=5.9"]
+otlp = ["opentelemetry-sdk>=1.22.0", "opentelemetry-exporter-otlp>=1.22.0"]
+all = ["psutil>=5.9", "opentelemetry-sdk>=1.22.0", "opentelemetry-exporter-otlp>=1.22.0"]
+
+[project.scripts]
+pytraceflow = "pytraceflow:main"
+pytraceflow-visual = "pytraceflow_visual:main"
+pytraceflow-export-otlp = "export_otlp:main"
+
+[tool.setuptools]
+py-modules = ["pytraceflow", "pytraceflow_visual", "export_otlp"]
+license-files = ["LICENSE"]