ServiceControl Integration added additional events

.gitignore

@@ -106,3 +106,4 @@ src/scaffolding.config
 *.sln.iml
 PromotedSqlScripts/
 /samples/servicecontrol/adapter-mixed-transports/SCTransportAdapter_2/.audit-db
+*.audit-db/

menu/menu.yaml

@@ -1267,6 +1267,8 @@
   - Title: Integration
     Url: servicecontrol/integration
     Articles:
+    - Title: Azure Application Insights
+      Url: servicecontrol/app-insights-integration
     - Title: Plugins
       Url: servicecontrol/plugins
       Articles:

samples/servicecontrol/azure-monitor-events/ServiceControlContracts_3/EndpointsMonitor/AzureMonitorConnector.csproj

@@ -0,0 +1,14 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFrameworks>netcoreapp3.1;netcoreapp2.1;net48</TargetFrameworks>
+    <OutputType>Exe</OutputType>
+    <LangVersion>7.3</LangVersion>
+  </PropertyGroup>
+  <ItemGroup>
+    <PackageReference Include="Newtonsoft.Json" Version="13.*" />
+    <PackageReference Include="NServiceBus" Version="7.*" />
+    <PackageReference Include="NServiceBus.Newtonsoft.Json" Version="2.*" />
+    <PackageReference Include="ServiceControl.Contracts" Version="3.*" />
+    <PackageReference Include="Microsoft.ApplicationInsights" Version="2.14.*" />
+  </ItemGroup>
+</Project>

samples/servicecontrol/azure-monitor-events/ServiceControlContracts_3/EndpointsMonitor/CustomEventsHandler.cs

@@ -0,0 +1,119 @@
+using System.Collections.Generic;
+using System.Linq;
+using System.Threading.Tasks;
+using Microsoft.ApplicationInsights;
+using Microsoft.ApplicationInsights.DataContracts;
+using NServiceBus;
+using NServiceBus.Logging;
+using ServiceControl.Contracts;
+
+#region AzureMonitorConnectorEventsHandler
+
+public class MessageFailedHandler :
+    IHandleMessages<MessageFailed>
+{
+    readonly TelemetryClient telemetryClient;
+    static ILog log = LogManager.GetLogger<CustomEventsHandler>();
+
+    public MessageFailedHandler(TelemetryClient telemetryClient)
+    {
+        this.telemetryClient = telemetryClient;
+    }
+
+    public Task Handle(MessageFailed message, IMessageHandlerContext context)
+    {
+
+        telemetryClient.TrackEvent("Message Failed", new Dictionary<string, string>
+        {
+            {"MessageId", message.FailedMessageId},
+        });
+
+        log.Error($"Received ServiceControl 'MessageFailed' event for a {message.MessageType} with ID {message.FailedMessageId}.");
+        return Task.CompletedTask;
+    }
+}
+
+#endregion
+
+public class CustomEventsHandler :
+    IHandleMessages<HeartbeatStopped>,
+    IHandleMessages<HeartbeatRestored>,
+    IHandleMessages<FailedMessagesArchived>,
+    IHandleMessages<FailedMessagesUnArchived>,
+    IHandleMessages<MessageFailureResolvedByRetry>,
+    IHandleMessages<MessageFailureResolvedManually>
+{
+    readonly TelemetryClient telemetryClient;
+    static ILog log = LogManager.GetLogger<CustomEventsHandler>();
+
+    public CustomEventsHandler(TelemetryClient telemetryClient)
+    {
+        this.telemetryClient = telemetryClient;
+    }
+
+    public Task Handle(HeartbeatStopped message, IMessageHandlerContext context)
+    {
+        telemetryClient.TrackEvent("Heartbeat Stopped", new Dictionary<string, string>
+        {
+            {"EndpointName", message.EndpointName},
+        });
+
+        log.Warn($"Heartbeats from {message.EndpointName} have stopped.");
+        return Task.CompletedTask;
+    }
+
+    public Task Handle(HeartbeatRestored message, IMessageHandlerContext context)
+    {
+        telemetryClient.TrackEvent("Heartbeat Restored", new Dictionary<string, string>
+        {
+            {"EndpointName", message.EndpointName},
+        });
+
+        log.Info($"Heartbeats from {message.EndpointName} have been restored.");
+        return Task.CompletedTask;
+    }
+
+    public Task Handle(FailedMessagesArchived message, IMessageHandlerContext context)
+    {
+        telemetryClient.TrackEvent("Failed Messages Archived", new Dictionary<string, string>
+        {
+            {"MessagesIds", string.Join(",", message.FailedMessagesIds)},
+        });
+
+        log.Error($"Received ServiceControl 'FailedMessageArchived' with ID {message.FailedMessagesIds.FirstOrDefault()}.");
+        return Task.CompletedTask;
+    }
+
+    public Task Handle(FailedMessagesUnArchived message, IMessageHandlerContext context)
+    {
+        telemetryClient.TrackEvent("Failed Messages Unarchived", new Dictionary<string, string>
+        {
+            {"MessagesIds", string.Join(",", message.FailedMessagesIds)},
+        });
+
+        log.Error($"Received ServiceControl 'FailedMessagesUnArchived' MessagesCount: {message.FailedMessagesIds.Length}.");
+        return Task.CompletedTask;
+    }   
+
+    public Task Handle(MessageFailureResolvedByRetry message, IMessageHandlerContext context)
+    {
+        telemetryClient.TrackEvent("Message Failure Resolved By Retry", new Dictionary<string, string>
+        {
+            {"MessageId", message.FailedMessageId},
+        });
+
+        log.Error($"Received ServiceControl 'MessageFailureResolvedByRetry' with ID {message.FailedMessageId}.");
+        return Task.CompletedTask;
+    }
+
+    public Task Handle(MessageFailureResolvedManually message, IMessageHandlerContext context)
+    {
+        telemetryClient.TrackEvent("Message Failure Resolved Manually", new Dictionary<string, string>
+        {
+            {"MessageId", message.FailedMessageId},
+        });
+
+        log.Error($"Received ServiceControl 'MessageFailureResolvedManually'  with ID {message.FailedMessageId}.");
+        return Task.CompletedTask;
+    }
+}

