Documentation for metrics

- Also fixup some examples for Bearer
dotnet · Sep 2, 2021 · ac302af · ac302af
1 parent 9edefbf
commit ac302af
Show file tree

Hide file tree

Showing 18 changed files with 297 additions and 32 deletions.
diff --git a/documentation/README.md b/documentation/README.md
@@ -19,6 +19,7 @@ When running a dotnet application, differences in diverse local and production e
     - [`/gcdump`](./api/gcdump.md)
     - [`/trace`](./api/trace.md)
     - [`/metrics`](./api/metrics.md)
+    - [`/collectmetrics`](./api/collectmetrics.md)
     - [`/logs`](./api/logs.md)
     - [`/info`](./api/info.md)
     - [`/operations`](.api/operations.md)

diff --git a/documentation/api/collectmetrics-custom.md b/documentation/api/collectmetrics-custom.md
@@ -0,0 +1,118 @@
+# Collectmetrics - Get Custom
+
+Captures metrics for a process, with the ability to specify custom metrics.
+
+## HTTP Route
+
+```http
+POST /collectmetrics?pid={pid}&uid={uid}&name={name}&metricsIntervalSeconds={metricsIntervalSeconds}&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.
+
+## Host Address
+
+The default host address for these routes is `https://localhost:52323`. This route is only available on the addresses configured via the `--urls` command line parameter and the `DOTNETMONITOR_URLS` environment variable.
+
+## URI Parameters
+
+| Name | In | Required | Type | Description |
+|---|---|---|---|---|
+| `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. |
+| `metricsIntervalSeconds` | query | false | int | The time interval used to collect metrics. Default is 5. |
+| `durationSeconds` | query | false | int | The duration of the metrics 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 metrics. When not specified, the metrics are 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.
+
+If none of `pid`, `uid`, or `name` are specified, artifacts for the [default process](defaultprocess.md) will be captured. Attempting to capture artifacts of the default process when the default process cannot be resolved will fail.
+
+## Authentication
+
+Authentication is enforced for this route. See [Authentication](./../authentication.md) for further information.
+
+Allowed schemes:
+- `Bearer`
+- `Negotiate` (Windows only, running as unelevated)
+
+## Request Body
+
+A request body of type [EventMetricsConfiguration](definitions.md#EventMetricsConfiguration) is required.
+
+The expected content type is `application/json`.
+
+## Responses
+
+| Name | Type | Description | Content Type |
+|---|---|---|---|
+| 200 OK | [Metric](./definitions.md/#Metric) | The metrics from the process formatted as json sequence. Each JSON object is a [metrics object](./definitions.md/#Metric)| `application/json-seq` |
+| 202 Accepted | | When an egress provider is specified, the Location header containers the URI of the operation for querying the egress status. | |
+| 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 requests at this time. Try to request metrics at a later time. | `application/problem+json` |
+
+## Examples
+
+### Sample Request
+
+```http
+GET /collectmetrics?pid=21632&metricsIntervalSeconds=10&durationSeconds=60 HTTP/1.1
+Host: localhost:52323
+Authorization: Bearer fffffffffffffffffffffffffffffffffffffffffff=
+
+{
+    "includeDefaultProviders": false,
+    "providers": [
+        {
+            "providerName": "CustomProvider",
+            "counterNames": [
+                "counter1",
+                "counter2"
+            ]
+
+        }
+    ]
+}
+```
+
+### Sample Response
+
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json-seq
+
+{
+    "timestamp": "2021-08-31T16:58:39.7514031+00:00",
+    "provider": "CustomProvider",
+    "name": "counter1",
+    "displayName": "Counter 1",
+    "unit": "B",
+    "counterType": "Metric",
+    "value": 3
+}
+{
+    "timestamp": "2021-08-31T16:58:39.7515128+00:00",
+    "provider": "CustomProvider",
+    "name": "counter2",
+    "displayName": "Counter 2",
+    "unit": "MB",
+    "counterType": "Metric",
+    "value": 126
+}
+```
+
+## 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+ |
+
+## Additional Notes
+
+### 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.
diff --git a/documentation/api/collectmetrics-get.md b/documentation/api/collectmetrics-get.md
@@ -0,0 +1,109 @@
+# Collectmetrics - Get
+
+Captures metrics for a chosen process.
+
+> **NOTE:** For Prometheus style metrics, use the [metrics](./metrics.md) endpoint.
+
+## HTTP Route
+
+```http
+GET /collectmetrics?pid={pid}&uid={uid}&name={name}&metricsIntervalSeconds={metricsIntervalSeconds}&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.
+
+## Host Address
+
+The default host address for these routes is `https://localhost:52323`. This route is only available on the addresses configured via the `--urls` command line parameter and the `DOTNETMONITOR_URLS` environment variable.
+
+## URI Parameters
+
+| Name | In | Required | Type | Description |
+|---|---|---|---|---|
+| `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. |
+| `metricsIntervalSeconds` | query | false | int | The time interval used to collect metrics. Default is 5. |
+| `durationSeconds` | query | false | int | The duration of the metrics 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 metrics. When not specified, the metrics are 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.
+
+If none of `pid`, `uid`, or `name` are specified, artifacts for the [default process](defaultprocess.md) will be captured. Attempting to capture artifacts of the default process when the default process cannot be resolved will fail.
+
+## Authentication
+
+Authentication is enforced for this route. See [Authentication](./../authentication.md) for further information.
+
+Allowed schemes:
+- `Bearer`
+- `Negotiate` (Windows only, running as unelevated)
+
+## Responses
+
+| Name | Type | Description | Content Type |
+|---|---|---|---|
+| 200 OK | [Metric](./definitions.md/#Metric) | The metrics from the process formatted as json sequence. | `application/json-seq` |
+| 202 Accepted | | When an egress provider is specified, the Location header containers the URI of the operation for querying the egress status. | |
+| 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 requests at this time. Try to request metrics at a later time. | `application/problem+json` |
+
+## Examples
+
+### Sample Request
+
+```http
+GET /collectmetrics?pid=21632&metricsIntervalSeconds=10&durationSeconds=60 HTTP/1.1
+Host: localhost:52323
+Authorization: Bearer fffffffffffffffffffffffffffffffffffffffffff=
+```
+
+### Sample Response
+
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json-seq
+
+{
+    "timestamp": "2021-08-31T16:58:39.7514031+00:00",
+    "provider": "System.Runtime",
+    "name": "cpu-usage",
+    "displayName": "CPU Usage",
+    "unit": "%",
+    "counterType": "Metric",
+    "value": 3
+}
+{
+    "timestamp": "2021-08-31T16:58:39.7515128+00:00",
+    "provider": "System.Runtime",
+    "name": "working-set",
+    "displayName": "Working Set",
+    "unit": "MB",
+    "counterType": "Metric",
+    "value": 126
+}
+{
+    "timestamp": "2021-08-31T16:58:39.7515232+00:00",
+    "provider": "System.Runtime",
+    "name": "gc-heap-size",
+    "displayName": "GC Heap Size",
+    "unit": "MB",
+    "counterType": "Metric",
+    "value": 16
+}
+```
+
+## 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+ |
+
+## Additional Notes
+
+### 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.
diff --git a/documentation/api/collectmetrics.md b/documentation/api/collectmetrics.md
@@ -0,0 +1,6 @@
+# Collect Metrics
+
+| Operation | Description |
+|---|---|
+| [Collect Metrics](collectmetrics-get.md) | Captures metrics using the default metric providers. |
+| [Collect Custom Metrics](collectmetrics-custom.md) | Captures metrics using custom metric providers. |
diff --git a/documentation/api/definitions.md b/documentation/api/definitions.md
@@ -22,6 +22,22 @@ Enumeration that describes the type of information to capture in a managed dump.
 | `Triage` | A small dump containing only stacks for each thread. |
 | `WithHeap` | A large and relatively comprehensive dump containing module lists, thread lists, all stacks, exception information, handle information, and all memory except for mapped images. |
 
