Ingerir métricas personalizadas para un recurso de Azure mediante la API de REST

Artículo
11/05/2024

En este artículo se muestra cómo enviar métricas personalizadas para recursos de Azure al almacén de métricas de Azure Monitor a través de la API de REST. Cuando las métricas están en Azure Monitor, puede hacer con ellas lo mismo que con las métricas estándar. Por ejemplo, puede generar gráficos y alertas y enrutar las métricas a otras herramientas externas.

Nota

La API de REST solo permite el envío de métricas personalizadas de los recursos de Azure. Para enviar métricas de recursos en otros entornos o de forma local, use Application Insights.

Envío de solicitudes REST para ingerir métricas personalizadas

Al enviar las métricas personalizadas a Azure Monitor, cada punto de datos (o valor) notificado en las métricas debe incluir la siguiente información.

Token de autenticación
Asunto
Región
Timestamp
Espacio de nombres
Nombre
Claves de dimensión
Valores de la dimensión
Valores de métrica

Autenticación

Para enviar métricas personalizadas a Azure Monitor, la entidad que envía la métrica debe tener un token de Microsoft Entra ID válido en el encabezado Bearer de la solicitud. Las formas admitidas para adquirir un token de portador válido incluyen:

Identidades administradas para recursos de Azure. Puede usar una identidad administrada para conceder permisos a los recursos para llevar a cabo determinadas operaciones. Un ejemplo es permitir que un recurso emita métricas sobre sí mismo. Se puede conceder a un recurso, o a su identidad administrada, permisos de Publicador de métricas de supervisión en otro recurso. Con este permiso, la identidad administrada también puede emitir métricas para otros recursos.
Entidad de servicio de Microsoft Entra. En este escenario, en una aplicación (o servicio) de Microsoft Entra, pueden asignarse permisos para emitir métricas sobre un recurso de Azure. Para autenticar la solicitud, Azure Monitor valida el token de la aplicación usando las claves públicas de Microsoft Entra. El rol Supervisión del publicador de métricas existente ya tiene este permiso. Está disponible en Azure Portal.

La entidad de servicio, en función de para qué recursos vaya a emitir las métricas personalizadas, puede recibir el rol Supervisión del publicador de métricas en el ámbito necesario. Algunos ejemplos son una suscripción, un grupo de recursos o un recurso específico.

Sugerencia

Cuando solicite un token de Microsoft Entra para emitir métricas personalizadas, asegúrese de que la audiencia o el recurso para los que se solicita el token es https://monitoring.azure.com/. Asegúrese de incluir la barra diagonal final.

Obtención de un token de autorización

Una vez que haya creado la identidad administrada o la entidad de servicio y asignado los permisos del Publicador de métricas de supervisión, puede obtener un token de autorización. Al solicitar un token, especifique resource: https://monitoring.azure.com.

Obtenga un token de autenticación mediante cualquiera de los siguientes métodos:

CLI
REST API
SDK

Al solicitar un token, debe proporcionar un parámetro resource. El parámetro resource es la dirección URL del recurso al que desea acceder.

Los recursos incluyen:

https://management.azure.com
https://api.loganalytics.io
https://monitoring.azure.com

Obtención de un token mediante una solicitud de REST

Use la siguiente llamada a la API de REST para obtener un token. Esta solicitud usa un identificador de cliente y un secreto de cliente para autenticar la solicitud. El identificador de cliente y el secreto de cliente se obtienen al registrar la aplicación con Microsoft Entra ID. Para obtener más información, consulte Registro de una aplicación para solicitar tokens de autorización y trabajar con API

curl -X POST 'https://login.microsoftonline.com/<tennant ID>/oauth2/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<your apps client ID>' \
--data-urlencode 'client_secret=<your apps client secret' \
--data-urlencode 'resource=https://monitoring.azure.com'

El cuerpo de la respuesta aparece en el formato siguiente:

{
    "token_type": "Bearer",
    "expires_in": "86399",
    "ext_expires_in": "86399",
    "expires_on": "1672826207",
    "not_before": "1672739507",
    "resource": "https://monitoring.azure.com",
    "access_token": "eyJ0eXAiOiJKV1Qi....gpHWoRzeDdVQd2OE3dNsLIvUIxQ"
}

