Skip to content

Commit 9c17149

Browse files
jander-msftjander-msft
authored
Merge main to release/5.0 for preview 6 (#590)
2 parents a99ec90 + 075a442 commit 9c17149

File tree

231 files changed

+9205
-2890
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

231 files changed

+9205
-2890
lines changed

‎documentation/README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
`dotnet monitor` is a tool that makes it easier to get access to diagnostics information in a dotnet process.
44

5-
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.
5+
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.
66

77
## Table of contents
88

@@ -20,6 +20,7 @@ When running a dotnet application differences in diverse local and production en
2020
- [`/trace`](./api/trace.md)
2121
- [`/metrics`](./api/metrics.md)
2222
- [`/logs`](./api/logs.md)
23+
- [`/info`](./api/info.md)
2324
- [Configuration](./configuration.md)
2425
- [JSON Schema](./schema.json)
2526
- [Authentication](./authentication.md)
@@ -29,3 +30,4 @@ When running a dotnet application differences in diverse local and production en
2930
- [Troubleshooting](./troubleshooting.md)
3031
- [Clone, build, and test the repo](./building.md)
3132
- [Official Build Instructions](./official-build-instructions.md)
33+
- [Release Process](./release-process.md)

‎documentation/api/README.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,10 +7,11 @@ The following are the root routes on the HTTP API surface.
77
| Route | Description |
88
|---|---|
99
| [`/processes`](processes.md) | Gets detailed information about discoverable processes. |
10-
| [`/dump`](dump.md) | Captures a managed dumps processes without using a debugger. |
10+
| [`/dump`](dump.md) | Captures managed dumps of processes without using a debugger. |
1111
| [`/gcdump`](gcdump.md) | Captures GC dumps of processes. |
1212
| [`/trace`](trace.md) | Captures traces of processes without using a profiler. |
1313
| [`/metrics`](metrics.md) | Captures metrics of a process. |
1414
| [`/logs`](logs.md) | Captures logs of processes. |
15+
| [`/info`](info.md) | Gets info about Dotnet Monitor. |
1516

16-
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.
17+
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‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
# Default Process
22

3-
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.
3+
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.
44

5-
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.
5+
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‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,16 @@
11
# Definitions
22

3+
## DotnetMonitorInfo
4+
5+
Object describing diagnostic/automation information about the executing instance of `dotnet monitor`.
6+
7+
| Name | Type | Description |
8+
|---|---|---|
9+
| Version | string | The current version of Dotnet-Monitor. |
10+
| RuntimeVersion | string | The version of the dotnet runtime. |
11+
| DiagnosticPortMode | DiagnosticPortConnectionMode | Indicates whether `dotnet monitor` is in `connect` mode or `listen` mode. |
12+
| DiagnosticPortName | string | The name of the named pipe or unix domain socket to use for connecting to the diagnostic server. |
13+
314
## DumpType
415

516
Enumeration that describes the type of information to capture in a managed dump.

‎documentation/api/dump.md‎

Lines changed: 7 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -7,25 +7,7 @@ Captures a managed dump of a specified process without using a debugger.
77
## HTTP Route
88

99
```http
10-
GET /dump/{pid}?type={type}&egressProvider={egressProvider} HTTP/1.1
11-
```
12-
13-
or
14-
15-
```http
16-
GET /dump/{uid}?type={type}&egressProvider={egressProvider} HTTP/1.1
17-
```
18-
19-
or
20-
21-
```http
22-
GET /dump/{name}?type={type}&egressProvider={egressProvider} HTTP/1.1
23-
```
24-
25-
or
26-
27-
```http
28-
GET /dump?type={type}&egressProvider={egressProvider} HTTP/1.1
10+
GET /dump?pid={pid}&uid={uid}&name={name}&type={type}&egressProvider={egressProvider} HTTP/1.1
2911
```
3012

3113
> **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
3820

3921
| Name | In | Required | Type | Description |
4022
|---|---|---|---|---|
41-
| `pid` | path | false | int | The ID of the process. |
42-
| `uid` | path | false | guid | A value that uniquely identifies a runtime instance within a process. |
43-
| `name` | path | false | string | The name of the process. |
23+
| `pid` | query | false | int | The ID of the process. |
24+
| `uid` | query | false | guid | A value that uniquely identifies a runtime instance within a process. |
25+
| `name` | query | false | string | The name of the process. |
4426
| `type` | query | false | [DumpType](definitions.md#DumpType) | The type of dump to capture. Default value is `WithHeap` |
4527
| `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. |
4628

@@ -70,15 +52,15 @@ Allowed schemes:
7052
### Sample Request
7153

7254
```http
73-
GET /dump/21632?type=Full HTTP/1.1
55+
GET /dump?pid=21632&type=Full HTTP/1.1
7456
Host: localhost:52323
7557
Authorization: MonitorApiKey fffffffffffffffffffffffffffffffffffffffffff=
7658
```
7759

7860
or
7961

8062
```http
81-
GET /dump/cd4da319-fa9e-4987-ac4e-e57b2aac248b?type=Full HTTP/1.1
63+
GET /dump?uid=cd4da319-fa9e-4987-ac4e-e57b2aac248b&type=Full HTTP/1.1
8264
Host: localhost:52323
8365
Authorization: MonitorApiKey fffffffffffffffffffffffffffffffffffffffffff=
8466
```
@@ -111,4 +93,4 @@ See [Process ID `pid` vs Unique ID `uid`](pidvsuid.md) for clarification on when
11193

11294
### View the collected dump file
11395

114-
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.
96+
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‎

Lines changed: 7 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -11,25 +11,7 @@ Captures a GC dump of a specified process. These dumps are useful for several sc
1111
## HTTP Route
1212

1313
```http
14-
GET /gcdump/{pid}&egressProvider={egressProvider} HTTP/1.1
15-
```
16-
17-
or
18-
19-
```http
20-
GET /gcdump/{uid}&egressProvider={egressProvider} HTTP/1.1
21-
```
22-
23-
or
24-
25-
```http
26-
GET /gcdump/{name}&egressProvider={egressProvider} HTTP/1.1
27-
```
28-
29-
or
30-
31-
```http
32-
GET /gcdump&egressProvider={egressProvider} HTTP/1.1
14+
GET /gcdump?pid={pid}&uid={uid}&name={name}&egressProvider={egressProvider} HTTP/1.1
3315
```
3416

3517
> **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
4224

4325
| Name | In | Required | Type | Description |
4426
|---|---|---|---|---|
45-
| `pid` | path | false | int | The ID of the process. |
46-
| `uid` | path | false | guid | A value that uniquely identifies a runtime instance within a process. |
47-
| `name` | path | false | string | The name of the process. |
27+
| `pid` | query | false | int | The ID of the process. |
28+
| `uid` | query | false | guid | A value that uniquely identifies a runtime instance within a process. |
29+
| `name` | query | false | string | The name of the process. |
4830
| `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. |
4931

5032
See [ProcessIdentifier](definitions.md#ProcessIdentifier) for more details about the `pid`, `uid`, and `name` parameters.
@@ -73,15 +55,15 @@ Allowed schemes:
7355
### Sample Request
7456

7557
```http
76-
GET /gcdump/21632 HTTP/1.1
58+
GET /gcdump?pid=21632 HTTP/1.1
7759
Host: localhost:52323
7860
Authorization: MonitorApiKey fffffffffffffffffffffffffffffffffffffffffff=
7961
```
8062

8163
or
8264

8365
```http
84-
GET /gcdump/cd4da319-fa9e-4987-ac4e-e57b2aac248b HTTP/1.1
66+
GET /gcdump?uid=cd4da319-fa9e-4987-ac4e-e57b2aac248b HTTP/1.1
8567
Host: localhost:52323
8668
Authorization: MonitorApiKey fffffffffffffffffffffffffffffffffffffffffff=
8769
```
@@ -116,4 +98,4 @@ On Windows, `.gcdump` files can be viewed in [PerfView](https://github.com/micro
11698

11799
You can collect multiple `.gcdump`s and open them simultaneously in Visual Studio to get a comparison experience.
118100

119-
Reports can be generated from `.gcdump` files using the [dotnet-gcdump](https://docs.microsoft.com/dotnet/core/diagnostics/dotnet-gcdump) tool.
101+
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‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# Info - Get
2+
3+
Gets information about the `dotnet monitor` version, the runtime version, and the diagnostic port settings.
4+
5+
## HTTP Route
6+
7+
```http
8+
GET /info HTTP/1.1
9+
```
10+
11+
## Host Address
12+
13+
The default host address for these routes is `https://localhost:52323`.
14+
15+
## Authentication
16+
17+
Authentication is enforced for this route. See [Authentication](./../authentication.md) for further information.
18+
19+
## Responses
20+
21+
| Name | Type | Description | Content Type |
22+
|---|---|---|---|
23+
| 200 OK | | Information about `dotnet monitor` formatted as JSON. | `application/json` |
24+
| 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` |
25+
| 401 Unauthorized | | Authentication is required to complete the request. See [Authentication](./../authentication.md) for further information. | |
26+
27+
## Examples
28+
29+
### Sample Request
30+
31+
```http
32+
GET /info HTTP/1.1
33+
Host: localhost:52323
34+
```
35+
36+
### Sample Response
37+
38+
```http
39+
HTTP/1.1 200 OK
40+
Content-Type: application/json
41+
42+
{
43+
"version": "5.0.0",
44+
"runtimeVersion": "3.1.16",
45+
"diagnosticPortMode": "Connect",
46+
"diagnosticPortName": null
47+
}
48+
```
49+
50+
## Supported Runtimes
51+
52+
| Operating System | Runtime Version |
53+
|---|---|
54+
| Windows | .NET Core 3.1, .NET 5+ |
55+
| Linux | .NET Core 3.1, .NET 5+ |
56+
| MacOS | .NET Core 3.1, .NET 5+ |

‎documentation/api/logs-custom.md‎

Lines changed: 7 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -7,25 +7,7 @@ Captures log statements that are logged to the [ILogger<> infrastructure](https:
77
## HTTP Route
88

99
```http
10-
POST /logs/{pid}?durationSeconds={durationSeconds}&egressProvider={egressProvider} HTTP/1.1
11-
```
12-
13-
or
14-
15-
```http
16-
POST /logs/{uid}?durationSeconds={durationSeconds}&egressProvider={egressProvider} HTTP/1.1
17-
```
18-
19-
or
20-
21-
```http
22-
POST /logs/{name}?durationSeconds={durationSeconds}&egressProvider={egressProvider} HTTP/1.1
23-
```
24-
25-
or
26-
27-
```http
28-
POST /logs?durationSeconds={durationSeconds}&egressProvider={egressProvider} HTTP/1.1
10+
POST /logs?pid={pid}&uid={uid}&name={name}&durationSeconds={durationSeconds}&egressProvider={egressProvider} HTTP/1.1
2911
```
3012

3113
> **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
3820

3921
| Name | In | Required | Type | Description |
4022
|---|---|---|---|---|
41-
| `pid` | path | false | int | The ID of the process. |
42-
| `uid` | path | false | guid | A value that uniquely identifies a runtime instance within a process. |
43-
| `name` | path | false | string | The name of the process. |
23+
| `pid` | query | false | int | The ID of the process. |
24+
| `uid` | query | false | guid | A value that uniquely identifies a runtime instance within a process. |
25+
| `name` | query | false | string | The name of the process. |
4426
| `durationSeconds` | query | false | int | The duration of the log collection operation in seconds. Default is `30`. Min is `-1` (indefinite duration). Max is `2147483647`. |
4527
| `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. |
4628

@@ -77,7 +59,7 @@ The expected content type is `application/json`.
7759
### Sample Request
7860

7961
```http
80-
POST /logs/21632?durationSeconds=60 HTTP/1.1
62+
POST /logs?pid=21632&durationSeconds=60 HTTP/1.1
8163
Host: localhost:52323
8264
Authorization: MonitorApiKey fffffffffffffffffffffffffffffffffffffffffff=
8365
@@ -93,7 +75,7 @@ Authorization: MonitorApiKey fffffffffffffffffffffffffffffffffffffffffff=
9375
or
9476

9577
```http
96-
POST /logs/cd4da319-fa9e-4987-ac4e-e57b2aac248b?durationSeconds=60 HTTP/1.1
78+
POST /logs?uid=cd4da319-fa9e-4987-ac4e-e57b2aac248b&durationSeconds=60 HTTP/1.1
9779
Host: localhost:52323
9880
Authorization: MonitorApiKey fffffffffffffffffffffffffffffffffffffffffff=
9981
@@ -136,4 +118,4 @@ data: => RequestId:0HM8M726ENU3K:0000002B, RequestPath:/, SpanId:|4791a4a7-433aa
136118

137119
### When to use `pid` vs `uid`
138120

139-
See [Process ID `pid` vs Unique ID `uid`](pidvsuid.md) for clarification on when it is best to use either parameter.
121+
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‎

Lines changed: 7 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -7,25 +7,7 @@ Captures log statements that are logged to the [ILogger<> infrastructure](https:
77
## HTTP Route
88

99
```http
10-
GET /logs/{pid}?level={level}&durationSeconds={durationSeconds}&egressProvider={egressProvider} HTTP/1.1
11-
```
12-
13-
or
14-
15-
```http
16-
GET /logs/{uid}?level={level}&durationSeconds={durationSeconds}&egressProvider={egressProvider} HTTP/1.1
17-
```
18-
19-
or
20-
21-
```http
22-
GET /logs/{name}?level={level}&durationSeconds={durationSeconds}&egressProvider={egressProvider} HTTP/1.1
23-
```
24-
25-
or
26-
27-
```http
28-
GET /logs?level={level}&durationSeconds={durationSeconds}&egressProvider={egressProvider} HTTP/1.1
10+
GET /logs?pid={pid}&uid={uid}&name={name}&level={level}&durationSeconds={durationSeconds}&egressProvider={egressProvider} HTTP/1.1
2911
```
3012

3113
> **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
3820

3921
| Name | In | Required | Type | Description |
4022
|---|---|---|---|---|
41-
| `pid` | path | false | int | The ID of the process. |
42-
| `uid` | path | false | guid | A value that uniquely identifies a runtime instance within a process. |
43-
| `name` | path | false | string | The name of the process. |
23+
| `pid` | query | false | int | The ID of the process. |
24+
| `uid` | query | false | guid | A value that uniquely identifies a runtime instance within a process. |
25+
| `name` | query | false | string | The name of the process. |
4426
| `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). |
4527
| `durationSeconds` | query | false | int | The duration of the log collection operation in seconds. Default is `30`. Min is `-1` (indefinite duration). Max is `2147483647`. |
4628
| `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:
7254
### Sample Request
7355

7456
```http
75-
GET /logs/21632?level=Information&durationSeconds=60 HTTP/1.1
57+
GET /logs?pid=21632&level=Information&durationSeconds=60 HTTP/1.1
7658
Host: localhost:52323
7759
Authorization: MonitorApiKey fffffffffffffffffffffffffffffffffffffffffff=
7860
```
7961

8062
or
8163

8264
```http
83-
GET /logs/cd4da319-fa9e-4987-ac4e-e57b2aac248b?level=Information&durationSeconds=60 HTTP/1.1
65+
GET /logs?uid=cd4da319-fa9e-4987-ac4e-e57b2aac248b&level=Information&durationSeconds=60 HTTP/1.1
8466
Host: localhost:52323
8567
Authorization: MonitorApiKey fffffffffffffffffffffffffffffffffffffffffff=
8668
```
@@ -118,4 +100,4 @@ data: Processing request 0b7ba879-fa80-4eb8-a87d-408f539952ca.
118100

119101
### When to use `pid` vs `uid`
120102

121-
See [Process ID `pid` vs Unique ID `uid`](pidvsuid.md) for clarification on when it is best to use either parameter.
103+
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‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,6 @@ Authentication is not enforced for this route.
3434
| 200 OK | | A list of metrics for a single process in the Prometheus exposition format. | `text/plain` |
3535
| 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` |
3636
| 401 Unauthorized | | Authentication is required to complete the request. See [Authentication](./../authentication.md) for further information. | |
37-
| 429 Too Many Requests | | There are too many trace requests at this time. Try to request a trace at a later time. | |
3837

3938
## Examples
4039

0 commit comments

Comments
 (0)