Functions in Azure Monitor log queries
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.
To view or use functions, you need
Microsoft.OperationalInsights/workspaces/query/*/readpermissions to the Log Analytics workspace, as provided by the Log Analytics Reader built-in role, for example.
To create or edit functions, you need
microsoft.operationalinsights/workspaces/savedSearches/writepermissions to the Log Analytics workspace, as provided by the Log Analytics Reader 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.
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
Create a function
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:
|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.
|User-defined category to help filter and group functions.
|Save as computer group
|Save the query as a computer group.
|Add a parameter for each variable in the function that requires a value when it's used. For more information, see 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:
|Data type for the value.
|Name for the parameter. This name must be used in the query to replace with the parameter 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.
Classic Application Insights resources don't support parameterized functions. If you have a workspace-based Application Insights resource, you can create parameterized functions from your Log Analytics workspace. For information on migrating your Classic Application Insights resource to a workspace-based resource, see Migrate to workspace-based Application Insights resources.
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.
Edit a function
Edit the properties or the code of a function by creating a new query. Hover over the name of the function and select Load function code. Make any modifications that you want to the code and select Save. Then select Edit function details. Make any changes you want to the properties and parameters of the function and select Save.
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.
| 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.
| where CategoryValue == CategoryParam
| where TimeGenerated > DateParam
Provide the following values for the function properties:
Define the following parameters before you save the function:
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.
See String operations for more information on how to write Azure Monitor log queries.