Obtención de un token mediante la CLI de Azure

Para obtener un token mediante la CLI, puede usar el siguiente comando

az account get-access-token

Para obtener más información, consulte az account get-access-token

Obtención de un token mediante los SDK

Los siguientes ejemplos de código muestran cómo obtener un token mediante:

C#
NodeJS
Python

C#

En el siguiente código se muestra cómo obtener un token mediante Azure. La biblioteca de identidades requiere un identificador de cliente y un secreto de cliente para autenticar la solicitud.

var context = new AuthenticationContext("https://login.microsoftonline.com/<tennant ID>");
var clientCredential = new ClientCredential("<your apps client ID>", "<your apps client secret>");
var result = context.AcquireTokenAsync("https://monitoring.azure.com", clientCredential).Result;

Como alternativa, puede usar la clase DefaultAzureCredential para obtener un token. Este método usa las credenciales predeterminadas de Azure para autenticar la solicitud y no requiere un identificador de cliente ni un secreto de cliente.

var credential = new DefaultAzureCredential();
var token = credential.GetToken(new TokenRequestContext(new[] { "https://management.azure.com/.default" }));

También puede especificar las credenciales de identidad administrada o entidad de servicio de la siguiente manera:

string userAssignedClientId = "<your managed identity client ID>";
var credential = new DefaultAzureCredential(
    new DefaultAzureCredentialOptions
    {
        ManagedIdentityClientId = userAssignedClientId
    });

var token = credential.GetToken(new TokenRequestContext(new[] { "https://management.azure.com/.default" }));

Para obtener más información, consulte Clase DefaultAzureCredential

Node.js

Para obtener información sobre la autenticación mediante JavaScript y NodeJS, consulte Autenticación de aplicaciones JavaScript en servicios de Azure mediante el SDK de Azure para JavaScript

En el siguiente código se muestra cómo obtener un token mediante la clase DefaultAzureCredential. Este método usa las credenciales predeterminadas de Azure para autenticar la solicitud y no requiere un identificador de cliente ni un secreto de cliente.

const { DefaultAzureCredential } = require("@azure/identity");

const credential = new DefaultAzureCredential();
const accessToken = await credential.getToken("https://management.azure.com/.default");

También puede usar la clase InteractiveBrowserCredential para obtener las credenciales. Este método proporciona una experiencia de autenticación basada en explorador para que los usuarios se autentiquen con los servicios de Azure.

Para obtener más información, consulte clase DefaultAzureCredential y Clase InteractiveBrowserCredential

Como alternativa, puede usar la clase ClientSecretCredential para obtener un token. Este método requiere un identificador de cliente y un secreto de cliente para autenticar la solicitud.

const { ClientSecretCredential } = require("@azure/identity");
credential = ClientSecretCredential(
    client_id="<client_id>",
    username="<username>",
    password="<password>"
   )
const accessToken = await credential.getToken("https://management.azure.com/.default");

Para obtener más información, consulte Clase ClientSecretCredential

Python

from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
token = credential.get_token('https://management.azure.com/.default')
print(token.token)

Para obtener más información, consulte clase DefaultAzureCredential y Clase InteractiveBrowserCredential

Como alternativa, puede usar la clase ClientSecretCredential para obtener un token. Este método requiere un identificador de cliente y un secreto de cliente para autenticar la solicitud.

from azure.identity import ClientSecretCredential

credential = ClientSecretCredential (
     tenant_id="<tenant id>",
     client_id="<Client id>",
     client_secret="client secret"
    )
token =  credential.get_token("https://management.azure.com/.default")
print(token.token)

Para obtener más información, consulte Clase ClientSecretCredential

Guarde el token de acceso de la respuesta para su uso en las siguientes solicitudes HTTP.

Asunto

Esta propiedad de asunto captura para qué identificador de recurso de Azure se notifica la métrica personalizada. Esta información se codifica en la dirección URL de la llamada API que se realiza. Cada API solo puede enviar los valores de métrica para un único recurso de Azure.

Nota

No se pueden emitir métricas personalizadas con el identificador de recurso de un grupo de recursos o una suscripción.

Region

