Monitoring and instrumenting Microsoft® Azure with Instana agent

The supported operating systems of the Microsoft® Azure sensor are consistent with host agents requirements. For more information, see the supported operating systems for each Instana host agent.

The Azure sensor version determines the subscription monitoring capabilities:

If you install the Instana agent outside your Azure environment, the agent uses the Azure public cloud endpoint by default.

To specify the Azure cloud endpoint that you want to use, modify the /opt/instana/agent/etc/instana/configuration.yaml agent configuration file as follows:

com.instana.plugin.azure:
  cloud: 'AzurePublicCloud'

Depending on the Azure cloud endpoint you want to use, you can select from these cloud configuration values: AzurePublicCloud, AzureChinaCloud, AzureUSGovernmentCloud, and AzureGermanCloud. For more information on Azure cloud endpoints, see Azure cloud endpoints.

Make sure that you have access to the following network endpoints for your selected Azure cloud environment:

To enable external monitoring of Azure services, configure your firewall to allow access to the above REST API endpoints based on your Azure cloud environment. Also, make sure that firewall access to the Log Analytics endpoint at https://api.loganalytics.io, which is required mainly for Databricks, regardless of Azure cloud endpoints.

Azure Resource Manager(ARM) API: Instana uses ARM API to discover the Azure resources within a subscription and collects configuration details such as names, types, locations, and tags. Instana also uses these details to understand how resources connect to each other.

ARM API endpoints typically use this pattern: https://{managementendpoint}/subscriptions/{subscriptionId}/...

Azure Monitor API: Instana uses the same Azure Monitor API, which shares ARM management endpoint, to collect monitoring data such as metrics, logs, and health information about Azure resources.

Azure Monitor API endpoints typically use this pattern: https://{managementendpoint}/subscriptions/{subscriptionId}/providers/Microsoft.Insights/...

To enable Azure monitoring, configure the host agent with a service principal that has at least reader permissions. You can create a service principal by using the Azure portal, Azure CLI, or Azure PowerShell.

By using the Azure portal:

1. In the Azure portal, select All services > General > Subscriptions.
2. On the subscriptions page, select your subscription, and then select Access control (IAM).
3. Select Add role assignment, and choose Reader. Click Next.
4. In the Members section, enter the following details:
   • For Assign access to, select user, group, or service principal.
   • For Members, click Select members, and then select your service principal from the list on the left.
5. Click Next, and then select Review + assign.

By using Azure CLI:

az ad sp create-for-rbac --name "<service-principal-name>" --role "Reader" --scopes /subscriptions/{subscription-id}

To verify reader role for a service principal by using Python script (optional), see the Python script.

com.instana.plugin.azure:
  enabled: true
  subscription: "Your-Subscription-Id"
  tenant: "Your-Tenant-Id"
  principals:
    - id: "Your-Service-Principal-Account-Id"
      secret: "Your-Service-Principal-Secret"

Restart the host agent to apply the new configuration. After the restart, the agent can automatically discover supported remote services on the specified subscription.

Azure Resource Manager (ARM) uses a token bucket–based throttling model, allowing short request bursts (for example, 250 reads) with a sustained refill rate (25 requests per seconds). Instana’s Azure monitoring collects metrics and resource data across subscriptions, which can generate a high number of API requests, especially in large environments. To overcome this limitation, you can create multiple service principals. For instructions on how to create service principles, see Use Azure PowerShell to create a service principal with a certificate.

After you create the service principals, update the /opt/instana/agent/etc/instana/configuration.yaml file on the Instana host agent as follows:

com.instana.plugin.azure:
  enabled: true
  subscription: "Your-Subscription-Id"
  tenant: "Your-Tenant-Id"
  principals:
    - id: "Your-Service-Principal-Account-Id-1"
      secret: "Your-Base64-encoded-Service-Principal-Secret-1"
    - id: "Your-Service-Principal-Account-Id-2"
      secret: "Your-Base64-encoded-Service-Principal-Secret-2"

To configure the Instana host agent to use a proxy, add the following settings to the agent configuration:

com.instana.plugin.azure:
  proxy_host: 'example.com' # proxy host name or ip address
  proxy_port: 3128 # proxy port
  proxy_username: 'username' # OPTIONAL: proxy username
  proxy_password: 'password' # OPTIONAL: proxy password
 

Define both the proxy_host and proxy_port fields to enable the agent to route traffic through a proxy server.

After you configure the proxy, restart the Instana agent for the changes to take place.

The Instana host agent supports filtering of Azure services. The filtering of services and their instances is based on tags and resource groups.

For more information on how to apply tags to Azure resources, see Use tags to organize your Azure resources and management hierarchy.

For more information about defining resource groups in Azure, see What is Azure Resource Manager?.

Apply filtering by modifying the Instana host agent configuration file at /opt/instana/agent/etc/instana/configuration.yaml as follows:

com.instana.plugin.azure:
  # Comma separated list of tags in key:value format
  include_tags:
  # Comma separated list of tags in key:value format
  exclude_tags:
  # Comma separated list of resource groups
  include_resource_groups:
  # Comma separated list of resource groups
  exclude_resource_groups:
 

You can also apply filtering at the level of specific services. For more information, see the Monitored Services section for details on specific services.

When you have too many APIs under one API Management service, it can be challenging to collect and analyze the data effectively. To focus on important APIs, configure API filtering by defining an inclusive or exclusive regular expression as shown in the following example YAML file:

com.instana.plugin.azure.apimanagement:
  monitorApiList:
    - serviceName: 'robotShopApiGateway'
      #inclusiveApiRegex: '^(API name 1|API name 2)$'
      exclusiveApiRegex: '^(API name 1|API name 2)$'
 

As shown in the preceding example, you can use complex regex expressions with or and and logic. If you define both inclusiveApiRegex and exclusiveApiRegex, the host agent prioritizes exclusiveApiRegex.

To monitor a very large number of resources, you can either configure multiple subscriptions per agent or deploy multiple agents, each with a single subscription. In both cases, ensure that subscriptions are not shared across agents and remain mutually exclusive.

• All subscriptions must belong to the same Azure tenant.
• Each subscription requires at least one service principal with Reader role permissions.

To monitor multiple Azure subscriptions, configure the Instana host agent with the subscription and service principal details in the /opt/instana/agent/etc/instana/configuration.yaml file:

com.instana.plugin.azure:
  enabled: true
  tenant: 'Your-Tenant-Id'
  subscriptions:
    - id: 'Subscription-Id-1'
      principals:
        - id: 'Service-Principal-Client-Id-1'
          secret: 'Service-Principal-Client-Secret-1'
        - id: 'Service-Principal-Client-Id-2'
          secret: 'Service-Principal-Client-Secret-2'
    - id: 'Subscription-Id-2'
      principals:
        - id: 'Service-Principal-Client-Id-3'
          secret: 'Service-Principal-Client-Secret-3'
        - id: 'Service-Principal-Client-Id-4'
          secret: 'Service-Principal-Client-Secret-4'

Each subscription can have multiple service principals configured to distribute API load.

• Service principal planning: Create at least 2-3 service principals per subscription to avoid throttling when monitoring a large number of resources.
• Resource distribution: When monitoring a large number of resources, consider distributing them across multiple subscriptions and different regions as described in the Azure Documentation.
• Required permissions: Ensure that each service principal has at least the reader role access to the subscription. Service principals without required permissions are skipped during the API client configuration.

The following observations outline the validated performance limits for the Instana agent when monitoring synthetic Azure resources. These results are based on stress testing on Ubuntu 24.04 to determine the safe limit for stable operations.