Skip to content

Latest commit

 

History

History
170 lines (119 loc) · 12.1 KB

File metadata and controls

170 lines (119 loc) · 12.1 KB

Lombiq Hosting - Azure Application Insights for Orchard Core

Lombiq.Hosting.Azure.ApplicationInsights NuGet Lombiq.Hosting.Azure.ApplicationInsights.Tests.UI NuGet

About

This Orchard Core module enables easy integration of Azure Application Insights telemetry into Orchard. Just install the module, configure the instrumentation key from a configuration source (like the appsettings.json file) as normally for AI, and use the AddOrchardCoreApplicationInsightsTelemetry() extension method in your Web project's Program.cs file and collected data will start appearing in the Azure Portal. Check out the module's demo here, and the Orchard Harvest 2023 conference talk about automated QA in Orchard Core here. Note that this module has an Orchard 1 version in the dev-orchard-1 branch.

What kind of data is collected from the telemetry and available for inspection in the Azure Portal?

  • All usual AI data, including e.g. server-side requests, client-side page views, exceptions and other log entries, dependency calls (like web requests and database queries).
  • Information on background task executions (as dependency operations).
  • All telemetry is enriched with Orchard-specific and general details like user ID, user name, shell (tenant) name, user agent, IP address.

And all of this can be configured in depth. Extended configuration for built-in AI features is also available, like being able to turn SQL query command text collection on or off.

We at Lombiq also used this module for the following projects:

Do you want to quickly try out this project and see it in action? Check it out in our Open-Source Orchard Core Extensions full Orchard Core solution and also see our other useful Orchard Core-related open-source projects!

Documentation

Setup and basic configuration

Configure the built-in AI options as detailed in the AI docs in an ASP.NET Core configuration source like the appsettings.json file like below (everything in the root "ApplicationInsights" section is just built-in AI configuration). Do note that contrary to the standard AI configuration all log entries will be sent to AI by default. If you want to restrict that to just warnings, for example, you also have to add a corresponding LogLevel as demonstrated.

{
  "ApplicationInsights": {
    "ConnectionString": "your connection string comes here"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Warning",
      //...
    },
    "ApplicationInsights": {
      "LogLevel": {
        "Default": "Warning"
      }
    }
  },
  "OrchardCore": {
    //...
  }
}

Add the AI services to the service collection in your Web project's Program.cs file:

var builder = WebApplication.CreateBuilder(args);

var configuration = builder.Configuration;

builder.Services
    .AddOrchardCms(orchardCoreBuilder =>
    {
        orchardCoreBuilder.AddOrchardCoreApplicationInsightsTelemetry(configuration);
    });

Note that due to how the Application Insights .NET SDK works, telemetry can only be collected for the whole app at once; collecting telemetry separately for each tenant is not supported.

You can also use ConfigureAzureHostingDefaultsWithApplicationInsightsTelemetry instead; this sets up all the recommended hosting configuration with ConfigureAzureHostingDefaults from Lombiq Helpful Libraries - Orchard Core Libraries.

When using the full CMS approach of Orchard Core (i.e. not decoupled or headless) then the client-side tracking script will be automatically injected as a head script. Otherwise, you can create it with ITrackingScriptFactory.

Advanced configuration

The module has its own configuration for further options. These need to come from an ASP.NET Core configuration source as well but on the contrary to the basic settings for built-in AI options these need to be put under the OrchardCore section, into Lombiq_Hosting_Azure_ApplicationInsights:

{
  "ApplicationInsights": {
    "ConnectionString": "your connection string comes here"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Debug",
      //...
    }
  },
  "OrchardCore": {
    "Lombiq_Hosting_Azure_ApplicationInsights": {
      // Deprecated, do not use in new projects.
      "QuickPulseTelemetryModuleAuthenticationApiKey": "your API key here"
    }
  }
}

⚠ Use of QuickPulseTelemetryModuleAuthenticationApiKey is deprecated and will be officially unsupported starting 30 September 2025. See Entra Authentication for the Live Metrics control channel for more information.

