[MUSIC]
>> Hey, I'm Carl from the Dotnet Monitor Team,
and I'm excited to finally share all the stuff that the
team's been working on in this getting started guide.
In this video, will be going over
all the fundamentals of Dotnet
Monitor that you need to know before
getting started from what it even is
and where you can find it to how to set
it up and install it, and then finally
actually using it with an application.
By the end, you have Dotnet Monitor up and running
on your local machine and you'll also have gotten
some experience writing configuration and collecting
artifacts for your application. Let's get started.
Getting started, what is Dotnet Monitor?
Dotnet Monitor is a tool meant to help you capture
diagnostic artifacts for
a target application manually or automatically.
These artifacts can be logs, dumps, GC dumps, traces, or metrics,
all of which can be accessed via
http or through a configured Egress provider.
We'll go more in-depth into all of this later, but for now,
let's jump right in and get our hands on the tool itself.
Before we install the Dotnet Monitor tool,
let's take a look at the GitHub repository.
Here, you'll find all of the source code for
the project as well as documentation,
licensing information, and the issues list
where you can file bug reports and feature requests.
Dotnet Monitor is currently under active development,
so this repository will continue to change with
future updates as new features are introduced.
To install Dotnet Monitor locally,
you can run the following installation command.
If you already have Dotnet Monitor installed,
you can use the Update command to get the latest version.
Dotnet Monitor is also available as
a container image via Microsoft Container Registry,
but for now, we're just going to install it as a Dotnet tool.
Once you have Dotnet Monitor installed,
let's check the help to see what commands are available.
This provides some basic usage information as well as
the three commands that form the basis of Dotnet Monitor;
collect, config, and generate key.
Let's run the generic key command to get
an API key that we can use for authentication.
Though Dotnet Monitor can be run without
authentication by using the no auth flag,
you should only disable authentication once you have
evaluated and mitigated the security implications of doing so.
Now that we have our API key,
let's go ahead and add it to our configuration.
Dotnet Monitor has four configuration sources;
command line parameters, user settings,
shared settings, and environment variables.
For now, let's add authentication into the user settings JSON file,
which can be found at the following locations
depending on your operating system.
We'll dedicate some time later to discussing how to configure
Dotnet Monitor depending on your use case but for now,
let's head back over to our shell.
Now that we've updated our configuration,
we can see it by running the config show command.
Our authentication shows up along with some other
default configuration, which means we can finally start up
Dotnet Monitor using the collect command.
Dotnet Monitor is now up and running, which means
we're able to collect artifacts for our target application.
We'll open to a browser now and go Dotnet Monitor's default URL.
Let's start something up that we can use as a target application.
For the purposes of this demo, I'll be using a sample Dotnet 6
application just to keep things simple,
but I'll be making a few adjustments
along the way as we collect artifacts.
Now that we have a basic web app, let's take another look at
what processes Dotnet Monitor is detecting.
This time we can see our process's name
as well as the process ID, and the unique identifier,
and you can use any of these to identify your target process.
Let's do that right now and collect
a dump of our target application.
Taking a look at the documentation for how to collect a dump,
there's three main things to specify;
the process you want to target,
the type of dump you'd like to capture,
and where you'd like the dump to be Egressed.
We'll take our process identifier that we got
in the last step and specify that here is the PID and we'll omit
the dump type and Egress provider fields.
If we kick this off, Dotnet Monitor
will immediately start collecting a dump,
and if we fast forward a few seconds,
we can see our dump show up here.
Let's say that we want to collect another dump,
but this time we want to collect a full dump and we want
to save it to a specific directory on our hard drive.
For this, we'll need to set up an Egress provider,
so let's hop back into our configuration file
where we set up our authentication.
We're going to specify that the Egress provider
we're adding is part of the file system,
later, we'll look at an example where we
Egress using Azure Blob Storage.
We'll specify a name for Egress provider, in this case artifacts,
and then we'll specify the path to this directory.
We save the configuration file,
Dotnet Monitor will automatically grab
those changes without needing to stop and
restart and now we can collect
our new dump with the updated query.
Skip ahead a few seconds and we can
see that the dump was successfully completed.
Let's manually collect one last dump and this
time we're going to Egress to Azure Blob Storage.
Before we update our configuration, first,
we need to make sure we have an Azure storage account
set up correctly with a place to Egress our blobs.
As you can see, I have a container here called
Dotnet Monitor with a folder inside it named Artifacts,
which is where I'll be egressing my dumps.
Hopping over into a configuration,
we'll add a section for Azure Blob Storage with
an Egress and we'll name it monitor Blob.
We'll also need to add our account URI, our container name,
our blob prefix and then a reference to our account key.
Assuming you've set that all up correctly,
we're ready to collect another dump.
Once again, we'll update our query this time
indicating they were Egressing to our Azure storage,
and if we fast forward
a few seconds and look at our storage account,
we can see our dump show up there.
At this point, we've covered
the manual collection of artifacts such as dumps,
but Dotnet Monitor also has the ability to automatically
collect artifacts when a certain set of conditions has been met.
This is made possible through collection rules,
which consists of four main components;
the trigger, the action list, the filter list, and limits.
Let's start out by talking a little bit about triggers.
They trigger monitors for a specific condition in
the target application and will raise
a notification when that condition has been observed.
Currently, there's five different types of triggers,
and more triggers will be added in future Dotnet Monitor releases.
Let's start out by creating
an empty rule and naming it high CPU usage.
You can name this whatever you want,
but it's a good idea to make this descriptive in
the event that you'll be creating multiple collection rules.
Now let's add a trigger to this rule that executes when CPU usage
continuously exceeds a specified value
for a certain period of time.
For the purposes of this demo,
I'll be setting these values relatively
low to ensure that the trigger executes,
and I'll also be making a few tweaks to the sample
web app so that it utilizes the CPU in the background.
The next step is adding actions,
which is where you'll have the opportunity to collect artifacts.
Since we used a dump in the prior example,
this time let's create an action where we collect a trace
whenever a high CPU trigger condition is satisfied.
We could add additional actions here,
but for now we'll keep things simple and only have this one action.
For filters, we can specify which
target process we want to apply this rule to.
For the purposes of this demo, we could probably leave this out,
but let's go ahead and specify the name of our process so that
Dotnet Monitor knows that this condition should
only be triggered for our target application.
Finally, we can add limits to our rule.
This allows us to specify things like how
long the collection rules should be active and
how many times the rule should be allowed to trigger
within the specified sliding window duration.
For our use case, this doesn't matter too much,
but let's go ahead and get a little bit of
practice and plug in a few values here.
At this point, we now have a collection rule,
but we need to make another change to
our configuration before we can get this up and running.
By default, Dotnet Monitor runs in connect mode.
In connect mode, your target application starts up and then
Dotnet Monitor connects to it at some point during its execution.
For collection rules, we want to make
sure that we're in listen mode.
Here, Dotnet processes connect to Dotnet Monitor
allowing it to monitor a process from when it first starts up.
In our configuration file, we can do this by adding a section for
our diagnostic port where we specify our connection mode.
Additionally, you'll need to set an environment
variable in your Dotnet process for this to work,
so I'll go ahead and add this into my sample web app.
Everything should be configured now for our collection rule,
so let's see it in action.
I'll start up Dotnet Monitor
and then the target application, and now
I'll cause the CPU to spike in our target app,
so our collection rule will trigger.
If we give this a few seconds,
we can see that the trace is underway,
and if we fast forward a bit and check our Egress directory,
we can see that our new trace just showed up.
If you have any questions or feedback,
feel free to leave them in our survey
or to create an issue on our GitHub page.
For more information on how to use Dotnet Monitor,
we'll continue adding tutorials to the linked playlist with
more scenarios and new features coming soon. Thanks for watching.
[MUSIC]