Check de OpenMetrics personalizado

Información general

Esta página explica en detalle la interfaz OpenMetricsBaseCheckV2 para un uso más avanzado, incluyendo un ejemplo de un check sencillo que recopila métricas de temporización y los eventos de estado de Kong. Para más detalles sobre la configuración de un check básico de OpenMetrics, consulta recopilación de métricas de Kubernetes Prometheus y OpenMetrics.

Nota: OpenMetricsBaseCheckV2 está disponible en Agent versión 7.26.x+ y requiere Python 3.

Si estás buscando la guía de implementación legacy o la guía de check personalizado de la interfaz OpenMetricsBasecheck, consulta Check de OpenMetrics legacy personalizado.

Uso avanzado: interfaz de check de OpenMetrics

Si tienes necesidades más avanzadas que el check genérico, como el preprocesamiento de métricas, puedes escribir un OpenMetricsBaseCheckV2 personalizado. Es la clase base del check genérico, y proporciona una estructura y algunos ayudantes para recopilar métricas, eventos y checks de servicio expuestos con Prometheus. La configuración mínima para checks basados en esta clase incluye:

  • Creación de una instancia por defecto con asignación de namespace y metrics.
  • Aplicación del método check() AND/OR:
  • Creación de un método con el nombre de la métrica de OpenMetric tratada (consulta self.prometheus_metric_name).

Consulta este ejemplo en la integración de Kong donde el valor de métrica de Prometheus kong_upstream_target_health se utiliza como check de servicio.

Escribir un check personalizado de OpenMetrics

Este es un ejemplo sencillo de escritura de un check de Kong para ilustrar el uso de la clase OpenMetricsBaseCheckV2. El siguiente ejemplo reproduce la funcionalidad del siguiente check genérico de Openmetrics:

instances:
  - openmetrics_endpoint: http://localhost:8001/status/
    namespace: "kong"
    metrics:
      - kong_bandwidth: bandwidth
      - kong_http_consumer_status: http.consumer.status
      - kong_http_status: http.status
      - kong_latency:
          name: latency
          type: counter
      - kong_memory_lua_shared_dict_bytes: memory.lua.shared_dict.bytes
      - kong_memory_lua_shared_dict_total_bytes: memory.lua.shared_dict.total_bytes
      - kong_nginx_http_current_connections: nginx.http.current_connections
      - kong_nginx_stream_current_connections: nginx.stream.current_connections
      - kong_stream_status: stream.status

Configuración

Los nombres de los archivos de configuración y check deben coincidir. Si tu check se llama micheck.py tu archivo de configuración debe llamarse micheck.yaml.

La configuración para un check de Openmetrics es casi igual que un check de Agent normal. La principal diferencia consiste en incluir la variable openmetrics_endpoint en tu archivo check.yaml. Esto va en conf.d/kong.yaml:

init_config:

instances:
    # URL of the Prometheus metrics endpoint
  - openmetrics_endpoint: http://localhost:8001/status/

Escribir el check

Todos los checks de OpenMetrics heredan de la clase OpenMetricsBasecheckV2:

from datadog_checks.base import OpenMetricsBaseCheckV2

class KongCheck(OpenMetricsBaseCheckV2):

Define el espacio de nombres de la integración

El valor de __NAMESPACE__ prefijará todas las métricas y checks de servicio recopilados por esta integración.

from datadog_checks.base import OpenMetricsBaseCheckV2

class KongCheck(OpenMetricsBaseCheckV2):
    __NAMESPACE__ = "kong"

Definir una asignación de métricas

La asignación de métricas permite cambiar el nombre de métrica y anular el tipo nativo de métrica.

from datadog_checks.base import OpenMetricsBaseCheckV2

class KongCheck(OpenMetricsBaseCheckV2):
    __NAMESPACE__ = "kong"

    def __init__(self, name, init_config, instances):
        super(KongCheck, self).__init__(name, init_config, instances)

        self.metrics_map =  {
            'kong_bandwidth': 'bandwidth',
            'kong_http_consumer_status': 'http.consumer.status',
            'kong_http_status': 'http.status',
            'kong_latency': {
                'name': 'latency',
                'type': 'counter',
            },
            'kong_memory_lua_shared_dict_bytes': 'memory.lua.shared_dict.bytes',
            'kong_memory_lua_shared_dict_total_bytes': 'memory.lua.shared_dict.total_bytes',
            'kong_nginx_http_current_connections': 'nginx.http.current_connections',
            'kong_nginx_stream_current_connections': 'nginx.stream.current_connections',
            'kong_stream_status': 'stream.status',
        }

Definir una instancia por defecto

Una instancia por defecto es la configuración básica utilizada para el check. La instancia por defecto debe anular metrics y openmetrics_endpoint. Anula la get_default_config en OpenMetricsBasecheckV2 con tu instancia por defecto.