See the ApplicationInsightsOptions class for all options and details.

Note that while telemetry from background tasks is collected in form of dependency operations it'll be collected even if EnableDependencyTrackingTelemetryModule is false.

If you use the security defaults from Lombiq Helpful Libraries - Orchard Core Libraries - Security, then the security headers necessary to use Application Insight's client-side tracking will automatically be added.

Entra Authentication for the Live Metrics control channel

Starting 30 September 2025, authentication using API keys is no longer supported for securing the Live Metrics control channel. Instead, you'll have to set up Entra Authentication for that. You may omit this if not needed; configuring the connection string is necessary in any case, and enough for simply collecting telemetry. Entra Authentication is only needed if you want to control the Live Metrics stream from the Azure Portal, like filtering telemetry.

Setting up Entra Authentication for Application Insights

⚠ This section is required if you have disabled Local Authentication on your AI resource, see the docs.

If you want to use Entra Authentication for Application Insights, or if you have disabled Local Authentication on your AI resource, you will have to set the EntraAuthenticationType option to the authentication type you want to use (ManagedIdentity or ServicePrincipal) in the Lombiq_Hosting_Azure_ApplicationInsights section of your configuration like below.

{
    "OrchardCore": {
        "Lombiq_Hosting_Azure_ApplicationInsights": {
            "EntraAuthenticationType": "ManagedIdentity"
        }
    }
}

⚠ Client-side tracking will currently fail with 401 Unauthorized if Local Authentication is disabled, see this bug report for the Application Insights .NET SDK. If you need client-side tracking, you will have to keep Local Authentication enabled on your AI resource for now.

To set up Entra Authentication for an application hosted on Azure you will have to set up a Managed Identity for the application and give it the Monitoring Metrics Publisher role (see more on assigning Azure roles here) to be able to publish metrics to AI. A managed identity will allow your app to authenticate with the Application Insights resource; see how to set it up for specific Azure services here. We recommend using the simpler system-assigned identity option, since then you can easily allow your app's identity to get a role under the Application Insights resource. Note that it might take a few minutes for the managed identity to work; until then, Live Metrics won't be available.

You can also use a service principal to authenticate. To set this up, you will have to provide the service principal credentials in the configuration. See the Service principal section for more information. This is also the only way to authenticate if you are using a non-Azure (or local) environment - or an Azure resource that does not support Managed Identities.

Once Entra Authentication is set up and the ConnectionString has been properly set, you should be able to control the Live Metrics stream from the Azure Portal, like filtering telemetry.

Service principal

Using a Service Principal is the only way to authenticate using Entra authentication if you are using a non-Azure (or local) environment.

If you want to use the Service Principal method for your Application Insights resource, you should set the EntraAuthenticationType option to ServicePrincipal in the Lombiq_Hosting_Azure_ApplicationInsights section of your configuration. To securely control the Live Metrics stream with Entra ID you will also have to provide the credentials of the service principal; to set this up, see the docs (you'll need to use the client secret authentication option).

{
  "OrchardCore": {
    "Lombiq_Hosting_Azure_ApplicationInsights": {
        "EntraAuthenticationType": "ServicePrincipal",
        "ServicePrincipalCredentials": {
            "TenantId": "your service principal tenant id",
            "ClientId": "your service principal client id",
            "ClientSecret": "your service principal client secret"
        }
    }
  }
}

For more information or scenarios not described here, see the official documentation.

Using collected data

All the collected data will be available in the Azure Portal as usual. Some custom properties will be added to all suitable telemetry with the "OrchardCore." prefix.

UI testing

The Lombiq.Hosting.Azure.ApplicationInsights.Tests.UI project contains UI test extension methods that you can call from your own test project. Check it out for details.

Contributing and support

Bug reports, feature requests, comments, questions, code contributions and love letters are warmly welcome. You can send them to us via GitHub issues and pull requests. Please adhere to our open-source guidelines while doing so.

This project is developed by Lombiq Technologies. Commercial-grade support is available through Lombiq.