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. Functions allow developers to provide solutions to different customers and for you to reuse query logic in your own environment. This article provides details on how to use functions and how to create your own.
Types of functions
There are two types of functions in Azure Monitor:
- Solution function: Pre-built functions included with Azure Monitor. These are available in all Log Analytics workspaces and can't be modified.
- Workspace functions: Functions installed in a particular Log Analytics workspace and can be modified and controlled by the user.
Viewing functions
You can view solution functions and workspace functions in the current workspace from the Functions tab in the left pane of a Log Analytics workspace. Use the Filter button to filter the functions included in the list and Group by to change their grouping. Type a string into 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 just 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 using the syntax: function_name(param1,param2,...)
.
Create a function
To create a function from the current query in the editor, select Save and then Save as function.
Create a function with Log Analytics in the Azure portal by clicking Save and then providing the information in the following table.
Setting | Description |
---|---|
Function Name | Name for the function. This may not include a space or any special characters. It also may not start with an underscore (_) since 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. See Function parameters for details. |
Function parameters
You can add parameters to a function so that you can provide values for certain variables when calling it. This allows the same function to 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 is the name that 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 are created with any parameters that have no default value positioned in front of those that have a default value.
Working 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 it to an empty query or the first line of an existing query, then it will add the function name to the tab. If it's a workspace function, then this 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 and then hover over the name of the function and select load function code. Make any modifications that you want to the code and select Save and then Edit function details. Make any changes you want to the properties and parameters of the function before clicking Save.
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 using hardcoded values. This verifies 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 and then save the function by selecting Save and then 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 saving the function.
Type | Name | Default value |
---|---|---|
string | CategoryParam | "Administrative" |
datetime | DateParam |
Create a new query and view the new function by hovering over it. Note the order of the parameters since this is the order they must be specified when you use the function.
Select Use in editor to add the new function to a query and then add values for the parameters. Note that you don't need to specify a value for CategoryParam because it has a default value.
Next steps
See other lessons for writing Azure Monitor log queries:
Feedback
Submit and view feedback for