Usage Reporting Setup

This document describes the settings required for collecting usage data to generate a usage report in ServicePulse.

Connection setup

In most scenarios, existing ServiceControl error instance connection settings will be used to establish a connection to the broker.

If there is a connection problem, specific usage settings can be provided as environment variables or directly in the ServiceControl.exe.config file.

The Usage Setup tab provides easy copy/paste functionality to obtain the required settings in the correct format, based on configuration type.

Refer to the Diagnostics tab to diagnose connection issues.

Azure Service Bus

ServiceControl reads the message counts for each queue from the namespace's metrics in Azure Monitor. This requires a Microsoft Entra identity, either a managed identity or a service principal, that has the Monitoring Reader role on the namespace. For a minimal permission set, see Minimum permissions.

Azure Service Bus supports two methods to authenticate: Microsoft Entra ID and shared access signatures (SAS). The method that the transport connection string uses determines which identity ServiceControl uses to read the metrics:

Transport connection string	Identity used to read the metrics	Settings required
Microsoft Entra ID authentication: a fully qualified namespace, or Authentication=Managed Identity	The same identity the transport uses	None
Shared access signature (SAS): Endpoint=sb://…;SharedAccessKeyName=…;SharedAccessKey=…	A separate service principal with a client secret	TenantId, ClientId, and ClientSecret

In both cases, setting SubscriptionId to the Azure subscription that contains the namespace is recommended. If it is not set, ServiceControl will use the first subscription that the identity can access, and report that it cannot find the namespace if the namespace is not in that first subscription.

When the transport uses Microsoft Entra ID authentication, assign the Monitoring Reader role on the namespace to the managed identity or service principal that the transport uses. TenantId, ClientId, and ClientSecret are not needed, and ServiceControl ignores them if they are set. With a fully qualified namespace, ServiceControl uses DefaultAzureCredential, so the identity can also be a service principal that authenticates with a certificate credential or a federated identity credential, configured through environment variables. For step-by-step certificate instructions, see Enabling Certificate Authentication.

When the transport uses a shared access signature (SAS), create a separate service principal for ServiceControl:

1. Create an app registration for ServiceControl, and note its Application (client) ID and Directory (tenant) ID.
2. Add a client secret to the app registration.
3. Assign the app registration's service principal the Monitoring Reader role on the namespace.
4. Configure TenantId, ClientId, and ClientSecret on the ServiceControl instance. See Settings.

The setup can be done via the portal or CLI.

Using Azure Portal

To use the Azure Portal:

1. Create the app registration (SAS only):
   • Navigate to: Home > App registrations
   • Select ➕ New registration
   • On the Overview page, note the Application (client) ID and Directory (tenant) ID
2. Add a client secret (SAS only):
   • Navigate to: > Certificates & secrets > Client secrets
   • Select ➕ New client secret, and note the secret's Value
3. Assign the Monitoring Reader role:
   • Navigate to: Home > Service Bus > > Access control (IAM)
   • Select: ➕ Add > Add role assignment
   • Enter:
     • Role: Monitoring Reader
     • Assign access to: User, group, or service principal for the app registration, or Managed identity for a managed identity
     • Members: Select ➕ Select members >
   • Select: Review + assign

Using Azure CLI

To use the Azure CLI or scripting:

# Set context first
az account set --subscription "YourAzureSubscriptionName"

# Create the app registration and its service principal (SAS only)
$applicationId = az ad app create --display-name ServiceControlUsageReporting --query appId --output tsv
az ad sp create --id $applicationId

# Add a client secret (SAS only). The output shows the ClientSecret (password) and TenantId (tenant)
az ad app credential reset --id $applicationId --append

# Store who gets the role: the app registration's ID, or the principal ID of the managed identity the transport uses
$assigneeId = $applicationId

# List subscription ID
az servicebus namespace list

# Store your Subscription ID
$subscriptionId = "<Your Subscription ID>"

# List resource group
az group list

# Store resource group and namespace names
$resourceGroupName = "<Your Resource Group Name>"
$namespaceName = "<Your Namespace Name>"

# Assign role to resource group
$scope = "/subscriptions/$subscriptionId/resourceGroups/$resourceGroupName"

