DOCSEARCHbyAlgolia
Submit Docs

.NET Core Diagnostics Tools

repository·main·Indexed 23 days ago

https://github.com/dotnet/diagnostics

Source code and documentation for .NET Core runtime diagnostic tools, including SOS, the LLDB SOS plugin, and CLI utilities such as dotnet-dump, dotnet-trace, dotnet-counters, dotnet-gcdump, and dotnet-symbol. The repository provides guidance on building tools from source, managing symbol servers via SSQP, and diagnosing production scenarios like memory leaks, high CPU, and hung applications.

Tokens
53.6K
Snippets
108
Records
290
Agent score
79%

What's inside dotnet-diagnostics

  1. Overview of .NET Core production diagnostics scenarios

    main

    The .NET Core diagnostics suite provides tools for collecting and analyzing data to identify root causes of production issues. The following diagnostic scenarios are covered in the tutorial series:

    • Memory Leaks: Investigating apps that eventually crash due to memory exhaustion.
    • High CPU/Slow Performance: Analyzing apps that are running slowly or consuming excessive CPU.
    • Intermittent Memory Spikes: Identifying causes of sudden, temporary increases in memory usage.
    • Hung Apps: Diagnosing applications that are not responding to requests.
    • Intermittent Exceptions: Investigating applications experiencing sporadic errors or exceptions.

  2. Overview of .NET Core Diagnostic Tools

    main

    This repository provides the source code and build infrastructure for several key .NET diagnostic utilities:

    • SOS: The managed debugger extension for inspecting the .NET runtime.
    • dotnet-dump: A utility for collecting and analyzing process dumps.
    • dotnet-gcdump: A tool for heap analysis that collects gcdumps from live .NET processes.
    • dotnet-trace: A tool to enable and collect event traces from a running .NET Core application into a local trace file.
    • dotnet-counters: A real-time performance monitoring tool for .NET Core application counters.
    • lldb SOS plugin: An extension for the LLDB debugger to provide SOS capabilities.

  3. Use the Diagnostics Client Library to interact with the .NET runtime

    main

    The Diagnostics Client Library (Microsoft.Diagnostics.NETCore.Client.dll) is a managed library used to interact with the .NET runtime (CoreCLR) via the diagnostics IPC protocol. It allows you to programmatically invoke diagnostics commands, such as starting EventPipe sessions, triggering core dumps, and attaching profilers. It acts as a client to the 'diagnostics server' hosted within the runtime.

    using Microsoft.Diagnostics.NETCore.Client;