samples/servicecontrol/azure-monitor-events/ServiceControlContracts_3/EndpointsMonitor/Program.cs

@@ -0,0 +1,57 @@
+using System;
+using System.Threading.Tasks;
+using Microsoft.ApplicationInsights;
+using Microsoft.ApplicationInsights.Extensibility;
+using NServiceBus;
+
+class Program
+{
+    static async Task Main()
+    {
+        Console.Title = "AzureMonitorConnector";
+        var endpointConfiguration = new EndpointConfiguration("AzureMonitorConnector");
+        endpointConfiguration.UseSerialization<NewtonsoftSerializer>();
+        endpointConfiguration.EnableInstallers();
+        endpointConfiguration.UsePersistence<InMemoryPersistence>();
+        endpointConfiguration.SendFailedMessagesTo("error");
+
+        var transport = endpointConfiguration.UseTransport<LearningTransport>();
+
+        var conventions = endpointConfiguration.Conventions();
+        conventions.DefiningEventsAs(
+            type =>
+            {
+                return typeof(IEvent).IsAssignableFrom(type) ||
+                       // include ServiceControl events
+                       type.Namespace != null &&
+                       type.Namespace.StartsWith("ServiceControl.Contracts");
+            });
+
+        #region AppInsightsSdkSetup
+
+        var envInstrumentationKey = "ApplicationInsightKey";
+        var instrumentationKey = Environment.GetEnvironmentVariable(envInstrumentationKey);
+
+        if (string.IsNullOrEmpty(instrumentationKey))
+        {
+            throw new Exception($"Environment variable '{envInstrumentationKey}' required.");
+        }
+
+        Console.WriteLine("Using application insights application key: {0}", instrumentationKey);
+
+
+        var telemetryConfiguration = new TelemetryConfiguration(instrumentationKey);
+        var telemetryClient = new TelemetryClient(telemetryConfiguration);
+
+        endpointConfiguration.RegisterComponents(cc => cc.RegisterSingleton(telemetryClient));
+
+        #endregion
+
+        var endpointInstance = await Endpoint.Start(endpointConfiguration)
+            .ConfigureAwait(false);
+        Console.WriteLine("Press any key to finish.");
+        Console.ReadKey();
+        await endpointInstance.Stop()
+            .ConfigureAwait(false);
+    }
+}

