example-agent

• 1: Agent开发
• 2: 配置项描述

1 - Agent开发

Agent开发

1. 创建项目并导入libagent库

   go get github.com/jkstack/libagent
   

2. 定义一个结构体并实现App接口

3. 在main函数中添加RegisterService、UnregisterService和Run等libagent库中的接口调用

   switch *act {
   case "install":
       agent.RegisterService(app)
   case "uninstall":
       agent.UnregisterService(app)
   default:
       agent.Run(app)
   }
   

研发与打包规范

1. 项目根目录中必须包含一个CHANGELOG.md文件，在打包过程中会自动读取该文件中的内容并自动填写到Release的描述信息中，格式可参考样例
2. 项目根目录中必须包含一个Makefile文件，在打包过程中会使用该文件中的第一个目标进行打包，打包成功后的产物必须存放到release目录下
3. 开发的代码在原则上需要支持谷歌维护的最新的两个go语言版本，因此在go.mod文件中目前会被设置为1.18版本
4. 在项目初始化的过程中需要修改contrib目录下的文件，如修改正确的打包路径等
5. 为方便于外部工具化部署，需要正确修改manifest.yaml文件，使其符合配置文件中的配置项描述

打包方法

通过在项目中引入workflows目录下的build.yml和release.yml可实现项目的自动化打包。

1. build.yml中定义了当master分支发生合并时会进行代码的lint检查及go build测试
2. release.yml中定义了当该项目被打上了v*.*.*的标签后将会触发release动作，首先会进行各种系统下的跨平台编译与打包，然后读取CHANGELOG.md中对应版本的描述信息进行创建release操作，并将release目录下的文件进行上传

更多示例

1. exec-agent: 远程执行脚本以及文件传输
2. metrics-agent: 监控数据采集

2 - 配置项描述

每一个Agent项目中的conf目录下必须包含一个manifest.yaml文件用于描述该Agent的配置项信息，该文件被用于外部工具做自动化部署时的展示。

该文件的内容最顶层为一个数组，其中每一个元素代表配置文件中的某一个字段，该字段的描述信息如下：

• key: 该字段在配置文件中的名称
• name.zh: 该字段的中文名称，用于自动化部署工具的展示
• desc.zh: 该字段的中文描述
• type: 该字段类型，目前已支持以下类型
  • string: 字符串
  • enum: 枚举值
  • csv: 逗号分隔的字符串，允许多个值
  • int: 有符号整数
  • uint: 无符号整数
  • float: 浮点数
  • bool: 布尔值
  • naddr: 网络地址，<ip>:<port>
  • path: 文件路径
  • bytes: 可视化字节数，(n)G、(n)M、(n)KB、(n)B等
  • duration: 时长，(n)h、(n)m、(n)s等
  • uuid: 唯一标识ID
• required: 是否必填
• default: (可选)默认值
• enum_valid: (可选)enum字段允许输入的内容
• csv_valid: (可选)csv字段允许输入的内容
• str_valid: (可选)string类型的匹配正则表达式
• min: (可选)最小值，支持的数据类型int、uint、float、bytes、duration
• max: (可选)最大值，支持的数据类型int、uint、float、bytes、duration
• len: (可选)最大长度，支持的数据类型string、csv、path
• allow_relative: (可选)是否允许使用相对路径，支持的数据类型path
• category: (可选)配置项分类

示例

- key: basic.id
  type: string
  name:
    zh: AgentID
  desc:
    zh: Agent的ID，在当前服务器下的集群内唯一
  required: true
- key: basic.server
  type: naddr
  name:
    zh: 服务端地址
  desc:
    zh: 链接服务器端的地址
  default: 127.0.0.1:13081
  required: true
- key: basic.log.target
  type: csv
  name:
    zh: 日志保存目标
  desc:
    zh: 日志保存目标，目前仅支持stdout和文件
  default: stdout
  csv_valid: [ stdout, file ]
  required: false
- key: basic.log.dir
  type: path
  name:
    zh: 日志保存路径
  desc:
    zh: 日志保存路径
  default: ./logs
  required: false
- key: basic.log.size
  type: bytes
  name:
    zh: 日志文件滚动大小
  desc:
    zh: 日志文件生成时每个文件的大小
  default: 10M
  min: 1M
  max: 100M
  required: false
- key: basic.log.rotate
  type: uint
  name:
    zh: 日志文件保留份数
  desc:
    zh: 日志文件生成时最多保留份数
  default: 7
  min: 1
  max: 100
  required: false

关联关系

示例1

log.target = stdout,file
log.dir = ./logs
log.size = 10M
log.rotate = 7

当log.target字段未设置file属性时，log.dir、log.size、log.rotate配置项是无效的。

示例2

monitor.enabled = true
monitor.interval = 10s

当monitor.enabled字段设置为false时，monitor.interval配置项是无效的。

基于以上两种情况，增加配置字段如下：

- key: basic.log.dir
  ...
  enabled:
    when:
      target: basic.log.target
      contain: file
- key: basic.monitor.interval
  ...
  enabled:
    when:
      target: basic.monitor.enabled
      equal: true

1. enabled字段用于表示当前字段的有效范围
2. when字段表示当条件中的描述符合要求时该字段有效
3. target: 该字段表示需要关联到的原始字段名称
4. contain: 针对于原始字段为csv类型时csv内容中包含该配置项时当前字段才有效
5. equal: 针对于原始字段为bool或数值类型时原始字段的值与要求内容相符时才有效