这是本节的多页打印视图。 点击此处打印.

返回本页常规视图.

SmartAgent老版本

老版本SmartAgent相关描述

实现原理

smartagent底层通过websocket协议进行服务端与客户端的RPC通信，同时通过内部的心跳机制来进行节点保活，从宏观上看agent的处理逻辑如下

agent_main

  1. smartagent底层使用websocket协议与服务端进行连接，在连接过程中含有一次握手的过程，握手过程中agent会上报配置文件中的agent_id信息与当前操作系统信息，服务端在收到握手信息后会通过manifest.json中的描述信息来分发对应操作系统的插件
  2. 握手过程中若发现当前上报的agent_id已存在（当前活跃连接中已包含该agent_id的agent连接）则会返回握手失败消息并告知id冲突
  3. executor为插件执行器，在非windows操作系统下支持插件切换到其他用户身份运行
  4. smartagent使用containerd/cgroups库来限制linux系统下的资源使用，目前仅支持cgroups v1

Msg结构

Msg结构为smartagent底层通信的核心数据结构，其结构如下

type Msg struct {
    Type      TypeName    `json:"type"`             // 消息类型，详见消息类型章节
    Important bool        `json:"-"`                // 是否是关键消息
    TaskID    string      `json:"tid,omitempty"`    // 任务ID
    Plugin    *PluginInfo `json:"plugin,omitempty"` // 所需调用的插件信息
    ErrorMsg  string      `json:"errmsg,omitempty"` // 错误消息的详情
    // ctrl
    Come      *ComePayload      `json:"come,omitempty"`      // 握手请求
    Handshake *HandshakePayload `json:"handshake,omitempty"` // 握手返回结果
    ...
}

  1. type字段是一个整数类型的字段，用于表明该消息的类型，目前已定义区段如下

     0~9: 系统保留，用于服务端到agent通信
 10+: 各插件使用

  2. tid字段用于表明该消息的id

  3. plugin字段用于表明该消息所需使用的插件信息，其中包含插件的版本号等，当agent收到的msg非系统消息且不包含plugin信息时该消息将被丢弃

     type PluginInfo struct {
     Name    string         `json:"name"`    // 插件名称
     Version string         `json:"version"` // 插件版本号
     MD5     [md5.Size]byte `json:"md5"`     // 插件文件的md5
     URI     string         `json:"uri"`     // 插件下载的uri
 }

  4. 在Msg结构的设计时，应尽量缩短字段名并增加omitempty关键字来忽略控制，以此来减少数据传输时的数据量

executor与插件化

executor是smartagent中的插件执行器，目前实现了以下功能：

  1. 下载并管理插件的可执行文件，当某个插件的低版本所有进程退出时进行旧版本文件清理

  2. 插件运行时参数配置信息生成，插件的运行参数将会被写入到临时文件内，插件运行参数通过临时文件尽心传递，在运行完毕后该临时文件将会被删除

  3. 插件运行时的日志将会通过stderr进行输出，executor在收集到日志后将会在每一行前面加上时间

  4. 插件返回数据可通过stdout进行输出，每一次插件运行允许输出多条数据，输出的格式如下

     <length(4字节)><crc32(4字节)><payload>

  5. 插件的基本实现原理如下

    plugin

1 - API接口文档

API接口文档

1.1 - 安装软件相关接口

安装软件相关接口，依赖install插件

1.1.1 - /install/run

安装软件

参数

  1. id: 机器id
  2. uri: 下载uri，可选
  3. url: 下载url，可选
  4. dir: 安装或解压路径，可选
  5. timeout: 超时时间，单位秒，可选，默认300
  6. auth: sudo、su或空值，可选
  7. user: 账号，可选
  8. pass: 密码，可选

返回值

{
  "code": 0,
  "payload": 任务ID
}

错误，未找到机器

{
  "code": 404,
  "msg": "client not found"
}

错误，其他运行时错误

{
  "code": 500,
  "msg": 错误内容
}

