maskati · February 17, 2025 16:19
diff --git a/#dotnet-remote-diagnostics.md b/#dotnet-remote-diagnostics.md
diff --git a/dotnet-remote-diagnostics.bicep b/dotnet-remote-diagnostics.bicep
 param location string = resourceGroup().location

 // storage account to store dotnet-monitor egressed artifacts
 resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' = {
  name: 'st${uniqueString(resourceGroup().id)}'
  location: location
  sku: {
    name: 'Standard_LRS'
  }
  kind: 'StorageV2'
  resource blobServices 'blobServices' = {
    name: 'default'
    resource monitorEgressContainer 'containers' = {
      name: 'monitoregress'
    }
  }
  resource fileServices 'fileServices' = {
    name: 'default'
    resource diagnosticsShare 'shares' = {
      name: 'diagnosticsshare'
    }
  }
 }

 resource containerAppEnvironment 'Microsoft.App/managedEnvironments@2024-03-01' = {
  name: 'cae-containerapp'
  location: location
  properties: {
    appLogsConfiguration: {
      destination: null
    }
    workloadProfiles: [
      {
        name: 'Consumption'
        workloadProfileType: 'Consumption'
      }
    ]
  }
  resource diagnosticsStorage 'storages' = {
    name: 'diagnosticsstorage'
    properties: {
      azureFile: {
        accountName: storageAccount.name
        shareName: storageAccount::fileServices::diagnosticsShare.name
        accountKey: storageAccount.listKeys().keys[0].value
        accessMode: 'ReadWrite'
      }
    }
  }
 }

 // identity used to dotnet-monitor to access storage account
 resource identity 'Microsoft.ManagedIdentity/userAssignedIdentities@2023-01-31' = {
  name: 'id-containerapp'
  location: location
 }

 // permission to write artifacts to storage account
 var storageBlobDataContributorRoleDefinitionId = subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'ba92f5b4-2d11-453d-a403-e96b0029c9fe')
 var storageBlobDataContributorRoleAssignmentName = guid(identity.id, storageAccount.id, storageBlobDataContributorRoleDefinitionId)
 resource storageBlobDataContributorRoleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: storageBlobDataContributorRoleAssignmentName
  scope: storageAccount
  properties: {
    roleDefinitionId: storageBlobDataContributorRoleDefinitionId
    principalType: 'ServicePrincipal'
    principalId: identity.properties.principalId
  }
 }

 resource containerApp 'Microsoft.App/containerApps@2024-03-01' = {
  name: 'cap-containerapp'
  location: location
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '${identity.id}': {}
    }
  }
  properties: {
    environmentId: containerAppEnvironment.id
    workloadProfileName: 'Consumption'
    configuration: {
      ingress: {
        external: true
        allowInsecure: false
        transport: 'auto'
        // https://learn.microsoft.com/en-us/dotnet/core/compatibility/containers/8.0/aspnet-port
        targetPort: 8080
      }
    }
    template: {
      volumes: [
        // replica-scoped ephemeral storage
        // used to create diagnostic port ipc socket between the aspnetapp and dotnet-monitor containers
        {
          name: 'dotnet-monitor-volume'
          storageType: 'EmptyDir'
        }
        {
          name: 'tmp-volume'
          storageType: 'EmptyDir'
        }
        {
          name: 'diagnostics-volume'
          storageType: 'AzureFile'
          storageName: containerAppEnvironment::diagnosticsStorage.name
        }
      ]
      containers: [
        // application container
        {
          name: 'aspnetapp'
          // https://github.com/dotnet/dotnet-docker/blob/main/documentation/distroless.md
          // https://mcr.microsoft.com/en-us/artifact/mar/dotnet/samples/about
          image: 'mcr.microsoft.com/dotnet/samples:aspnetapp-chiseled-8.0'
          env: [
            // connect to dotnet-monitor listener on shared socket
            // https://learn.microsoft.com/en-us/dotnet/core/diagnostics/diagnostic-port#configure-additional-diagnostic-ports
            {
              name: 'DOTNET_DiagnosticPorts'
              value: '/dotnet-monitor/dotnet-monitor.sock'
            }
          ]
          volumeMounts: [
            {
              volumeName: 'dotnet-monitor-volume'
              mountPath: '/dotnet-monitor'
            }
            {
              volumeName: 'tmp-volume'
              mountPath: '/tmp'
            }
          ]
          resources: {
            cpu: json('0.25')
            memory: '0.5Gi'
          }
        }
        // monitor container
        {
          name: 'monitor'
          // https://learn.microsoft.com/en-us/dotnet/core/diagnostics/dotnet-monitor
          // https://github.com/dotnet/dotnet-monitor
          // https://mcr.microsoft.com/en-us/artifact/mar/dotnet/monitor/about
          image: 'mcr.microsoft.com/dotnet/monitor:8.0'
          env: [
            // if DOTNETMONITOR_DiagnosticPort__ConnectionMode is Listen and DOTNETMONITOR_Storage__DefaultSharedPath is set
            // no need to configure DOTNETMONITOR_DiagnosticPort__EndpointName
            // the combination automatically creates a Unix Domain Socket named dotnet-monitor.sock under the default shared path
            // => in this case /dotnet-monitor/dotnet-monitor.sock
            // https://github.com/dotnet/dotnet-monitor/blob/37d10517d7f85294634a0404fabf61fb3532fb0d/documentation/configuration/diagnostic-port-configuration.md
            {
              name: 'DOTNETMONITOR_DiagnosticPort__ConnectionMode'
              value: 'Listen'
            }
            // https://github.com/dotnet/dotnet-monitor/blob/37d10517d7f85294634a0404fabf61fb3532fb0d/documentation/configuration/storage-configuration.md#default-shared-path
            {
              name: 'DOTNETMONITOR_Storage__DefaultSharedPath'
              value: '/dotnet-monitor'
            }
            // bindings for the diagnostics api, http ok on internal endpoint
            {
              name: 'DOTNETMONITOR_Urls'
              value: 'http://+:52323'
            }
            // binds to metric urls that only expose the /metrics endpoint
            // unlike the other endpoints the metrics urls do not require authentication as metrics generally safe
            // https://github.com/dotnet/dotnet-monitor/blob/37d10517d7f85294634a0404fabf61fb3532fb0d/documentation/configuration/metrics-configuration.md#metrics-urls
            {
              name: 'DOTNETMONITOR_Metrics__Endpoints'
              value: 'http://+:52325'
            }
            // use non-json logging to stdout
            // https://learn.microsoft.com/en-us/dotnet/core/extensions/console-log-formatter#simple
            {
              name: 'Logging__Console__FormatterName'
              value: 'simple'
            }
            // https://github.com/dotnet/dotnet-monitor/blob/37d10517d7f85294634a0404fabf61fb3532fb0d/documentation/configuration/egress-configuration.md
            {
              name: 'DOTNETMONITOR_Egress__AzureBlobStorage__monitorBlob__accountUri'
              value: storageAccount.properties.primaryEndpoints.blob
            }
            {
              name: 'DOTNETMONITOR_Egress__AzureBlobStorage__monitorBlob__containerName'
              value: storageAccount::blobServices::monitorEgressContainer.name
            }
            {
              name: 'DOTNETMONITOR_Egress__AzureBlobStorage__monitorBlob__managedIdentityClientId'
              value: identity.properties.clientId
            }
            // Enable Call Stacks and Exceptions History
            // Some features of dotnet monitor require loading libraries into target applications
            // https://github.com/dotnet/dotnet-monitor/blob/37d10517d7f85294634a0404fabf61fb3532fb0d/documentation/configuration/in-process-features-configuration.md
            {
              name: 'DOTNETMONITOR_InProcessFeatures__Enabled'
              value: 'true'
            }
            // Captures parameters for one or more methods each time they are called
            // This feature is currently marked as experimental and so needs to be explicitly enabled
            // https://github.com/dotnet/dotnet-monitor/blob/37d10517d7f85294634a0404fabf61fb3532fb0d/documentation/api/parameters.md#enabling
            {
              name: 'DOTNETMONITOR_InProcessFeatures__ParameterCapturing__Enabled'
              value: 'true'
            }
          ]
          // https://github.com/dotnet/dotnet-monitor/blob/3498f108bd0248e4f7aeb649364e3e02fed6fb94/documentation/compatibility/7.0/README.md#docker-container-entrypoint-split
          // https://learn.microsoft.com/en-us/dotnet/core/diagnostics/dotnet-monitor#dotnet-monitor-collect
          args: [
            'collect'
            // requires users to specify an egress provider by preventing the default HTTP response for logs, traces, dumps, gcdumps, and live metrics
            // https://github.com/dotnet/dotnet-monitor/blob/37d10517d7f85294634a0404fabf61fb3532fb0d/documentation/egress.md#disabling-http-egress
            '--no-http-egress'
            // do not require authentication => do not use in production
            // https://github.com/dotnet/dotnet-monitor/blob/37d10517d7f85294634a0404fabf61fb3532fb0d/documentation/authentication.md#disabling-authentication
            '--no-auth'
          ]
          volumeMounts: [
            {
              volumeName: 'dotnet-monitor-volume'
              mountPath: '/dotnet-monitor'
            }
          ]
          // https://github.com/dotnet/dotnet-monitor/blob/3498f108bd0248e4f7aeb649364e3e02fed6fb94/documentation/docker-compose.md#recommended-container-limits
          resources: {
            cpu: json('0.25')
            memory: '0.5Gi'
          }
        }
        // interactive shell container
        {
          name: 'azurelinux'
          // https://mcr.microsoft.com/en-us/artifact/mar/azurelinux/base/core/about
          image: 'mcr.microsoft.com/azurelinux/base/core:3.0'
          env: [
            {
              name: 'PATH'
              value: '/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/root/.dotnet/tools'
            }
          ]
          command: [
            '/bin/bash'
            '-c'
            join([
              'tdnf update -y && tdnf -y install ca-certificates jq dotnet-sdk-9.0 powershell'
              // https://learn.microsoft.com/en-us/dotnet/core/diagnostics/dotnet-counters#install
              'dotnet tool install --global dotnet-counters'
              // https://learn.microsoft.com/en-us/dotnet/core/diagnostics/dotnet-trace#install
              'dotnet tool install --global dotnet-trace'
              'sleep infinity'
            ], '\n')
          ]
          volumeMounts: [
            {
              volumeName: 'dotnet-monitor-volume'
              mountPath: '/dotnet-monitor'
            }
            {
              volumeName: 'tmp-volume'
              mountPath: '/tmp'
            }
            {
              volumeName: 'diagnostics-volume'
              mountPath: '/dotnet-diagnostics'
            }
          ]
          resources: {
            cpu: json('0.25')
            memory: '0.5Gi'
          }
        }
      ]
      scale: {
        minReplicas: 1
        maxReplicas: 1
      }
    }
  }
 }
