viztracer

VizTracer

VizTracer es una herramienta de registro, depuración y creación de perfiles de bajo costo que puede rastrear y visualizar la ejecución de su código Python.

La interfaz de usuario del front-end funciona con Perfetto. Utilice "AWSD" para hacer zoom/navegar . Puede encontrar más ayuda en "Soporte - Controles".

Reflejos

• Información detallada de entrada/salida de funciones en la línea de tiempo con código fuente
• Súper fácil de usar, sin cambios en el código fuente para la mayoría de las funciones, sin dependencia de paquetes
• Gastos generales reducidos, probablemente el trazador más rápido del mercado
• Admite subprocesos, multiprocesamiento, subprocesos, asíncrono y PyTorch
• Potente interfaz, capaz de representar el seguimiento a nivel de GB sin problemas
• Funciona en Linux/MacOS/Windows

Instalar

La forma preferida de instalar VizTracer es mediante pip

pip install viztracer

Uso básico

Línea de comando

 # Instead of "python3 my_script.py arg1 arg2"
viztracer my_script.py arg1 arg2

Se generará un archivo result.json , que podrá abrir con vizviewer

 # You can display all the files in a directory and open them in browser too
vizviewer ./
# For very large trace files, try external trace processor
vizviewer --use_external_processor result.json

vizviewer alojará un servidor HTTP en http://localhost:9001 . También puedes abrir tu navegador y usar esa dirección.

Si no desea que vizviewer abra el navegador web automáticamente, puede utilizar

vizviewer --server_only result.json

Si sólo necesita abrir el informe de seguimiento una vez y no desea el servidor persistente, utilice

vizviewer --once result.json

vizviewer result.json

Hay disponible una extensión de VS Code para hacerle la vida aún más fácil.

Agregue --open para abrir los informes inmediatamente después del seguimiento

viztracer --open my_script.py arg1 arg2
viztracer -o result.html --open my_script.py arg1 arg2

También se admiten módulos y scripts de consola (como flask ).

viztracer -m your_module

viztracer flask run

En línea

También puede iniciar/detener VizTracer manualmente en su secuencia de comandos.

 from viztracer import VizTracer

tracer = VizTracer ()
tracer . start ()
# Something happens here
tracer . stop ()
tracer . save () # also takes output_file as an optional argument

O puedes hacerlo with una declaración.

 with VizTracer ( output_file = "optional.json" ) as tracer :
    # Something happens here

Jupyter

Si está utilizando Jupyter, puede utilizar magia celular viztracer.

 # You need to load the extension first
% load_ext viztracer 

 % % viztracer
# Your code after

Aparecerá un botón VizTracer Report después de la celda y podrá hacer clic en él para ver los resultados.

PyTorch

VizTracer puede registrar llamadas nativas y eventos de GPU de PyTorch (basado en torch.profiler ) con --log_torch .

 with VizTracer ( log_torch = True ) as tracer :
    # Your torch code 

viztracer --log_torch your_model.py

Uso avanzado

Filtro de seguimiento

VizTracer puede filtrar los datos que no desea para reducir los gastos generales y conservar la información durante un período de tiempo más largo antes de volcar el registro.

• Duración mínima
• Profundidad máxima de apilamiento
• Incluir archivos
• Excluir archivos
• Ignorar la función C
• Registro disperso

Registros adicionales sin cambio de código

VizTracer puede registrar información adicional sin cambiar su código fuente

• Cualquier variable/atributo con RegEx
• Entrada de función
• Variables en función especificada
• Operación del recolector de basura
• Argumentos de entrada de función
• Valor de retorno de la función
• Eventos de auditoría
• Excepciones planteadas

Agregar evento personalizado

VizTracer admite la inserción de eventos personalizados mientras el programa se está ejecutando. Esto funciona como una depuración de impresión, pero puede saber cuándo se produce esta impresión mientras observa los datos de seguimiento.

• Evento instantáneo
• Evento variable
• Duración Evento

Varios