samples/servicecontrol/azure-monitor-events/ServiceControlContracts_3/EndpointsMonitoring.StartupProjects.txt

@@ -0,0 +1,3 @@
+EndpointsMonitor\AzureMonitorConnector.csproj
+NServiceBusEndpoint\NServiceBusEndpoint.csproj
+PlatformLauncher\PlatformLauncher.csproj

samples/servicecontrol/azure-monitor-events/ServiceControlContracts_3/EndpointsMonitoring.sln

@@ -0,0 +1,29 @@
+Microsoft Visual Studio Solution File, Format Version 12.00
+# Visual Studio Version 16
+VisualStudioVersion = 16.0.29728.190
+MinimumVisualStudioVersion = 15.0.26730.12
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "NServiceBusEndpoint", "NServiceBusEndpoint\NServiceBusEndpoint.csproj", "{814CEA2E-C5F5-4315-8FC3-8517B09C5931}"
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "AzureMonitorConnector", "EndpointsMonitor\AzureMonitorConnector.csproj", "{7A1C1662-35D1-4720-9F9F-4D23E9A57CE1}"
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "PlatformLauncher", "PlatformLauncher\PlatformLauncher.csproj", "{EED01887-FC83-4920-901E-2B52AFFDCBE6}"
+EndProject
+Global
+	GlobalSection(SolutionConfigurationPlatforms) = preSolution
+		Debug|Any CPU = Debug|Any CPU
+	EndGlobalSection
+	GlobalSection(ProjectConfigurationPlatforms) = postSolution
+		{814CEA2E-C5F5-4315-8FC3-8517B09C5931}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{814CEA2E-C5F5-4315-8FC3-8517B09C5931}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{7A1C1662-35D1-4720-9F9F-4D23E9A57CE1}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{7A1C1662-35D1-4720-9F9F-4D23E9A57CE1}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{EED01887-FC83-4920-901E-2B52AFFDCBE6}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{EED01887-FC83-4920-901E-2B52AFFDCBE6}.Debug|Any CPU.Build.0 = Debug|Any CPU
+	EndGlobalSection
+	GlobalSection(SolutionProperties) = preSolution
+		HideSolutionNode = FALSE
+	EndGlobalSection
+	GlobalSection(ExtensibilityGlobals) = postSolution
+		SolutionGuid = {E4ACEBE4-E83E-4146-9EFF-9E61728BD574}
+	EndGlobalSection
+EndGlobal

samples/servicecontrol/azure-monitor-events/sample.md

