{"id":13461653,"url":"https://github.com/gaogaotiantian/viztracer","last_synced_at":"2025-05-13T16:07:08.833Z","repository":{"id":37267638,"uuid":"285134677","full_name":"gaogaotiantian/viztracer","owner":"gaogaotiantian","description":"VizTracer is a low-overhead logging/debugging/profiling tool that can trace and visualize your python code execution.","archived":false,"fork":false,"pushed_at":"2024-10-15T01:22:31.000Z","size":52341,"stargazers_count":5067,"open_issues_count":15,"forks_count":379,"subscribers_count":49,"default_branch":"master","last_synced_at":"2024-10-29T15:12:58.027Z","etag":null,"topics":["debugging","flamegraph","logging","profiling","python","python3","tracer","visualization"],"latest_commit_sha":null,"homepage":"https://viztracer.readthedocs.io/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gaogaotiantian.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"gaogaotiantian"}},"created_at":"2020-08-05T00:29:56.000Z","updated_at":"2024-10-29T14:41:14.000Z","dependencies_parsed_at":"2023-12-20T16:33:03.889Z","dependency_job_id":"d511d112-6f30-49aa-98ee-2d1c0a62b043","html_url":"https://github.com/gaogaotiantian/viztracer","commit_stats":{"total_commits":611,"total_committers":29,"mean_commits":21.06896551724138,"dds":0.08837970540098194,"last_synced_commit":"7822b451606cf801a9a6cef2aeecc2d35d8a84ff"},"previous_names":["gaogaotiantian/codesnap"],"tags_count":82,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gaogaotiantian%2Fviztracer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gaogaotiantian%2Fviztracer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gaogaotiantian%2Fviztracer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gaogaotiantian%2Fviztracer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gaogaotiantian","download_url":"https://codeload.github.com/gaogaotiantian/viztracer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250246746,"owners_count":21398919,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["debugging","flamegraph","logging","profiling","python","python3","tracer","visualization"],"created_at":"2024-07-31T11:00:50.956Z","updated_at":"2025-04-22T13:21:37.019Z","avatar_url":"https://github.com/gaogaotiantian.png","language":"Python","funding_links":["https://github.com/sponsors/gaogaotiantian"],"categories":["Python","Profiling","Software Engineering","语言资源库","Python 程序","Python specific"],"sub_categories":["Python","Curated Python packages","python","网络服务_其他","Ranking/Recommender"],"readme":"# VizTracer\n\n[![build](https://github.com/gaogaotiantian/viztracer/workflows/build/badge.svg)](https://github.com/gaogaotiantian/viztracer/actions?query=workflow%3Abuild)  [![flake8](https://github.com/gaogaotiantian/viztracer/workflows/lint/badge.svg)](https://github.com/gaogaotiantian/viztracer/actions?query=workflow%3ALint)  [![readthedocs](https://img.shields.io/readthedocs/viztracer)](https://viztracer.readthedocs.io/en/stable/)  [![coverage](https://img.shields.io/codecov/c/github/gaogaotiantian/viztracer)](https://codecov.io/gh/gaogaotiantian/viztracer)  [![pypi](https://img.shields.io/pypi/v/viztracer.svg)](https://pypi.org/project/viztracer/)  [![Visual Studio Marketplace Version](https://img.shields.io/visual-studio-marketplace/v/gaogaotiantian.viztracer-vscode?logo=visual-studio)](https://marketplace.visualstudio.com/items?itemName=gaogaotiantian.viztracer-vscode)  [![support-version](https://img.shields.io/pypi/pyversions/viztracer)](https://img.shields.io/pypi/pyversions/viztracer)  [![license](https://img.shields.io/github/license/gaogaotiantian/viztracer)](https://github.com/gaogaotiantian/viztracer/blob/master/LICENSE)  [![commit](https://img.shields.io/github/last-commit/gaogaotiantian/viztracer)](https://github.com/gaogaotiantian/viztracer/commits/master)  [![sponsor](https://img.shields.io/badge/%E2%9D%A4-Sponsor%20me-%23c96198?style=flat\u0026logo=GitHub)](https://github.com/sponsors/gaogaotiantian)\n\nVizTracer is a low-overhead logging/debugging/profiling tool that can trace and visualize your python code execution.\n\nThe front-end UI is powered by [Perfetto](https://perfetto.dev/). **Use \"AWSD\" to zoom/navigate**.\nMore help can be found in \"Support - Controls\".\n\n[![example_img](https://github.com/gaogaotiantian/viztracer/blob/master/img/example.png)](https://github.com/gaogaotiantian/viztracer/blob/master/img/example.png)\n\n\n## Highlights\n\n* Detailed function entry/exit information on timeline with source code\n* Super easy to use, no source code change for most features, no package dependency\n* Low overhead, probably the fastest tracer in the market\n* Supports threading, multiprocessing, subprocess, async and PyTorch\n* Powerful front-end, able to render GB-level trace smoothly\n* Works on Linux/MacOS/Windows\n\n## Install\n\nThe preferred way to install VizTracer is via pip\n\n```sh\npip install viztracer\n```\n\n## Basic Usage\n\n### Command Line\n\n```sh\n# Instead of \"python3 my_script.py arg1 arg2\"\nviztracer my_script.py arg1 arg2\n```\n\n\u003cdetails\u003e\n\n\u003csummary\u003e\nA \u003ccode\u003eresult.json\u003c/code\u003e file will be generated, which you can open with \u003ccode\u003evizviewer\u003c/code\u003e\n\u003c/summary\u003e\n\n```sh\n# You can display all the files in a directory and open them in browser too\nvizviewer ./\n# For very large trace files, try external trace processor\nvizviewer --use_external_processor result.json\n```\n\nvizviewer will host an HTTP server on ``http://localhost:9001``. You can also open your browser and use that address.\n\nIf you do not want vizviewer to open the webbrowser automatically, you can use\n\n```sh\nvizviewer --server_only result.json\n```\n\nIf you just need to bring up the trace report once, and do not want the persistent server, use\n\n```sh\nvizviewer --once result.json\n```\n\n\u003c/details\u003e\n\n```sh\nvizviewer result.json\n```\n\nA [VS Code Extension](https://marketplace.visualstudio.com/items?itemName=gaogaotiantian.viztracer-vscode)\nis available to make your life even easier.\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://github.com/gaogaotiantian/viztracer-vscode/raw/master/assets/demo.gif\" /\u003e\n\u003c/p\u003e\n\n\u003cdetails\u003e\n\n\u003csummary\u003e\nAdd \u003ccode\u003e--open\u003c/code\u003e to open the reports right after tracing\n\u003c/summary\u003e\n\n```sh\nviztracer --open my_script.py arg1 arg2\nviztracer -o result.html --open my_script.py arg1 arg2\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\n\u003csummary\u003e\nmodules and console scripts(like \u003ccode\u003eflask\u003c/code\u003e) are supported as well\n\u003c/summary\u003e\n\n```sh\nviztracer -m your_module\n```\n\n```sh\nviztracer flask run\n```\n\n\u003c/details\u003e\n\n### Inline\n\nYou can also manually start/stop VizTracer in your script as well.\n\n```python\nfrom viztracer import VizTracer\n\ntracer = VizTracer()\ntracer.start()\n# Something happens here\ntracer.stop()\ntracer.save() # also takes output_file as an optional argument\n```\n\nOr, you can do it with ```with``` statement\n\n```python\nwith VizTracer(output_file=\"optional.json\") as tracer:\n    # Something happens here\n```\n\n### Jupyter\n\nIf you are using Jupyter, you can use viztracer cell magics.\n\n```python\n# You need to load the extension first\n%load_ext viztracer\n```\n\n```python\n%%viztracer\n# Your code after\n```\n\nA ``VizTracer Report`` button will appear after the cell and you can click it to view the results\n\n### PyTorch\n\nVizTracer can log native calls and GPU events of PyTorch (based on `torch.profiler`) with\n``--log_torch``.\n\n```python\nwith VizTracer(log_torch=True) as tracer:\n    # Your torch code\n```\n\n```sh\nviztracer --log_torch your_model.py\n```\n\n## Advanced Usage\n\n### Trace Filter\n\nVizTracer can filter out the data you don't want to reduce overhead and keep info of a longer time period before you dump the log.\n\n* [Min Duration](https://viztracer.readthedocs.io/en/stable/filter.html#min-duration)\n* [Max Stack Depth](https://viztracer.readthedocs.io/en/stable/filter.html#max-stack-depth)\n* [Include Files](https://viztracer.readthedocs.io/en/stable/filter.html#include-files)\n* [Exclude Files](https://viztracer.readthedocs.io/en/stable/filter.html#exclude-files)\n* [Ignore C Function](https://viztracer.readthedocs.io/en/stable/filter.html#ignore-c-function)\n* [Sparse Log](https://viztracer.readthedocs.io/en/stable/filter.html#log-sparse)\n\n### Extra Logs without Code Change\n\nVizTracer can log extra information without changing your source code\n\n* [Any Variable/Attribute with RegEx](https://viztracer.readthedocs.io/en/stable/extra_log.html#log-variable)\n* [Function Entry](https://viztracer.readthedocs.io/en/stable/extra_log.html#log-function-entry)\n* [Variables in Specified Function](https://viztracer.readthedocs.io/en/stable/extra_log.html#log-function-execution)\n* [Garbage Collector Operation](https://viztracer.readthedocs.io/en/stable/extra_log.html#log-garbage-collector)\n* [Function Input Arguments](https://viztracer.readthedocs.io/en/stable/extra_log.html#log-function-arguments)\n* [Function Return Value](https://viztracer.readthedocs.io/en/stable/extra_log.html#log-function-return-value)\n* [Audit Events](https://viztracer.readthedocs.io/en/stable/extra_log.html#log-audit)\n* [Raised Exceptions](https://viztracer.readthedocs.io/en/stable/extra_log.html#log-exception)\n\n### Add Custom Event\n\nVizTracer supports inserting custom events while the program is running. This works like a print debug, but you can know when this print happens while looking at trace data.\n\n* [Instant Event](https://viztracer.readthedocs.io/en/stable/custom_event_intro.html#instant-event)\n* [Variable Event](https://viztracer.readthedocs.io/en/stable/custom_event_intro.html#variable-event)\n* [Duration Event](https://viztracer.readthedocs.io/en/stable/custom_event_intro.html#duration-event)\n\n## Misc\n\n### Multi Thread Support\n\nFor Python3.12+, VizTracer supports Python-level multi-thread tracing without the need to do any modification to your code.\n\nFor versions before 3.12, VizTracer supports python native ```threading``` module. Just start ```VizTracer``` before you create threads and it will just work.\n\nFor other multi-thread scenarios, you can use ``enable_thread_tracing()`` to notice VizTracer about the thread to trace it.\n\n[![example_img](https://github.com/gaogaotiantian/viztracer/blob/master/img/multithread_example.png)](https://github.com/gaogaotiantian/viztracer/blob/master/img/multithread_example.png)\n\nRefer to [multi thread docs](https://viztracer.readthedocs.io/en/stable/concurrency.html) for details\n\n\n### Multi Process Support\n\nVizTracer supports ```subprocess```, ```multiprocessing```, ```os.fork()```, ```concurrent.futures```, and ```loky``` out of the box.\n\nFor more general multi-process cases, VizTracer can support with some extra steps.\n\n[![example_img](https://github.com/gaogaotiantian/viztracer/blob/master/img/multiprocess_example.png)](https://github.com/gaogaotiantian/viztracer/blob/master/img/multiprocess_example.png)\n\nRefer to [multi process docs](https://viztracer.readthedocs.io/en/stable/concurrency.html) for details\n\n### Async Support\n\nVizTracer supports ```asyncio``` natively, but could enhance the report by using ```--log_async```.\n\n[![example_img](https://github.com/gaogaotiantian/viztracer/blob/master/img/async_example.png)](https://github.com/gaogaotiantian/viztracer/blob/master/img/async_example.png)\n\nRefer to [async docs](https://viztracer.readthedocs.io/en/stable/concurrency.html) for details\n\n### Flamegraph\n\nPerfetto supports native flamegraph, just select slices on the UI and choose \"Slice Flamegraph\".\n\n[![example_img](https://github.com/gaogaotiantian/viztracer/blob/master/img/flamegraph.png)](https://github.com/gaogaotiantian/viztracer/blob/master/img/flamegraph.png)\n\n### Remote attach\n\nVizTracer supports remote attach to an arbitrary Python process to trace it, as long as viztracer is importable\n\nRefer to [remote attach docs](https://viztracer.readthedocs.io/en/stable/remote_attach.html)\n\n### JSON alternative\n\nVizTracer needs to dump the internal data to json format. It is recommended for the users to install ```orjson```, which is much faster than the builtin ```json``` library. VizTracer will try to import ```orjson``` and fall back to the builtin ```json``` library if ```orjson``` does not exist.\n\n## Performance\n\nVizTracer puts in a lot of effort to achieve low overhead. The actual performance impact largely depends on your application.\nFor typical codebases, the overhead is expected to be below 1x. If your code has infrequent function calls,\nthe overhead could be minimal.\n\n\u003cdetails\u003e\n\n\u003csummary\u003e\nDetailed explanation\n\u003c/summary\u003e\n\nThe overhead introduced by VizTracer is basically a fixed amount of time during function entry and exit, so the more time spent on\nfunction entries and exits, the more overhead will be observed. A pure recursive ```fib``` function could suffer 3x-4x overhead\non Python3.11+ (when the Python call is optimized, before that Python call was slower so the overhead ratio would be less).\n\nIn the real life scenario, your code should not spend too much time on function calls (they don't really do anything useful), so\nthe overhead would be much smaller.\n\nMany techniques are applied to minimize the overall overhead during code execution to reduce the inevitable skew introduced by\nVizTracer (the report saving part is not as critical). For example, VizTracer tries to use the CPU timestamp counter instead of\na syscall to get the time when available. On Python 3.12+, VizTracer uses ```sys.monitoring``` which has less overhead than\n```sys.setprofile```. All of the efforts made it observably faster than ```cProfile```, the Python stdlib profiler.\n\nHowever, VizTracer is a tracer, which means it has to record every single function entry and exit, so it can't be as fast as\nthe sampling profilers - they are not the same thing. With the extra overhead, VizTracer provides a lot more information than\nnormal sampling profilers.\n\n\u003c/details\u003e\n\n## Documentation\n\nFor full documentation, please see [https://viztracer.readthedocs.io/en/stable](https://viztracer.readthedocs.io/en/stable)\n\n## Bugs/Requests\n\nPlease send bug reports and feature requests through [github issue tracker](https://github.com/gaogaotiantian/viztracer/issues). VizTracer is currently under development now and it's open to any constructive suggestions.\n\n## License\n\nCopyright 2020-2025 Tian Gao.\n\nDistributed under the terms of the  [Apache 2.0 license](https://github.com/gaogaotiantian/viztracer/blob/master/LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgaogaotiantian%2Fviztracer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgaogaotiantian%2Fviztracer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgaogaotiantian%2Fviztracer/lists"}