{"id":28715,"date":"2020-06-23T10:13:00","date_gmt":"2020-06-23T17:13:00","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/dotnet\/?p=28715"},"modified":"2021-05-20T07:21:02","modified_gmt":"2021-05-20T14:21:02","slug":"introducing-dotnet-monitor","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/dotnet\/introducing-dotnet-monitor\/","title":{"rendered":"Introducing dotnet-monitor, an experimental tool"},"content":{"rendered":"

dotnet-monitor<\/code> is an experimental tool that makes it easier to get access to diagnostics information in a dotnet process.<\/p>\n

When running a dotnet application differences in diverse local and production environments can make collecting diagnostics artifacts (e.g., logs, traces, process dumps) challenging. dotnet-monitor<\/code> aims to simplify the process by exposing a consistent REST API regardless of where your application is run.<\/p>\n

This blog post details how to get started with dotnet-monitor<\/code> and covers the following:<\/p>\n

    \n
  1. How to setup dotnet-monitor<\/code><\/li>\n
  2. What diagnostics artifacts can be collected; and<\/li>\n
  3. How to collect each of the artifacts<\/li>\n<\/ol>\n

    Tour of dotnet-monitor<\/h2>\n

    Setup dotnet-monitor<\/code><\/h3>\n

    dotnet-monitor<\/code> will be made available via two different distribution mechanism:<\/p>\n

      \n
    1. As a .NET Core global tool; and<\/li>\n
    2. As a container image available via the Microsoft Container Registry (MCR)<\/li>\n<\/ol>\n

      The setup instructions for dotnet-monitor<\/code> vary based on the target environment. The following section covers some common environments.<\/p>\n

      In the default configuration dotnet-monitor<\/code> binds to two different groups of URLs. The URLs controlled via the --urls<\/code> parameter (defaults to http:\/\/localhost:52323<\/a>) expose all the collection endpoints. The URLs controlled via the --metricUrls<\/code> parameter (defaults to http:\/\/localhost:52325<\/a>) only expose the \/metrics<\/code> endpoint. Since diagnostics artifacts such as logs, dumps, and traces can leak sensitive information about the application, it is strongly recommended<\/strong> that you do not publicly expose these endpoints.<\/p>\n

      Local Machine<\/h4>\n

      To get started with dotnet-monitor<\/code> locally, you will need to have .NET Core<\/a> installed on your machine. You can then installdotnet-monitor<\/code> as a global tool using the following command:<\/p>\n

      dotnet tool install -g dotnet-monitor --add<\/span>-source<\/span> https:<\/span>\/\/dnceng.pkgs.visualstudio.com<\/span>\/public\/_packaging\/dotnet-tools\/nuget\/v3\/index<\/span>.json --version<\/span> 5.0<\/span>.0<\/span>-preview.*\r\n<\/code><\/pre>\n
      Once installed you can run dotnet-monitor<\/code> via the following command:<\/p>\n
      dotnet monitor <\/span>collect\r\n<\/code><\/pre>\n
      Running in Docker<\/h4>\n
      When consuming dotnet-monitor<\/code> as a container image, it can be pulled from MCR<\/a> using the following command:<\/p>\n
      docker pull mcr.microsoft<\/span>.com<\/span>\/dotnet\/nightly\/monitor:5.0<\/span>.0<\/span>-preview.1\r\n<\/code><\/pre>\n
      Once you have the image pulled locally, you will need to share a volume mount between your application container and dotnet-monitor<\/code> using the following commands:<\/p>\n
      docker volume create diagnosticserver\r\ndocker run -d --rm -p<\/span> 8000<\/span>:80<\/span> -v diagnosticsserver:\/tmp mcr.microsoft<\/span>.com<\/span>\/dotnet\/core\/samples:aspnetapp\r\ndocker run -it --rm -p<\/span> 52323<\/span>:52323<\/span> -v diagnosticsserver:\/tmp mcr.microsoft<\/span>.com<\/span>\/dotnet\/nightly\/monitor:5.0<\/span>.0<\/span>-preview.1 --urls http:\/\/*:52323<\/span>\r\n<\/code><\/pre>\n
      Running in a Kubernetes cluster<\/h4>\n
      When running in a cluster, it is recommend to run the dotnet-monitor<\/code> container as a sidecar alongside your application container in the same pod. The sample Kubernetes manifest below shows how to configure your deployment to include a sidecar container.<\/p>\n
      apiVersion<\/span>: apps\/v1\r\nkind<\/span>: Deployment\r\nmetadata<\/span>:\r\n  name<\/span>: dotnet-hello-world\r\nspec<\/span>:\r\n  replicas<\/span>: 1<\/span>\r\n  selector<\/span>:\r\n    matchLabels<\/span>:\r\n      app<\/span>: dotnet-hello-world\r\n  template<\/span>:\r\n    metadata<\/span>:\r\n      labels<\/span>:\r\n        app<\/span>: dotnet-hello-world\r\n    spec<\/span>:\r\n      volumes<\/span>:\r\n      - name<\/span>: diagnostics\r\n        emptyDir<\/span>: {}\r\n      containers<\/span>:\r\n      - name<\/span>: server\r\n        image<\/span>: mcr.microsoft.com\/dotnet\/core\/samples<\/span>:aspnetapp\r\n        ports<\/span>:\r\n        - containerPort<\/span>: 80<\/span>\r\n        volumeMounts<\/span>:\r\n          - mountPath<\/span>: \/tmp\r\n            name<\/span>: diagnostics\r\n      - name<\/span>: sidecar\r\n        image<\/span>: mcr.microsoft.com\/dotnet\/nightly\/monitor:5.0.0-preview.1\r\n        ports<\/span>:\r\n        - containerPort<\/span>: 52325<\/span>\r\n        # args<\/span>: [\"--urls\"<\/span>, \"http:\/\/*:52323\"<\/span>, \"--metricUrls\"<\/span>, \"http:\/\/*:52325\"<\/span>]\r\n        volumeMounts<\/span>:\r\n          - name<\/span>: diagnostics\r\n            mountPath<\/span>: \/tmp\r\n<\/code><\/pre>\n
      Unlike other target environments, this configuration does not make the diagnostics endpoint available on your host network. You will need to port forward traffic from your host to your target cluster.<\/p>\n
      To do this, obtain the name of the pod you wish to forward traffic to using the kubectl<\/code> command:<\/p>\n
      $ kubectl get pod -l app=dotnet-hello-world\r\nNAME                                 READY   STATUS    RESTARTS   AGE\r\ndotnet-hello-world-dc6f67566-t2dzd   2<\/span>\/2<\/span>     Running   0<\/span>          37<\/span>m\r\n<\/code><\/pre>\n
      Once you have your target pod name, forward traffic using the kubectl port-forward<\/code> command:<\/p>\n
      In PowerShell,<\/p>\n
      PS> $job<\/span> = Start-Job<\/span> -ScriptBlock { kubectl port-forward pods\/dotnet-hello-world-dc6f67566-t2dzd 52323<\/span>:52323<\/span> }\r\n<\/code><\/pre>\n
      In bash,<\/p>\n
      $ kubectl port-forward pods\/dotnet-hello-world-dc6f67566<\/span>-t2dzd 52323:52323<\/span> >\/dev\/null &\r\n<\/code><\/pre>\n
      Once you have started forwarding traffic from your local network to the desired pod, you can make your desired API call. As an example, you can run the following command:<\/p>\n
      In PowerShell,<\/p>\n
      PS> Invoke-RestMethod http:<\/span>\/\/localhost:52323\/processes<\/span>\r\n<\/code><\/pre>\n
      In bash,<\/p>\n
      $ <\/span>curl -s http:<\/span>\/\/localhost:52323\/processes<\/span> | jq\r\n<\/code><\/pre>\n
      Once you have completed collecting the desired diagnostics artifacts, you can stop forwarding traffic into the container using the following command:<\/p>\n
      In PowerShell,<\/p>\n
      PS> Stop-Job<\/span> $job<\/span>\r\nPS> Remove-Job<\/span> $job<\/span>\r\n<\/code><\/pre>\n
      In bash,<\/p>\n
      $ <\/span>pkill kubectl\r\n<\/code><\/pre>\n
      Endpoints<\/h3>\n
      The REST API exposed by dotnet-monitor exposes the following endpoints:<\/p>\n