Add Tags for API Requests (#2919)

documentation/api/definitions.md

@@ -286,6 +286,8 @@ Detailed information about an operation.
 | `status` | [OperationState](#operationstate) | The current status of operation. |
 | `egressProviderName` | string | (8.0+) The name of the egress provider that the artifact is being sent to. This will be null if the artifact is being sent directly back to the user from an HTTP request. |
 | `isStoppable` | bool | (8.0+) Whether this operation can be gracefully stopped using [Stop Operation](operations-stop.md). Not all operations support being stopped. |
+| `process` | [OperationProcessInfo](#operationprocessinfo) | (6.3+) The process on which the operation is performed. |
+| `tags` | set (of string) | (8.0+) A set of user-readable identifiers for the operation. |
 
 ### Example
 
@@ -298,6 +300,14 @@ Detailed information about an operation.
     "status": "Succeeded",
     "egressProviderName": "monitorBlob",
     "isStoppable": false,
+    "process": {
+        "pid": 21632,
+        "uid": "cd4da319-fa9e-4987-ac4e-e57b2aac248b",
+        "name": "dotnet"
+    },
+    "tags": [
+        "tag1"
+    ]
 }
 ```
 
@@ -313,6 +323,7 @@ Summary state of an operation.
 | `egressProviderName` | string | (8.0+) The name of the egress provider that the artifact is being sent to. This will be null if the artifact is being sent directly back to the user from an HTTP request. |
 | `isStoppable` | bool | (8.0+) Whether this operation can be gracefully stopped using [Stop Operation](operations-stop.md). Not all operations support being stopped. |
 | `process` | [OperationProcessInfo](#operationprocessinfo) | (6.3+) The process on which the operation is performed. |
+| `tags` | set (of string) | (8.0+) A set of user-readable identifiers for the operation. |
 
 ### Example
 
@@ -327,7 +338,11 @@ Summary state of an operation.
         "pid": 21632,
         "uid": "cd4da319-fa9e-4987-ac4e-e57b2aac248b",
         "name": "dotnet"
-    }
+    },
+    "tags": [
+        "tag1",
+        "tag2"
+    ]
 }
 ```
 

documentation/api/dump.md

@@ -10,7 +10,7 @@ Captures a managed dump of a specified process without using a debugger.
 ## HTTP Route
 
 ```http
-GET /dump?pid={pid}&uid={uid}&name={name}&type={type}&egressProvider={egressProvider} HTTP/1.1
+GET /dump?pid={pid}&uid={uid}&name={name}&type={type}&egressProvider={egressProvider}&tags={tags} 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.
@@ -28,6 +28,7 @@ The default host address for these routes is `https://localhost:52323`. This rou
 | `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. |
+| `tags` | query | false | string | (8.0+) A comma-separated list of user-readable identifiers for the operation. |
 
 See [ProcessIdentifier](definitions.md#processidentifier) for more details about the `pid`, `uid`, and `name` parameters.
 

documentation/api/gcdump.md

@@ -14,7 +14,7 @@ Captures a GC dump of a specified process. These dumps are useful for several sc
 ## HTTP Route
 
 ```http
-GET /gcdump?pid={pid}&uid={uid}&name={name}&egressProvider={egressProvider} HTTP/1.1
+GET /gcdump?pid={pid}&uid={uid}&name={name}&egressProvider={egressProvider}&tags={tags} 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.
@@ -31,6 +31,7 @@ The default host address for these routes is `https://localhost:52323`. This rou
 | `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. |
+| `tags` | query | false | string | (8.0+) A comma-separated list of user-readable identifiers for the operation. |
 
 See [ProcessIdentifier](definitions.md#processidentifier) for more details about the `pid`, `uid`, and `name` parameters.
 

documentation/api/livemetrics-custom.md

@@ -8,7 +8,7 @@ Captures metrics for a process, with the ability to specify custom metrics.
 ## HTTP Route
 
 ```http
-POST /livemetrics?pid={pid}&uid={uid}&name={name}&durationSeconds={durationSeconds}&egressProvider={egressProvider} HTTP/1.1
+POST /livemetrics?pid={pid}&uid={uid}&name={name}&durationSeconds={durationSeconds}&egressProvider={egressProvider}&tags={tags} 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.
@@ -26,6 +26,7 @@ The default host address for these routes is `https://localhost:52323`. This rou
 | `name` | query | false | string | The name of the process. |
 | `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. |
+| `tags` | query | false | string | (8.0+) A comma-separated list of user-readable identifiers for the operation. |
 
 See [ProcessIdentifier](definitions.md#processidentifier) for more details about the `pid`, `uid`, and `name` parameters.
 

documentation/api/livemetrics-get.md

@@ -10,7 +10,7 @@ Captures metrics for a chosen process.
 ## HTTP Route
 
 ```http
-GET /livemetrics?pid={pid}&uid={uid}&name={name}&durationSeconds={durationSeconds}&egressProvider={egressProvider} HTTP/1.1
+GET /livemetrics?pid={pid}&uid={uid}&name={name}&durationSeconds={durationSeconds}&egressProvider={egressProvider}&tags={tags} 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.
@@ -28,6 +28,7 @@ The default host address for these routes is `https://localhost:52323`. This rou
 | `name` | query | false | string | The name of the process. |
 | `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. |
+| `tags` | query | false | string | (8.0+) A comma-separated list of user-readable identifiers for the operation. |
 
 See [ProcessIdentifier](definitions.md#processidentifier) for more details about the `pid`, `uid`, and `name` parameters.
 

documentation/api/logs-custom.md

@@ -10,7 +10,7 @@ Captures log statements that are logged to the [ILogger<> infrastructure](https:
 ## HTTP Route
 
 ```http
-POST /logs?pid={pid}&uid={uid}&name={name}&durationSeconds={durationSeconds}&egressProvider={egressProvider} HTTP/1.1
+POST /logs?pid={pid}&uid={uid}&name={name}&durationSeconds={durationSeconds}&egressProvider={egressProvider}&tags={tags} 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.
@@ -28,6 +28,7 @@ The default host address for these routes is `https://localhost:52323`. This rou
 | `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. |
+| `tags` | query | false | string | (8.0+) A comma-separated list of user-readable identifiers for the operation. |
 
 See [ProcessIdentifier](definitions.md#processidentifier) for more details about the `pid`, `uid`, and `name` parameters.
 

documentation/api/logs-get.md

@@ -10,7 +10,7 @@ Captures log statements that are logged to the [ILogger<> infrastructure](https:
 ## HTTP Route
 
 ```http
-GET /logs?pid={pid}&uid={uid}&name={name}&level={level}&durationSeconds={durationSeconds}&egressProvider={egressProvider} HTTP/1.1
+GET /logs?pid={pid}&uid={uid}&name={name}&level={level}&durationSeconds={durationSeconds}&egressProvider={egressProvider}&tags={tags} 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.
@@ -29,6 +29,7 @@ The default host address for these routes is `https://localhost:52323`. This rou
 | `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. |
+| `tags` | query | false | string | (8.0+) A comma-separated list of user-readable identifiers for the operation. |
 
 See [ProcessIdentifier](definitions.md#processidentifier) for more details about the `pid`, `uid`, and `name` parameters.
 

documentation/api/operations-get.md

@@ -60,7 +60,8 @@ Content-Type: application/json
         "pid":1,
         "uid":"95b0202a-4ed3-44a6-98f1-767d270ec783",
         "name":"dotnet-monitor-demo"
-    }
+    },
+    "tags": []
 }
 ```
 

documentation/api/operations-list.md

@@ -8,7 +8,7 @@ Lists all operations that have been created, as well as their status.
 ## HTTP Route
 
 ```http
-GET /operations?pid={pid}&uid={uid}&name={name} HTTP/1.1
+GET /operations?pid={pid}&uid={uid}&name={name}&tags={tags} HTTP/1.1
 ```
 
 ## Host Address
@@ -22,13 +22,16 @@ The default host address for these routes is `https://localhost:52323`. This rou
 | `pid` | query | false | int | (6.3+) The ID of the process. |
 | `uid` | query | false | guid | (6.3+) A value that uniquely identifies a runtime instance within a process. |
 | `name` | query | false | string | (6.3+) The name of the process. |
+| `tags` | query | false | string | (8.0+) A comma-separated list of user-readable identifiers for the operation. |
 
 See [ProcessIdentifier](definitions.md#processidentifier) for more details about the `pid`, `uid`, and `name` parameters.
 
 If none of `pid`, `uid`, or `name` are specified, all operations will be listed.
 
 > **Note**: If multiple processes match the provided parameters (e.g., two processes named "MyProcess"), the operations for all matching processes will be listed.
 
+> **Note**: An operation must include all of the provided tags to be shown in the results (e.g., tags=tag1,tag2 only includes operations with tag1 and tag2, not one or the other). 
+
 ## Authentication
 
 Authentication is enforced for this route. See [Authentication](./../authentication.md) for further information.
@@ -73,7 +76,8 @@ Content-Type: application/json
             "pid":1,
             "uid":"95b0202a-4ed3-44a6-98f1-767d270ec783",
             "name":"dotnet-monitor-demo"
-        }
+        },
+        "tags": []
     },
     {
         "operationId": "06ac07e2-f7cd-45ad-80c6-e38160bc5881",
@@ -86,7 +90,11 @@ Content-Type: application/json
             "pid":1,
             "uid":"95b0202a-4ed3-44a6-98f1-767d270ec783",
             "name":"dotnet-monitor-demo"
-        }
+        },
+        "tags": [
+            "tag1",
+            "tag2"
+        ]
     },
     {
         "operationId": "26e74e52-0a16-4e84-84bb-27f904bfaf85",
@@ -99,7 +107,8 @@ Content-Type: application/json
             "pid":11782,
             "uid":"23c289b3-b5ce-428a-aaa8-c864b3766bc2",
             "name":"dotnet-monitor-demo2"
-        }
+        },
+        "tags": []
     }
 ]
 ```
@@ -130,7 +139,43 @@ Content-Type: application/json
             "pid":1,
             "uid":"95b0202a-4ed3-44a6-98f1-767d270ec783",
             "name":"dotnet-monitor-demo"
-        }
+        },
+        "tags": []
+    }
+]
+```
+
+### Sample Request 3
+
+```http
+GET /operations?tags=tag1 HTTP/1.1
+Host: localhost:52323
+Authorization: Bearer fffffffffffffffffffffffffffffffffffffffffff=
+```
+
+### Sample Response 3
+
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+[
+    {
+        "operationId": "06ac07e2-f7cd-45ad-80c6-e38160bc5881",
+        "createdDateTime": "2021-07-21T20:22:15.315861Z",
+        "status": "Stopping",
+        "egressProviderName": null,
+        "isStoppable": false,
+        "process":
+        {
+            "pid":1,
+            "uid":"95b0202a-4ed3-44a6-98f1-767d270ec783",
+            "name":"dotnet-monitor-demo"
+        },
+        "tags": [
+            "tag1",
+            "tag2"
+        ]
     }
 ]
 ```

documentation/api/stacks.md

@@ -10,7 +10,7 @@ Captures the call stacks of the currently running process. Note that only manage
 ## HTTP Route
 
 ```http