Tool	Description	Supports remote diagnostics
diagnostic tools	Command line utilities, which connect to your .NET process to perform diagnostics.	Limited support. `dotnet-counters` and `dotnet-trace` support remote diagnostics with shared diagnostic port socket (for example shared `/tmp` for default port). Currently other utilities such as `dotnet-dump` require shared process namespace. There is a PR to add such support to `dotnet-dump` and feature request to expand support to other tools.
dotnet monitor	Hosts an HTTP API exposing diagnostic functionality targeting your .NET process.	Supported with shared diagnostic port socket (for example shared `/tmp` for default port). Requires a fair amount of configuration. Connecting to an existing .NET process currently requires knowing and configuring the default diagnostic port socket. There is a feature request to support process discovery. Advanced in-process features such as call stacks and exception monitoring require listen mode and target application configuration, since these features load additional libraries into the target application.
diagnostics client library	Library on which diagnostic tools and dotnet monitor are based, but which can also be used to develop your own diagnostic tooling.	Supported in the latest release with shared diagnostic port socket (for example shared `/tmp` for default port). Version 0.2.607501 has added support for creating a `DiagnosticClient` by connecting to a diagnostic port, which removes the shared process namespace requirement (a related bugfix has not yet been released which somewhat changes the call API). This means that we can remotely connect to a default diagnostics port without a shared process namespace (technically this was previously possible, but required complex implementation and use of reflection to invoke internal members).
	param location string = resourceGroup().location

	// storage account to store dotnet-monitor egressed artifacts
	resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' = {
	name: 'st${uniqueString(resourceGroup().id)}'
	location: location
	sku: {
	name: 'Standard_LRS'
	}
	kind: 'StorageV2'
	resource blobServices 'blobServices' = {
	name: 'default'
	resource monitorEgressContainer 'containers' = {
	name: 'monitoregress'
	}
	}
	resource fileServices 'fileServices' = {
	name: 'default'
	resource diagnosticsShare 'shares' = {
	name: 'diagnosticsshare'
	}
	}
	}

	resource containerAppEnvironment 'Microsoft.App/managedEnvironments@2024-03-01' = {
	name: 'cae-containerapp'
	location: location
	properties: {
	appLogsConfiguration: {
	destination: null
	}
	workloadProfiles: [
	{
	name: 'Consumption'
	workloadProfileType: 'Consumption'
	}
	]
	}
	resource diagnosticsStorage 'storages' = {
	name: 'diagnosticsstorage'
	properties: {
	azureFile: {
	accountName: storageAccount.name
	shareName: storageAccount::fileServices::diagnosticsShare.name
	accountKey: storageAccount.listKeys().keys[0].value
	accessMode: 'ReadWrite'
	}
	}
	}
	}

	// identity used to dotnet-monitor to access storage account
	resource identity 'Microsoft.ManagedIdentity/userAssignedIdentities@2023-01-31' = {
	name: 'id-containerapp'
	location: location
	}

	// permission to write artifacts to storage account
	var storageBlobDataContributorRoleDefinitionId = subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'ba92f5b4-2d11-453d-a403-e96b0029c9fe')
	var storageBlobDataContributorRoleAssignmentName = guid(identity.id, storageAccount.id, storageBlobDataContributorRoleDefinitionId)
	resource storageBlobDataContributorRoleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
	name: storageBlobDataContributorRoleAssignmentName
	scope: storageAccount
	properties: {
	roleDefinitionId: storageBlobDataContributorRoleDefinitionId
	principalType: 'ServicePrincipal'
	principalId: identity.properties.principalId
	}
	}

	resource containerApp 'Microsoft.App/containerApps@2024-03-01' = {
	name: 'cap-containerapp'
	location: location
	identity: {
	type: 'UserAssigned'
	userAssignedIdentities: {
	'${identity.id}': {}
	}
	}
	properties: {
	environmentId: containerAppEnvironment.id
	workloadProfileName: 'Consumption'
	configuration: {
	ingress: {
	external: true
	allowInsecure: false
	transport: 'auto'
	// https://learn.microsoft.com/en-us/dotnet/core/compatibility/containers/8.0/aspnet-port
	targetPort: 8080
	}
	}
	template: {
	volumes: [
	// replica-scoped ephemeral storage
	// used to create diagnostic port ipc socket between the aspnetapp and dotnet-monitor containers
	{
	name: 'dotnet-monitor-volume'
	storageType: 'EmptyDir'
	}
	{
	name: 'tmp-volume'
	storageType: 'EmptyDir'
	}
	{
	name: 'diagnostics-volume'
	storageType: 'AzureFile'
	storageName: containerAppEnvironment::diagnosticsStorage.name
	}
	]
	containers: [
	// application container
	{
	name: 'aspnetapp'
	// https://github.com/dotnet/dotnet-docker/blob/main/documentation/distroless.md
	// https://mcr.microsoft.com/en-us/artifact/mar/dotnet/samples/about
	image: 'mcr.microsoft.com/dotnet/samples:aspnetapp-chiseled-8.0'
	env: [
	// connect to dotnet-monitor listener on shared socket
	// https://learn.microsoft.com/en-us/dotnet/core/diagnostics/diagnostic-port#configure-additional-diagnostic-ports
	{
	name: 'DOTNET_DiagnosticPorts'
	value: '/dotnet-monitor/dotnet-monitor.sock'
	}
	]
	volumeMounts: [
	{
	volumeName: 'dotnet-monitor-volume'
	mountPath: '/dotnet-monitor'
	}
	{
	volumeName: 'tmp-volume'
	mountPath: '/tmp'
	}
	]
	resources: {
	cpu: json('0.25')
	memory: '0.5Gi'
	}
	}
	// monitor container
	{
	name: 'monitor'
	// https://learn.microsoft.com/en-us/dotnet/core/diagnostics/dotnet-monitor
	// https://github.com/dotnet/dotnet-monitor
	// https://mcr.microsoft.com/en-us/artifact/mar/dotnet/monitor/about
	image: 'mcr.microsoft.com/dotnet/monitor:8.0'
	env: [
	// if DOTNETMONITOR_DiagnosticPort__ConnectionMode is Listen and DOTNETMONITOR_Storage__DefaultSharedPath is set
	// no need to configure DOTNETMONITOR_DiagnosticPort__EndpointName
	// the combination automatically creates a Unix Domain Socket named dotnet-monitor.sock under the default shared path
	// => in this case /dotnet-monitor/dotnet-monitor.sock
	// https://github.com/dotnet/dotnet-monitor/blob/37d10517d7f85294634a0404fabf61fb3532fb0d/documentation/configuration/diagnostic-port-configuration.md
	{
	name: 'DOTNETMONITOR_DiagnosticPort__ConnectionMode'
	value: 'Listen'
	}
	// https://github.com/dotnet/dotnet-monitor/blob/37d10517d7f85294634a0404fabf61fb3532fb0d/documentation/configuration/storage-configuration.md#default-shared-path
	{
	name: 'DOTNETMONITOR_Storage__DefaultSharedPath'
	value: '/dotnet-monitor'
	}
	// bindings for the diagnostics api, http ok on internal endpoint
	{
	name: 'DOTNETMONITOR_Urls'
	value: 'http://+:52323'
	}
	// binds to metric urls that only expose the /metrics endpoint
	// unlike the other endpoints the metrics urls do not require authentication as metrics generally safe
	// https://github.com/dotnet/dotnet-monitor/blob/37d10517d7f85294634a0404fabf61fb3532fb0d/documentation/configuration/metrics-configuration.md#metrics-urls
	{
	name: 'DOTNETMONITOR_Metrics__Endpoints'
	value: 'http://+:52325'
	}
	// use non-json logging to stdout
	// https://learn.microsoft.com/en-us/dotnet/core/extensions/console-log-formatter#simple
	{
	name: 'Logging__Console__FormatterName'
	value: 'simple'
	}
	// https://github.com/dotnet/dotnet-monitor/blob/37d10517d7f85294634a0404fabf61fb3532fb0d/documentation/configuration/egress-configuration.md
	{
	name: 'DOTNETMONITOR_Egress__AzureBlobStorage__monitorBlob__accountUri'
	value: storageAccount.properties.primaryEndpoints.blob
	}
	{
	name: 'DOTNETMONITOR_Egress__AzureBlobStorage__monitorBlob__containerName'
	value: storageAccount::blobServices::monitorEgressContainer.name
	}
	{
	name: 'DOTNETMONITOR_Egress__AzureBlobStorage__monitorBlob__managedIdentityClientId'
	value: identity.properties.clientId
	}
	// Enable Call Stacks and Exceptions History
	// Some features of dotnet monitor require loading libraries into target applications
	// https://github.com/dotnet/dotnet-monitor/blob/37d10517d7f85294634a0404fabf61fb3532fb0d/documentation/configuration/in-process-features-configuration.md
	{
	name: 'DOTNETMONITOR_InProcessFeatures__Enabled'
	value: 'true'
	}
	// Captures parameters for one or more methods each time they are called
	// This feature is currently marked as experimental and so needs to be explicitly enabled
	// https://github.com/dotnet/dotnet-monitor/blob/37d10517d7f85294634a0404fabf61fb3532fb0d/documentation/api/parameters.md#enabling
	{
	name: 'DOTNETMONITOR_InProcessFeatures__ParameterCapturing__Enabled'
	value: 'true'
	}
	]
	// https://github.com/dotnet/dotnet-monitor/blob/3498f108bd0248e4f7aeb649364e3e02fed6fb94/documentation/compatibility/7.0/README.md#docker-container-entrypoint-split
	// https://learn.microsoft.com/en-us/dotnet/core/diagnostics/dotnet-monitor#dotnet-monitor-collect
	args: [
	'collect'
	// requires users to specify an egress provider by preventing the default HTTP response for logs, traces, dumps, gcdumps, and live metrics
	// https://github.com/dotnet/dotnet-monitor/blob/37d10517d7f85294634a0404fabf61fb3532fb0d/documentation/egress.md#disabling-http-egress
	'--no-http-egress'
	// do not require authentication => do not use in production
	// https://github.com/dotnet/dotnet-monitor/blob/37d10517d7f85294634a0404fabf61fb3532fb0d/documentation/authentication.md#disabling-authentication
	'--no-auth'
	]
	volumeMounts: [
	{
	volumeName: 'dotnet-monitor-volume'
	mountPath: '/dotnet-monitor'
	}
	]
	// https://github.com/dotnet/dotnet-monitor/blob/3498f108bd0248e4f7aeb649364e3e02fed6fb94/documentation/docker-compose.md#recommended-container-limits
	resources: {
	cpu: json('0.25')
	memory: '0.5Gi'
	}
	}
	// interactive shell container
	{
	name: 'azurelinux'
	// https://mcr.microsoft.com/en-us/artifact/mar/azurelinux/base/core/about
	image: 'mcr.microsoft.com/azurelinux/base/core:3.0'
	env: [
	{
	name: 'PATH'
	value: '/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/root/.dotnet/tools'
	}
	]
	command: [
	'/bin/bash'
	'-c'
	join([
	'tdnf update -y && tdnf -y install ca-certificates jq dotnet-sdk-9.0 powershell'
	// https://learn.microsoft.com/en-us/dotnet/core/diagnostics/dotnet-counters#install
	'dotnet tool install --global dotnet-counters'
	// https://learn.microsoft.com/en-us/dotnet/core/diagnostics/dotnet-trace#install
	'dotnet tool install --global dotnet-trace'
	'sleep infinity'
	], '\n')
	]
	volumeMounts: [
	{
	volumeName: 'dotnet-monitor-volume'
	mountPath: '/dotnet-monitor'
	}
	{
	volumeName: 'tmp-volume'
	mountPath: '/tmp'
	}
	{
	volumeName: 'diagnostics-volume'
	mountPath: '/dotnet-diagnostics'
	}
	]
	resources: {
	cpu: json('0.25')
	memory: '0.5Gi'
	}
	}
	]
	scale: {
	minReplicas: 1
	maxReplicas: 1
	}
	}
	}
	}