说明

  1. dir参数仅当msi、exe或压缩包时有效
  2. url和uri参数必须传一个，且uri参数的优先级高于url参数
  3. 目前仅支持deb、rpm、tar、tar.gz、tar.bz2、zip、msi和exe类型的安装包

1.1.2 - /install/status

获取安装任务详情

参数

  1. task_id: 任务ID

返回值

{
  "code": 0,
  "payload": {
    "done": 是否完成,
    "actions": [
      {
        "action": 任务类型,
        "name": 名称,
        "time": 时间戳,
        "ok": 是否成功,
        "msg": 失败信息
      }, ...
    ]
  }
}

错误，任务不存在

{
  "code": 404,
  "msg": 错误信息
}

说明

  1. 任务类型包含以下几种：
    • download: 下载安装包
    • install: 安装或解压安装包
    • file: 附加文件
    • done: 完成
  2. name字段定义：
    • download: 安装包下载路径
    • install: 安装包下载路径
    • file: 附加文件保存路径

1.2 - 插件相关接口

插件相关接口

1.2.1 - /plugin/reload

重载插件

参数

无

返回值

{
  "code": 0
}

1.3 - 服务器端相关接口

服务器端相关接口

1.3.1 - /server/info

获取当前服务端信息

参数

无

返回值

{
  "code": 0,
  "payload": {
    "clients": 连接客户端数量,
    "plugins": 插件数量,
    "version": 版本号,
    "created": 安装时间
  }
}

1.4 - 节点相关接口

节点相关接口

1.4.1 - /host/info

获取单个节点的基本信息

参数

  1. id: 机器ID

返回值

{
  "code": 0,
  "payload": {
    "hostname": 主机名,
    "os": linux或windows
  }
}

1.4.2 - /host/list

查询节点列表

参数

  1. ids: 需获取主机ID列表，可选，csv

返回值

{
  "code": 0,
  "payload": [
    {
      "id": 机器ID,
      "version": agent版本号,
      "ip": ip地址,
      "mac": mac地址,
      "os": 操作系统（windows或linux）,
      "platform": 操作系统名称（centos或debian）,
      "arch": 操作系统位数（amd64或i386）
    }, ...
  ]
}

说明

  1. 当不传ids参数时表示获取所有主机列表，否则获取给定ID的列表，若给定ID不存在则忽略

1.4.3 - /host/search

根据IP地址或MAC地址查找节点

参数

  1. keyword: IP地址或MAC地址

返回值

{
  "code": 0,
  "payload": 主机ID
}

错误，未找到

{
  "code": 404,
  "msg": "client not found"
}

1.5 - 流程编排相关接口

流程编排相关接口，目前仅支持exec和file插件

1.5.1 - /layout/run

执行编排文件

参数

  1. ids: id列表，csv格式
  2. mode: 执行顺序，可选，默认sequence
  3. continue: 出错时是否继续，可选，默认为false
  4. file: 资源文件tar包
  5. user: 账号，可选
  6. pass: 密码，可选

返回值

{
  "code": 0,
  "payload": 任务ID
}

错误，检测未通过

{
  "code": 1,
  "msg": 错误内容
}

错误，指定agentid未找到

{
  "code": 404,
  "msg": 错误内容
}

说明

  1. mode参数支持以下执行方式:

    sequence: 顺序执行，按给定的id列表顺序一个一个agent执行
parallel: 并发执行，按给定的id列表同时执行，此时continue参数无效
evenodd: 奇偶模式执行，按给定的id列表顺序分为两组，分别执行

  2. 上传的tar包中必须包含main.yaml或main.json文件作为执行时的编排文件

  3. tar包中不允许包含软链文件，在解压时软链文件将被忽略

1.5.2 - /layout/status

获取执行进度信息

参数

  1. task_id: 任务ID

返回值