-GET /stacks?pid={pid}&uid={uid}&name={name}&egressProvider={egressProvider} HTTP/1.1
+GET /stacks?pid={pid}&uid={uid}&name={name}&egressProvider={egressProvider}&tags={tags} 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.
@@ -27,6 +27,7 @@ The default host address for these routes is `https://localhost:52323`. This rou
 | `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 stacks. When not specified, the stacks are written to the HTTP response stream. See [Egress Providers](../egress.md) for more details. |
+| `tags` | query | false | string | (8.0+) A comma-separated list of user-readable identifiers for the operation. |
 
 See [ProcessIdentifier](definitions.md#processidentifier) for more details about the `pid`, `uid`, and `name` parameters.
 

documentation/api/trace-custom.md

@@ -8,7 +8,7 @@ Captures a diagnostic trace of a process using the given set of event providers
 ## HTTP Route
 
 ```http
-POST /trace?pid={pid}&uid={uid}&name={name}&durationSeconds={durationSeconds}&egressProvider={egressProvider} HTTP/1.1
+POST /trace?pid={pid}&uid={uid}&name={name}&durationSeconds={durationSeconds}&egressProvider={egressProvider}&tags={tags} 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.
@@ -26,6 +26,7 @@ The default host address for these routes is `https://localhost:52323`. This rou
 | `name` | query | false | string | The name of the process. |
 | `durationSeconds` | query | false | int | The duration of the trace 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 trace. When not specified, the trace is written to the HTTP response stream. See [Egress Providers](../egress.md) for more details. |
