Log Analytics virtual machine extension for Linux

  • Article

Overview

Azure Monitor Logs provides monitoring, alerting, and alert remediation capabilities across cloud and on-premises assets. The Log Analytics virtual machine extension for Linux is published and supported by Azure. The extension installs the Log Analytics agent on Azure virtual machines, and enrolls virtual machines into an existing Log Analytics workspace. This document details the supported platforms, configurations, and deployment options for the Log Analytics virtual machine extension for Linux.

Note

Azure Arc-enabled servers enables you to deploy, remove, and update the Log Analytics agent VM extension to non-Azure Windows and Linux machines, simplifying the management of your hybrid machine through their lifecycle. For more information, see VM extension management with Azure Arc-enabled servers.

Prerequisites

Operating system

For details about the supported Linux distributions, refer to the Overview of Azure Monitor agents article.

Agent and VM Extension version

The following table provides a mapping of the version of the Log Analytics VM extension and Log Analytics agent bundle for each release. A link to the release notes for the Log Analytics agent bundle version is included. Release notes include details on bug fixes and new features available for a given agent release.

Log Analytics Linux VM extension version Log Analytics Agent bundle version
1.19.0 1.19.0
1.18.1 1.18.1
1.17.2 1.17.2
1.17.1 1.17.1
1.16.0 1.16.0
1.14.23 1.14.23
1.14.20 1.14.20
1.14.19 1.14.19
1.14.16 1.14.16
1.14.13 1.14.13
1.14.11 1.14.11
1.14.9 1.14.9
1.13.40 1.13.40
1.13.35 1.13.35
1.13.33 1.13.33
1.13.27 1.13.27
1.13.15 1.13.9-0
1.12.25 1.12.15-0
1.11.15 1.11.0-9
1.10.0 1.10.0-1
1.9.1 1.9.0-0
1.8.11 1.8.1-256
1.8.0 1.8.0-256
1.7.9 1.6.1-3
1.6.42.0 1.6.0-42
1.4.60.2 1.4.4-210
1.4.59.1 1.4.3-174
1.4.58.7 14.2-125
1.4.56.5 1.4.2-124
1.4.55.4 1.4.1-123
1.4.45.3 1.4.1-45
1.4.45.2 1.4.0-45
1.3.127.5 1.3.5-127
1.3.127.7 1.3.5-127
1.3.18.7 1.3.4-15

Microsoft Defender for Cloud

Microsoft Defender for Cloud automatically provisions the Log Analytics agent and connects it to a default Log Analytics workspace created by Defender for Cloud in your Azure subscription. If you are using Microsoft Defender for Cloud, do not run through the steps in this document. Doing so overwrites the configured workspace and breaks the connection with Microsoft Defender for Cloud.

Internet connectivity

The Log Analytics agent extension for Linux requires that the target virtual machine is connected to the internet.

Extension schema

The following JSON shows the schema for the Log Analytics agent extension. The extension requires the workspace ID and workspace key from the target Log Analytics workspace; these values can be found in your Log Analytics workspace in the Azure portal. Because the workspace key should be treated as sensitive data, it should be stored in a protected setting configuration. Azure VM extension protected setting data is encrypted, and only decrypted on the target virtual machine. Note that workspaceId and workspaceKey are case-sensitive.

Note

Because the Container Monitoring solution is being retired, the following documentation uses the optional setting "skipDockerProviderInstall": true.

{
  "type": "Microsoft.Compute/virtualMachines/extensions",
  "name": "OMSExtension",
  "apiVersion": "2018-06-01",
  "location": "<location>",
  "dependsOn": [
    "[concat('Microsoft.Compute/virtualMachines/', <vm-name>)]"
  ],
  "properties": {
    "publisher": "Microsoft.EnterpriseCloud.Monitoring",
    "type": "OmsAgentForLinux",
    "typeHandlerVersion": "1.16",
    "autoUpgradeMinorVersion": true,
    "settings": {
      "workspaceId": "myWorkspaceId",
      "skipDockerProviderInstall": true
    },
    "protectedSettings": {
      "workspaceKey": "myWorkSpaceKey"
    }
  }
}

Note

The schema above assumes that it will be placed at the root level of the template. If you put it inside the virtual machine resource in the template, the type and name properties should be changed, as described further down.

Property values

Name Value / Example
apiVersion 2018-06-01
publisher Microsoft.EnterpriseCloud.Monitoring
type OmsAgentForLinux
typeHandlerVersion 1.16
workspaceId (e.g) 6f680a37-00c6-41c7-a93f-1437e3462574
workspaceKey (e.g) z4bU3p1/GrnWpQkky4gdabWXAhbWSTz70hm4m2Xt92XI+rSRgE8qVvRhsGo9TXffbrTahyrwv35W0pOqQAU7uQ==

Template deployment

Note

Certain components of the Log Analytics VM extension are also shipped in the Diagnostics VM extension. Due to this architecture, conflicts can arise if both extensions are instantiated in the same ARM template. To avoid these install-time conflicts, use the dependsOn directive to ensure the extensions are installed sequentially. The extensions can be installed in either order.

Azure VM extensions can be deployed with Azure Resource Manager templates. Templates are ideal when deploying one or more virtual machines that require post deployment configuration such as onboarding to Azure Monitor Logs. A sample Resource Manager template that includes the Log Analytics agent VM extension can be found on the Azure Quickstart Gallery.

The JSON configuration for a virtual machine extension can be nested inside the virtual machine resource, or placed at the root or top level of a Resource Manager JSON template. The placement of the JSON configuration affects the value of the resource name and type. For more information, see Set name and type for child resources.

The following example assumes the VM extension is nested inside the virtual machine resource. When nesting the extension resource, the JSON is placed in the "resources": [] object of the virtual machine.