{
  "code": 0,
  "payload": {
    "done": 是否全部完成,
    "created": 开始时间戳,
    "finished": 结束时间戳未完成时为0,
    "total_count": 总触达节点数量,
    "finished_count": 完成节点数量,
    "nodes": [
      {
        "id": 节点ID,
        "created": 开始时间戳,
        "finished": 结束时间戳未完成时为0,
        "ok": 是否成功,
        "msg": 错误信息
      }, ...
    ]
  }
}

错误，任务不存在

{
  "code": 404,
  "msg": 错误内容
}

1.6 - 命令行相关接口

命令行相关接口，依赖exec插件

1.6.1 - /cmd/kill

杀死正在执行的进程

参数

  1. id: 机器id
  2. pid: 进程id

返回值

{
  "code": 0
}

错误，未找到机器

{
  "code": 404,
  "msg": "(client|process) not found"
}

1.6.2 - /cmd/ps

列出当前正在执行的命令列表

参数

  1. id: 机器ID

返回值

{
  "code": 0,
  "payload": [
    {
      "id": 进程ID,
      "channel": 输出信息的管道ID,
      "name": 进程名称,
      "start_time": 进程创建时间戳,
      "up_time": 启动时间（秒）
    }, ...
  ]
}

错误，未找到机器

{
  "code": 404,
  "msg": "client not found"
}

1.6.3 - /cmd/pty

获取脚本输出内容

参数

  1. id: 机器ID
  2. pid: 进程ID

返回值

http_code=200
body=内容

pid不存在

http_code=404
body=process not found

错误，其他异常

http_code=500
body=错误内容

1.6.4 - /cmd/run

执行命令

参数

  1. id: 机器ID
  2. cmd: 命令
  3. args: 运行参数，csv，逗号用%2c%编码
  4. timeout: 运行超时秒数，可选（默认3600）
  5. auth: sudo、su或空值，可选
  6. user: 账号，可选
  7. pass: 密码，可选
  8. workdir: 工作目录，可选
  9. env: 环境变量，csv，逗号用%2c%编码
  10. defer_rm: 运行完毕后删除的文件路径，可选
  11. callback: 运行完毕后回调地址，可选

返回值

{
  "code": 0,
  "payload": {
    "channel_id": "20220706-00002-f230bae72f2ca269", // 任务ID
    "pid": 9655 // 进程id
  }
}

错误，未找到机器

{
  "code": 404,
  "msg": "client not found"
}

错误，超时

{
  "code": 408,
  "msg": "timeout"
}

错误，命令执行失败

{
  "code": 1,
  "msg": "错误原因"
}

说明

  1. 当给定defer_rm参数时命令执行完毕后将会删除给定路径的文件
  2. 当给定callback参数时将会通过GET的方式进行回调，同时将以下参数拼接在url内部
    • agent_id: 执行agent的ID
    • pid: 创建进程ID

1.6.5 - /cmd/status

获取进程运行状态

参数

  1. id: 机器ID
  2. pid: 进程ID

返回值

{
  "code": 0,
  "payload": {
    "id": 进程ID,
    "channel": 该进程的channel id,
    "created": 进程创建时间,
    "running": 该进程是否在执行中,
    "code": 返回码（仅当running=false时有效）
  }
}

错误，未找到机器或进程

{
  "code": 404,
  "msg": 错误内容
}

1.6.6 - /cmd/sync_run

执行命令并同步等待其完成

参数

  1. id: 机器ID
  2. cmd: 命令
  3. args: 运行参数，csv，逗号用%2c%编码
  4. timeout: 运行超时秒数，可选（默认60，最大60）
  5. auth: sudo、su或空值，可选
  6. user: 账号，可选
  7. pass: 密码，可选
  8. workdir: 工作目录，可选
  9. env: 环境变量，csv，逗号用%2c%编码
  10. defer_rm: 运行完毕后删除的文件路径，可选

返回值

{
  "code": 0,
  "payload": {
    "code": 0, // 返回码（-65535表示执行失败或超时）
    "data": "aGVsbG8gd29ybGQ=", // 返回内容经过base64编码
  }
}

错误，未找到机器

{
  "code": 404,
  "msg": "client not found"
}

