Creación de un conector personalizado a un origen de datos - Amazon CloudWatch
Uso de una plantilla Creación de un origen de datos personalizado desde cero

Creación de un conector personalizado a un origen de datos

Tiene dos opciones para conectar un origen de datos personalizado a CloudWatch:

  • Comience con una plantilla de ejemplo que proporciona CloudWatch. Puede usar JavaScript o Python con esta plantilla. Estas plantillas incluyen un ejemplo de código de Lambda que le resultará útil a la hora de crear la función de Lambda. A continuación, puede modificar la función de Lambda de la plantilla para conectarla al origen de datos personalizado.

  • Cree una función AWS Lambda desde cero que implemente el conector del origen de datos, la consulta de datos y la preparación de las series temporales para que CloudWatch las utilice. Esta función debe añadir previamente o combinar puntos de datos si es necesario y también alinear el período y las marcas de tiempo para que sea compatible con CloudWatch.

Uso de una plantilla

El uso de una plantilla crea una función de Lambda de muestra y puede ayudar a crear el conector personalizado más rápido. Estas funciones de ejemplo proporcionan códigos de ejemplo para muchos escenarios comunes relacionados con la creación de un conector personalizado. Puede examinar el código de Lambda después de crear un conector con una plantilla y, a continuación, modificarlo para utilizarlo en la conexión al origen de datos.

Además, si usa la plantilla, CloudWatch se encarga de crear la política de permisos de Lambda y de adjuntar etiquetas de recursos a la función de Lambda.

Cómo usar la plantilla para crear un conector a un origen de datos personalizado

  1. Abra la consola de CloudWatch en https://console.aws.amazon.com/cloudwatch/.

  2. En el panel de navegación, seleccione Configuración.

  3. Seleccione la pestaña Orígenes de datos de métricas.

  4. Elija Crear origen de datos.

  5. Seleccione el botón de radio de Personalización: plantilla de inicio y, a continuación, seleccione Siguiente.

  6. Escriba un nombre para el origen de datos.

  7. Seleccione una de las plantillas de la lista.

  8. Seleccione Node.js o Python.

  9. Elija Crear origen de datos.

    El nuevo origen personalizado que acaba de añadir no aparecerá hasta que la pila AWS CloudFormation haya terminado de crearlo. Para comprobar el progreso, puede elegir Ver el estado de mi pila de CloudFormation. O puede seleccionar el icono de actualización para actualizar esta lista.

    Cuando el nuevo origen de datos aparezca en esta lista, estará listo para que lo pruebe en la consola y lo modifique.

  10. (Opcional) Para consultar los datos de prueba de este origen en la consola, siga las instrucciones en Creación de un gráfico de métricas a partir de otro origen de datos.

  11. Modifique la función de Lambda según sus necesidades.

    1. En el panel de navegación, seleccione Configuración.

    2. Seleccione la pestaña Orígenes de datos de métricas.

    3. Seleccione Ver en la consola de Lambda para el origen que desea modificar.

    Ahora puede modificar la función para obtener acceso al origen de datos. Para obtener más información, consulte Paso 1: crear la función.

    nota

    Al utilizar la plantilla, al escribir la función de Lambda no es necesario seguir las instrucciones en Paso 2: crear una política de permisos de Lambda o Paso 3: asociar la etiqueta de recurso a la función de Lambda. CloudWatch realizó estos pasos porque utilizó la plantilla.

Creación de un origen de datos personalizado desde cero

Siga los pasos de esta sección para crear una función de Lambda que conecte CloudWatch con un origen de datos.

Paso 1: crear la función

Un conector de origen de datos personalizado debe admitir eventos GetMetricData de CloudWatch. Si lo desea, también puede implementar un evento DescribeGetMetricData para proporcionar documentación a los usuarios en la consola de CloudWatch sobre cómo usar el conector. La respuesta DescribeGetMetricData también se puede usar para establecer los valores predeterminados que se utilizan en el generador de consultas personalizadas de CloudWatch.

CloudWatch proporciona fragmentos de código como ejemplos para ayudarlo a comenzar. Para obtener más información, consulte el repositorio de muestras en https://github.com/aws-samples/cloudwatch-data-source-samples.