{
  "type": "extensions",
  "name": "OMSExtension",
  "apiVersion": "2018-06-01",
  "location": "<location>",
  "dependsOn": [
    "[concat('Microsoft.Compute/virtualMachines/', <vm-name>)]"
  ],
  "properties": {
    "publisher": "Microsoft.EnterpriseCloud.Monitoring",
    "type": "OmsAgentForLinux",
    "typeHandlerVersion": "1.16",
    "settings": {
      "workspaceId": "myWorkspaceId",
      "skipDockerProviderInstall": true
    },
    "protectedSettings": {
      "workspaceKey": "myWorkSpaceKey"
    }
  }
}

When placing the extension JSON at the root of the template, the resource name includes a reference to the parent virtual machine, and the type reflects the nested configuration.

{
  "type": "Microsoft.Compute/virtualMachines/extensions",
  "name": "<parentVmResource>/OMSExtension",
  "apiVersion": "2018-06-01",
  "location": "<location>",
  "dependsOn": [
    "[concat('Microsoft.Compute/virtualMachines/', <vm-name>)]"
  ],
  "properties": {
    "publisher": "Microsoft.EnterpriseCloud.Monitoring",
    "type": "OmsAgentForLinux",
    "typeHandlerVersion": "1.16",
    "settings": {
      "workspaceId": "myWorkspaceId",
      "skipDockerProviderInstall": true
    },
    "protectedSettings": {
      "workspaceKey": "myWorkSpaceKey"
    }
  }
}

Azure CLI deployment

The Azure CLI can be used to deploy the Log Analytics agent VM extension to an existing virtual machine. Replace the myWorkspaceKey value below with your workspace key and the myWorkspaceId value with your workspace ID. These values can be found in your Log Analytics workspace in the Azure portal under Advanced Settings. Replace the latestVersion value with a version from Log Analytics Linux VM extension version.

az vm extension set \
  --resource-group myResourceGroup \
  --vm-name myVM \
  --name OmsAgentForLinux \
  --publisher Microsoft.EnterpriseCloud.Monitoring \
  --protected-settings '{"workspaceKey":"myWorkspaceKey"}' \
  --settings '{"workspaceId":"myWorkspaceId","skipDockerProviderInstall": true}' \
  --version latestVersion

Azure PowerShell deployment

The Azure Powershell cmdlets can be used to deploy the Log Analytics agent VM extension to an existing virtual machine. Replace the myWorkspaceKey value below with your workspace key and the myWorkspaceId value with your workspace ID. These values can be found in your Log Analytics workspace in the Azure portal under Advanced Settings. Replace the latestVersion value with a version from Log Analytics Linux VM extension version.

Set-AzVMExtension \
  -ResourceGroupName myResourceGroup \
  -VMName myVM \
  -ExtensionName OmsAgentForLinux \
  -ExtensionType OmsAgentForLinux \
  -Publisher Microsoft.EnterpriseCloud.Monitoring \
  -TypeHandlerVersion latestVersion \
  -ProtectedSettingString '{"workspaceKey":"myWorkspaceKey"}' \
  -SettingString '{"workspaceId":"myWorkspaceId","skipDockerProviderInstall": true}'

Troubleshoot and support

Troubleshoot

Data about the state of extension deployments can be retrieved from the Azure portal, and by using the Azure CLI or Azure Powershell. To see the deployment state of extensions for a given VM, run the following command if you are using the Azure CLI.

az vm extension list --resource-group myResourceGroup --vm-name myVM -o table

Extension execution output is logged to the following file:

/var/log/azure/Microsoft.EnterpriseCloud.Monitoring.OmsAgentForLinux/extension.log

To retrieve the OMS extension version installed on a VM, run the following command if you are using Azure CLI.

az vm extension show --resource-group myResourceGroup --vm-name myVM --instance-view

To retrieve the OMS extension version installed on a VM, run the following command if you are using Azure PowerShell.

Get-AzVMExtension -ResourceGroupName my_resource_group  -VMName my_vm_name -Name OmsAgentForLinux -Status

Error codes and their meanings

Error Code Meaning Possible Action
9 Enable called prematurely Update the Azure Linux Agent to the latest available version.
10 VM is already connected to a Log Analytics workspace To connect the VM to the workspace specified in the extension schema, set stopOnMultipleConnections to false in public settings or remove this property. This VM gets billed once for each workspace it is connected to.
11 Invalid config provided to the extension Follow the preceding examples to set all property values necessary for deployment.
17 Log Analytics package installation failure
18 Installation of OMSConfig package failed. Look through the command output for the root failure.
19 OMI package installation failure
20 SCX package installation failure
33 Error generating metaconfiguration for omsconfig. File a GitHub Issue with details from the output.
51 This extension is not supported on the VM's operation system
52 This extension failed due to a missing dependency or permission Check the output and logs for more information about which dependency or permission is missing.
53 This extension failed due to missing or wrong configuration parameters Check the output and logs for more information about what went wrong. Additionally, check the correctness of the workspace ID, and verify that the machine is connected to the internet.
55 Cannot connect to the Azure Monitor service or required packages missing or dpkg package manager is locked Check that the system either has internet access, or that a valid HTTP proxy has been provided. Additionally, check the correctness of the workspace ID, and verify that curl and tar utilities are installed.

Additional troubleshooting information can be found on the Log Analytics-Agent-for-Linux Troubleshooting Guide.

Support

If you need more help at any point in this article, you can contact the Azure experts on the Azure support. Alternatively, you can file an Azure support incident. Go to the Azure support site and submit your request. For information about using Azure Support, read the 21Vianet Azure support FAQ.