+## EventMetricsConfiguration
+
+Describes custom metrics.
+
+| Name | Type | Description |
+|---|---|---|
+| `includeDefaultProviders` | bool | Determines if the default counter providers should be used (such as System.Runtime). |
+| `providers` | [EventMetricsProvider](#EventMetricsProvider)[] | Array of providers for metrics to collect. |
+
+## EventMetricsProvider
+
+| Name | Type | Description |
+|---|---|---|
+| `providerName` | string | The name of the metric provider. Note this is case-insensitive. |
+| `counterNames` | string[] | Array of providers for metrics to collect. These are case-sensitive. |
+
 ## EventProvider
 
 Object describing which events to capture from a single event provider with keywords and event levels.
@@ -132,6 +148,20 @@ The following configuration will collect logs for the Microsoft.AspNetCore.Hosti
 }
 ```
 
+## Metric
+
+Object describing a metric from the application.
+
+| Name | Type | Description |
+|---|---|---|
+| `name`| string | The unique name of this metric. |
+| `displayName` | string | Friendly name for the metric. |
+| `timestamp` | DateTime | Time when the metric was collected. |
+| `provider` | string | The provider name for the metric. |
+| `unit` | string | The unit for the metric. Can be null. |
+| `counterType` | string | The type of metric. This is typically `Rate` or `Metric`. |
+| `value` | double | The value of the metric. |
+
 ## OperationError
 
 | Name | Type | Description |

diff --git a/documentation/api/dump.md b/documentation/api/dump.md
@@ -35,7 +35,7 @@ If none of `pid`, `uid`, or `name` are specified, a dump of the [default process
 Authentication is enforced for this route. See [Authentication](./../authentication.md) for further information.
 
 Allowed schemes:
-- `MonitorApiKey`
+- `Bearer`
 - `Negotiate` (Windows only, running as unelevated)
 
 ## Responses
@@ -55,15 +55,15 @@ Allowed schemes:
 ```http
 GET /dump?pid=21632&type=Full HTTP/1.1
 Host: localhost:52323