@@ -0,0 +1,99 @@
+---
+title: Monitor with ServiceControl events with Azure Application Insights
+summary: A sample showing how to monitor events published by ServiceControl with Azure Application Insights
+component: ServiceControlContracts
+reviewed: 2021-04-16
+related:
+ - servicecontrol
+ - servicecontrol/contracts
+ - servicecontrol/plugins
+ - samples/servicecontrol/monitoring3rdparty
+---
+
+This sample shows how to monitor a running NServiceBus system with ServiceControl and ServicePulse, as well as how to integrate with existing monitoring solutions. The sample uses the [Learning Transport](/transports/learning/) and a portable version of the Particular Service Platform tools. Installing ServiceControl is **not** required.
+
+include: platformlauncher-windows-required
+
+downloadbutton
+
+
+## Running the project
+
+Running the project will result in 3 console windows:
+
+1. **NServiceBusEndpoint**: The endpoint that represents the system being monitored.
+1. **AzureMonitorConnector**: The endpoint that subscribes to ServiceControl notification events and pushes them to Application Insights as custom telemetry events.
+1. **PlatformLauncher**: Runs an in-process version of ServiceControl and ServicePulse. When the ServiceControl instance is ready, a browser window will be launched displaying the ServicePulse Dashboard.
+
+The samples enables triggering two types of events:
+
+### Message Failures
+
+A `MessageFailed` event is emitted when processing a message fails and the message is moved to the error queue.
+
+To observe this in action, press <kbd>Enter</kbd> in the `NServiceBusEndpoint`console window. It will cause generate new `SimpleMessage` event that causes failure when processed.
+
+NOTE: The exception will cause the debugger to enter a breakpoint. It may be preferable to detach the debugger in order to better observe what's going on.
+
+When a `MessageFailed` event is received, the `AzureMonitorConnector` prints the following message in its console window: 
+
+```
+> Received ServiceControl 'MessageFailed' event for a SimpleMessage with ID 42f25e40-a673-61f3-a505-c8dee6d16f8a
+```
+
+The failed message can also be viewed in the ServicePulse browser window. Navigating to the failed message allows viewing more details about the message failure.
+
+
+### Heartbeat statuses
+
+The `HeartbeatStopped` event is published whenever an endpoint fails to send a control message within the expected interval. The `HeartbeatRestored` event is published whenever the endpoint successfully sends a control message again. 
+
+Note: The monitor must receive at least one control message before it can observe that the endpoint stopped responding.
+
+To observe this in action, stop the `NServiceBusEndpoint` process and wait up to 30 seconds. When a `HeartbeatStopped` event is received, the `AzureMonitorConnector` prints the following message to the console window:
+
+> `Heartbeat from NServiceBusEndpoint stopped.`
+
+Next, restart the `NServiceBusEndpoint` application and wait up to 30 seconds. When a `HeartbeatRestored` event is received, the `AzureMonitorConnector` prints the following message in its console window:
+
+> `Heartbeat from EndpointsMonitoring.NServiceBusEndpoint restored.`
+
+
+## Code walk-through 
+
+
+### NServiceBusEndpoint
+
+Retries are disabled in the sample for simplicity; messages are immediately moved to the error queue after a processing failure:
+
+snippet: DisableRetries
+
+The `MessageFailed` event is published whenever ServiceControl detects a new message in the error queue.
+
+In order to receive `HeartbeatStopped` and `HeartbeatRestored` events, the endpoint must use the [heartbeats plugin](/monitoring/heartbeats).
+
+NOTE: Heartbeat control messages are sent [every 30 seconds by default](/monitoring/heartbeats/legacy#configuration-time-to-live-ttl) so there will be up to a 30 second delay before ServiceControl realizes that it lost or restored connection with the endpoint.
+
+## Connect to Application Insights Azure Monitor
+
+To connect the sample code to Application Insights, the instrumentation key must be provided. The key gets loaded from `ApplicationInsightKey` environment variable. 
+
+The instrumentation key can be retrieved from the Azure Portal by locating the Application Insights instance, and then navigating to the Properties view.
+
+snippet: AppInsightsSdkSetup
+
+### AzureMonitorConnector
+
+In order to get notifications when the exposed ServiceControl events occur, create an NServiceBus endpoint. Next, reference the `ServiceControl.Contracts` NuGet package and implement a handler which handles specific ServiceControl events:
+
+snippet: AzureMonitorConnectorEventsHandler
+
+The handler creates a custom telemetry event and pushes it to Application Insights.
+
+## Notes on other transports
+
+This sample uses the [Learning Transport](/transports/learning/) in order to be portable with no transport dependencies.
+
+If adjusting this sample to use the [Azure Service Bus transport](/transports/azure-service-bus/legacy/), note that the subscribing endpoint must also use the same name shortening strategy as ServiceControl. See the [configuration settings](/transports/azure-service-bus/configuration.md#entity-creation), or if using the [legacy Azure Service Bus transport](), see its [sanitization strategy documentation](/transports/azure-service-bus/legacy/sanitization.md). 
+
+Same applies to [Azure Storage Queues](/transports/azure-storage-queues) name [sanitization strategy](/transports/azure-storage-queues/sanitization.md#backward-compatibility-with-versions-7-and-below)