dotnet-trace
Generated by GPT-5-miniExpansion Funnel Raw 1 → Dedup 0 → NER 0 → Enqueued 0
| dotnet-trace | |
|---|---|
| Name | dotnet-trace |
| Developer | Microsoft |
| Written in | C# |
| Platform | .NET |
| License | MIT License |
| Initial release | 2019 |
| Website | Microsoft Docs |
dotnet-trace
dotnet-trace is a cross-platform command-line tool for collecting performance traces from .NET applications. It integrates with the .NET runtime, the EventPipe infrastructure, and the Diagnostic Tools ecosystem to produce trace artifacts usable by analysis tools such as PerfView, Visual Studio, and Windows Performance Analyzer. dotnet-trace supports production diagnostics scenarios for applications running on servers, containers, cloud platforms like Azure, and developer environments including Windows, macOS, and Linux.
Overview
dotnet-trace is designed to work with the .NET Core and .NET 5+ runtimes and is part of the .NET diagnostics toolset alongside tools like the Diagnostics Server, dotnet-counters, and dotnet-dump. The tool leverages EventPipe, a high-performance in-process tracing mechanism implemented in CoreCLR and Mono, to sample CPU stacks, record runtime events, and capture custom events emitted via EventSource. dotnet-trace produces trace files in the default EventPipe file format (ETL/NETTrace) that are widely consumed by analysis projects and vendors. The project is maintained within the .NET Foundation and receives contributions from teams at Microsoft, external contributors, and performance engineering groups.
Installation and usage
dotnet-trace is distributed as a global .NET tool and as a binary artifact for platforms supported by .NET SDK releases. Typical installation methods include the dotnet tool install command, package managers used by Ubuntu, Fedora, and Homebrew, and binaries shipped in SDK toolsets from Microsoft. Users often obtain the tool as part of the .NET SDK bundle when installing via installers produced by Microsoft or packages curated by Red Hat, Canonical, and other distributors. After installation, developers run dotnet-trace from terminals such as PowerShell, Windows Terminal, macOS Terminal, or Linux consoles, and integrate it into CI pipelines managed by Jenkins, GitHub Actions, GitLab CI, Azure DevOps, and TeamCity.
Trace formats and providers
The primary trace format produced is the EventPipe trace format, compatible with analysis tools that understand ETL and .NET trace semantics. Event providers include runtime providers implemented in CoreCLR, ASP.NET Core diagnostics providers, System.Diagnostics.Tracing EventSource-based providers authored by application teams, and third-party libraries such as Serilog, NLog, and Microsoft.Extensions.Logging when adapted to emit EventSource events. The tool interoperates with profiler interfaces used by Visual Studio Profiler, JetBrains dotTrace, and Redgate ANTS, enabling cross-tool workflows where EventPipe traces are post-processed by PerfView, Windows Performance Analyzer, or the Linux perf infrastructure. Integration with Azure Monitor, Application Insights, and Datadog can be achieved by exporting or ingesting trace artifacts produced by dotnet-trace.
Commands and options
dotnet-trace exposes commands and options to start, collect, and stop tracing sessions, choose providers, set circular buffer sizes, and control sampling frequencies. Common command switches resemble those used by other .NET CLI diagnostics tools and include process identification via PID, process name filters used by system administrators at companies like Microsoft and Google, duration limits used in automated test suites at Facebook and Amazon, and output file path specification familiar to users of Visual Studio, JetBrains, and Red Hat tooling. Options to configure verbosity, provider keywords, and event levels mirror concepts present in EventSource, ETW, and System.Diagnostics. Administrators often combine dotnet-trace with orchestration platforms such as Kubernetes, Docker, and OpenShift to capture traces from containerized workloads.
Common scenarios and examples
Typical scenarios include capturing CPU sampling traces during high-CPU incidents on Linux VMs used by Netflix or server fleets managed by LinkedIn, recording allocation and GC events in ASP.NET Core services deployed to Azure App Service, and tracing startup performance for desktop applications developed by teams at Microsoft or independent ISVs. Example workflows show attaching to a running PID, capturing a fixed-duration trace for postmortem analysis with PerfView, or piping trace files into Visual Studio for timeline analysis. Developers use dotnet-trace in combination with dotnet-counters for lightweight monitoring, dotnet-dump for heap inspection, and diagnostics scenarios supported by teams at Intel, AMD, and Arm when investigating JIT or runtime behavior on different CPU architectures.
Diagnostics and performance considerations
Because dotnet-trace uses EventPipe, its overhead is typically low for sampling workloads but can increase when enabling verbose providers or large buffer sizes. Performance engineers from Microsoft, Oracle, and IBM have documented trade-offs when tracing high-throughput scenarios, noting potential impacts on latency-sensitive systems such as financial trading platforms at Goldman Sachs or market data pipelines at Bloomberg. Best practices include using targeted providers, selecting appropriate sampling intervals, and employing remote collection strategies supported by SSH, WinRM, or Azure Bastion when working with cloud-hosted instances. Security teams at enterprises like SAP and Cisco recommend storing traces securely due to potential inclusion of sensitive telemetry emitted via EventSource.
Limitations and compatibility
dotnet-trace depends on runtime support for EventPipe and diagnostic server protocols present in .NET Core 3.0 and later, .NET 5, .NET 6, and subsequent releases; older .NET Framework versions lack integrated EventPipe support and require alternative tools such as ETW-based profilers or CLRMD-based inspectors. Some features vary across OSes and CLR implementations (CoreCLR vs Mono), and certain providers or event payloads may not be available on all platforms or in trimmed/ready-to-run builds used by Xamarin or Unity. There are known constraints when running under heavy sandboxing used by mobile platforms from Apple and Google, or when container runtimes restrict access to process namespaces in environments orchestrated by Kubernetes or Docker Desktop. Ongoing work in the .NET community and vendors such as GitHub, Red Hat, and Canonical aims to expand compatibility and reduce limitations.