Skip to content

Small reorganization of docs to move logging up to its own topic, and… #35444

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 4 commits into from
Closed

Small reorganization of docs to move logging up to its own topic, and… #35444

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
9352a04
Small reorganization of docs to move logging up to its own topic, and…
May 22, 2023
b157ed7
Update toc.yml
samsp-msft May 23, 2023
5ac1906
Apply suggestions from code review
IEvangelist May 23, 2023
e2b0c72
Apply suggestions from code review
samsp-msft May 23, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 13 additions & 4 deletions docs/core/diagnostics/logging-tracing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,14 @@ ms.date: 4/29/2022
---
# .NET logging and tracing

Code can be instrumented to produce a log, which serves as a record of interesting events that occurred while the program was running. To understand the application's behavior, logs are reviewed. Logging and tracing both encapsulate this technique. .NET has accumulated several different logging APIs over its history and this article will help you understand what options are available.
Code can be instrumented to produce a log, which serves as a record of interesting events that occurred while the program was running. To understand the application's behavior, logs can be reviewed. .NET has accumulated several different logging APIs over its history and this article will help you understand what options are available.

> [!NOTE]
> The term 'tracing' has different meanings and in this article we use to it as a synonym for logging. Historically many developers tended to use 'tracing' when referring to logging that was particularly verbose, used a binary format, or was done as part of performance analysis. More recently 'tracing' has also been adopted as shorthand for [Distributed Tracing](./distributed-tracing.md) - which collects high-level activity & timing data for request based systems, and correlates the requests across services to give a view of how each request is processed by the complete system.

The terms logging and tracing are commonly synonymous, the distinction we usually take is that logging output is expected to be collected all the time, and so should have a low overhead. Tracing is typically more invasive and collects more information from deeper parts of the application and .NET runtime, so is either used when diagnosing specific problems, or automatically for short periods of time as part of deeper performance analysis systems.

Another pivot on the tracing term is [Distributed Tracing](./distributed-tracing.md) - which collects high-level activity & timing data for request based systems, and correlates the requests across services to give a view of how each request is processed by the complete system.

## Key distinctions in logging APIs

Expand All @@ -30,15 +37,17 @@ Most logging APIs allow log messages to be sent to different destinations called

### ILogger