from datadog_checks.base import OpenMetricsBaseCheckV2

class KongCheck(OpenMetricsBaseCheckV2):
    __NAMESPACE__ = "kong"

    def __init__(self, name, init_config, instances):
        super(KongCheck, self).__init__(name, init_config, instances)

        self.metrics_map = {
            'kong_bandwidth': 'bandwidth',
            'kong_http_consumer_status': 'http.consumer.status',
            'kong_http_status': 'http.status',
            'kong_latency': {
                'name': 'latency',
                'type': 'counter',
            },
            'kong_memory_lua_shared_dict_bytes': 'memory.lua.shared_dict.bytes',
            'kong_memory_lua_shared_dict_total_bytes': 'memory.lua.shared_dict.total_bytes',
            'kong_nginx_http_current_connections': 'nginx.http.current_connections',
            'kong_nginx_stream_current_connections': 'nginx.stream.current_connections',
            'kong_stream_status': 'stream.status',
        }

      def get_default_config(self):
            return {'metrics': self.metrics_map}

Aplicación del método de check

Si deseas implementar funciones adicionales, sobrescribe la función check().

Desde instance, utiliza endpoint, que es el endpoint de métricas de Prometheus u OpenMetrics desde el que sondear métricas:

def check(self, instance):
    endpoint = instance.get('openmetrics_endpoint')
Excepciones

Si un check no puede ejecutarse debido a una configuración incorrecta, un error de programación o porque no pudo recopilar ninguna métrica, debe lanzar una excepción significativa. Esta excepción se registra y se muestra en el comando de estado del Agent para la depuración. Por ejemplo:

$ sudo /etc/init.d/datadog-agent info

  Checks
  ======

    my_custom_check
    ---------------
      - instance #0 [ERROR]: Unable to find openmetrics_endpoint in config file.
      - Collected 0 metrics & 0 events

Mejora tu método de check() con ConfigurationError:

from datadog_checks.base import ConfigurationError

def check(self, instance):
    endpoint = instance.get('openmetrics_endpoint')
    if endpoint is None:
        raise ConfigurationError("Unable to find openmetrics_endpoint in config file.")

En cuanto dispongas de datos, elimina:


def check(self, instance):
    endpoint = instance.get('openmetrics_endpoint')
    if endpoint is None:
        raise ConfigurationError("Unable to find openmetrics_endpoint in config file.")

    super().check(instance)

Ponerlo todo junto

from datadog_checks.base import OpenMetricsBaseCheckV2
from datadog_checks.base import ConfigurationError

class KongCheck(OpenMetricsBaseCheckV2):
    __NAMESPACE__ = "kong"

    def __init__(self, name, init_config, instances):
        super(KongCheck, self).__init__(name, init_config, instances)

        self.metrics_map = {
            'kong_bandwidth': 'bandwidth',
            'kong_http_consumer_status': 'http.consumer.status',
            'kong_http_status': 'http.status',
            'kong_latency': {
                'name': 'latency',
                'type': 'counter',
            },
            'kong_memory_lua_shared_dict_bytes': 'memory.lua.shared_dict.bytes',
            'kong_memory_lua_shared_dict_total_bytes': 'memory.lua.shared_dict.total_bytes',
            'kong_nginx_http_current_connections': 'nginx.http.current_connections',
            'kong_nginx_stream_current_connections': 'nginx.stream.current_connections',
            'kong_stream_status': 'stream.status',
        }

      def get_default_config(self):
            return {'metrics': self.metrics_map}

      def check(self, instance):
          endpoint = instance.get('openmetrics_endpoint')
          if endpoint is None:
              raise ConfigurationError("Unable to find openmetrics_endpoint in config file.")

          super().check(instance)

Aprender más

Para obtener más información sobre las integraciones de base de Prometheus y OpenMetrics, consulta documentos para desarrolladores de integraciones.

Para ver todas las opciones de configuración disponibles en Openmetrics, consulta el conf.yaml.example. Puedes mejorar tu check de OpenMetrics al incluir valores por defecto para opciones adicionales de configuración:

exclude_metrics
algunas métricas se ignoran porque son duplicados o introducen una cardinalidad alta. Las métricas incluidas en esta lista se omiten silenciosamente sin una línea de depuración Unable to handle metric en los logs. Para excluir todas las métricas excepto las que coincidan con un filtro específico, puedes utilizar un regex de búsqueda negativa como: - ^(?!foo).*$
share_labels
si se proporciona la asignación de share_labels, la asignación permite compartir etiquetas entre múltiples métricas. Las claves representan las métricas expuestas desde las que compartir etiquetas, y los valores son asignaciones que configuran el comportamiento para compartir. Cada asignación debe tener al menos una de las siguientes claves: labels, match, o values.

exclude_labels exclude_labels es una matriz de etiquetas a excluir. Esas etiquetas no se añaden como etiquetas al enviar la métrica.

Leer más