Monitoring and Instrumenting Microsoft® Azure with Azure agent

Installing Instana agent outside your Azure environment

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

You can specify the Azure Cloud endpoint that you want to use by modifying 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 that you want to use, these cloud configuration values are available: AzurePublicCloud, AzureChinaCloud, AzureUSGovernmentCloud, and AzureGermanCloud.

For more information on Azure Cloud endpoints, see Azure Cloud Endpoints.

Service Principal

To enable Azure monitoring the Azure Agent must be configured with a service principal that has at least reader permissions. The following steps describe how to create a service-principal account with read-access to your resources in Azure Portal.

1. Create a Service Principal by registering an Application in Azure Portal:

   1. Go to the Azure Management Portal and select Microsoft Entra ID.

   2. Copy the value of Tenant ID as it is required for configuring the Agent to connect to the Azure account.

   3. Select App registrations in the navigation pane.

   4. Create a new App by selecting New registration at the top of the App registrations tab.

   5. Type the name of your App and leave all other settings with their default values and select Register.

   6. Copy the value of Application (client) ID as it is required for configuring the Service Principal ID that the Agent uses to connect to the Azure account.

   7. Select the newly created App and select Certificates & secrets > New client secret in the navigation pane to create a new security key.

   8. Copy the value of the Key's Value and save it as it is required for configuring the Service Principal Secret that the Agent uses to connect to the Azure account.

      Client secret values cannot be viewed, except for immediately after creation. Be sure to save the secret when you create it and before you leave the page.

2. Grant reader permission for your service principal:

   1. In 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 select Reader. Select Next.

   4. In Members, enter the following data:

      • For Assign access to, select User, group, or service principal.
      • For Members, select Select members and then select your service principal from the list on the left.

   5. Select Next, and then select Review + assign.

3. Enable the Azure sensor in the agent's configuration.yaml file. A minimal sensor configuration looks like as follows:

   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"
   

The host agent must be restarted for the new configuration to be applied. After restarting, the agent can automatically discover supported remote-services on the specified subscription.

Proxy configuration

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

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

Both proxy_host and proxy_port fields must be defined to enable the Agent to route traffic through a proxy server.

After the proxy configuration is defined, the Instana agent must be restarted for changes to take place.

Filtering and tagging

The Azure Agent supports filtering of Azure services. The filtering of services and their instances is based on tags and the resource groups.

For more information on how to apply tags to Azure resources, see the Use tags to organize your Azure resources and management hierarchy documentation. For more information about defining resource groups in Azure, see What is Azure Resource Manager?.

The filtering is applied by modifying the agent configuration file /opt/instana/agent/etc/instana/configuration.yaml of the Azure Agent 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:

Filtering can also be applied at the level of the specific service; for more information, refer to the documentation of the specific services, which is linked from the Monitored Services section.

Multiple service principals

Azure Monitoring API comes with a limitation of 12000 requests per Service principal, which limits the number of services one Azure Agent can monitor. To overcome this limitation, you can create multiple service principals. For information on how to create service principles, refer to the How to: Use Azure PowerShell to create a service principal with a certificate documentation.

After the service principals are created, update the /opt/instana/agent/etc/instana/configuration.yaml file on the Azure agent host to look like 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"

Changes to these principal configurations are hot-reloaded by the Azure Agent, meaning that they take effect without needing to restart the Azure Agent.

Filtering API per API Management service

Sometimes there might be too many APIs per one API Management Service to collect the data from and to efficiently make sense from. To focus on only those important APIs, there is an additional configuration option to inclusively or exclusively filter API per name by defining a 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 this example, you can use complex regex expressions with or and and. If both inclusiveApiRegex and exclusiveApiRegex are defined, exclusiveApiRegex is prioritized.