错误，超时

{
  "code": 408,
  "msg": "timeout"
}

错误，命令执行失败

{
  "code": 1,
  "msg": "错误原因"
}

说明

  1. 当给定defer_rm参数时当命令执行完毕后将会执行对应操作

1.7 - 日志采集相关接口

日志采集相关接口，依赖log-agent

1.7.1 - /logging/config

下发日志采集配置

参数

  1. pid: 项目ID
  2. type: k8s、docker、logtail中的任意一个
  3. exclude: 去除日志的正则，可选
  4. batch: 批量上报条数，默认1000
  5. buffer: 批量上报数据量，单位字节，默认4096
  6. interval: 批量上报间隔超时时间，单位秒，默认30

k8s参数

  1. ns: 所需采集的namespace
  2. name: 所需采集的项目名，csv
  3. dir: 文件路径，支持通配符
  4. api: k8s接口地址
  5. token: k8s采集时所需的token信息

docker参数

  1. ids: 目标机器id，csv
  2. ct_name: 容器名称
  3. ct_tag: 容器tag，可选
  4. dir: 文件路径，支持通配符

logtail参数

  1. ids: 目标机器id，csv
  2. dir: 文件路径，支持通配符

返回值

{
  "code": 0
}

错误：没有可用的采集节点

{
  "code": 1,
  "msg": 错误内容
}

说明

  1. 当type参数为k8s或docker且dir参数为空时表示采集该容器的stdout输出信息

1.7.2 - /logging/remove

删除采集任务

参数

  1. pid: 项目ID

返回值

{
  "code": 0
}

错误，任务不存在

{
  "code": 404,
  "msg": 错误内容
}

1.7.3 - /logging/start

启动采集任务

参数

  1. pid: 项目ID

返回值

{
  "code": 0
}

错误，项目已启动

{
  "code": 1,
  "msg": 错误内容
}

错误，任务不存在

{
  "code": 404,
  "msg": 错误内容
}

1.7.4 - /logging/stop

停止采集任务

参数

  1. pid: 项目ID

返回值

{
  "code": 0
}

错误，项目未启动

{
  "code": 1,
  "msg": 错误内容
}

错误，任务不存在

{
  "code": 404,
  "msg": 错误内容
}

1.7.5 - /logging/task_info

获取采集任务详情

参数

  1. pid: 项目ID

返回值

{
  "code": 0,
    "payload": {
      "type": 任务类型,
      "exclude": 去除日志的正则,
      "batch": 批量上报条数,
      "buffer": 批量上报数据量,
      "interval": 批量上报间隔超时时间,
      "created": 创建时间戳,
      "nodes": [
        {
          "id": 节点ID,
          "status": running或stoped,
          "info": [
            { // k8s
              "ns": namespace,
              "name": 项目名,
              "dir": 文件路径,
              "pods": 上一次采集时的pod数量，定期上报
            },
            { // docker
            },
            { // file
              "dir": 文件路径
            }, ...
          ]
        }, ...
      ]
    }
  }
}

错误，任务不存在

{
  "code": 404,
  "msg": 错误内容
}

1.8 - 文件操作相关接口

文件操作相关接口，依赖file插件

1.8.1 - /file/download

下载某个节点上的文件

参数

  1. id: 机器id
  2. dir: 文件路径
  3. timeout: 超时事件，默认10分钟

返回值

文件内容

错误，未找到机器或文件

http_code=404
body=(client/file) not found

错误，超时

http_code=408
body=timeout

错误，校验码错误

http_code=409
body=invalid checksum

错误，运行时错误

http_code=503
body=错误内容

1.8.2 - /file/ls

查询某个节点上的文件

参数

  1. id: 机器ID
  2. dir: 目录

返回值

{
  "code": 0,
  "payload": {
    "dir": 目录,
    "files": [
      {
        "name": 名称,
        "auth": 权限,
        "user": 所属用户,
        "group": 所属组,
        "size": 文件大小,
        "mod_time": 更新时间戳,
        "is_dir": 是否是目录,
        "is_link": 是否是软链
      }, ...
    ]
  }
}

