Merge main to release/5.0 for preview 6 (#590)

documentation/README.md

@@ -2,7 +2,7 @@
 
 `dotnet monitor` is a tool that makes it easier to get access to diagnostics information in a dotnet process.
 
-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` aims to simplify the process by exposing a consistent HTTP API regardless of where your application is run.
+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` aims to simplify the process by exposing a consistent HTTP API regardless of where your application is run.
 
 ## Table of contents
 
@@ -20,6 +20,7 @@ When running a dotnet application differences in diverse local and production en
     - [`/trace`](./api/trace.md)
     - [`/metrics`](./api/metrics.md)
     - [`/logs`](./api/logs.md)
+    - [`/info`](./api/info.md)
 - [Configuration](./configuration.md)
     - [JSON Schema](./schema.json)
 - [Authentication](./authentication.md)
@@ -29,3 +30,4 @@ When running a dotnet application differences in diverse local and production en
 - [Troubleshooting](./troubleshooting.md)
 - [Clone, build, and test the repo](./building.md)
 - [Official Build Instructions](./official-build-instructions.md)
+- [Release Process](./release-process.md)

documentation/api/README.md

@@ -7,10 +7,11 @@ The following are the root routes on the HTTP API surface.
 | Route | Description |
 |---|---|
 | [`/processes`](processes.md) | Gets detailed information about discoverable processes. |
-| [`/dump`](dump.md) | Captures a managed dumps processes without using a debugger. |
+| [`/dump`](dump.md) | Captures managed dumps of processes without using a debugger. |
 | [`/gcdump`](gcdump.md) | Captures GC dumps of processes. |
 | [`/trace`](trace.md) | Captures traces of processes without using a profiler. |
 | [`/metrics`](metrics.md) | Captures metrics of a process. |
 | [`/logs`](logs.md) | Captures logs of processes. |
+| [`/info`](info.md) | Gets info about Dotnet Monitor. |
 
-The `dotnet monitor` tool is able to detect .NET Core 3.1 and .NET 5+ applications. When connecting to a .NET Core 3.1 application, some information may not be available and is called out in the documentation.
+The `dotnet monitor` tool is able to detect .NET Core 3.1 and .NET 5+ applications. When connecting to a .NET Core 3.1 application, some information may not be available and is called out in the documentation.

documentation/api/defaultprocess.md

@@ -1,5 +1,5 @@
 # Default Process
 
-When using APIs to capture diagnostic artifacts, typically a `pid`, `uid`, or `name` is provided to perform the operation on a specific process. However, these parameters may be omitted if dotnet-monitor is able to resolve a default process.
+When using APIs to capture diagnostic artifacts, typically a `pid`, `uid`, or `name` is provided to perform the operation on a specific process. However, these parameters may be omitted if `dotnet monitor` is able to resolve a default process.
 
-The tool is able to resolve a default process if there is one and only one observable process. If there are no processes or there are more that one process, any API that allows operating on the default process will fail when invoked.
+The tool is able to resolve a default process if there is one and only one observable process. If there are no processes or there are more that one process, any API that allows operating on the default process will fail when invoked.

documentation/api/definitions.md

@@ -1,5 +1,16 @@
 # Definitions
 
+## DotnetMonitorInfo
+
+Object describing diagnostic/automation information about the executing instance of `dotnet monitor`.
+
+| Name | Type | Description |
+|---|---|---|
+| Version | string | The current version of Dotnet-Monitor. |
+| RuntimeVersion | string | The version of the dotnet runtime. |
+| DiagnosticPortMode | DiagnosticPortConnectionMode | Indicates whether `dotnet monitor` is in `connect` mode or `listen` mode. |
+| DiagnosticPortName | string | The name of the named pipe or unix domain socket to use for connecting to the diagnostic server. |
+
 ## DumpType
 
 Enumeration that describes the type of information to capture in a managed dump.

documentation/api/dump.md

@@ -7,25 +7,7 @@ Captures a managed dump of a specified process without using a debugger.
 ## HTTP Route
 
 ```http
-GET /dump/{pid}?type={type}&egressProvider={egressProvider} HTTP/1.1
-```
-
-or 
-
-```http
-GET /dump/{uid}?type={type}&egressProvider={egressProvider} HTTP/1.1
-```
-
-or
-
-```http
-GET /dump/{name}?type={type}&egressProvider={egressProvider} HTTP/1.1
-```
-
-or
-
-```http
-GET /dump?type={type}&egressProvider={egressProvider} HTTP/1.1
+GET /dump?pid={pid}&uid={uid}&name={name}&type={type}&egressProvider={egressProvider} HTTP/1.1
 ```
 
 > **NOTE:** Process information (IDs, names, environment, etc) may change between invocations of these APIs. Processes may start or stop between API invocations, causing this information to change.
@@ -38,9 +20,9 @@ The default host address for these routes is `https://localhost:52323`. This rou
 
 | Name | In | Required | Type | Description |
 |---|---|---|---|---|
-| `pid` | path | false | int | The ID of the process. |
-| `uid` | path | false | guid | A value that uniquely identifies a runtime instance within a process. |
-| `name` | path | false | string | The name of the process. |
+| `pid` | query | false | int | The ID of the process. |
+| `uid` | query | false | guid | A value that uniquely identifies a runtime instance within a process. |
+| `name` | query | false | string | The name of the process. |
 | `type` | query | false | [DumpType](definitions.md#DumpType) | The type of dump to capture. Default value is `WithHeap` |
 | `egressProvider` | query | false | string | If specified, uses the named egress provider for egressing the collected dump. When not specified, the dump is written to the HTTP response stream. See [Egress Providers](../egress.md) for more details. |
 
@@ -70,15 +52,15 @@ Allowed schemes:
 ### Sample Request
 
 ```http
-GET /dump/21632?type=Full HTTP/1.1
+GET /dump?pid=21632&type=Full HTTP/1.1
 Host: localhost:52323
 Authorization: MonitorApiKey fffffffffffffffffffffffffffffffffffffffffff=
 ```
 
 or
 
 ```http
-GET /dump/cd4da319-fa9e-4987-ac4e-e57b2aac248b?type=Full HTTP/1.1
+GET /dump?uid=cd4da319-fa9e-4987-ac4e-e57b2aac248b&type=Full HTTP/1.1
 Host: localhost:52323
 Authorization: MonitorApiKey fffffffffffffffffffffffffffffffffffffffffff=
 ```
@@ -111,4 +93,4 @@ See [Process ID `pid` vs Unique ID `uid`](pidvsuid.md) for clarification on when
 
 ### View the collected dump file
 
-Dump files collected from this route can be analyzed using tools such as [dotnet-dump](https://docs.microsoft.com/dotnet/core/diagnostics/dotnet-dump) or Visual Studio.
+Dump files collected from this route can be analyzed using tools such as [dotnet-dump](https://docs.microsoft.com/dotnet/core/diagnostics/dotnet-dump) or Visual Studio.

documentation/api/gcdump.md

@@ -11,25 +11,7 @@ Captures a GC dump of a specified process. These dumps are useful for several sc
 ## HTTP Route
 
 ```http
-GET /gcdump/{pid}&egressProvider={egressProvider} HTTP/1.1
-```
-
-or 
-
-```http
-GET /gcdump/{uid}&egressProvider={egressProvider} HTTP/1.1
-```
-
-or
-
-```http
-GET /gcdump/{name}&egressProvider={egressProvider} HTTP/1.1
-```
-
-or
-
-```http
-GET /gcdump&egressProvider={egressProvider} HTTP/1.1
+GET /gcdump?pid={pid}&uid={uid}&name={name}&egressProvider={egressProvider} HTTP/1.1
 ```
 
 > **NOTE:** Process information (IDs, names, environment, etc) may change between invocations of these APIs. Processes may start or stop between API invocations, causing this information to change.
@@ -42,9 +24,9 @@ The default host address for these routes is `https://localhost:52323`. This rou
 
 | Name | In | Required | Type | Description |
 |---|---|---|---|---|
-| `pid` | path | false | int | The ID of the process. |
-| `uid` | path | false | guid | A value that uniquely identifies a runtime instance within a process. |
-| `name` | path | false | string | The name of the process. |
+| `pid` | query | false | int | The ID of the process. |
+| `uid` | query | false | guid | A value that uniquely identifies a runtime instance within a process. |
+| `name` | query | false | string | The name of the process. |
 | `egressProvider` | query | false | string | If specified, uses the named egress provider for egressing the collected GC dump. When not specified, the GC dump is written to the HTTP response stream. See [Egress Providers](../egress.md) for more details. |
 
 See [ProcessIdentifier](definitions.md#ProcessIdentifier) for more details about the `pid`, `uid`, and `name` parameters.
@@ -73,15 +55,15 @@ Allowed schemes:
 ### Sample Request
 
 ```http
-GET /gcdump/21632 HTTP/1.1
+GET /gcdump?pid=21632 HTTP/1.1
 Host: localhost:52323
 Authorization: MonitorApiKey fffffffffffffffffffffffffffffffffffffffffff=
 ```
 
 or
 
 ```http
-GET /gcdump/cd4da319-fa9e-4987-ac4e-e57b2aac248b HTTP/1.1
+GET /gcdump?uid=cd4da319-fa9e-4987-ac4e-e57b2aac248b HTTP/1.1
 Host: localhost:52323
 Authorization: MonitorApiKey fffffffffffffffffffffffffffffffffffffffffff=
 ```
@@ -116,4 +98,4 @@ On Windows, `.gcdump` files can be viewed in [PerfView](https://github.com/micro
 
 You can collect multiple `.gcdump`s and open them simultaneously in Visual Studio to get a comparison experience.
 
-Reports can be generated from `.gcdump` files using the [dotnet-gcdump](https://docs.microsoft.com/dotnet/core/diagnostics/dotnet-gcdump) tool.
+Reports can be generated from `.gcdump` files using the [dotnet-gcdump](https://docs.microsoft.com/dotnet/core/diagnostics/dotnet-gcdump) tool.

documentation/api/info.md

@@ -0,0 +1,56 @@
+# Info - Get
+
+Gets information about the `dotnet monitor` version, the runtime version, and the diagnostic port settings.
+
+## HTTP Route
+
+```http
+GET /info HTTP/1.1
+```
+
+## Host Address
+
+The default host address for these routes is `https://localhost:52323`.
+
+## Authentication
+
+Authentication is enforced for this route. See [Authentication](./../authentication.md) for further information.
+
+## Responses
+
+| Name | Type | Description | Content Type |
+|---|---|---|---|
+| 200 OK | | Information about `dotnet monitor` formatted as JSON.  | `application/json` |
+| 400 Bad Request | [ValidationProblemDetails](definitions.md#ValidationProblemDetails) | An error occurred due to invalid input. The response body describes the specific problem(s). | `application/problem+json` |
+| 401 Unauthorized | | Authentication is required to complete the request. See [Authentication](./../authentication.md) for further information. | |
+
+## Examples
+
+### Sample Request
+
+```http
+GET /info HTTP/1.1
+Host: localhost:52323
+```
+
+### Sample Response
+
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+    "version": "5.0.0",
+    "runtimeVersion": "3.1.16",
+    "diagnosticPortMode": "Connect",
+    "diagnosticPortName": null
+}
+```
+
+## Supported Runtimes
+
+| Operating System | Runtime Version |
+|---|---|
+| Windows | .NET Core 3.1, .NET 5+ |
+| Linux | .NET Core 3.1, .NET 5+ |
+| MacOS | .NET Core 3.1, .NET 5+ |

documentation/api/logs-custom.md

@@ -7,25 +7,7 @@ Captures log statements that are logged to the [ILogger<> infrastructure](https:
 ## HTTP Route
 
 ```http
-POST /logs/{pid}?durationSeconds={durationSeconds}&egressProvider={egressProvider} HTTP/1.1
-```
-
-or 
-
-```http
-POST /logs/{uid}?durationSeconds={durationSeconds}&egressProvider={egressProvider} HTTP/1.1
-```
-
-or
-
-```http
-POST /logs/{name}?durationSeconds={durationSeconds}&egressProvider={egressProvider} HTTP/1.1
-```
-
-or
-
-```http
-POST /logs?durationSeconds={durationSeconds}&egressProvider={egressProvider} HTTP/1.1
+POST /logs?pid={pid}&uid={uid}&name={name}&durationSeconds={durationSeconds}&egressProvider={egressProvider} HTTP/1.1
 ```
 
 > **NOTE:** Process information (IDs, names, environment, etc) may change between invocations of these APIs. Processes may start or stop between API invocations, causing this information to change.
@@ -38,9 +20,9 @@ The default host address for these routes is `https://localhost:52323`. This rou
 
 | Name | In | Required | Type | Description |
 |---|---|---|---|---|
-| `pid` | path | false | int | The ID of the process. |
-| `uid` | path | false | guid | A value that uniquely identifies a runtime instance within a process. |
-| `name` | path | false | string | The name of the process. |
+| `pid` | query | false | int | The ID of the process. |
+| `uid` | query | false | guid | A value that uniquely identifies a runtime instance within a process. |
+| `name` | query | false | string | The name of the process. |
 | `durationSeconds` | query | false | int | The duration of the log collection operation in seconds. Default is `30`. Min is `-1` (indefinite duration). Max is `2147483647`. |
 | `egressProvider` | query | false | string | If specified, uses the named egress provider for egressing the collected logs. When not specified, the logs are written to the HTTP response stream. See [Egress Providers](../egress.md) for more details. |
 
@@ -77,7 +59,7 @@ The expected content type is `application/json`.
 ### Sample Request
 
 ```http
-POST /logs/21632?durationSeconds=60 HTTP/1.1
+POST /logs?pid=21632&durationSeconds=60 HTTP/1.1
 Host: localhost:52323
 Authorization: MonitorApiKey fffffffffffffffffffffffffffffffffffffffffff=
 
@@ -93,7 +75,7 @@ Authorization: MonitorApiKey fffffffffffffffffffffffffffffffffffffffffff=
 or
 
 ```http
-POST /logs/cd4da319-fa9e-4987-ac4e-e57b2aac248b?durationSeconds=60 HTTP/1.1
+POST /logs?uid=cd4da319-fa9e-4987-ac4e-e57b2aac248b&durationSeconds=60 HTTP/1.1
 Host: localhost:52323
 Authorization: MonitorApiKey fffffffffffffffffffffffffffffffffffffffffff=
 
@@ -136,4 +118,4 @@ data: => RequestId:0HM8M726ENU3K:0000002B, RequestPath:/, SpanId:|4791a4a7-433aa
 
 ### When to use `pid` vs `uid`
 
-See [Process ID `pid` vs Unique ID `uid`](pidvsuid.md) for clarification on when it is best to use either parameter.
+See [Process ID `pid` vs Unique ID `uid`](pidvsuid.md) for clarification on when it is best to use either parameter.

documentation/api/logs-get.md

@@ -7,25 +7,7 @@ Captures log statements that are logged to the [ILogger<> infrastructure](https:
 ## HTTP Route
 
 ```http
-GET /logs/{pid}?level={level}&durationSeconds={durationSeconds}&egressProvider={egressProvider} HTTP/1.1
-```
-
-or 
-
-```http
-GET /logs/{uid}?level={level}&durationSeconds={durationSeconds}&egressProvider={egressProvider} HTTP/1.1
-```
-
-or
-
-```http
-GET /logs/{name}?level={level}&durationSeconds={durationSeconds}&egressProvider={egressProvider} HTTP/1.1
-```
-
-or
-
-```http
-GET /logs?level={level}&durationSeconds={durationSeconds}&egressProvider={egressProvider} HTTP/1.1
+GET /logs?pid={pid}&uid={uid}&name={name}&level={level}&durationSeconds={durationSeconds}&egressProvider={egressProvider} HTTP/1.1
 ```
 
 > **NOTE:** Process information (IDs, names, environment, etc) may change between invocations of these APIs. Processes may start or stop between API invocations, causing this information to change.
@@ -38,9 +20,9 @@ The default host address for these routes is `https://localhost:52323`. This rou
 
 | Name | In | Required | Type | Description |
 |---|---|---|---|---|
-| `pid` | path | false | int | The ID of the process. |
-| `uid` | path | false | guid | A value that uniquely identifies a runtime instance within a process. |
-| `name` | path | false | string | The name of the process. |
+| `pid` | query | false | int | The ID of the process. |
+| `uid` | query | false | guid | A value that uniquely identifies a runtime instance within a process. |
+| `name` | query | false | string | The name of the process. |
 | `level` | query | false | [LogLevel](definitions.md#LogLevel) | The name of the log level at which log events are collected. If not specified, logs are collected levels as specified by the [application-defined configuration](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/logging/#configure-logging). |
 | `durationSeconds` | query | false | int | The duration of the log collection operation in seconds. Default is `30`. Min is `-1` (indefinite duration). Max is `2147483647`. |
 | `egressProvider` | query | false | string | If specified, uses the named egress provider for egressing the collected logs. When not specified, the logs are written to the HTTP response stream. See [Egress Providers](../egress.md) for more details. |
@@ -72,15 +54,15 @@ Allowed schemes:
 ### Sample Request
 
 ```http
-GET /logs/21632?level=Information&durationSeconds=60 HTTP/1.1
+GET /logs?pid=21632&level=Information&durationSeconds=60 HTTP/1.1
 Host: localhost:52323
 Authorization: MonitorApiKey fffffffffffffffffffffffffffffffffffffffffff=
 ```
 
 or
 
 ```http
-GET /logs/cd4da319-fa9e-4987-ac4e-e57b2aac248b?level=Information&durationSeconds=60 HTTP/1.1
+GET /logs?uid=cd4da319-fa9e-4987-ac4e-e57b2aac248b&level=Information&durationSeconds=60 HTTP/1.1
 Host: localhost:52323
 Authorization: MonitorApiKey fffffffffffffffffffffffffffffffffffffffffff=
 ```
@@ -118,4 +100,4 @@ data: Processing request 0b7ba879-fa80-4eb8-a87d-408f539952ca.
 
 ### When to use `pid` vs `uid`
 
-See [Process ID `pid` vs Unique ID `uid`](pidvsuid.md) for clarification on when it is best to use either parameter.
+See [Process ID `pid` vs Unique ID `uid`](pidvsuid.md) for clarification on when it is best to use either parameter.

documentation/api/metrics.md

@@ -34,7 +34,6 @@ Authentication is not enforced for this route.
 | 200 OK | | A list of metrics for a single process in the Prometheus exposition format. | `text/plain` |
 | 400 Bad Request | [ValidationProblemDetails](definitions.md#ValidationProblemDetails) | An error occurred due to invalid input. The response body describes the specific problem(s). | `application/problem+json` |
 | 401 Unauthorized | | Authentication is required to complete the request. See [Authentication](./../authentication.md) for further information. | |
-| 429 Too Many Requests | | There are too many trace requests at this time. Try to request a trace at a later time. | |
 
 ## Examples