Functions in Azure Monitor log queries

Article
11/01/2024

A function is a log query in Azure Monitor that can be used in other log queries as though it's a command. You can use functions to provide solutions to different customers and also reuse query logic in your own environment. This article describes how to use functions and how to create your own.

Permissions required

Action	Permissions required
View or use functions	`Microsoft.OperationalInsights/workspaces/query/*/read` permissions to the Log Analytics workspace, as provided by the Log Analytics Reader built-in role, for example.
Create or edit functions	`microsoft.operationalinsights/workspaces/savedSearches/write` permissions to the Log Analytics workspace, as provided by the Log Analytics Contributor built-in role, for example.

Types of functions

There are two types of functions in Azure Monitor:

Solution functions: Prebuilt functions are included with Azure Monitor. These functions are available in all Log Analytics workspaces and can't be modified.
Workspace functions: These functions are installed in a particular Log Analytics workspace. They can be modified and controlled by the user.

View functions

You can view solution functions and workspace functions in the current workspace on the Functions tab in the left pane of a Log Analytics workspace. Use Filter to filter the functions included in the list. Use Group by to change their grouping. Enter a string in the Search box to locate a particular function. Hover over a function to view details about it, including a description and parameters.

Use a function

Use a function in a query by typing its name with values for any parameters the same as you would type in a command. The output of the function can either be returned as results or piped to another command.

Add a function to the current query by double-clicking on its name or hovering over it and selecting Use in editor. Functions in the workspace will also be included in IntelliSense as you type in a query.

If a query requires parameters, provide them by using the syntax function_name(param1,param2,...).

To create a function from the current query in the editor, select Save > Save as function.

Create a function with Log Analytics in the Azure portal by selecting Save and then providing the information in the following table:

Setting	Description
Function name	Name for the function. The name may not include a space or any special characters. It also may not start with an underscore (_) because this character is reserved for solution functions.
Legacy category	User-defined category to help filter and group functions.
Save as computer group	Save the query as a computer group.
Parameters	Add a parameter for each variable in the function that requires a value when it's used. For more information, see Function parameters.

The following sample uses the Microsoft.OperationalInsights workspaces/savedSearches template to create a function. For more information about Azure Resource Manager templates, see Understand the structure and syntax of ARM templates.

To learn more about how to deploy resources from a custom template, go to Deploy resources with ARM templates and Azure portal.

Note

See Azure Resource Manager samples for Azure Monitor for a list of samples that are available and guidance on deploying them in your Azure subscription.

Template file

{
  "$schema": "
https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#"
,
  "contentVersion": "1.0.0.0",
  "resources": [
    {
      "type": "Microsoft.OperationalInsights/workspaces/savedSearches",
      "apiVersion": "2020-08-01",
      "name": "[concat(parameters('workspaceName'), '/', parameters('functionName'))]",
      "location": "[parameters('location')]",
      "properties": {
        "etag": "*",
        "displayName": "[parameters('functionDisplayName')]",
        "category": "[parameters('category')]",
        "query": "[parameters('query')]",
        "functionAlias": "[parameters('functionAlias')]",
        "version": 1
      }
    }
  ],
  "parameters": {
    "workspaceName": {
      "type": "string",
      "metadata": {
        "description": "Name of the Log Analytics workspace"
      }
    },
    "functionName": {
      "type": "string",
      "metadata": {
        "description": "Name of the function"
      }
    },
    "location": {
      "type": "string",
      "metadata": {
        "description": "Location of the Log Analytics workspace"
      }
    },
    "functionDisplayName": {
      "type": "string",
      "metadata": {
        "description": "Display name of the function"
      }
    },
    "category": {
      "type": "string",
      "metadata": {
        "description": "Category of the function"
      }
    },
    "query": {
      "type": "string",
      "metadata": {
        "description": "Kusto query for the function"
      }
    },
    "functionAlias": {
      "type": "string",
      "metadata": {
        "description": "Alias for the function"
      }
    }
  }
}

Function parameters

You can add parameters to a function so that you can provide values for certain variables when you call it. As a result, the same function can be used in different queries, each providing different values for the parameters. Parameters are defined by the following properties:

Setting	Description
Type	Data type for the value.
Name	Name for the parameter. This name must be used in the query to replace with the parameter value.
Default value	Value to be used for the parameter if a value isn't provided.

Parameters are ordered as they're created. Parameters that have no default value are positioned in front of parameters that have a default value.

Work with function code

You can view the code of a function either to gain insight into how it works or to modify the code for a workspace function. Select Load the function code to add the function code to the current query in the editor.

If you add the function code to an empty query or the first line of an existing query, the function name is added to the tab. A workspace function enables the option to edit the function details.

Example

The following sample function returns all events in the Azure activity log since a particular date and that match a particular category.

Start with the following query by using hardcoded values to verify that the query works as expected.

AzureActivity
| where CategoryValue == "Administrative"
| where TimeGenerated > todatetime("2021/04/05 5:40:01.032 PM")

Next, replace the hardcoded values with parameter names. Then save the function by selecting Save > Save as function.

AzureActivity
| where CategoryValue == CategoryParam
| where TimeGenerated > DateParam

Provide the following values for the function properties:

Property	Value
Function name	AzureActivityByCategory
Legacy category	Demo functions

Define the following parameters before you save the function:

Type	Name	Default value
string	CategoryParam	"Administrative"
datetime	DateParam

Create a new query and view the new function by hovering over it. Look at the order of the parameters. They must be specified in this order when you use the function.

Select Use in editor to add the new function to a query. Then add values for the parameters. You don't need to specify a value for CategoryParam because it has a default value.

Next steps

See String operations for more information on how to write Azure Monitor log queries.