// Use DiagnosticsClient to interact with a process
var client = new DiagnosticsClient(processId);

  4. Understand the .NET Core Diagnostics Vision

    main
    The .NET Core diagnostics vision aims to make .NET the most diagnosable and manageable platform for cloud services. The strategy focuses on providing high-fidelity information that helps developers monitor service failures, response times, costs, and security, while ensuring the diagnostic data is actionable and helps identify the correct owner of a problem (e.g., the cloud vendor vs. the application code).

  5. What is SOS and how is it used?

    main

    SOS is a debugger extension designed to inspect the managed state of a .NET Core and desktop runtime process. It allows developers to look into managed memory, stacks, and objects that are otherwise invisible to native debuggers.

    SOS can be loaded into the following debuggers:

    • Windows: WinDbg or cdb
    • Linux and MacOS: lldb

  6. Performance considerations for ProcDump exception monitoring

    main

    ProcDump for Linux monitors exceptions by attaching to the target process using the profiler API. When an exception occurs, the profiler receives a notification and, if the filter criteria are met, uses the .NET diagnostics pipe to instruct the runtime to generate a dump.

    Overhead: Attaching a profiler introduces some performance overhead. However, this overhead is typically minimal unless the application is throwing a very high volume of exceptions.

  7. The role of the .NET Core runtime in diagnostics

    main

    The .NET Core runtime is not responsible for high-level cloud concerns (like billing or geolocation), but it provides the foundational infrastructure for diagnostics through the following roles:

    • Providing Hooks: Enabling detailed logging, traditional debugging, and 'Profiler' hooks to collect information about runtime internals.
    • Exposing Runtime Information: Ensuring all internal runtime metrics and state are exposed via accessible interfaces.
    • Providing Instrumentation Standards: Offering APIs, standards, and guidance for instrumenting code outside the runtime (e.g., traditional logging, lightweight counters, and correlation IDs for semantic grouping like user requests).
    • Library Instrumentation: Using these standards to instrument core .NET Framework libraries.

  8. Security and usage considerations for symbol servers

    main

    The zip package based symbol server is best suited for controlled settings where publishers follow consistent conventions (e.g., a specific project team or a small company).

    Warning: This service does not provide intrinsic trust mechanisms. In unrestricted environments (like worldwide publishing), malicious actors could submit packages with conflicting indexing information, leading to undefined results for SSQP clients. For large-scale use, additional arbitration procedures are recommended.

  9. The relationship between SOS, DAC, and the Runtime

    main

    SOS acts as a bridge between the native debugger (WinDbg) and the managed runtime (CoreCLR). It relies on the Data Access Component (DAC) to inspect the debuggee's memory.

    • DAC (Data Access Component): Provides APIs to read runtime-specific data structures (like ThreadStore or MethodTable) from the debuggee's memory space into the debugger's memory space. It handles the complex marshalling and memory copying required to interpret raw bytes as structured types.
    • SOS (Son of Strike): Uses DAC APIs to perform high-level diagnostic tasks. For example, SOS calls ISOSDacInterface::GetThreadStoreData to get a version-independent view of thread information, which it then uses to locate specific managed threads.
    • Breaking Change Versioning: To prevent SOS from attempting to interpret incompatible runtime structures, SOS uses a SOS_BREAKING_CHANGE_VERSION (retrieved via DAC) to verify compatibility with the current CoreCLR version.

  10. CollectTracing Commands Overview

    main

    The CollectTracing family of commands is used to start EventPipe sessions. These sessions stream event data in the nettrace format. After the runtime responds with a sessionId, the client should continue listening on the transport for the event stream. To stop the stream and receive the final 'run down' metadata, the client must send a StopTracing command.

    Note: If a stream is stopped prematurely due to errors, the resulting nettrace file may be corrupted.

  11. Understand the Diagnostic IPC Protocol flow

    main

    The Diagnostic IPC Protocol is used by external clients to communicate with the .NET runtime's Diagnostics Server.

    General Communication Flow:

    1. Request: The client sends a Diagnostic IPC Message (Header + Payload) to the server.
    2. Response: The server responds with a Diagnostic IPC Message (Header + Payload).
    3. Optional Continuation: After the initial exchange, the client and runtime may reuse the same pipe for command-specific communication (e.g., a continuous stream of trace data). This continuation does not need to follow the standard IPC message format.

    Example (EventPipe):

    • Client sends CollectTracing command with a configuration payload.
    • Server responds with Server OK and a sessionId.
    • Server then sends a continuous stream of nettrace data (Optional Continuation).
    • A StopTracing message is typically sent on a separate connection to end the session.

  12. Use CLRMA interfaces for managed analysis

    main

    The CLRMA contract is composed of several key interfaces used to inspect a crash:

    • ICLRManagedAnalysis: The root interface. It handles setup via ProviderName/AssociateClient and provides access to thread and exception interfaces.
    • ICLRMAClrThread: Provides details for a specific or current managed thread, including the managed stack trace and current exceptions.
    • ICLRMAClrException: Provides details for a specific or current thread's managed exception, including type, message, stack trace, and inner exceptions.
    • ICLRMAObjectInspection: An optional interface used to inspect object fields (e.g., getting the _fileName from a FileNotFoundException) to refine crash bucketing. Note: This is currently not implemented for Native AOT or .NET Core.