Merge pull request #273842 from AbhishekMallick-MS/Apr-30-2024-Freshness2

System function updates

Author: prmerger-automator[bot]

articles/backup/backup-reports-system-functions.md

@@ -1,30 +1,33 @@
 ---
 title: System functions on Azure Monitor Logs
 description: Write custom queries on Azure Monitor Logs using system functions
+ms.service: backup
 ms.topic: conceptual
-ms.date: 04/18/2023
+ms.date: 04/30/2024
 author: AbhishekMallick-MS
 ms.author: v-abhmallick
 ---
 
 # System functions on Azure Monitor Logs
 
+This article describes how to write custom queries on Azure Monitor Logs using system functions.
+
 Azure Backup provides a set of functions, called system functions or solution functions that are available by default in your Log Analytics (LA) workspaces.
 
 These functions operate on data in the [raw Azure Backup tables](./backup-azure-reports-data-model.md) in LA and return formatted data that helps you easily retrieve information of all your backup-related entities, using simple queries. Users can pass parameters to these functions to filter the data that is returned by these functions. 
 
-It's recommended to use system functions for querying your backup data in LA workspaces for creating custom reports, as they provide a number of benefits, as detailed in the section below.
+We recommend you to use system functions for querying your backup data in LA workspaces for creating custom reports, as they provide a number of benefits, as detailed in the section below.
 
 ## Benefits of using system functions
 
 * **Simpler queries**: Using functions helps you reduce the number of joins needed in your queries. By default, the functions return ‘flattened’ schemas that incorporate all information pertaining to the entity (backup instance, job, vault, and so on) being queried. For example, if you need to get a list of successful backup jobs by backup item name and its associated container, a simple call to the **_AzureBackup_getJobs()** function will give you all of this information for each job. On the other hand, querying the raw tables directly would require you to perform multiple joins between [AddonAzureBackupJobs](./backup-azure-reports-data-model.md#addonazurebackupjobs) and [CoreAzureBackup](./backup-azure-reports-data-model.md#coreazurebackup) tables.
 
 * **Smoother transition from the legacy diagnostics event**: Using system functions helps you transition smoothly from the [legacy diagnostics event](./backup-azure-diagnostic-events.md#legacy-event) (AzureBackupReport in AzureDiagnostics mode) to the [resource-specific events](./backup-azure-diagnostic-events.md#diagnostics-events-available-for-azure-backup-users). All the system functions provided by Azure Backup allows you to specify a parameter that lets you choose whether the function should query data only from the resource-specific tables, or query data from both the legacy table and the resource-specific tables (with deduplication of records).
     * If you have successfully migrated to the resource-specific tables, you can choose to exclude the legacy table from being queried by the function.
-    * If you are currently in the process of migration and have some data in the legacy tables which you require for analysis, you can choose to include the legacy table. When the transition is complete, and you no longer need data from the legacy table, you can simply update the value of the parameter passed to the function in your queries, to exclude the legacy table.
-    * If you are still using only the legacy table, the functions will still work if you choose to include the legacy table via the same parameter. However, it is recommended to [switch to the resource-specific tables](./backup-azure-diagnostic-events.md#steps-to-move-to-new-diagnostics-settings-for-a-log-analytics-workspace) at the earliest.
+    * If you're currently in the process of migration and have some data in the legacy tables which you require for analysis, you can choose to include the legacy table. When the transition is complete, and you no longer need data from the legacy table, you can update the value of the parameter passed to the function in your queries, to exclude the legacy table.
+    * If you're still using only the legacy table, the functions will still work if you choose to include the legacy table via the same parameter. However, it's recommended to [switch to the resource-specific tables](./backup-azure-diagnostic-events.md#steps-to-move-to-new-diagnostics-settings-for-a-log-analytics-workspace) at the earliest.
 
-* **Reduces possibility of custom queries breaking**: If Azure Backup introduces improvements to the schema of the underlying LA tables to accommodate future reporting scenarios, the definition of the functions will also be updated to take into account the schema changes. Thus, if you use system functions for creating custom queries, your queries will not break, even if there are changes in the underlying schema of the tables.
+* **Reduces possibility of custom queries breaking**: If Azure Backup introduces improvements to the schema of the underlying LA tables to accommodate future reporting scenarios, the definition of the functions will also be updated to take into account the schema changes. Thus, if you use system functions for creating custom queries, your queries won't break, even if there are changes in the underlying schema of the tables.
 
 > [!NOTE]
 > System functions are maintained by Microsoft and their definitions cannot be edited by users. If you require editable functions, you can create [saved functions](../azure-monitor/logs/functions.md) in LA.
@@ -126,7 +129,7 @@ This function returns a list of all backup and restore related jobs that were tr
 | VaultTypeList     | Use this parameter to filter the output of the function to records pertaining to a particular vault type. By default, the value of this parameter is '*', which makes the function search for both Recovery Services vaults and Backup vaults. | N | "Microsoft.RecoveryServices/vaults"| String |
 | ExcludeLegacyEvent  | Use this parameter to choose whether to query data in the legacy AzureDiagnostics table or not. If the value of this parameter is false, the function queries data from both the AzureDiagnostics table and the Resource specific tables. If the value of this parameter is true, the function queries data from only the Resource specific tables. Default value is true. | N | true | Boolean | 
 | BackupSolutionList | Use this parameter to filter the output of the function for a certain set of backup solutions used in your Azure environment. For example, if you specify `Azure Virtual Machine Backup,SQL in Azure VM Backup,DPM` as the value of this parameter, the function only returns records that are related to items backed up using Azure Virtual Machine backup, SQL in Azure VM backup or DPM to Azure backup. By default, the value of this parameter is '*', which makes the function return records pertaining to all backup solutions that are supported by Backup Reports (supported values are "Azure Virtual Machine Backup", "SQL in Azure VM Backup", "SAP HANA in Azure VM Backup", "Azure Storage (Azure Files) Backup", "Azure Backup Agent", "DPM", "Azure Backup Server", "Azure Database for PostgreSQL Server Backup", "Azure Blob Backup", "Azure Disk Backup" or a comma-separated combination of any of these values). | N | `Azure Virtual Machine Backup,SQL in Azure VM Backup,DPM,Azure Backup Agent` | String | 
-| JobOperationList | Use this parameter to filter the output of the function for a specific type of job. For example, Backup or Restore. By default, the value of this parameter is "*", which makes the function search for both Backup and Restore jobs. | N | "Backup" |  String |
+| JobOperationList | Use this parameter to filter the output of the function for a specific type of job. For example, the backup or restore operations. By default, the value of this parameter is "*", which makes the function search for both Backup and Restore jobs. | N | "Backup" |  String |
 | JobStatusList | Use this parameter to filter the output of the function for a specific job status. For example, Completed, Failed, and so on. By default, the value of this parameter is "*", which makes the function search for all jobs irrespective of status. | N | `Failed,CompletedWithWarnings` | String |
 | JobFailureCodeList | Use this parameter to filter the output of the function for a specific failure code. By default, the value of this parameter is "*", which makes the function search for all jobs irrespective of failure code. | N | "Success" | String |
 | DatasourceSetName | Use this parameter to filter the output of the function to a particular parent resource. For example, to return SQL in Azure VM backup instances belonging to the virtual machine "testvm", specify _testvm_ as the value of this parameter. By default, the value is "*", which makes the function search for records across all backup instances. | N | "testvm" | String |
@@ -186,7 +189,7 @@ This function returns the list of backup instances that are associated with your
 | ProtectionInfoList | Use this parameter to choose whether to include only those backup instances that are actively protected, or to also include those instances for which protection has been stopped and instances for which initial backup is pending. For Recovery services vault workloads, supported values are "Protected", "ProtectionStopped", "InitialBackupPending" or a comma-separated combination of any of these values. For Backup vault workloads, supported values are "Protected", "ConfiguringProtection", "ConfiguringProtectionFailed", "UpdatingProtection", "ProtectionError", "ProtectionStopped" or a comma-separated combination of any of these values. By default, the value is "*", which makes the function search for all backup instances irrespective of protection details. | N | "Protected" | String |
 | DatasourceSetName | Use this parameter to filter the output of the function to a particular parent resource. For example, to return SQL in Azure VM backup instances belonging to the virtual machine "testvm", specify _testvm_ as the value of this parameter. By default, the value is "*", which makes the function search for records across all backup instances. | N | "testvm" | String |
 | BackupInstanceName | Use this parameter to search for a particular backup instance by name. By default, the value is "*", which makes the function search for all backup instances. | N | "testvm" | String |
-| DisplayAllFields | Use this parameter to choose whether to retrieve only a subset of the fields returned by the function. If the value of this parameter is false, the function eliminates storage and retention point related information from the output of the function. This is useful if you are using this function as an intermediate step in a larger query and need to optimize the performance of the query by eliminating columns which you do not require for analysis. By default, the value of this parameter is true, which makes the function return all fields pertaining to the backup instance. | N | true | Boolean |
+| DisplayAllFields | Use this parameter to choose whether to retrieve only a subset of the fields returned by the function. If the value of this parameter is false, the function eliminates storage and retention point related information from the output of the function. This is useful if you're using this function as an intermediate step in a larger query and need to optimize the performance of the query by eliminating columns which you don't require for analysis. By default, the value of this parameter is true, which makes the function return all fields pertaining to the backup instance. | N | true | Boolean |
 
 **Returned Fields**
 
@@ -282,8 +285,8 @@ This function returns historical records for each backup instance, allowing you
 | ProtectionInfoList | Use this parameter to choose whether to include only those backup instances that are actively protected, or to also include those instances for which protection has been stopped and instances for which initial backup is pending. For Recovery services vault workloads, supported values are "Protected", "ProtectionStopped", "InitialBackupPending" or a comma-separated combination of any of these values. For Backup vault workloads, supported values are "Protected", "ConfiguringProtection", "ConfiguringProtectionFailed", "UpdatingProtection", "ProtectionError", "ProtectionStopped" or a comma-separated combination of any of these values. By default, the value is "*", which makes the function search for all backup instances irrespective of protection details. | N | "Protected" | String |
 | DatasourceSetName | Use this parameter to filter the output of the function to a particular parent resource. For example, to return SQL in Azure VM backup instances belonging to the virtual machine "testvm", specify _testvm_ as the value of this parameter. By default, the value is "*", which makes the function search for records across all backup instances. | N | "testvm" | String |
 | BackupInstanceName | Use this parameter to search for a particular backup instance by name. By default, the value is "*", which makes the function search for all backup instances. | N | "testvm" | String |
-| DisplayAllFields | Use this parameter to choose whether to retrieve only a subset of the fields returned by the function. If the value of this parameter is false, the function eliminates storage and retention point related information from the output of the function. This is useful if you are using this function as an intermediate step in a larger query and need to optimize the performance of the query by eliminating columns which you do not require for analysis. By default, the value of this parameter is true, which makes the function return all fields pertaining to the backup instance. | N | true | Boolean |
-| AggregationType | Use this parameter to specify the time granularity at which data should be retrieved. If the value of this parameter is "Daily", the function returns a record per backup instance per day, allowing you to analyze daily trends of storage consumption and backup instance count. If the value of this parameter is "Weekly", the function returns a record per backup instance per week, allowing you to analyze weekly trends. Similarly, you can specify "Monthly" to analyze monthly trends. Default value is "Daily". If you are viewing data across larger time ranges, it is recommended to use "Weekly" or "Monthly" for better query performance and ease of trend analysis. | N | "Weekly" | String |
+| DisplayAllFields | Use this parameter to choose whether to retrieve only a subset of the fields returned by the function. If the value of this parameter is false, the function eliminates storage and retention point related information from the output of the function. This is useful if you're using this function as an intermediate step in a larger query and need to optimize the performance of the query by eliminating columns which you don't require for analysis. By default, the value of this parameter is true, which makes the function return all fields pertaining to the backup instance. | N | true | Boolean |
+| AggregationType | Use this parameter to specify the time granularity at which data should be retrieved. If the value of this parameter is "Daily", the function returns a record per backup instance per day, allowing you to analyze daily trends of storage consumption and backup instance count. If the value of this parameter is "Weekly", the function returns a record per backup instance per week, allowing you to analyze weekly trends. Similarly, you can specify "Monthly" to analyze monthly trends. Default value is "Daily". If you're viewing data across larger time ranges, it's recommended to use "Weekly" or "Monthly" for better query performance and ease of trend analysis. | N | "Weekly" | String |
 
 **Returned Fields**
 
@@ -334,7 +337,7 @@ This function returns historical records for each billing entity, allowing you t
 | ExcludeLegacyEvent  | Use this parameter to choose whether to query data in the legacy AzureDiagnostics table or not. If the value of this parameter is false, the function queries data from both the AzureDiagnostics table and the Resource specific tables. If the value of this parameter is true, the function queries data from only the Resource specific tables. Default value is true. | N | true | Boolean |
 | BackupSolutionList | Use this parameter to filter the output of the function for a certain set of backup solutions used in your Azure environment. For example, if you specify `Azure Virtual Machine Backup,SQL in Azure VM Backup,DPM` as the value of this parameter, the function only returns records that are related to items backed up using Azure Virtual Machine backup, SQL in Azure VM backup or DPM to Azure backup. By default, the value of this parameter is '*', which makes the function return records pertaining to all backup solutions that are supported by Backup Reports (supported values are "Azure Virtual Machine Backup", "SQL in Azure VM Backup", "SAP HANA in Azure VM Backup", "Azure Storage (Azure Files) Backup", "Azure Backup Agent", "DPM", "Azure Backup Server", "Azure Database for PostgreSQL Server Backup", "Azure Blob Backup", "Azure Disk Backup" or a comma-separated combination of any of these values). | N | `Azure Virtual Machine Backup,SQL in Azure VM Backup,DPM,Azure Backup Agent` | String |
 | BillingGroupName | Use this parameter to search for a particular billing group by name. By default, the value is "*", which makes the function search for all billing groups. | N | "testvm" | String |
-| AggregationType | Use this parameter to specify the time granularity at which data should be retrieved. If the value of this parameter is "Daily", the function returns a record per billing group per day, allowing you to analyze daily trends of storage consumption and frontend size. If the value of this parameter is "Weekly", the function returns a record per backup instance per week, allowing you to analyze weekly trends. Similarly, you can specify "Monthly" to analyze monthly trends. Default value is "Daily". If you are viewing data across larger time ranges, it is recommended to use "Weekly" or "Monthly" for better query performance and ease of trend analysis. | N | "Weekly" | String |
+| AggregationType | Use this parameter to specify the time granularity at which data should be retrieved. If the value of this parameter is "Daily", the function returns a record per billing group per day, allowing you to analyze daily trends of storage consumption and frontend size. If the value of this parameter is "Weekly", the function returns a record per backup instance per week, allowing you to analyze weekly trends. Similarly, you can specify "Monthly" to analyze monthly trends. Default value is "Daily". If you're viewing data across larger time ranges, it's recommended to use "Weekly" or "Monthly" for better query performance and ease of trend analysis. | N | "Weekly" | String |
 
 **Returned Fields**