Soporte para múltiples subprocesos

Para Python3.12+, VizTracer admite el seguimiento de subprocesos múltiples a nivel de Python sin la necesidad de realizar ninguna modificación en el código.

Para versiones anteriores a la 3.12, VizTracer admite el módulo threading nativo de Python. Simplemente inicie VizTracer antes de crear subprocesos y funcionará.

Para otros escenarios de subprocesos múltiples, puede usar enable_thread_tracing() para notificar a VizTracer sobre el subproceso para rastrearlo.

Consulte los documentos de varios subprocesos para obtener más detalles.

Soporte multiproceso

VizTracer admite subprocess , multiprocessing , os.fork() , concurrent.futures y loky listos para usar.

Para casos de procesos múltiples más generales, VizTracer puede brindar soporte con algunos pasos adicionales.

Consulte los documentos de procesos múltiples para obtener más detalles.

Soporte asíncrono

VizTracer admite asyncio de forma nativa, pero podría mejorar el informe utilizando --log_async .

Consulte los documentos asíncronos para obtener más detalles.

Flamegrafo

Perfetto admite flamegraph nativo, simplemente seleccione sectores en la interfaz de usuario y elija "Slice Flamegraph".

Conexión remota

VizTracer admite la conexión remota a un proceso Python arbitrario para rastrearlo, siempre que viztracer sea importable

Consulte los documentos de conexión remota

alternativa JSON

VizTracer necesita volcar los datos internos al formato json. Se recomienda a los usuarios instalar orjson , que es mucho más rápido que la biblioteca json incorporada. VizTracer intentará importar orjson y recurrirá a la biblioteca json incorporada si orjson no existe.

Actuación

VizTracer se esfuerza mucho para lograr bajos gastos generales. El impacto real en el rendimiento depende en gran medida de su aplicación. Para las bases de código típicas, se espera que la sobrecarga sea inferior a 1x. Si su código tiene llamadas a funciones poco frecuentes, la sobrecarga podría ser mínima.

Explicación detallada

La sobrecarga introducida por VizTracer es básicamente una cantidad fija de tiempo durante la entrada y salida de la función, por lo que cuanto más tiempo se dedique a la entrada y salida de la función, más sobrecarga se observará. Una función fib recursiva pura podría sufrir una sobrecarga de 3x-4x en Python3.11+ (cuando la llamada de Python está optimizada, antes de esa llamada de Python era más lenta, por lo que la proporción de sobrecarga sería menor).

En el escenario de la vida real, su código no debería dedicar demasiado tiempo a llamadas a funciones (en realidad no hacen nada útil), por lo que la sobrecarga sería mucho menor.

Se aplican muchas técnicas para minimizar la sobrecarga general durante la ejecución del código para reducir el sesgo inevitable introducido por VizTracer (la parte de guardar informes no es tan crítica). Por ejemplo, VizTracer intenta utilizar el contador de marca de tiempo de la CPU en lugar de una llamada al sistema para obtener la hora cuando esté disponible. En Python 3.12+, VizTracer usa sys.monitoring , que tiene menos gastos generales que sys.setprofile . Todos los esfuerzos lo hicieron notablemente más rápido que cProfile , el generador de perfiles stdlib de Python.

Sin embargo, VizTracer es un rastreador, lo que significa que tiene que registrar cada entrada y salida de función, por lo que no puede ser tan rápido como los perfiladores de muestreo: no son lo mismo. Con la sobrecarga adicional, VizTracer proporciona mucha más información que los perfiladores de muestreo normales.

Documentación

Para obtener la documentación completa, consulte https://viztracer.readthedocs.io/en/stable

Errores/Solicitudes

Envíe informes de errores y solicitudes de funciones a través del rastreador de problemas de github. VizTracer se encuentra actualmente en desarrollo y está abierto a cualquier sugerencia constructiva.

Licencia

Copyright 2020-2024 Tian Gao.

Distribuido bajo los términos de la licencia Apache 2.0.