search

dotnet / docs

This repository contains .NET Documentation.
https://learn.microsoft.com/dotnet
Creative Commons Attribution 4.0 International
4.17k stars 5.83k forks source link

Missing some documentation for adding arguments to EventPipe using environment variables #37864

Open joshmouch opened 8 months ago

joshmouch commented 8 months ago

Hello,

In this document: docs/core/diagnostics/eventpipe.md there is a section at the end on how to "Trace using environment variables". It mentions using the DOTNET_EventPipeConfig environment variable with the format <provider>:<keyword>:<level>.

However, most useful traces seem to need additional arguments passed to the provider. For example: dotnet trace collect --name SampleApp --providers="Microsoft-Diagnostics-DiagnosticSource:::FilterAndPayloadSpecs=[AS]*" dotnet trace collect --name SampleApp --providers="System.Diagnostics.Metrics:::Metrics=SampleMeter" dotnet trace collect --name SampleApp --providers="Microsoft-Extensions-Logging:2::FilterSpecs=SampleApp*:Information;Microsoft*:Warning"

In other words, there are four values being passed to the provider argument, not three.

If you run any of these from the command line, the resulting trace is as expected. However, if you take that exact provider value and put it into the DOTNET_EventPipeConfig environment variable (along with the DOTNET_EnableEventPipe=1 to enable the tracing) and run any app, tracing does not contain output from those providers.

I believe this is because the arguments are not being passed to the provider. So, either that's not supported, and the documentation should state so or else it's missing the syntax to do so.

Document Details

⚠ Do not edit this section. It is required for learn.microsoft.com ➟ GitHub issue linking.

tommcdon commented 7 months ago

Adding @lateralusX The parsing code for the DOTNET_EventPipeConfig variable is located here: https://github.com/dotnet/runtime/blob/3d1b2543593f0dc3fbbdc2b8cad9b1f8e7554af6/src/native/eventpipe/ep.c#L1041-L1087. When the env variable is in use, we should be calling enable_default_session_via_env_variables which will then call ep_enable_2, which will invoke the above referenced parsing code. With a cursory review of the parsing code it seems that it should be able to correctly handle provider configuration.
@joshmouch do you have a small repro we can use to investigate?

vvuk commented 2 weeks ago

At least one issue here is probably that the original provider strings are using the names of keywords/levels/etc. as well as wildcards, e.g. Microsoft*:Warning. From what I can tell, the code in ep.c can only parse full provider names (unless ep_enable handles wildcards, which I didn't dig into), and integer values -- e.g. 3 instead of Warning.

vvuk commented 2 weeks ago

Additionally -- just noticed -- whereas xperf (and maybe dotnet trace?) allows you to configure the same provider multiple times with different keywords/levels, e.g.: Microsoft-Windows-DotNETRuntime:0x8:4,Microsoft-Windows-DotNETRuntime:0x30:5, the DOTNET_EventPipeConfig parser does not; it seems to take just the first configuration for a provider and ignores all others for it. (e.g. in the above I get Module Load/Unload events, but I don't get MethodLoadVerbose events)