Esta propiedad de región captura en qué región de Azure se implementará el recurso para el que se van a emitir las métricas. Las métricas se deben emitir al mismo punto de conexión regional de Azure Monitor que la región donde se implementa el recurso. Por ejemplo, las métricas personalizadas para una máquina virtual que se implementa en el Oeste de EE. UU. deben enviarse al punto de conexión de Azure Monitor regional WestUS. La información de región también está codificada en la dirección URL de la llamada API.

Marca de tiempo

Cada punto de datos que se envía a Azure Monitor debe marcarse con una marca de tiempo. Esta marca de tiempo captura la fecha y hora en que se midió o recopiló el valor de la métrica. Azure Monitor acepta datos de métrica con marcas de tiempo de hasta 20 minutos en el pasado y hasta 5 minutos en el futuro. La marca de tiempo debe estar en formato ISO 8601.

Espacio de nombres

Los espacios de nombres son una manera de clasificar o agrupar las métricas similares. Mediante el uso de espacios de nombres se puede conseguir el aislamiento entre los grupos de métricas que puedan estar recopilando diferentes conclusiones o indicadores de rendimiento. Por ejemplo, podría tener un espacio de nombres denominado contosomemorymetrics que realice el seguimiento de las métricas de uso de memoria que perfile una aplicación. Otro espacio de nombres denominado contosoapptransaction podría realizar un seguimiento de todas las métricas sobre las transacciones de usuario en la aplicación.

Nombre

La propiedad de nombre es el nombre de la métrica que se notifica. Normalmente, el nombre es lo suficientemente descriptivo como para ayudar a identificar lo que se está midiendo. Un ejemplo es una métrica que mide el número de bytes de memoria que se usan en una VM. Podría tener un nombre de métrica como Bytes de memoria en uso.

Claves de dimensión

Una dimensión es un par clave-valor que sirve de ayuda a la hora de describir las otras características de la métrica que se recopila. El uso de estas otras características le permitirá recopilar más información acerca de la métrica y, por tanto, obtener conclusiones más detalladas.

Por ejemplo, la métrica Bytes de memoria en uso podría tener una clave de dimensión denominada Proceso que capture el número de bytes de memoria que consume cada proceso en una máquina virtual. Con esta clave, puede filtrar la métrica para ver cuánta memoria usan procesos específicos o para identificar los cinco procesos principales por uso de memoria.

Las dimensiones son opcionales, pero no todas las métricas tienen dimensiones. Una métrica personalizada puede tener hasta 10 dimensiones.

Valores de dimensión

Al informar de un punto de datos de métrica, para cada clave de dimensión en la métrica notificada, hay un valor de dimensión correspondiente. Por ejemplo, si quiere informar de la memoria que usa ContosoApp en la VM:

El nombre de la métrica sería Bytes de memoria en uso.
La clave de dimensión sería Proceso.
El valor de la dimensión sería ContosoApp.exe.

Al publicar un valor de métrica, solo puede especificar un único valor de dimensión por clave de dimensión. Si recopila el mismo uso de memoria para varios procesos en la máquina virtual, puede informar sobre varios valores de métricas para esa marca de tiempo. Cada valor de métrica especificaría un valor de dimensión diferente para la clave de dimensión Proceso.

Aunque las dimensiones son opcionales, si en una publicación de métrica se definen las claves de dimensión, los valores de dimensión correspondientes serán obligatorios.

Valores de métrica

Azure Monitor almacena todas las métricas a intervalos de granularidad de un minuto. Durante un minuto determinado, es posible que una métrica tenga que ser muestreada varias veces. Un ejemplo es el uso de CPU. O bien, es posible que sea necesario medir una métrica para muchos eventos discretos, como las latencias de transacción de inicio de sesión.

Para limitar el número de valores sin procesar que tenga que emitir y pagar en Azure Monitor, puede agregarlos previamente de manera local y emitir los valores:

Mínimo: el valor mínimo observado de todas las muestras y medidas durante el minuto.
Máximo: el valor máximo observado de todas las muestras y medidas durante el minuto.
Suma: el sumatorio de todos los valores observados de todas las muestras y medidas durante el minuto.
Recuento: el número de muestras y medidas tomadas durante el minuto.

Nota:

Azure Monitor no permite definir Unidades para una métrica personalizada.