错误，未找到机器或目录不存在

{
  "code": 404,
  "msg": "(client/directory) not found"
}

错误，超时

{
  "code": 408,
  "msg": "timeout"
}

错误，其他错误

{
  "code": 500,
  "msg": 错误内容
}

1.8.3 - /file/upload_from

从指定url上传文件到某个节点

参数

  1. id: 机器id
  2. dir: 保存位置
  3. name: 文件名
  4. uri: 下载uri
  5. auth: sudo、su或空值，可选
  6. user: 账号，可选
  7. pass: 密码，可选
  8. mod: 文件权限，十进制，可选，默认0644
  9. own_user: 文件所属用户
  10. own_group: 文件所属分组
  11. timeout: 超时时间，单位秒，可选，默认60

返回值

{
  "code": 0,
  "payload": {
    "dir": 文件存放路径
  }
}

错误，未找到机器

{
  "code": 404,
  "msg": "client not found"
}

错误，其他运行时错误

{
  "code": 500,
  "msg": 错误内容
}

错误，上传失败

{
  "code": 1,
  "msg": 错误内容
}

错误，文件内容错误

{
  "code": 2,
  "msg": 错误内容
}

1.8.4 - /file/upload

上传文件到某个节点

参数

  1. id: 机器id
  2. dir: 保存位置
  3. auth: sudo、su或空值，可选
  4. user: 账号，可选
  5. pass: 密码，可选
  6. mod: 文件权限，十进制，可选，默认0644
  7. own_user: 文件所属用户
  8. own_group: 文件所属分组
  9. file: http标准文件上传字段
  10. timeout: 超时时间，单位秒，可选，默认60
  11. md5: 文件md5，可选

返回值

{
  "code": 0,
  "payload": null
}

错误，未找到机器

{
  "code": 404,
  "msg": "client not found"
}

错误，其他运行时错误

{
  "code": 500,
  "msg": 错误内容
}

错误，上传失败

{
  "code": 1,
  "msg": 错误内容
}

错误，文件内容错误

{
  "code": 2,
  "msg": 错误内容
}

1.9 - 主机信息采集相关接口

主机信息采集相关接口，依赖host.monitor插件

1.9.1 - /hm/static

获取主机的静态监控数据

参数

  1. id: 机器ID

返回值

{
  "code": 0,
  "payload": {
    "timestamp": 上报时间戳,
    "host_name": 主机名,
    "uptime": 启动时长,
    "os_name": 系统类型，linux、windows,
    "platform": 系统名称，如debian、centos,
    "platform_version": 系统版本号,
    "kernel_arch": 内核类型，如i386、amd64,
    "kernel_version": 内核版本，如3.10.0-1062.el7.x86_64,
    "physical_core": 物理核心数,
    "logical_core": 逻辑核心数,
    "cores": [
      {
        "processor": 该核心编号,
        "model": 名称，如Intel(R) Xeon(R) CPU E5-2620 v2 @ 2.10GHz,
        "core": 所在物理核上的编号,
        "cores": 某块CPU上的编号,
        "physical": 物理CPU编号
      }, ...
    ]
    "physical_memory": 物理内存大小,
    "swap_memory": swap内存大小,
    "disks": [
      {
        "name": 名称，linux为挂载路径如/run，windows为盘符如C:,
        "type": 文件系统类型，如NTFS,
        "options": [附加参数，如rw，nosuid，nodev, ...],
        "total": 总容量,
        "inodes": inode数量
      }, ...
    ],
    "intfs": [
      {
        "index": 编号,
        "name": 名称,
        "mtu": mtu,
        "flags": [附加信息, ...],
        "mac": mac地址,
        "addrs": [ip地址, ...],
      }, ...
    ]
  }
}

错误，未找到机器

{
  "code": 404,
  "msg": "client not found"
}

错误，超时

{
  "code": 408,
  "msg": "timeout"
}