{"id":23302379,"url":"https://github.com/lowleveldesign/wtrace","last_synced_at":"2025-04-04T09:09:39.551Z","repository":{"id":54806351,"uuid":"67476802","full_name":"lowleveldesign/wtrace","owner":"lowleveldesign","description":"Command line tracing tool for Windows, based on ETW.","archived":false,"fork":false,"pushed_at":"2024-01-16T18:40:00.000Z","size":6149,"stargazers_count":678,"open_issues_count":1,"forks_count":52,"subscribers_count":37,"default_branch":"master","last_synced_at":"2025-03-28T08:08:27.597Z","etag":null,"topics":["diagnostics","etw","profiling","strace","trace"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lowleveldesign.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"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}},"created_at":"2016-09-06T05:38:44.000Z","updated_at":"2025-03-24T02:40:54.000Z","dependencies_parsed_at":"2024-01-12T03:36:28.978Z","dependency_job_id":"c64cad82-436b-41df-8f1d-c934a18874fa","html_url":"https://github.com/lowleveldesign/wtrace","commit_stats":{"total_commits":108,"total_committers":5,"mean_commits":21.6,"dds":0.2407407407407407,"last_synced_commit":"4f03f32cc02b03bbbb5f2722a2d112efe9a375f8"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lowleveldesign%2Fwtrace","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lowleveldesign%2Fwtrace/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lowleveldesign%2Fwtrace/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lowleveldesign%2Fwtrace/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lowleveldesign","download_url":"https://codeload.github.com/lowleveldesign/wtrace/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247149502,"owners_count":20891954,"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":["diagnostics","etw","profiling","strace","trace"],"created_at":"2024-12-20T10:28:58.071Z","updated_at":"2025-04-04T09:09:39.534Z","avatar_url":"https://github.com/lowleveldesign.png","language":"C#","readme":"\n# wtrace\n\n![.NET](https://github.com/lowleveldesign/wtrace/workflows/build/badge.svg)\n\n------------------------\n\n**:warning: Some antivirus engines mark wtrace as malware/virus :warning:**\n\nThose are **false-positives**. As you know, wtrace source code is open, and all the officially released binaries are built using GitHub Actions (you may check the workflow in the [release.yml](.github/workflows/release.yml) file). If your antivirus thinks that wtrace is malware, calculate the binary checksum, and if it matches the one on the release page, please report it as false-positive. Thank you!\n\n------------------------\n\n**Table of contents**:\n\n\u003c!-- MarkdownTOC --\u003e\n\n- [Introduction](#introduction)\n- [Installation](#installation)\n- [Tracing targets](#tracing-targets)\n    - [System-only \\(-s\\)](#system-only-s)\n    - [System-wide](#system-wide)\n    - [A single process \\(optionally, with child processes\\)](#a-single-process-optionally-with-child-processes)\n- [Filtering events](#filtering-events)\n- [Event handlers](#event-handlers)\n- [RPC](#rpc)\n- [Error messages](#error-messages)\n    - [WARNING: the session did not finish in the allotted time.](#warning-the-session-did-not-finish-in-the-allotted-time)\n    - [WARNING: … events were lost in the session.](#warning-events-were-lost-in-the-session)\n    - [Other issues](#other-issues)\n- [Thanks](#thanks)\n\n\u003c!-- /MarkdownTOC --\u003e\n\n## Introduction\n\nWtrace [spelled: *wɪtreɪs*] is a command-line tool for recording trace events from the Operating System or a group of processes. Wtrace may collect, among others, **File I/O** and **Registry** operations, **TPC/IP** connections, and **RPC** calls. Its purpose is to give you some insights into what is happening in the system.\n\nAdditionally, it has various **filtering capabilities** and may also dump statistics at the end of the trace session. As it's just a standard command-line tool, you may pipe its output to another tool for further processing.\n\nThe available options are listed below:\n\n```\nUsage: wtrace [OPTIONS] [pid|imagename args]\n\nOptions:\n  -f, --filter=FILTER   Displays only events which satisfy a given FILTER.\n                        (Does not impact the summary)\n  --handlers=HANDLERS   Displays only events coming from the specified HANDLERS.\n  -c, --children        Collects traces from the selected process and all its\n                        children.\n  --newconsole          Starts the process in a new console window.\n  -s, --system          Collect only system statistics (Processes and DPC/ISR)\n                        - shown in the summary.\n  --nosummary           Prints only ETW events - no summary at the end.\n  -v, --verbose         Shows wtrace diagnostics logs.\n  -h, --help            Shows this message and exits.\n\n  The HANDLERS parameter is a list of handler names, separated with a comma.\n\n  Accepted handlers include:\n    process   - only Process/Thread events (this handler is always enabled)\n    file      - File I/O events\n    registry  - Registry events (voluminous, disabled by default)\n    rpc       - RPC events (enable image handler to allow RPC method name resolution)\n    tcp       - TCP/IP events\n    udp       - UDP events\n    image     - image (module) events (load/unload)\n\n  Example: --handlers 'tcp,file,registry'\n\n  Each FILTER is built from a keyword, an operator, and a value. You may\n  define multiple events (filters with the same keywords are OR-ed).\n\n  Keywords include:\n    pid     - filtering on the proces ID\n    pname   - filtering on on the process name\n    name    - filtering on the event name\n    level   - filtering on the event level (1 [critical] - 5 [debug])\n    path    - filtering on the event path\n    details - filtering on the event details\n\n  Operators include:\n    =, \u003c\u003e (does not equal), \u003c= (ends with), \u003e= (starts with), ~ (contains)\n\n  Example: -f 'pid = 1234', -f 'name ~ FileIO', -f 'level \u003c= 4'\n```\n\n## Installation\n\nWtrace works on Windows 8.1+ and requires .NET 4.8.x. It is a **single file** application, and you may download the latest version from the [release page](https://github.com/lowleveldesign/wtrace/releases).\n\nAlternatively, you may install wtrace using [Chocolatey](https://chocolatey.org/):\n\n```\nchoco install wtrace\n```\n\n## Tracing targets\n\nWtrace may trace drivers, all processes in the system, or only a specific process with its children.\n\n### System-only (-s)\n\nThe **-s option** (**system-only**) is a special mode in which wtrace collects statistics of the **ISR/DPC and process events**. It later dumps them at the end of the trace session. It will also show the tree of processes running during the session.\n\n### System-wide\n\nTo trace all processes (**system-wide**), run wtrace with **no arguments**. Tracing system-wide produces lots of events, and if no filtering is applied, there is a risk that wtrace will lose some events. Therefore, I highly recommend setting event filters or limit the number of handles in the system-wide sessions. If you want to trace the system for a longer time, consider adding the **–no-summary** option. This option will turn off the statistics, keeping wtrace memory usage minimum.\n\n```\n# show File write events from all the processes\nwtrace --handlers file -f ‘eventname=FileIO/Write’\n\n# show RPC events from all the processes\nwtrace --handlers rpc\n```\n\n### A single process (optionally, with child processes)\n\nWtrace can either trace a **running process** or start and **trace a new process**. In both scenarios, adding the **-c/--children** option makes wtrace also trace the processes launched by the target process, including their future children.\n\nIf **the first command-line argument is a number**, wtrace assumes that it's a process ID that it should start tracing:\n\n```\n# Trace File I/O operations of the process with id 1234 and its children\nwtrace -f “name \u003e= FileIO/” -c 1234\n```\n\nIf **the command-line argument is not a number**, wtrace tries to start the process with arguments that follow the executable path.\n\n```\n# Start and trace the opening of the test.txt file by notepad.exe\nwtrace notepad c:\\temp\\test.txt\n```\n\n## Filtering events\n\nWe may define an event filter with the **-f/--filter** option. The filter is built from a **keyword**, an **operator**, and a **value**. The **keyword** represents an event field and must be one of the following values:\n\n- **pid** - the process ID (useful in system-wide tracing)\n- **pname** - the process name\n- **name** - the event name\n- **level** - the event level (debug [5], info [4], warning [3], error [2], critical [1])\n- **path** - the event path\n- **details** - the event details\n\nThe **operators** are the same for numeric and text values and include: =, \u003c\u003e, \u003c=, \u003e=, ~. For numbers, the ~ operator has the same effect as the = operator. For text fields, the \u003e= operator returns true if the field value starts with a given text value. Consequently, the \u003c= operator returns true if the field value ends with a given text value. The ~ operator returns true if the field value contains a given text value. The text filters are case-insensitive.\n\nThe **value** part of the filter string is everything that comes after the operator sign, except for white spaces at the beginning and the end of the text value. Therefore, you don't need to use any apostrophes inside the filter text unless you want them to be a part of the text value.\n\nYou may define **multiple filters** for a trace session. Wtrace combines them similarly to Process Monitor, so **filters with the same keyword** are OR-ed together (disjunction). **Filters which keywords differ are AND-ed together** (conjunction). At the start, wtrace will print the parsed filters so you can verify if it's what you expected. Event filters do not affect statistics. If the statistics collection is on (you haven't used the --nosummary flag), you will see the statistics at the end of the session for all the enabled handlers' events (check the Event Handlers section to learn more)\n\n```\n# Trace system-wide and filter events for processes which name \n# is either notepad or notepad2 and the path starts with \"d:\\temp\"\nwtrace -f “pname = notepad” -f “pname = notepad2” -f “path \u003e= d:\\temp”\n```\n\n```\n# Trace a process with id 12572 and its children and show only TCP/IP events\nwtrace -f \"name \u003e= tcp\" -c 12572\n```\n\n## Event handlers\n\nApart from defining filters, we may also specify which handlers wtrace should enable in the session. Handlers are the components responsible for collecting and parsing trace events. Each handler handles a unique set of events. If we disable a handler, none of its events will appear in the live trace output. The statistics built from the handler's events will also be missing. The following handlers are available:\n\n- **process** - for collecting process and thread lifetime events\n- **file** - for collecting File I/O events\n- **registry** - for collecting Windows Registry events (careful, \u003e 1000 events / s)\n- **rpc** - for collecting RPC events\n- **tcp** - for collecting TCP/IP events\n- **udp** - for collecting UDP events\n- **image** - for collecting module load/unload events (this handler is required for RPC endpoint parsing)\n\nBy default, wtrace enables process, image, file, rpc,tcp, and udp handlers for a trace session. Even when tracing system-wide, this set of handlers should not be too voluminous and should not overload the console output. However, if you enable, for example, the registry handler, the number of events might quickly make the console window unusable. Therefore, it's essential to choose the right set of handlers for a session and apply filters, if only possible.\n\n```\n# Trace only registry and tcp events system-wide\nwtrace --handlers registry,tcp\n```\n\n## RPC\n\nWtrace displays the endpoint name, the interface ID, and the procedure index, for example:\n\n```\n14:14:53.3295 firefox (12572.21620) RPC/ClientCallEnd 'fb8a0729-2d04-4658-be93-27b4ad553fac (lsapolicylookup) [5]' -\u003e SUCCESS\n```\n\nThanks to the [NtApiDotNet](https://www.nuget.org/packages/NtApiDotNet) library, wtrace may resolve RPC procedure names in the summary view. To make it work, make sure the image handler is enabled and you have symbols configured for the wtrace session. If you have the `_NT_SYMBOL_PATH` environment variable set (I highly recommend configuring it), wtrace will use it. Otherwise, you need to set debugging symbols path through the `--symbols` parameter, for example:\n\n```\nwtrace.exe --symbols=\"SRV*C:\\symbols\\*https://msdl.microsoft.com/download/symbols\" -v notepad.exe\n```\n\nIf RPC procedure name resolution worked, you should see a procedure name in the curly braces, next to the procedure number:\n\n```\n--------------------------------\n       RPC (client calls)\n--------------------------------\nfb8a0729-2d04-4658-be93-27b4ad553fac (ncalrpc:[lsapolicylookup]) [5]{LsaLookuprGetDomainInfo} calls: 2\n\n```\n\n## Error messages\n\n### WARNING: the session did not finish in the allotted time.\n\nThis warning may indicate a problem with ETW session handling. If it happens, the wtrace ETW session might still be running in your system. You may stop it using the logman tool:\n\n```\nlogman stop wtrace-rt -ets\n```\n\n### WARNING: … events were lost in the session.\n\nThis warning usually indicates that the number of events was too high, and wtrace could not process them. In such a case, add some additional filters to the command line or disable the unneeded handlers.\n\n### Other issues\n\nIf you find an error in wtrace, please [report it on GitHub](https://github.com/lowleveldesign/wtrace/issues), providing the error message and steps to reproduce the problem. Thank you!\n\n## Thanks\n\nI would like to thank the authors of the [TraceEvent](https://github.com/Microsoft/perfview) and [NtApiDotNet](https://github.com/googleprojectzero/sandbox-attacksurface-analysis-tools) libraries. Wtrace would not exist without those libraries.\n","funding_links":[],"categories":["\u003ca id=\"ac43a3ce5a889d8b18cf22acb6c31a72\"\u003e\u003c/a\u003eETW"],"sub_categories":["\u003ca id=\"0af4bd8ca0fd27c9381a2d1fa8b71a1f\"\u003e\u003c/a\u003e工具"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flowleveldesign%2Fwtrace","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flowleveldesign%2Fwtrace","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flowleveldesign%2Fwtrace/lists"}