# or to specific resource in resource group
$scope = "/subscriptions/$subscriptionId/resourceGroups/$resourceGroupName/providers/Microsoft.ServiceBus/namespaces/$namespaceName"
# end alternative

# Assign the Monitoring Reader role
az role assignment create --assignee $assigneeId --role "Monitoring Reader" --scope $scope

Settings

Refer to the Usage Reporting when using the Azure Service Bus transport section of the ServiceControl config file for an explanation of the Azure Service Bus-specific settings.

Minimum Permissions

The built-in role Monitoring Reader is sufficient to access the required Azure Service Bus metrics.

To restrict permissions to the minimal required set, create a custom role with the following permissions:

{
    "properties": {
        "roleName": "myrolename",
        "description": "",
        "assignableScopes": [
            "/subscriptions/xxxxxxxxxxxxxxxxxxxxx"
        ],
        "permissions": [
            {
                "actions": [
                    "Microsoft.ServiceBus/namespaces/read",
                    "Microsoft.ServiceBus/namespaces/providers/Microsoft.Insights/metricDefinitions/read",
                    "Microsoft.ServiceBus/namespaces/queues/read",
                    "Microsoft.Resources/subscriptions/read",
                    "Microsoft.Resources/subscriptions/resources/read",
                    "Microsoft.Insights/Metrics/Read"
                ],
                "notActions": [],
                "dataActions": [],
                "notDataActions": []
            }
        ]
    }
}

The Microsoft.ServiceBus permissions are required to read queue names and metric data from Azure Monitor. The Microsoft.Resources/subscriptions permissions are required in order to locate the Service Bus namespace within the Azure subscription. The Microsoft.Insights/Metrics/Read permissions are required to find the available metrics.

Amazon SQS

Settings

Refer to the Usage Reporting when using the Amazon SQS transport section of the ServiceControl config file for an explanation of the Amazon SQS-specific settings.

Minimum Permissions

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": "cloudwatch:GetMetricStatistics",
            "Resource": "*"
        },
        {
            "Sid": "VisualEditor1",
            "Effect": "Allow",
            "Action": "sqs:ListQueues",
            "Resource": "*"
        }
    ]
}

SQL Server

Settings

Refer to the Usage Reporting when using the SqlServer transport section of the ServiceControl config file for an explanation of the SQL Server-specific settings.

Minimum Permissions

User with rights to query [INFORMATION_SCHEMA].[COLUMNS] table.

PostgreSQL

Settings

Refer to the Usage Reporting when using the PostgreSQL transport section of the ServiceControl config file for an explanation of the PostgreSQL Server-specific settings.

Minimum Permissions

User with rights to query [INFORMATION_SCHEMA].[COLUMNS] table.

RabbitMQ

Settings

Refer to the Usage Reporting when using the RabbitMQ transport section of the ServiceControl config file for an explanation of the RabbitMQ-specific settings.

Querying of metrics from RabbitMQ requires access to the management API. If it is not possible to access the management API, e.g. due to security considerations, then use audit and monitoring data instead.

Minimum permissions

User with monitoring tag and read permission.

MSMQ

MSMQ does not support native querying of metrics. Use audit and monitoring data instead.

IBM MQ

IBM MQ does not support native querying of metrics. Use audit and monitoring data instead.

Azure Storage Queues

Azure Storage Queues does not support native querying of metrics. Use audit and monitoring data instead.

Audit and monitoring data

For transports that do not support querying broker-side metrics, ServiceControl generates the usage report from data collected by the Audit and/or Monitoring instances. To enable this:

• Auditing
  • install the Audit instance
  • configure auditing on all NServiceBus endpoints
• Monitoring
  • install the Monitoring instance
  • configure metrics on all NServiceBus endpoints

Diagnostics

The Diagnostics tab helps to diagnose any connection issues to the broker, as well as the audit and monitoring instances.

After making any setting changes, press the Refresh Connection Test button to verify whether the problem is resolved. If unable to resolve the issue, open a non-critical support case and include the diagnostic output.

Report masks

Sensitive information can be anonymized in the usage report. Endpoint, queue, and machine names sometimes contain customer, project, or product names; any such word can be masked so that it is redacted (obfuscated) before the report is generated and never leaves the environment.

Specify the words to anonymize in the Mask Report Data tab, one word per line. Every occurrence of a listed word is replaced in the generated report.