Uso de funciones en consultas de registros de Azure Monitor

Una función es una consulta de registro en Azure Monitor que se puede usar en otras consultas de registro como si se tratase de un comando. Puede utilizar funciones para proporcionar soluciones a distintos clientes, además de reutilizar la lógica de consulta en su propio entorno. En este artículo se describe cómo usar funciones y cómo crear las suyas propias.

Permisos necesarios

• Para ver o usar funciones, necesita permisos de Microsoft.OperationalInsights/workspaces/query/*/read para el área de trabajo de Log Analytics, tal y como lo proporciona el Rol integrado de lector de Log Analytics, por ejemplo.

• Para crear o editar funciones, necesita permisos de microsoft.operationalinsights/workspaces/savedSearches/write para el área de trabajo de Log Analytics, tal y como lo proporciona el Rol integrado de lector de Log Analytics, por ejemplo.

Tipos de funciones

Hay dos tipos de funciones en Azure Monitor:

• Funciones de solución: Las funciones precompiladas se incluyen con Azure Monitor. Estas funciones están disponibles en todas las áreas de trabajo de Log Analytics y no se pueden modificar.
• Funciones del área de trabajo: estas funciones se instalan en un área de trabajo de Log Analytics determinada. El usuario puede modificarlas y controlarlas.

Funciones de vista

Puede ver las funciones de solución y las funciones del área de trabajo en el área de trabajo actual en la pestaña Funciones del panel izquierdo de un área de trabajo de Log Analytics. Use Filtro para filtrar las funciones incluidas en la lista. Use Agrupar por para cambiar la agrupación. Escriba una cadena en el cuadro Buscar para buscar una función determinada. Mantenga el puntero sobre una función para ver más detalles sobre ella, incluida una descripción y parámetros.

Uso de una función

Use una función en una consulta escribiendo su nombre con valores para cualquier parámetro igual que lo haría en un comando. La salida de la función se puede devolver como resultados o canalizarse a otro comando.

Para agregar una función a la consulta actual, haga doble clic en su nombre o mantenga el puntero sobre ella y seleccione Usar en el editor. Las funciones del área de trabajo también se incluirán en IntelliSense a medida que escriba una consulta.

Si una consulta requiere parámetros, puede proporcionarlos mediante la sintaxis function_name(param1,param2,...).

Creación de una función

Para crear una función a partir de la consulta actual del editor, seleccione Guardar>Guardar como función.

Para crear una función con Log Analytics en Azure Portal, seleccione Guardar y, después, proporcione la información de la tabla siguiente:

Configuración	Descripción
Nombre de la función	El nombre de la función. El nombre no puede incluir ningún espacio o carácter especial. Tampoco puede comenzar con un carácter de subrayado (_), ya que este carácter está reservado para las funciones de solución.
Categoría heredada	Categoría definida por el usuario para ayudar a filtrar y agrupar funciones.
Guardar como grupo de equipos	Guarde la consulta como un grupo de equipos.
Parámetros	Agregue un parámetro para cada variable de la función que requiera un valor cuando se utilice. Para obtener más información, consulte Parámetros de función.

Parámetros de función

Puede agregar parámetros a una función para que pueda proporcionar valores de determinadas variables al llamarla. Esto permite usar la misma función en consultas diferentes, cada una de las cuales proporciona valores diferentes para los parámetros. Los parámetros se definen mediante las siguientes propiedades:

Configuración	Descripción
Tipo	Tipo de datos para el valor.
Nombre	Nombre del parámetro. Este nombre debe usarse en la consulta para reemplazar por el valor del parámetro.
Valor predeterminado	Valor que se usará para el parámetro si no se proporciona ningún valor.

Los parámetros se ordenan a medida que se crean. Primero aparecen los parámetros sin ningún valor predeterminado y, después, aquellos que sí lo tienen.

Nota

Los recursos clásicos de Application Insights no admiten funciones parametrizadas. Si tiene un recurso de Application Insights basado en el área de trabajo, puede crear funciones parametrizadas desde el área de trabajo de Log Analytics. Para obtener información sobre cómo migrar el recurso de Application Insights clásico a un recurso basado en áreas de trabajo, consulte Migración a recursos de Application Insights basados en áreas de trabajo.

Uso del código de función

Puede ver el código de una función para obtener información sobre cómo funciona o para modificar el código de una función del área de trabajo. Seleccione Cargar el código de la función para agregar el código de la función a la consulta actual del editor.

Si agrega el código de función a una consulta vacía o a la primera línea de una consulta existente, se agregará el nombre de función a la pestaña. Una función del área de trabajo, permite editar los detalles de la función.

Edición de una función

Edite las propiedades o el código de una función creando una nueva consulta. Mantenga el puntero sobre el nombre de la función y seleccione Cargar código de función. Realice las modificaciones que desee en el código y seleccione Guardar. A continuación, seleccione Editar detalles de la función. Realice los cambios que desee en las propiedades y parámetros de la función y seleccione Guardar.

Ejemplo

La siguiente función de ejemplo devuelve todos los eventos del registro de actividades de Azure a partir de una fecha determinada y los eventos que coinciden con una categoría determinada.

Comience con la consulta siguiente mediante el uso de valores codificados de forma rígida para comprobar que la consulta funciona según lo previsto.

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

A continuación, reemplace los valores codificados de forma rígida por nombres de parámetro. A continuación, guarde la función seleccionando Guardar>Guardar como función.

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

Proporcione los siguientes valores para las propiedades de función:

Propiedad	Value
Nombre de función	AzureActivityByCategory
Categoría heredada	Funciones de demostración

Defina los parámetros siguientes antes de guardar la función:

Tipo	Nombre	Valor predeterminado
string	CategoryParam	"Administrativa"
datetime	DateParam

Cree una nueva consulta y mantenga el puntero sobre ella para ver la nueva función. Examine el orden de los parámetros. Deben especificarse en este orden cuando se usa la función.

Seleccione Usar en el editor para agregar la nueva función a una consulta. A continuación, agregue valores para los parámetros. No es necesario especificar un valor para CategoryParam porque tiene un valor predeterminado.

Pasos siguientes

Consulte Operaciones de cadena para más información sobre cómo escribir consultas de registro de Azure Monitor.