Restricciones

  • La respuesta de Lambda debe ser inferior a 6 Mb. Si la respuesta supera los 6 Mb, la respuesta GetMetricData marca la función de Lambda como InternalError y no devuelve ningún dato.

  • La función de Lambda debe completar la ejecución en 10 segundos para fines de visualización y creación de cuadros de mando, o en 4,5 segundos para el uso de alarmas. Si el tiempo de ejecución supera ese tiempo, la respuesta GetMetricData marca la función de Lambda como InternalError y no se devuelve ningún dato.

  • La función de Lambda debe enviar su salida mediante marcas de tiempo de época en segundos.

  • Si la función de Lambda no vuelve a muestrear los datos y, en cambio, devuelve datos que no corresponden a la hora de inicio ni a la duración del período que solicitó el usuario de CloudWatch, CloudWatch ignora esos datos. Los datos adicionales se descartan de cualquier visualización o alarma. También se descartan todos los datos que no estén entre la hora de inicio y la hora de finalización.

    Por ejemplo, si un usuario solicita datos entre las 10:00 y las 11:00 con un período de 5 minutos, los intervalos de tiempo válidos para devolver los datos son de “10:00:00 a 10:04:59” y “10:05:00 a 10:09:59”. Debe devolver una serie temporal que incluya 10:00 value1, 10:05 value2, etc. Si la función devuelve 10:03 valueX, por ejemplo, se descarta porque las 10:03 no corresponden a la hora ni al período de inicio solicitados.

  • Los conectores de orígenes de datos de CloudWatch no admiten consultas multilínea. Cada fuente de línea se reemplaza por un espacio cuando se ejecuta la consulta o cuando se crea una alarma o un widget de panel con la consulta. En algunos casos, esto puede hacer que la consulta no sea válida.

Evento GetMetricData

Carga de solicitud

El siguiente es un ejemplo de una carga de solicitud GetMetricData enviada como entrada a la función de Lambda.

{
  "EventType": "GetMetricData",
  "GetMetricDataRequest": {
    "StartTime": 1697060700,
    "EndTime": 1697061600,
    "Period": 300,
    "Arguments": ["serviceregistry_external_http_requests{host_cluster!=\"prod\"}"] 
  }
}

  • StartTime: la marca de tiempo que especifica los primeros datos que se devolverán. El tipo es marca de tiempo, época y segundos.

  • EndTime: la marca de tiempo que especifica los últimos datos que se van a devolver. El tipo es marca de tiempo, época y segundos.

  • Período: el número de segundos que representa cada agregación de los datos de las métricas. El mínimo es de 60 segundos. El tipo es segundos.

  • Argumentos: una matriz de argumentos para pasar a la expresión matemática métrica de Lambda. Para obtener más información sobre cómo pasar argumentos, consulte Cómo pasar argumentos a la función de Lambda.

Carga de respuesta

A continuación, se muestra un ejemplo de una carga de respuesta GetMetricData que devuelve la función de Lambda.

{
   "MetricDataResults": [
      {
         "StatusCode": "Complete",
         "Label": "CPUUtilization",
         "Timestamps": [ 1697060700, 1697061000, 1697061300 ],
         "Values": [ 15000, 14000, 16000 ]
      }
   ]
}

La carga de respuesta contendrá un campo MetricDataResults o un campo Error, pero no ambos.

Un campo MetricDataResults es una lista de campos de series temporales de tipo MetricDataResult. Cada uno de esos campos de series temporales puede incluir los siguientes campos.

  • StatusCode: (opcional) Complete indica que se devolvieron todos los puntos de datos del intervalo de tiempo solicitado. PartialData significa que se devolvió un conjunto de puntos de datos incompleto. Si esto se omite, el valor predeterminado es Complete.

    Valores válidos: Complete | InternalError | PartialData | Forbidden

  • Mensajes: lista opcional de mensajes con información adicional sobre los datos devueltos.

    Tipo: matriz de objetos MessageData con cadenas Code y Value.

  • Etiqueta: la etiqueta legible por humanos asociada a los datos.

    Tipo: cadena

  • Marcas temporales: las marcas de tiempo de los puntos de datos, formateadas por épocas. El número de marcas de tiempo siempre coincide con el número de valores y el valor de Timestamps[x] es Values[x].

    Tipo: matriz de marcas temporales

  • Valores: los valores de los puntos de datos de la métrica, correspondientes a Timestamps. El número de valores siempre coincide con el número de marcas temporales y el valor de Timestamps[x] es Values[x].

    Tipo: matriz de dobles

Para obtener más información acerca de objetos Error, consulte las siguientes secciones.

Formatos de respuesta a errores

Si lo desea, puede utilizar la respuesta de error para proporcionar más información sobre los errores. Le recomendamos que devuelva un error de validación del código cuando se produzca un error de validación, por ejemplo, cuando falte un parámetro o sea del tipo incorrecto.

El siguiente es un ejemplo de la respuesta cuando la función de Lambda quiere generar una excepción de validación GetMetricData.

{
   "Error": {
      "Code": "Validation",
      "Value": "Invalid Prometheus cluster"
   }
}

