Merge main into feature/egressExtension branch

NuGet.config

@@ -13,6 +13,7 @@
     <add key="dotnet-eng" value="https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-eng/nuget/v3/index.json" />
     <!-- Standard feeds -->
     <add key="dotnet-public" value="https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-public/nuget/v3/index.json" />
+    <add key="dotnet-libraries" value="https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-libraries/nuget/v3/index.json" />
   </packageSources>
   <disabledPackageSources />
 </configuration>

documentation/README.md

@@ -30,7 +30,9 @@ When running a dotnet application, differences in diverse local and production e
     - [API Key (Recommended)](./authentication.md#api-key-authentication)
       - [API Key Setup Guide](./api-key-setup.md)
     - [Windows](./authentication.md#windows-authentication)
-- [Collection Rules](./collectionrules.md)
+- [Collection Rules](./collectionrules/collectionrules.md)
+    - [Collection Rules examples](./collectionrules/collectionruleexamples.md)
+    - [Trigger shortcut](./collectionrules/triggershortcuts.md)
 - [Egress Providers](./egress.md)
 - [Troubleshooting](./troubleshooting.md)
 - [Clone, build, and test the repo](./building.md)

documentation/collectionrules/templates.md

@@ -0,0 +1,294 @@
+# Templates
+
+Templates allow users to design reusable collection rule components to decrease configuration verbosity, reduce duplication between rules, and speed up the process of writing complex scenarios.
+
+Templates associate a name with a single Filter, Trigger, Action, or Limit; this name can then be used throughout configuration to represent the use of that Filter/Trigger/Action/Limit. This is ideal for scenarios where multiple collection rules re-use the same functionality, allowing the author to write/edit the configuration in a single place.
+
+You can easily translate existing configuration to Templates using the format in the following sample; once defined, the Template is referenced by its name in the collection rule.
+
+<details>
+  <summary>JSON</summary>
+
+  ```json
+  {
+    "Templates": {
+      "CollectionRuleActions": {
+        "NameOfActionTemplate": {
+          "Type": "CollectTrace",
+          "Settings": {
+            "Egress": "artifacts",
+            "SlidingWindowDuration": "00:00:15",
+            "Profile": "Cpu"
+          }
+        }
+      },
+      "CollectionRuleTriggers": {
+        "NameOfTriggerTemplate": {
+          "Type": "AspNetRequestCount",
+          "Settings": {
+            "RequestCount": 10,
+            "SlidingWindowDuration": "00:01:00"
+          }
+        }
+      }
+    },
+    ...
+    "CollectionRules": {
+      "NameOfCollectionRule": {
+        "Trigger": "NameOfTriggerTemplate",
+        "Actions": [
+          "NameOfActionTemplate"
+        ] 
+      }
+    }
+  }
+  ```
+</details>
+
+<details>
+  <summary>Kubernetes ConfigMap</summary>
+
+  ```yaml
+  Templates__CollectionRuleActions__NameOfActionTemplate__Type: "CollectTrace"
+  Templates__CollectionRuleActions__NameOfActionTemplate__Settings__Egress: "artifacts"
+  Templates__CollectionRuleActions__NameOfActionTemplate__Settings__SlidingWindowDuration: "00:00:15"
+  Templates__CollectionRuleActions__NameOfActionTemplate__Settings__Profile: "Cpu"
+  Templates__CollectionRuleTriggers__NameOfTriggerTemplate__Type: "AspNetRequestCount"
+  Templates__CollectionRuleTriggers__NameOfTriggerTemplate__Settings__RequestCount: "10"
+  Templates__CollectionRuleTriggers__NameOfTriggerTemplate__Settings__SlidingWindowDuration: "00:01:00"
+  CollectionRules__NameOfCollectionRule__Trigger: "NameOfTriggerTemplate"
+  CollectionRules__NameOfCollectionRule__Actions__0: "NameOfActionTemplate"
+  ```
+</details>
+
+<details>
+  <summary>Kubernetes Environment Variables</summary>
+
+  ```yaml
+  - name: DotnetMonitor_Templates__CollectionRuleActions__NameOfActionTemplate__Type
+    value: "CollectTrace"
+  - name: DotnetMonitor_Templates__CollectionRuleActions__NameOfActionTemplate__Settings__Egress
+    value: "artifacts"
+  - name: DotnetMonitor_Templates__CollectionRuleActions__NameOfActionTemplate__Settings__SlidingWindowDuration
+    value: "00:00:15"
+  - name: DotnetMonitor_Templates__CollectionRuleActions__NameOfActionTemplate__Settings__Profile
+    value: "Cpu"
+  - name: DotnetMonitor_Templates__CollectionRuleTriggers__NameOfTriggerTemplate__Type
+    value: "AspNetRequestCount"
+  - name: DotnetMonitor_Templates__CollectionRuleTriggers__NameOfTriggerTemplate__Settings__RequestCount
+    value: "10"
+  - name: DotnetMonitor_Templates__CollectionRuleTriggers__NameOfTriggerTemplate__Settings__SlidingWindowDuration
+    value: "00:01:00"
+  - name: DotnetMonitor_CollectionRules__NameOfCollectionRule__Trigger
+    value: "NameOfTriggerTemplate"
+  - name: DotnetMonitor_CollectionRules__NameOfCollectionRule__Actions__0
+    value: "NameOfActionTemplate"
+  ```
+</details>
+
+## Example
+
+The following example creates a template trigger named "HighRequestCount", two template actions named "CpuTrace" and "ErrorLogs", a template filter named "AppName", and a template limit named "ShortDuration". These templates are integrated into collection rules alongside the existing configuration format to demonstrate that rules can contain a mix of templates and standard configuration.
+
+<details>
+  <summary>JSON</summary>
+
+  ```json
+  {
+    "Templates": {
+      "CollectionRuleActions": {
+        "CPUTrace": {
+          "Type": "CollectTrace",
+          "Settings": {
+            "Egress": "artifacts",
+            "SlidingWindowDuration": "00:00:15",
+            "Profile": "Cpu"
+          }
+        },
+        "ErrorLogs": {
+          "Type": "CollectLogs",
+          "Settings": {
+            "Egress": "artifacts",
+            "DefaultLevel": "Error",
+            "UseAppFilters": false,
+            "Duration": "00:01:00"
+          }
+        }
+      },
+      "CollectionRuleTriggers": {
+        "HighRequestCount": {
+          "Type": "AspNetRequestCount",
+          "Settings": {
+            "RequestCount": 10,
+            "SlidingWindowDuration": "00:01:00"
+          }
+        }
+      },
+      "CollectionRuleFilters": {
+        "AppName": {
+          "Key": "ProcessName",
+          "Value": "MyProcessName",
+          "MatchType": "Exact"
+        }
+      },
+      "CollectionRuleLimits": {
+        "ShortDuration": {
+          "RuleDuration": "00:05:00",
+          "ActionCount": "1",
+          "ActionCountSlidingWindowDuration": "00:00:30"
+        }
+      }
+    },
+    ...
+    "CollectionRules": {
+      "LogAndDumpWhenHighRequestCount": {
+        "Trigger": "HighRequestCount",
+        "Actions": [
+          "ErrorLogs",
+          {
+            "Type": "CollectDump",
+            "Settings": {
+              "Egress": "artifacts",
+              "Type": "Full"
+            }
+          }
+        ],
+        "Filters": [
+          "AppName"
+        ],
+        "Limits": "ShortDuration"  
+      }
+    },
+    "TraceWhenHighCPU": {
+      "Trigger": {
+        "Type": "EventCounter",
+        "Settings": {
+          "ProviderName": "System.Runtime",
+          "CounterName": "cpu-usage",
+          "GreaterThan": 60,
+          "SlidingWindowDuration": "00:00:10"
+        }
+      },
+      "Actions": [
+        "CPUTrace"
+      ],
+      "Filters": [
+        {
+          "ProcessId": "12345"
+        }
+      ]
+    }
+  }
+  ```
+</details>
+
+<details>
+  <summary>Kubernetes ConfigMap</summary>
+
+  ```yaml
+  Templates__CollectionRuleActions__CPUTrace__Type: "CollectTrace"
+  Templates__CollectionRuleActions__CPUTrace__Settings__Egress: "artifacts"
+  Templates__CollectionRuleActions__CPUTrace__Settings__SlidingWindowDuration: "00:00:15"
+  Templates__CollectionRuleActions__CPUTrace__Settings__Profile: "Cpu"
+  Templates__CollectionRuleActions__ErrorLogs__Type: "CollectLogs"
+  Templates__CollectionRuleActions__ErrorLogs__Settings__Egress: "artifacts"
+  Templates__CollectionRuleActions__ErrorLogs__Settings__DefaultLevel: "Error"
+  Templates__CollectionRuleActions__ErrorLogs__Settings__UseAppFilters: "false"
+  Templates__CollectionRuleActions__ErrorLogs__Settings__Duration: "00:01:00"
+  Templates__CollectionRuleTriggers__HighRequestCount__Type: "AspNetRequestCount"
+  Templates__CollectionRuleTriggers__HighRequestCount__Settings__RequestCount: "10"
+  Templates__CollectionRuleTriggers__HighRequestCount__Settings__SlidingWindowDuration: "00:01:00"
+  Templates__CollectionRuleFilters__AppName__Key: "ProcessName"
+  Templates__CollectionRuleFilters__AppName__Value: "MyProcessName"
+  Templates__CollectionRuleFilters__AppName__MatchType: "Exact"
+  Templates__CollectionRuleLimits__ShortDuration__RuleDuration: "00:05:00"
+  Templates__CollectionRuleLimits__ShortDuration__ActionCount: "1"
+  Templates__CollectionRuleLimits__ShortDuration__ActionCountSlidingWindowDuration: "00:00:30"
+
+  CollectionRules__LogAndDumpWhenHighRequestCount__Trigger: "HighRequestCount"
+  CollectionRules__LogAndDumpWhenHighRequestCount__Actions__0: "ErrorLogs"
+  CollectionRules__LogAndDumpWhenHighRequestCount__Actions__1__Type: "CollectDump"
+  CollectionRules__LogAndDumpWhenHighRequestCount__Actions__1__Settings__Egress: "artifacts"
+  CollectionRules__LogAndDumpWhenHighRequestCount__Actions__1__Settings__Type: "Full"
+  CollectionRules__LogAndDumpWhenHighRequestCount__Filters__0: "AppName"
+  CollectionRules__LogAndDumpWhenHighRequestCount__Limits: "ShortDuration"
+  CollectionRules__TraceWhenHighCPU__Trigger__Type: "EventCounter"
+  CollectionRules__TraceWhenHighCPU__Trigger__Settings__ProviderName: "System.Runtime"
+  CollectionRules__TraceWhenHighCPU__Trigger__Settings__CounterName: "cpu-usage"
+  CollectionRules__TraceWhenHighCPU__Trigger__Settings__GreaterThan: "60"
+  CollectionRules__TraceWhenHighCPU__Trigger__Settings__SlidingWindowDuration: "00:00:10"
+  CollectionRules__TraceWhenHighCPU__Actions__0: "CPUTrace"
+  CollectionRules__TraceWhenHighCPU__Filters__0__ProcessId: "12345"
+  ```
+</details>
+
+<details>
+  <summary>Kubernetes Environment Variables</summary>
+
+  ```yaml
+  - name: DotnetMonitor_Templates__CollectionRuleActions__CPUTrace__Type
+    value: "CollectTrace"
+  - name: DotnetMonitor_Templates__CollectionRuleActions__CPUTrace__Settings__Egress
+    value: "artifacts"
+  - name: DotnetMonitor_Templates__CollectionRuleActions__CPUTrace__Settings__SlidingWindowDuration
+    value: "00:00:15"
+  - name: DotnetMonitor_Templates__CollectionRuleActions__CPUTrace__Settings__Profile
+    value: "Cpu"
+  - name: DotnetMonitor_Templates__CollectionRuleActions__ErrorLogs__Type
+    value: "CollectLogs"
+  - name: DotnetMonitor_Templates__CollectionRuleActions__ErrorLogs__Settings__Egress
+    value: "artifacts"
+  - name: DotnetMonitor_Templates__CollectionRuleActions__ErrorLogs__Settings__DefaultLevel
+    value: "Error"
+  - name: DotnetMonitor_Templates__CollectionRuleActions__ErrorLogs__Settings__UseAppFilters
+    value: "false"
+  - name: DotnetMonitor_Templates__CollectionRuleActions__ErrorLogs__Settings__Duration
+    value: "00:01:00"
+  - name: DotnetMonitor_Templates__CollectionRuleTriggers__HighRequestCount__Type
+    value: "AspNetRequestCount"
+  - name: DotnetMonitor_Templates__CollectionRuleTriggers__HighRequestCount__Settings__RequestCount
+    value: "10"
+  - name: DotnetMonitor_Templates__CollectionRuleTriggers__HighRequestCount__Settings__SlidingWindowDuration
+    value: "00:01:00"
+  - name: DotnetMonitor_Templates__CollectionRuleFilters__AppName__Key
+    value: "ProcessName"
+  - name: DotnetMonitor_Templates__CollectionRuleFilters__AppName__Value
+    value: "MyProcessName"
+  - name: DotnetMonitor_Templates__CollectionRuleFilters__AppName__MatchType
+    value: "Exact"
+  - name: DotnetMonitor_Templates__CollectionRuleLimits__ShortDuration__RuleDuration
+    value: "00:05:00"
+  - name: DotnetMonitor_Templates__CollectionRuleLimits__ShortDuration__ActionCount
+    value: "1"
+  - name: DotnetMonitor_Templates__CollectionRuleLimits__ShortDuration__ActionCountSlidingWindowDuration
+    value: "00:00:30"
+  - name: DotnetMonitor_CollectionRules__LogAndDumpWhenHighRequestCount__Trigger
+    value: "HighRequestCount"
+  - name: DotnetMonitor_CollectionRules__LogAndDumpWhenHighRequestCount__Actions__0
+    value: "ErrorLogs"
+  - name: DotnetMonitor_CollectionRules__LogAndDumpWhenHighRequestCount__Actions__1__Type
+    value: "CollectDump"
+  - name: DotnetMonitor_CollectionRules__LogAndDumpWhenHighRequestCount__Actions__1__Settings__Egress
+    value: "artifacts"
+  - name: DotnetMonitor_CollectionRules__LogAndDumpWhenHighRequestCount__Actions__1__Settings__Type
+    value: "Full"
+  - name: DotnetMonitor_CollectionRules__LogAndDumpWhenHighRequestCount__Filters__0
+    value: "AppName"
+  - name: DotnetMonitor_CollectionRules__LogAndDumpWhenHighRequestCount__Limits
+    value: "ShortDuration"
+  - name: DotnetMonitor_CollectionRules__TraceWhenHighCPU__Trigger__Type
+    value: "EventCounter"
+  - name: DotnetMonitor_CollectionRules__TraceWhenHighCPU__Trigger__Settings__ProviderName
+    value: "System.Runtime"
+  - name: DotnetMonitor_CollectionRules__TraceWhenHighCPU__Trigger__Settings__CounterName
+    value: "cpu-usage"
+  - name: DotnetMonitor_CollectionRules__TraceWhenHighCPU__Trigger__Settings__GreaterThan
+    value: "60"
+  - name: DotnetMonitor_CollectionRules__TraceWhenHighCPU__Trigger__Settings__SlidingWindowDuration
+    value: "00:00:10"
+  - name: DotnetMonitor_CollectionRules__TraceWhenHighCPU__Actions__0
+    value: "CPUTrace"
+  - name: DotnetMonitor_CollectionRules__TraceWhenHighCPU__Filters__0__ProcessId
+    value: "12345"
+  ```
+</details>

documentation/configuration.md

@@ -266,12 +266,13 @@ Alternatively, `dotnet monitor` can be set to `Listen` mode using the expanded f
   ```
 </details>
 
-When `dotnet monitor` is in `Listen` mode, you have to configure .NET processes to connect to `dotnet monitor`. You can do so by specifying the appropriate environment variable on your .NET process
+When `dotnet monitor` is in `Listen` mode, you have to configure .NET processes to connect to `dotnet monitor`. You can do so by specifying the appropriate environment variable on your .NET process.
 
-```powershell
-$env:DOTNET_DiagnosticPorts="dotnet-monitor-pipe,suspend"
+```bash
+export DOTNET_DiagnosticPorts="/diag/port.sock,suspend"
 ```
 
+
 #### Maximum connection
 
 When operating in `Listen` mode, you can also specify the maximum number of incoming connections for `dotnet monitor` to accept via the following configuration:
@@ -718,6 +719,7 @@ In addition to enabling custom providers, `dotnet monitor` also allows you to di
 | accountKey | string | false | The account key used to access the Azure blob storage account; must be specified if `accountKeyName` is not specified.|
 | sharedAccessSignature | string | false | The shared access signature (SAS) used to access the azure blob storage account; if using SAS, must be specified if `sharedAccessSignatureName` is not specified.|
 | accountKeyName | string | false | Name of the property in the Properties section that will contain the account key; must be specified if `accountKey` is not specified.|
+| managedIdentityClientId | string | false | The ClientId of the ManagedIdentity that can be used to authorize egress. Note this identity must be used by the hosting environment (such as Kubernetes) and must also have a Storage role with appropriate permissions. |
 | sharedAccessSignatureName | string | false | Name of the property in the Properties section that will contain the SAS token; if using SAS, must be specified if `sharedAccessSignature` is not specified.|
 | queueName | string | false | The name of the queue to which a message will be dispatched upon writing to a blob.|
 | queueAccountUri | string | false | The URI of the Azure queue account.|

documentation/kubernetes.md

@@ -33,12 +33,10 @@ spec:
         - name: ASPNETCORE_URLS
           value: http://+:80
         - name: DOTNET_DiagnosticPorts
-          value: /diag/port
+          value: /diag/port.sock
         volumeMounts:
         - mountPath: /diag
           name: diagvol
-        - mountPath: /dumps
-          name: dumpsvol
         resources:
           limits:
             cpu: 250m
@@ -50,12 +48,10 @@ spec:
         - name: ASPNETCORE_URLS
           value: http://+:81
         - name: DOTNET_DiagnosticPorts
-          value: /diag/port
+          value: /diag/port.sock
         volumeMounts:
         - mountPath: /diag
           name: diagvol
-        - mountPath: /dumps
-          name: dumpsvol
         resources:
           limits:
             cpu: 250m
@@ -70,18 +66,16 @@ spec:
         - name: DOTNETMONITOR_DiagnosticPort__ConnectionMode
           value: Listen
         - name: DOTNETMONITOR_DiagnosticPort__EndpointName
-          value: /diag/port
+          value: /diag/port.sock
         - name: DOTNETMONITOR_Storage__DumpTempFolder
-          value: /dumps
+          value: /diag/dumps
         # ALWAYS use the HTTPS form of the URL for deployments in production; the removal of HTTPS is done for
         # demonstration purposes only in this example. Please continue reading after this example for further details.
         - name: DOTNETMONITOR_Urls
           value: http://localhost:52323
         volumeMounts:
         - mountPath: /diag
           name: diagvol
-        - mountPath: /dumps
-          name: dumpsvol
         resources:
           requests:
             cpu: 50m
@@ -92,8 +86,6 @@ spec:
       volumes:
       - name: diagvol
         emptyDir: {}
-      - name: dumpsvol
-        emptyDir: {}
 ```
 
 ## Example Details