+| `tags` | query | false | string | (8.0+) A comma-separated list of user-readable identifiers for the operation. |
 
 See [ProcessIdentifier](definitions.md#processidentifier) for more details about the `pid`, `uid`, and `name` parameters.
 

documentation/api/trace-get.md

@@ -8,7 +8,7 @@ Captures a diagnostic trace of a process based on a predefined set of trace prof
 ## HTTP Route
 
 ```http
-GET /trace?pid={pid}&uid={uid}&name={name}&profile={profile}&durationSeconds={durationSeconds}&egressProvider={egressProvider} HTTP/1.1
+GET /trace?pid={pid}&uid={uid}&name={name}&profile={profile}&durationSeconds={durationSeconds}&egressProvider={egressProvider}&tags={tags} 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.
@@ -27,6 +27,7 @@ The default host address for these routes is `https://localhost:52323`. This rou
 | `profile` | query | false | [TraceProfile](definitions.md#traceprofile) | The name of the profile(s) used to collect events. See [TraceProfile](definitions.md#traceprofile) for details on the list of event providers, levels, and keywords each profile represents. Multiple profiles may be specified by separating them with commas. Default is `Cpu,Http,Metrics` |
 | `durationSeconds` | query | false | int | The duration of the trace 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 trace. When not specified, the trace is written to the HTTP response stream. See [Egress Providers](../egress.md) for more details. |
+| `tags` | query | false | string | (8.0+) A comma-separated list of user-readable identifiers for the operation. |
 
 See [ProcessIdentifier](definitions.md#processidentifier) for more details about the `pid`, `uid`, and `name` parameters.