Cloudinsight Agent 在 4.7.0 版本,将 Agent 名称从 oneapm-ci-agent 更换至 cloudinsight-agent。若您在使用过程中,出现无法正常工作的情况,请加入售后群:433349863
X

自定义 AgentCheck

概览

本文介绍如何通过自定义 AgentCheck 从数据源收集指标。下面,我们将通过一个简单的示例对 AgentCheck 接口一窥究竟。


安装探针

本文的基础是你已经成功安装探针,如果没有安装成功,请参考问题排错指南。如果已经成功安装探针,可以进行接下来的操作了。


Agent Check 接口

自定义的 check 都需要从 checks/__init__.py 继承 AgentCheck 类,并且 check 方法要有一个 instance 参数,其中 instance 是一个特定实例的字典,check 方法会在每个实例检查周期(即30s)内执行一次。


发送指标

在 check 中发送指标非常容易,发送指标有以下几个方法:

self.gauge( ... ) # Sample a gauge metric
self.increment( ... ) # Increment a counter metric
self.decrement( ... ) # Decrement a counter metric
self.histogram( ... ) # Sample a histogram metric
self.rate( ... ) # Sample a point, with the rate calculated at the end of the check
self.count( ... ) # Sample a raw count metric
self.monotonic_count( ... ) # Sample an increasing counter metric

所有的这些方法都有下面几个参数:

  • metric: 指标名称
  • value: 指标的值(默认递增为1,递减为-1)
  • tags:(可选)和这个指标关联的标签
  • hostname:(可选)和这个指标关联的主机,默认为当前主机
  • device_name:(可选)和这个指标关联的设备

这些方法可以在 check 函数的任意地方被调用,check 函数执行完后,所有的指标都会被收集并和其他探针指标一并提交至 Cloudinsight


异常

如果由于配置不正确或者编码错误导致 check 不能运行,或者无法收集到任何指标,这时应该抛出一个特定的异常信息。这个异常将可以被记录到探针的log(即/var/log/cloudinsight-agent/collector.log)中,您也可以通过探针的 info 命令进行输出,便于调试,如下:

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

  Checks
  ======

  my_custom_check
  ---------------
    - instance #0 [ERROR]: ConnectionError('Connection refused.',)
    - Collected 0 metrics & 0 events

日志信息

我们可以在自定义的 check 函数中通过 self.log 记录日志信息,例如 self.log.info('hello') 。记录的日志信息可以在探针日志文件(即/var/log/cloudinsight-agent/collector.log)中被找到,例如 checks.{name},其中 {name} 是您 check 模块的名字。


配置

每个 check 都有一个配置文件,位于 conf.d 目录下,配置文件是采用 yaml 格式编写的,名字需要和 check 模块的名字一致(例如 nginx.pynginx.yaml)。

配置文件结构如下:

init_config:
    key1: val1
    key2: val2

instances:
    - username: jon_smith
      password: 1234

    - username: jane_smith
      password: 5678
  • init_config: init_config 部分可以配置任意数量的键值对,这个会在每次 check 函数初始化时用到。
  • instances: instances 部分是一个实例的列表,其中的每个实例都会被作为参数传递至 check 函数并执行,这意味着 check 函数支持多实例。

目录结构

在您开始编写自定义 check 前,您需要对探针端 checks 的目录结构有足够的了解。有两个地方可以存放您的自定义 check 相关文件,如下:

  • checks.d 文件夹,也是探针所在地

所有的 Linux 系统,您可以在下面找到文件:

/etc/cloudinsight-agent/checks.d/

Windows Server >= 2008 系统,您可以在下面找到文件:

C:\Program Files (x86)\Cloudinsight\Cloudinsight Agent\checks.d
或
C:\Program Files\Cloudinsight\Cloudinsight Agent\checks.d
  • conf.d 文件夹,探针配置文件所在地

Linux 系统中,您可以在下面找到文件:

/etc/cloudinsight-agent/conf.d

Windows Server >= 2008 系统,您可以在下面找到文件:

C:\ProgramData\Cloudinsight\conf.d
或
C:\Documents and Settings\All Users\Application Data\Cloudinsight\conf.d\

一个简单的 HTTP check

配置文件的名字和 check 的名字必须一致,例如你要 check 的文件是 mycheck.py,那你的配置文件名称就必须为 mycheck.yaml

现在让我们编写一个检测 HTTP 节点状态的 check,每运行一次 check,都向 HTTP 节点发送一个 get 请求,如果响应成功(即返回200),则将响应时间作为一项指标提交至 Cloudinsight。

  • 定义配置文件 conf.d/http.yaml,如下:
init_config:
    default_timeout: 5

instances:
  - url: https://cn.bing.com

  - url: http://httpbin.org/delay/10
    timeout: 8

  - url: http://httpbin.org/status/400
  • 定义 check 方法,check 的核心就是制造 http 请求并获取该请求的响应时间,checks.d/http.py 文件内容如下:
import time
import requests

from collector.checks import AgentCheck

class HTTPCheck(AgentCheck):
    def check(self, instance):
        if 'url' not in instance:
            self.log.info("Skipping instance, no url found.")
            return

        # Load values from the instance config
        url = instance['url']
        default_timeout = self.init_config.get('default_timeout', 5)
        timeout = float(instance.get('timeout', default_timeout))

        # Check the URL
        start_time = time.time()
        try:
            r = requests.get(url, timeout=timeout)
            end_time = time.time()
        except requests.exceptions.Timeout as e:
            self.log.error(e)
            raise

        if r.status_code != 200:
            return

        timing = end_time - start_time
        self.gauge('http.reponse_time', timing, tags=['http_check'])


if __name__ == '__main__':
    check, instances = HTTPCheck.from_yaml('/path/to/conf.d/http.yaml')
    for instance in instances:
        print "\nRunning the check against url: %s" % (instance['url'])
        check.check(instance)
        print 'Metrics: %s' % (check.get_metrics())

可见,check 接口是很简单的,非常容易上手,还不 try 一把?


排错

您可以执行以下命令进行调试:

sudo -u cloudinsight-agent ci-agent check my_check

Windows 测试自定义 check

测试 Windows 自定义 check 很简单,探针安装后有一个 shell.exe 的文件,您可以直接在上面运行 Python 文件。

例如你 check my_check,保证已经配置正确 .py 和 .yaml 文件,可以在 shell.exe 里面运行:

>>> from checks import run_check
>>> run_check('my_check')

将输出 check 返回的指标数据。


如果您对 Cloudinsight 感兴趣,可以选择试用我们的产品,只需要点击下面的按钮免费注册即可。


立即注册 Cloudinsight