Add support for a StoppingEvent on CollectTrace action (#2557)

dotnet · Oct 11, 2022 · 1449f49 · 1449f49
1 parent fefea42
commit 1449f49
Show file tree

Hide file tree

Showing 25 changed files with 1,058 additions and 6 deletions.
diff --git a/documentation/api/definitions.md b/documentation/api/definitions.md
@@ -372,6 +372,16 @@ The `uid` property is useful for uniquely identifying a process when it is runni
     "processArchitecture": "x64"
 }
 ```
+## TraceEventFilter
+
+Object describing a filter for trace events.
+
+| Name | Type | Description |
+|---|---|---|
+| `ProviderName` | string | The event provider that will produce the specified event. |
+| `EventName` | string | The name of the event, which is a concatenation of the task name and opcode name, if any. The task and opcode names are separated by a '/'. If the event has no opcode, then the event name is just the task name. |
+| `PayloadFilter` | map (of string) | (Optional) A mapping of event payload field names to their expected value. A subset of the payload fields may be specified. |
+
 
 ## TraceProfile
 

diff --git a/documentation/configuration.md b/documentation/configuration.md
@@ -1503,6 +1503,7 @@ An action that collects a trace of the process that the collection rule is targe
 | `BufferSizeMegabytes` | int | false | The size (in megabytes) of the event buffer used in the runtime. If the event buffer is filled, events produced by event providers may be dropped until the buffer is cleared. Increase the buffer size to mitigate this or pair down the list of event providers, keywords, and level to filter out extraneous events. Only applies when `Providers` is specified. | `256` | `1` | `1024` |
 | `Duration` | TimeSpan? | false | The duration of the trace operation. | `"00:00:30"` (30 seconds) | `"00:00:01"` (1 second) | `"1.00:00:00"` (1 day) |
 | `Egress` | string | true | The named [egress provider](egress.md) for egressing the collected trace. | | | |
+| `StoppingEvent` | [TraceEventFilter](api/definitions.md#traceeventfilter)? | false | The event to watch for while collecting the trace, and once either the event is hit or the `Duration` is reached the trace will be stopped. This can only be specified if `Providers` is set. | `null` | | |
 
 ##### Outputs
 

diff --git a/documentation/schema.json b/documentation/schema.json
@@ -1722,6 +1722,17 @@
           "type": "string",
           "description": "The name of the egress provider to which the trace is egressed.",
           "minLength": 1
+        },
+        "StoppingEvent": {
+          "description": "The event to watch for while collecting the trace, and once observed the trace will be stopped.",
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "$ref": "#/definitions/TraceEventFilter"
+            }
+          ]
         }
       }
     },
@@ -1793,6 +1804,36 @@
         "Verbose"
       ]
     },
+    "TraceEventFilter": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "ProviderName",
+        "EventName"
+      ],
+      "properties": {
+        "ProviderName": {
+          "type": "string",
+          "description": "The event provider that will produce the specified event.",
+          "minLength": 1
+        },
+        "EventName": {
+          "type": "string",
+          "description": "The name of the event, which is a concatenation of the task name and opcode name, if any. The task and opcode names are separated by a '/'. If the event has no opcode, then the event name is just the task name.",
+          "minLength": 1
+        },
+        "PayloadFilter": {
+          "type": [
+            "null",
+            "object"
+          ],
+          "description": "A mapping of event payload field names to their expected value. A subset of the payload fields may be specified.",
+          "additionalProperties": {
+            "type": "string"
+          }
+        }
+      }
+    },
     "ExecuteOptions": {
       "type": "object",
       "additionalProperties": false,

diff --git a/src/Microsoft.Diagnostics.Monitoring.Options/OptionsDisplayStrings.Designer.cs b/src/Microsoft.Diagnostics.Monitoring.Options/OptionsDisplayStrings.Designer.cs
diff --git a/src/Microsoft.Diagnostics.Monitoring.Options/OptionsDisplayStrings.resx b/src/Microsoft.Diagnostics.Monitoring.Options/OptionsDisplayStrings.resx
@@ -729,4 +729,20 @@
   <data name="DisplayAttributeDescription_CollectStacksOptions_Egress" xml:space="preserve">
     <value>The name of the egress provider to which the call stacks are egressed.</value>
   </data>
+  <data name="DisplayAttributeDescription_CollectTraceOptions_StoppingEvent" xml:space="preserve">
+    <value>The event to watch for while collecting the trace, and once observed the trace will be stopped.</value>
+    <comment>The description provided for the StoppingEvent parameter on CollectTraceOptions.</comment>
+  </data>
+  <data name="DisplayAttributeDescription_TraceEventFilter_EventName" xml:space="preserve">
+    <value>The name of the event, which is a concatenation of the task name and opcode name, if any. The task and opcode names are separated by a '/'. If the event has no opcode, then the event name is just the task name.</value>
+    <comment>The description provided for the EventName parameter on TraceEventFilter.</comment>
+  </data>
+  <data name="DisplayAttributeDescription_TraceEventFilter_ProviderName" xml:space="preserve">
+    <value>The event provider that will produce the specified event.</value>
+    <comment>The description provided for the ProviderName parameter on TraceEventFilter.</comment>
+  </data>
+  <data name="DisplayAttributeDescription_TraceEventFilter_PayloadFilter" xml:space="preserve">
+    <value>A mapping of event payload field names to their expected value. A subset of the payload fields may be specified.</value>
+    <comment>The description provided for the PayloadFilter parameter on TraceEventFilter.</comment>
+  </data>
 </root>