For most cases, whether adding logging to an existing project or creating a new project, the [ILogger](../extensions/logging.md) interface is a good default choice. `ILogger` supports fast structured logging, flexible configuration, and a collection of [common sinks](../extensions/logging-providers.md#built-in-logging-providers). Additionally, the `ILogger` interface can also serve as a facade over many [third party logging implementations](../extensions/logging-providers.md#third-party-logging-providers) that offer more functionality and extensibility.
For most cases, whether adding logging to an existing project or creating a new project, the [ILogger infrastructure](../extensions/logging.md) is a good default choice. `ILogger` supports fast structured logging, flexible configuration, and a collection of [common sinks](../extensions/logging-providers.md#built-in-logging-providers) including the console, which is what you see when running an ASP.NET app. Additionally, the `ILogger` interface can also serve as a facade over many [third party logging implementations](../extensions/logging-providers.md#third-party-logging-providers) that offer more functionality and extensibility.

`ILogger` provides the logging story for the Open Telemetry implementation for .NET, which enables egress of logs from you application to a variety of APM systems for further analysis.

### EventSource

[EventSource](./eventsource.md) is an older high performance structured logging API. It was originally designed to integrate well with [Event Tracing for Windows (ETW)](/windows/win32/etw/event-tracing-portal), but was later extended to support [EventPipe](./eventpipe.md) cross-platform tracing and <xref:System.Diagnostics.Tracing.EventListener> for custom sinks. In comparison to `ILogger`, `EventSource` has relatively few pre-made logging sinks and there is no built-in support to configure via separate configuration files. `EventSource` is excellent if you want tighter control over [ETW](/windows/win32/etw/event-tracing-portal) or [EventPipe](./eventpipe.md) integration, but for general purpose logging, `ILogger` is more flexible and easier to use.
[EventSource](./eventsource.md) is an older high performance tracing API with structured logging. It was originally designed to integrate well with [Event Tracing for Windows (ETW)](/windows/win32/etw/event-tracing-portal), but was later extended to support [EventPipe](./eventpipe.md) cross-platform tracing and <xref:System.Diagnostics.Tracing.EventListener> for custom sinks. In comparison to `ILogger`, `EventSource` has relatively few pre-made logging sinks and there is no built-in support to configure via separate configuration files. `EventSource` is excellent if you want tighter control over [ETW](/windows/win32/etw/event-tracing-portal) or [EventPipe](./eventpipe.md) integration, but for general purpose logging, `ILogger` is more flexible and easier to use.

### Trace

<xref:System.Diagnostics.Trace?displayProperty=nameWithType> and <xref:System.Diagnostics.Debug?displayProperty=nameWithType> are .NET's oldest logging APIs. These classes have flexible configuration APIs and a large ecosystem of sinks, but only support unstructured logging. On .NET Framework they can be configured via an app.config file, but in .NET Core, there's no built-in, file-based configuration mechanism. The .NET team continues to support these APIs for backward-compatibility purposes, but no new functionality will be added. These APIs are a fine choice for applications that are already using them. For newer apps that haven't already committed to a logging API, `ILogger` may offer better functionality.
<xref:System.Diagnostics.Trace?displayProperty=nameWithType> and <xref:System.Diagnostics.Debug?displayProperty=nameWithType> are .NET's oldest logging APIs. These classes have flexible configuration APIs and a large ecosystem of sinks, but only support unstructured logging. On .NET Framework they can be configured via an app.config file, but in .NET Core, there's no built-in, file-based configuration mechanism. A common use-case is producing diagnostics output for the developer while running under the debugger. The .NET team continues to support these APIs for backward-compatibility purposes, but no new functionality will be added. These APIs are a fine choice for applications that are already using them. For newer apps that haven't already committed to a logging API, `ILogger` may offer better functionality.

## Specialized logging APIs

Expand Down
47 changes: 47 additions & 0 deletions docs/core/diagnostics/performance-tracing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
---
title: Performance tracing
description: A guide to tracing in .NET
ms.date: 05/19/2023
---

# Performance tracing overview

Performance tracing is the ability to collect detailed diagnostic information about what is happening inside .NET processes, and includes telemetry information for the Runtime, GC, Libraries and application code.

There are a number of aspects to performance tracing for .NET, including:

## How events are sourced

There are two main mechanisms within .NET for providing events for use with performance tracing:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To the best of my knowledge DiagnosticSource is not often used for performance tracing. The main uses I've seen are APM tools and OpenTelemetry. Occasionally it gets used in combination with DiagnosticSourceEventSource for things like VS profiler database profiling.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we need a better title than just tracing - Event Tracing or Performance & Diagnostics tracing are ideas I had.


| Name | Description |
| --- | --- |
| [EventSource](./eventsource.md) | <xref:System.Diagnostics.Tracing.EventSource?displayProperty=nameWithType> is a fast structured logging solution built into the .NET runtime. On .NET Framework EventSource can send events to [Event Tracing for Windows (ETW)](/windows/win32/etw/event-tracing-portal) and <xref:System.Diagnostics.Tracing.EventListener?displayProperty=nameWithType>. On .NET Core EventSource additionally supports [EventPipe](./eventpipe.md), a cross-platform tracing option. Most often developers use EventSource logs for performance analysis, but EventSource can be used for any diagnostic tasks where logs are useful. The .NET runtime is already instrumented with [built-in events](./well-known-event-providers.md) and you can log your own custom events. |
| [DiagnosticSource](./diagnosticsource-diagnosticlistener.md) | <xref:System.Diagnostics.DiagnosticSource?displayProperty=nameWithType> is a module that allows code to be instrumented for production-time logging of rich data payloads for consumption within the process that was instrumented. At run time, consumers can dynamically discover data sources and subscribe to the ones of interest. <xref:System.Diagnostics.DiagnosticSource?displayProperty=nameWithType> was designed to allow in-process tools to access rich data. DiagnosticSource data can also be egressed via EventPipe enabling rich diagnostic data to be collected by dedicated tools. |

## How events are collected

Events can be collected:

| Mechanism | Description |
| --- | --- |
| In-Process | `EventSource` and `DiagnosticSource` can both be listened to in-process and used by tools such as [Open Telemetry](https://opentelemetry.io/docs/instrumentation/net/) to collect detailed events about features like ASP.NET or HttpClient and then produce metrics based on those events. For example Open Telemetry uses DiagnosticSource to create an [Instumentation Library for ASP.NET](https://github.com/open-telemetry/opentelemetry-dotnet/blob/main/src/OpenTelemetry.Instrumentation.AspNetCore/README.md). |
| Out-of-process | .NET supports rich collection of tracing data via [EventPipe](./eventpipe.md), which can be used by external tools to collect performance tracing data, then can the be analyzed by different tools. |

## Collection tools

The primary collection tools for performance data for .NET are:

| Tool | OS | Description |
| --- | --- | --- |
| [dotnet-trace](./dotnet-trace.md) | All | `dotnet-trace` is a command line tool that will collect traces in the .nettrace format. It can also convert traces to the Chromium or Speedscope formats for viewing. |
| [dotnet-monitor](./dotnet-monitor.md) | All | `dotnet-monitor` is an agent that can be instructed to collect a trace for .NET processes, either by making Web API calls, or by configuring trigger-based rules for CPU or Memory usage thresholds. |
| [Visual Studio](https://learn.microsoft.com/visualstudio/profiling/events-viewer?view=vs-2022) | Windows | Microsoft Visual Studio supports collecting traces for .NET processes as part of the *Performance Profiler* feature. In addition to being able to collect traces, it also can open `.nettrace` traces collected with the other tools in this table. |
| [PerfView](https://github.com/Microsoft/perfview) | Windows | PerfView is a tool for collecting and examining perfomance traces on Windows |
| [PerfCollect](./trace-perfcollect-lttng.md) | Linux | Perfcollect is a collection of scripts that works with the Linux `LTTng` and `perf` tools to collect detailed performance traces for .NET Processes. The resulting traces can be analyzed with a variety of tools include PerfView. |
| [Windows Performance Analyzer](https://learn.microsoft.com/windows-hardware/test/wpt/wpt-getting-started-portal) | Windows | WPA includes a performance recorder and viewer based on the Windows `ETW` event recorder system. It can record a trace of the complete system, including all processes and how they interact with the OS functionality for Networking, Disk IO etc. |

## See also

[Debug high CPU usage](./debug-highcpu.md)
[Collect a performance trace in Linux with PerfCollect](./trace-perfcollect-lttng.md)
10 changes: 7 additions & 3 deletions docs/fundamentals/toc.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -640,6 +640,10 @@ items:
items:
- name: Overview
href: ../core/diagnostics/index.md
- name: Logging and tracing
href: ../core/diagnostics/logging-tracing.md
- name: ILogger logging
href: ../core/extensions/logging.md
- name: Managed debuggers
href: ../core/diagnostics/managed-debuggers.md
- name: Diagnostic port
Expand All @@ -653,11 +657,11 @@ items:
href: ../core/diagnostics/debug-linux-dumps.md
- name: SOS debugger extension
href: ../core/diagnostics/sos-debugging-extension.md
- name: Logging and tracing
- name: Performance tracing
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm fine with the idea that we'd give people some information specifically through a lense of performance tracing, but I don't like that we'd home all of the EventSource, DiagnosticSource, and EventPipe information there. Most DiagnosticSource usage is not performance tracing and EventSource/EventPipe have significant uses that are both performance and non-performance related. To me this organization seems more confusing than before.

Is the goal to highlight ILogger better? What if we just made ILogger first under
logging and tracing?

Logging and Tracing
- ILogger 
- EventSource
  - ...
  - Well-known event providers
  - EventPipe
- DiagnosticSource

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We need to move ILogger out as its the #1 thing that users will use.
Then step back and ask yourself "When are users going to use EventSource or DiagnosticSource?" I would suggest that most of that is going to be for diagnosing performance.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We need to move ILogger out as its the #1 thing that users will use.

If you want to make ILogger extra prominent how about:

- ILogger
- Logging and Tracing
  - ILogger 
  - EventSource
    - ...
    - Well-known event providers
    - EventPipe
  - DiagnosticSource

I don't think making logger prominent requires anything else to be re-arranged.

Then step back and ask yourself "When are users going to use EventSource or DiagnosticSource?" I would suggest that most of that is going to be for diagnosing performance.

If a customer asked me I'd answer:
EventSource - 60% diagnosing performance, 20% functional logging, 20% generic out-of-proc transport for other types of telemetry. Prominent examples of its use for functional logging are OTel SDK and Azure SDK.
DiagnosticSource - 60% APM/distributed tracing, 20% custom in-proc diagnostic tools, 20% performance tracing (when combined with DiagnosticSourceEventSource)

I think characterizing these tools as being primarily for "performance tracing" is simplified for EventSource (I acknowledge there are times where simple is good) and wrong for DiagnosticSource. Saying they are "for diagnosing performance" is a somewhat better fit, but that is a much broader characterization than "performance tracing" which would also include technologies like metrics and distributed tracing too.

Over time I think we are going to see increasing scenario crossover between ILogger and EventSource, not less. For example I'd like to change dotnet-trace so that you can specify ILogger categories as providers and have options for text or binary formats. OpenTelemetry is trying to make EventSource be another API you can use to produce the logging signal. I expect creating a view where logging and performance tracing are treated as very different and APIs should only be thought of as doing one or the other will be an increasingly strained organizational principle over time.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the amount of direct customer usage of EventSource in their code, either emitting or consuming events is going to be minimal - it's going to pretty much be relegated to us as part of the framework/runtime. The interaction that customers will have with EventSource is via a trace, which is most likely to be performance related.

items:
- name: Overview
displayName: logging tracing
href: ../core/diagnostics/logging-tracing.md
displayName: Performance tracing overview
href: ../core/diagnostics/performance-tracing.md
- name: Well-known event providers
href: ../core/diagnostics/well-known-event-providers.md
- name: Event Source
Expand Down