El siguiente ejemplo muestra la respuesta cuando la función de Lambda indica que no puede devolver datos debido a un problema de acceso. La respuesta se traduce en una serie temporal única con un código de estado de Forbidden.

{
   "Error": {
      "Code": "Forbidden",
      "Value": "Unable to access ..."
   }
}

A continuación se muestra un ejemplo de cuando la función de Lambda genera una excepción InternalError general, que se traduce en una única serie temporal con un código de estado InternalError y un mensaje. Siempre que un código de error tenga un valor distinto de Validation o Forbidden, CloudWatch asume que se trata de un error interno genérico.

{
   "Error": {
      "Code": "PrometheusClusterUnreachable",
      "Value": "Unable to communicate with the cluster"
   }
}

Evento DescribeGetMetricData

Carga de solicitud

El siguiente es un ejemplo de una carga de solicitud de DescribeGetMetricData.

{
  "EventType": "DescribeGetMetricData"
}

Carga de respuesta

El siguiente es un ejemplo de una carga de respuesta de DescribeGetMetricData.

{
    "Description": "Data source connector",
    "ArgumentDefaults": [{
        Value: "default value"
     }]
}

  • Descripción: descripción de cómo utilizar el conector del origen de datos. Esta descripción aparecerá en la consola de CloudWatch. Se admite Markdown.

    Tipo: cadena

  • ArgumentDefaults: matriz opcional de valores predeterminados de argumentos que se utiliza para rellenar previamente el generador de orígenes de datos personalizados.

    Si se devuelve [{ Value: "default value 1"}, { Value: 10}], el generador de consultas de la consola de CloudWatch muestra dos entradas: la primera con el “valor predeterminado 1” y la segunda con 10.

    Si no se proporciona ArgumentDefaults, se muestra una única entrada con el tipo predeterminado establecido en String.

    Tipo: matriz de objetos que contiene el valor y el tipo.

  • Error: (opcional) se puede incluir un campo de error en cualquier respuesta. Puede ver algunos ejemplos en Evento GetMetricData.

Consideraciones importantes sobre las alarmas de CloudWatch

Si va a utilizar el origen de datos para configurar las alarmas de CloudWatch, debe configurarlo para que notifique los datos con marcas temporales a cada minuto a CloudWatch. Para obtener más información y otras consideraciones sobre la creación de alarmas en las métricas de los orígenes de datos conectados, consulte Creación de una alarma basada en un origen de datos conectado.

(Opcional) Uso de AWS Secrets Manager para almacenar credenciales

Si la función de Lambda necesita usar credenciales para acceder al origen de datos, le recomendamos que utilice AWS Secrets Manager para almacenar estas credenciales en lugar de codificarlas en la función de Lambda. Para obtener más información sobre el uso de AWS Secrets Manager con Lambda, consulte Utilizar secretos de AWS Secrets Manager en funciones de AWS Lambda.

(Opcional) Conexión a un origen de datos en una VPC

Si el origen de datos se encuentra en una VPC administrada por Amazon Virtual Private Cloud, debe configurar la función de Lambda para tener acceso. Para obtener más información, consulte Conexión de redes salientes a los recursos de una VPC.

Es posible que también necesite configurar los puntos de conexión del servicio de VPC para acceder a servicios como AWS Secrets Manager. Para obtener más información, consulte Acceso a un servicio de AWS a través de un punto de conexión de VPC de interfaz.

Paso 2: crear una política de permisos de Lambda

Debe crear una declaración de política que conceda permiso a CloudWatch para usar la función de Lambda que ha creado. Puede utilizar la AWS CLI o la consola de Lambda para crear la declaración de política.

Cómo usar la AWS CLI para crear la declaración de política

  • Escriba el siguiente comando. Sustituya 123456789012 por el ID de la cuenta, sustituya my-data-source-function por el nombre de la función de Lambda y sustituya MyDataSource-DataSourcePermission1234 por un valor único arbitrario.

    aws lambda add-permission --function-name my-data-source-function --statement-id MyDataSource-DataSourcePermission1234 --action lambda:InvokeFunction --principal lambda.datasource.cloudwatch.amazonaws.com --source-account 123456789012

Paso 3: asociar la etiqueta de recurso a la función de Lambda

La consola CloudWatch determina qué funciones de Lambda son conectores de orígenes de datos mediante una etiqueta. Al crear un origen de datos mediante uno de los asistentes, la pila AWS CloudFormation que la configura aplica automáticamente la etiqueta. Al crear un origen de datos usted mismo, puede usar la siguiente etiqueta para la función de Lambda. Esto hace que el conector aparezca en el menú desplegable Orígenes de datos de la consola de CloudWatch al consultar las métricas.

  • Una etiqueta con cloudwatch:datasource como la clave y custom como el valor.