Por ejemplo, si durante un minuto se realizaron cuatro transacciones de inicio de sesión a la aplicación, las latencias resultantes que se hayan medido para cada una de ellas podrían ser las siguientes:

Transacción 1	Transacción 2	Transacción 3	Transacción 4
7 ms	4 ms	13 ms	16 ms

De acuerdo con estos datos, la publicación de métricas resultante en Azure Monitor sería la siguiente:

Mín.: 4
Máx.: 16
Suma: 40
Recuento: 4

Si la aplicación no se puede agregar previamente de manera local y debe emitir cada muestra o evento discretos inmediatamente después de la recopilación, puede emitir los valores de medida sin procesar. Por ejemplo, cada vez que se produzca una transacción de inicio de sesión en la aplicación, publica una métrica en Azure Monitor con solo una única medida. Por ejemplo, si una transacción de inicio de sesión tardó 12 milisegundos en completarse, la publicación de métricas sería la siguiente:

Mín.: 12
Máx.: 12
Suma: 12
Recuento: 1

Con este proceso, puede emitir varios valores para la misma combinación de métricas o dimensiones durante un minuto dado. A continuación, Azure Monitor toma todos los valores sin procesar emitidos para un minuto dado y los suma.

Publicación de métricas personalizadas de ejemplo

En el ejemplo siguiente, cree una métrica personalizada denominada Bytes de memoria en Uso en el espacio de nombres de métrica Perfil de memoria para una máquina virtual. La métrica tiene una única dimensión denominada Proceso. En cuanto a la marca de tiempo, se emiten valores de métrica para dos procesos.

Almacene el siguiente JSON en un archivo denominado custommetric.json en el equipo local. Actualice el parámetro de tiempo para que se encuentre dentro de los últimos 20 minutos. No se puede colocar en el almacén una métrica si pasan más de 20 minutos desde su creación.

{
    "time": "2024-01-07T11:25:20-7:00",
    "data": {

      "baseData": {

        "metric": "Memory Bytes in Use",
        "namespace": "Memory Profile",
        "dimNames": [
          "Process"
        ],
        "series": [
          {
            "dimValues": [
              "ContosoApp.exe"
            ],
            "min": 10,
            "max": 89,
            "sum": 190,
            "count": 4
          },
          {
            "dimValues": [
              "SalesApp.exe"
            ],
            "min": 10,
            "max": 23,
            "sum": 86,
            "count": 4
          }
        ]
      }
    }
  }

Envíe la siguiente solicitud HTTP POST con las siguientes variables:

location: región de implementación del recurso para el que emite métricas.
resourceId: identificador del recurso de Azure contra el que está realizando el seguimiento de la métrica.

accessToken: el token de autorización adquirido en el paso Obtener un token de autorización.

curl -X POST 'https://<location>.monitoring.azure.com/<resourceId>/metrics' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <accessToken>' \
-d @custommetric.json

Visualización de las métricas

Inicie sesión en Azure Portal.
En el menú de la izquierda, seleccione Monitor.
En la página Monitor, seleccione Métricas.
Cambie el período de agregación a Última hora.
En la lista desplegable Ámbito, seleccione el recurso para el que envía la métrica.
En la lista desplegable Espacio de nombres de métricas, seleccione Perfil de memoria.
En la lista desplegable Métrica, seleccione Bytes de memoria en Usar.

Solución de problemas

Si recibe un mensaje de error en alguna parte del proceso, tenga en cuenta la siguiente información de solución de problemas:

Si no puede emitir métricas en una suscripción o un grupo de recursos, o un recurso, compruebe que la aplicación o la entidad de servicio tengan asignado el rol Publicador de métricas de supervisión en Control de acceso (IAM).
Compruebe que el número de nombres de dimensión coincide con los valores numéricos.
Compruebe que está emitiendo métricas al punto de conexión regional de Azure Monitor correcto. Por ejemplo, si el recurso se implementa en Oeste de EE. UU., debe emitir métricas al punto de conexión regional oeste de EE. UU.
Compruebe que la marca de tiempo está dentro de los últimos 20 minutos.
Compruebe que la marca de tiempo está en formato ISO 8601.
Compruebe que el nombre de la métrica es válido. Por ejemplo, no puede contener espacios.

Pasos siguientes

Más información acerca de las métricas personalizadas.

Compartir a través de