-Authorization: MonitorApiKey fffffffffffffffffffffffffffffffffffffffffff=
+Authorization: Bearer fffffffffffffffffffffffffffffffffffffffffff=
 ```
 
 or
 
 ```http
 GET /dump?uid=cd4da319-fa9e-4987-ac4e-e57b2aac248b&type=Full HTTP/1.1
 Host: localhost:52323
-Authorization: MonitorApiKey fffffffffffffffffffffffffffffffffffffffffff=
+Authorization: Bearer fffffffffffffffffffffffffffffffffffffffffff=
 ```
 
 ### Sample Response

diff --git a/documentation/api/gcdump.md b/documentation/api/gcdump.md
@@ -38,7 +38,7 @@ If none of `pid`, `uid`, or `name` are specified, a GC dump of the [default proc
 Authentication is enforced for this route. See [Authentication](./../authentication.md) for further information.
 
 Allowed schemes:
-- `MonitorApiKey`
+- `Bearer`
 - `Negotiate` (Windows only, running as unelevated)
 
 ## Responses
@@ -58,15 +58,15 @@ Allowed schemes:
 ```http
 GET /gcdump?pid=21632 HTTP/1.1
 Host: localhost:52323
-Authorization: MonitorApiKey fffffffffffffffffffffffffffffffffffffffffff=
+Authorization: Bearer fffffffffffffffffffffffffffffffffffffffffff=
 ```
 
 or
 
 ```http
 GET /gcdump?uid=cd4da319-fa9e-4987-ac4e-e57b2aac248b HTTP/1.1
 Host: localhost:52323
-Authorization: MonitorApiKey fffffffffffffffffffffffffffffffffffffffffff=
+Authorization: Bearer fffffffffffffffffffffffffffffffffffffffffff=
 ```
 
 ### Sample Response

diff --git a/documentation/api/logs-custom.md b/documentation/api/logs-custom.md
@@ -35,7 +35,7 @@ If none of `pid`, `uid`, or `name` are specified, logs for the [default process]
 Authentication is enforced for this route. See [Authentication](./../authentication.md) for further information.
 
 Allowed schemes:
-- `MonitorApiKey`
+- `Bearer`
 - `Negotiate` (Windows only, running as unelevated)
 
 ## Request Body
@@ -62,7 +62,7 @@ The expected content type is `application/json`.
 ```http
 POST /logs?pid=21632&durationSeconds=60 HTTP/1.1
 Host: localhost:52323
-Authorization: MonitorApiKey fffffffffffffffffffffffffffffffffffffffffff=
+Authorization: Bearer fffffffffffffffffffffffffffffffffffffffffff=
 
 {
     "filterSpecs": {
@@ -78,7 +78,7 @@ or
 ```http
 POST /logs?uid=cd4da319-fa9e-4987-ac4e-e57b2aac248b&durationSeconds=60 HTTP/1.1
 Host: localhost:52323
-Authorization: MonitorApiKey fffffffffffffffffffffffffffffffffffffffffff=
+Authorization: Bearer fffffffffffffffffffffffffffffffffffffffffff=
 
 {
     "filterSpecs": {

diff --git a/documentation/api/logs-get.md b/documentation/api/logs-get.md
@@ -36,7 +36,7 @@ If none of `pid`, `uid`, or `name` are specified, logs for the [default process]
 Authentication is enforced for this route. See [Authentication](./../authentication.md) for further information.
 
 Allowed schemes:
-- `MonitorApiKey`
+- `Bearer`
 - `Negotiate` (Windows only, running as unelevated)
 
 ## Responses
@@ -57,15 +57,15 @@ Allowed schemes:
 ```http
 GET /logs?pid=21632&level=Information&durationSeconds=60 HTTP/1.1
 Host: localhost:52323
-Authorization: MonitorApiKey fffffffffffffffffffffffffffffffffffffffffff=
+Authorization: Bearer fffffffffffffffffffffffffffffffffffffffffff=
 ```
 
 or
 
 ```http
 GET /logs?uid=cd4da319-fa9e-4987-ac4e-e57b2aac248b&level=Information&durationSeconds=60 HTTP/1.1
 Host: localhost:52323
-Authorization: MonitorApiKey fffffffffffffffffffffffffffffffffffffffffff=
+Authorization: Bearer fffffffffffffffffffffffffffffffffffffffffff=
 ```
 
 ### Sample Response