logkit 管理用户 API

用户 API 允许通过 Token 或 AK/SK 鉴权， Token的生成方式与数据推送相同。

Agents

获取 agent 列表

  1. GET /v1/api/agents?tag=<tagValue>&id=<idValue>&state=<stateValue1,stateValue2>&sort=<sortKey>&order=<order>&page=<pageNum>&size=<pageSize>&search=<search>

返回值

  • 如果没有错误, 返回：
    1. {
    2.   "agentList":[
    3.   {
    4.       "id": "<agent_id>",
    5.       "ip":"10.10.0.1",
    6.       "tags":["tag1", "tag2"],
    7.       "hostname":"nb110",
    8.       "create_time": <timestamp>,
    9.       "state": "<state>",
    10.       "runners": ["runner1", "runner2"],
    11.       "machine": {
    12.           "hostname": "<hostname>",
    13.           "boot_time": <启动时间>,
    14.           "kernel": "<内核类型>",
    15.           "kernel_version": "<内核版本>",
    16.           "platform": "<平台类型>",
    17.           "platform_version": "<平台版本>",
    18.           "cpu": {
    19.               "model": "<cpu_model_name>",
    20.               "Mhz": <主频, 单位 Mhz>,
    21.               "Cache": <二级缓存大小>,
    22.               "Cores": <cpu 核数>,
    23.               "count": <cpu 个数>
    24.           },
    25.           "memory": <内存大小>,
    26.           "interface": [ //网卡信息
    27.               {
    28.                   "name": "<名称>",
    29.                   "mtu": <最大数据包大小(字节)>,
    30.                   "mac": "<Mac 地址>",
    31.                   "ip": [
    32.                       "<ip1>",
    33.                       "<ip2>",
    34.                       ...
    35.                   ],
    36.                   "mask": [
    37.                       "<子网掩码1>",
    38.                       "<子网掩码2>",
    39.                       ...
    40.                   ] // 子网掩码的与 ip 一一对应
    41.               },
    42.               ...
    43.           ],
    44.           "disk": [
    45.               {
    46.                   "device": "<名称>",
    47.                   "fstype": "<文件系统类型>",
    48.                   "mount": "<挂载点>",
    49.                   "size": <容量>
    50.               },
    51.               ...
    52.           ]
    53.       }
    54.   },
    55.   ...
    56.   ],
    57.   "totalSize":<total_size>
    58. }
  • 如果有错误则返回相应错误

参数说明

  • 参数 tag、id 和 state 非空时将作为被操作 agent 的过滤条件，即上述操作只对满足对应条件的 agent 有效
  • 参数 sort、order 会根据 sort 的值进行升序/降序排序，order 的值可以是 ascend/descend，sort 默认为 hostname，order 默认为 ascend
  • 参数 search 会对 hostname 进行搜索，将包含 search 值的结果搜索出来
  • status 状态有三种，ok 表示正常（30s 内有联系）；bad 表示 1 分钟内有联系；lost 表示超过 1 分钟无心跳
  • 如果需要分页则提供当前页数 page 以及每页的数量 size
  • 状态有三种:
    • register: 注册了但是还没有发第一次心跳
    • online: 与 tcpserver 保持连接时
    • offline: 与 tcpserver 断开连接时

删除 agents

  1. DELETE /v1/api/agents?tag=tagValue&id=idvalue&state=stateValue

返回值

  • 如果没有错误，返回空
  • 如果有错误则返回相应错误

参数说明

  • 参数 tag、id 和 state 非空时将作为被操作 agent 的过滤条件，即上述操作只对满足对应条件的 agent 有效
  • 执行该操作进行后，agent 必须重启才能重新注册到 server 端

删除多个 agent

  1. DELETE /v1/api/agents/batch?id=<agent_id1>,<agent_id2>

返回值

  • 如果没有错误，返回空
  • 如果有错误则返回相应错误

为 agent 添加标签

  1. POST /v1/api/agents/<agent_id>/tags/<tag_name>

返回值

  • 如果没有错误，返回空
  • 如果有错误则返回相应错误

为 agent 添加多个标签

  1. POST /v1/api/agents/<agent_id>/tags
  2. Content-Type: application/json
  3. {
  4.    "tags": ["<tag_name1>","<tag_name2>"]
  5. }

返回值

  • 如果没有错误，返回空
  • 如果有错误则返回相应错误

删除 agent 标签

  1. DELETE /v1/api/agents/<agent_id>/tags/<tag_name>

返回值

  • 如果没有错误，返回空
  • 如果有错误则返回相应错误

获取 release 的最新信息

  1. GET /v1/api/release

返回值

  1. [
  2.     {
  3.         "os": "<os>",
  4.         "arch":"<arch>",
  5.         "hash":"<hash>",
  6.         "message":"<message>",
  7.         "version":"<version>",
  8.         "package":"<package>",
  9.         "download_url":"<download_url>",
  10.         "version_stamp":"<version_stamp>"
  11.     }
  12.     ...
  13. ]

升级 agent

  1. POST /v1/api/agents/upgrade
  2. Content-Type: application/json
  3. {
  4.     "agent_ids": [],
  5.     "tags": []
  6. }

Configs

获取 config 列表

  1. GET /v1/api/configs?name=<tagName>&sort=<sortKey>&order=<order>&page=<pageNum>&size=<pageSize>&search=<search>

返回值

  • 如果没有错误, 返回：
  1. {
  2.     "configs":[
  3.         {
  4.             "name": "<config_name>",
  5.             "tags": ["tag1", "tag2"],
  6.             "config": {},
  7.             "note": "<config 备注>",
  8.             "timestamp": <timestamp>
  9.         },
  10.         ...
  11.     ],
  12.     "totalSize":<total_size>
  13. }
  • 如果有错误则返回相应错误

参数说明

  • 参数 sort、order 会根据 sort 的值进行升序/降序排序，order 的值可以是 ascend/descend，sort 默认为 hostname，order 默认为 ascend
  • 参数 search 会对 hostname 进行搜索，将包含 search 值的结果搜索出来

添加 config

  1. POST /v1/api/configs/<config_name>
  2. Content-Type: application/json
  3. {
  4.    "name": "<config_name>",
  5.    "tags": "["tag1", "tag2"]",
  6.    "config": <runner_config>,
  7.    "note": "<config 说明>"
  8. }

返回值

  • 如果没有错误，返回空
  • 如果有错误则返回相应错误

参数说明

  • name 字段可有可无，最终会被链接中的 <config_name> 替换掉

更新 config

  1. PUT /v1/api/configs/<config_name>/config
  2. Content-Type: application/json
  3. {
  4.    "config": <runner_config>,
  5.    "note": "<config 说明>"
  6. }

返回值

  • 如果没有错误，返回空
  • 如果有错误则返回相应错误

参数说明

  • 当前仅支持更新 config 和 note 字段

删除 config

  1. DELETE /v1/api/configs/<config_name>

返回值

  • 如果没有错误，返回空
  • 如果有错误则返回相应错误

删除多个 config

  1. POST /v1/api/configs/delete
  2. Content-Type: application/json
  3. [
  4.     "config1", "config2"
  5. ]

返回值

  • 如果没有错误，返回空
  • 如果有错误则返回相应错误

分配 tags 给 config

  1. POST /v1/api/configs/<config_name>/tags
  2. Content-Type: application/json
  3. {
  4.    "tags": ["<tag1>", "<tag2>"]
  5. }

返回值

  • 如果没有错误，返回空
  • 如果有错误则返回相应错误

分发 config 到 agents

  1. POST /v1/api/configs/<config_name>/agents
  2. Content-Type: application/json
  3. {
  4.    "agent_ids": ["<agent_id1>", "<agent_id2>"]
  5. }

返回值

  • 如果没有错误，返回空
  • 如果有错误则返回相应错误

Metrics

获取用户设定信息

  1. GET /v1/api/metrics/machine

返回值

  • 如果用户填写过 metrics 信息的设定，则返回：

    1. {
    2.   "opened": true,
    3.   "interval": "3",
    4.   "repo_name":"logkit_pro_internal"
    5. }

  • 如果用户没有填写过, 则返回：

  1. {
  2.     "opened": false
  3. }

获取某个 agent 对应机器的 metric 信息

  1. GET /v1/api/metrics/<agent_id>?beginTime=<begin_time>&endTime=<end_time>

返回值

  • 如果该 agent 开通了 metrics 收集, 则返回：

    1. {
    2.   "opened": true,
    3.   "data": {
    4.       "cpu_usage": {                                  // cpu 利用率
    5.           "buckets": [
    6.               {
    7.                   "cpu_usage_system":{
    8.                       "value":null                    // 可能为 null
    9.                   },
    10.                   "cpu_usage_user":{
    11.                       "value":null
    12.                   },
    13.                   "key":1517413680000                 // 时间戳(毫秒级)
    14.               },
    15.               {
    16.                   "cpu_usage_system":{                // 系统 cpu 资源占用
    17.                       "value":11.126897295316061      // 百分比
    18.                   },
    19.                   "cpu_usage_user":{                  // 用户 cpu 资源占用
    20.                       "value":20.454540321562025      // 百分比
    21.                   },
    22.                   "key":1517824920000
    23.               },
    24.               ...
    25.           ]
    26.       }
    27.       "diskio":{                                      // 磁盘 I/O
    28.           "buckets":[
    29.               {
    30.                   "key":1517808260000                 // 可能不存在这个字段(只会在第一个值时出现)
    31.               },
    32.               {
    33.                   "diskio_reads_rate":{
    34.                       "value":null                    // 可能为 null
    35.                   },
    36.                   "diskio_writes_rate":{
    37.                       "value":null
    38.                   },
    39.                   "key":1517808360000
    40.               },
    41.               {
    42.                   "diskio_reads_rate":{               // 磁盘读取频率
    43.                       "value":3800.909496286884       // 单位 op/sec
    44.                   },
    45.                   "diskio_writes_rate":{              // 磁盘写入频率
    46.                       "value":2468.5610533740837      // 单位 op/sec
    47.                   },
    48.                   "key":1517809740000                 // 时间戳
    49.               },
    50.           ]
    51.       },
    52.       "mem_used_percent":{                            // 内存占用
    53.           "buckets":[
    54.               {
    55.                   "key":1517413680000,
    56.                   "mem_used_percent":{
    57.                       "value":null                    // 可能为 null
    58.                   }
    59.               },
    60.               {
    61.                   "key":1517818020000,                // 时间戳
    62.                   "mem_used_percent":{                // 内存占用
    63.                       "value":78.59851748055786       // 百分比
    64.                   }
    65.               },
    66.               ...
    67.           ]
    68.       },
    69.       "net_bytes_rate":{                              // 网络流量
    70.           "buckets":[
    71.               {
    72.                   "key":1517413680000                 // 字段可能不存在
    73.               },
    74.               {
    75.                   "bytes_recv_rate":{
    76.                       "value":null                    // 字段可能为 null
    77.                   },
    78.                   "bytes_sent_rate":{
    79.                       "value":null
    80.                   },
    81.                   "key":1517806980000
    82.               },
    83.               {
    84.                   "bytes_recv_rate":{                 // 接收速率
    85.                       "value":5683943.616149664       // bytes/sec
    86.                   },
    87.                   "bytes_sent_rate":{                 // 发送速率
    88.                       "value":2472513.4745543003
    89.                   },
    90.                   "key":1517808360000                 // 时间戳
    91.               },
    92.           ]
    93.       },
    94.       "net_packets_rate":{                            // 收发包速率
    95.           "buckets":[
    96.               {
    97.                   "key":1517413680000                 // 字段可能不存在
    98.               },
    99.               {
    100.                   "key":1517415060000,
    101.                   "packets_recv_rate":{               // 字段可能为 null
    102.                       "value":null
    103.                   },
    104.                   "packets_sent_rate":{               // 字段可能为 null
    105.                       "value":null
    106.                   }
    107.               },
    108.               {
    109.                   "key":1517809740000,                // 时间戳
    110.                   "packets_recv_rate":{               // 接收包速率
    111.                       "value":8283.852036660304       // 单位 个/sec
    112.                   },
    113.                   "packets_sent_rate":{               // 发送包速率
    114.                       "value":6568.934223250486
    115.                   }
    116.               },
    117.           ]
    118.       },
    119.       "system_load":{                                 // 负载
    120.           "buckets":[
    121.               {
    122.                   "key":1517413680000
    123.                   "system_load1":{
    124.                       "value":null                    // 字段可能为空
    125.                   },
    126.                   "system_load15":{
    127.                       "value":null
    128.                   },
    129.                   "system_load5":{
    130.                       "value":null
    131.                   }
    132.               },
    133.               {
    134.                   "key":1517820780000,                // 时间戳
    135.                   "system_load1":{                    // 一分钟平均负载
    136.                       "value":2.496029057745206
    137.                   },
    138.                   "system_load15":{                   // 十五分钟平均负载
    139.                       "value":2.340774799951918
    140.                   },
    141.                   "system_load5":{                    // 五分钟平均负载
    142.                       "value":2.3685714188268627
    143.                   }
    144.               },
    145.               ...
    146.           ]
    147.       },
    148.       "tcp_established_num":{                         // TCP 连接数
    149.           "buckets":[
    150.               {
    151.                   "key":1517413680000,
    152.                   "tcp_established_num":{
    153.                       "value":null                    // 字段可能为 null
    154.                   }
    155.               },
    156.               {
    157.                   "key":1517815260000,
    158.                   "tcp_established_num":{
    159.                       "value":67.02427184466019
    160.                   }
    161.               },
    162.               ...
    163.           ]
    164.       }
    165.   }

  • 如果没有开通，则返回：

  1. {
  2.     "opened": false,
  3.     "data": {
  4.         "post_url": "<开通请求的 url>",
  5.         "message": "<提示语>",
  6.         <可能会有其他的字段>
  7.     }
  8. }

参数说明

  • beginTime 和 endTime 请提供时间戳，精度秒级（10 位数字）
  • 返回的数据中的时间戳将覆盖从 beginTime 到 endTime 的所有时间点, 没有数据的使用 null 来填充
  • 对于 “速率” 类的指标可能会出现字段不存在的情况，但是只会在第一个时间点的时候出现
  • 无论提供的时间段有多长, 返回的数据量都在 300 左右
  • 开通请求的 url 不包括 url 前缀, 即以该 API（/v1/metrics）为例, post_url 字段的内容为 /metrics
  • message 是对于用户的提示语, 比如: “开通后所有的agent都将开始收集其所在系统上的metric信息,并发往pandora平台”
  • 以上两个字段是一定会有的，剩下的字段根据场景可能会没有
  • 剩下的字段每个都是一个 object, 每个 object 都有两个字段, chinese 表示中文的字段名称, default 表示默认值.

Runners

获取 runner 列表

  1. GET /v1/api/runners?tag=<tagvalue>&id=<idvalue>&name=<runnerName>&agents=<true|false>&sort=<sortKey>&order=<order>&page=<pageNum>&size=<pageSize>&search=<search>

返回值

  • 如果没有错误，返回：
    1. {
    2.   "runners": [
    3.       {
    4.           "name": "<runner_name1>",
    5.           "agent_id": "<agent_id>",
    6.           "config": "<runner_config>",
    7.           "state": "<runner_state>",
    8.           "status": "<runner_status>",
    9.           "config_timestamp": <config_timestamp>
    10.       },
    11.       {
    12.           "name": "<runner_name2>",
    13.           "agent_id": "<agent_id>",
    14.           "state": "<runner_state>",
    15.           "config": "<runner_config>",
    16.           "status": "<runner_status>",
    17.           "config_timestamp": <config_timestamp>,
    18.       },
    19.       ...
    20.   ],
    21.   "agents": {
    22.       "<agent_id>"":{
    23.           "hostname": "<hostname>",
    24.           "ip": "<ip>",
    25.           ...
    26.       }
    27.   }
    28.   "totalSize":<totalSize>
    29. }
  • 如果有错误则返回相应错误

参数说明

  • 参数 tag 和 id 是指 agent 的属性, name 是 runner 的属性，他们都可以作为 runner 的过滤条件
  • 参数sort、order会根据sort的值进行升序/降序排序，order的值可以是ascend/descend，sort默认为name，order默认为ascend
  • 参数search会对hostnam进行搜索，将包含search值的结果搜索出来
  • 获取的 runner name list 为各个符合条件的 agent 上的 runner name 的并集
  • 返回的数据中没有 tag 信息，因为后端不太好加，如果前端需要且前端无法自己解决的话，再协商
  • state 有 running 和 stopped 两种情况，分别代表 运行中 和 已停止 两种状态

启动 runners

  1. POST /v1/api/runners/start
  2. [
  3.     {
  4.         "config_name": "config1",
  5.         "agent_id": "agent_id1"
  6.     },
  7.     {
  8.         "config_name": "config1",
  9.         "agent_id": "agent_id2"
  10.     }
  11.     ...
  12. ]

返回值

  • 如果没有错误，返回空
  • 如果有错误则返回相应错误

停止 runners

  1. POST /v1/api/runners/stop
  2. [
  3.     {
  4.         "config_name": "config1",
  5.         "agent_id": "agent_id1"
  6.     },
  7.     {
  8.         "config_name": "config1",
  9.         "agent_id": "agent_id2"
  10.     }
  11.     ...
  12. ]

返回值

  • 如果没有错误，返回空
  • 如果有错误则返回相应错误

重置 runners

  1. POST /v1/api/runners/reset
  2. [
  3.     {
  4.         "config_name": "config1",
  5.         "agent_id": "agent_id1"
  6.     },
  7.     {
  8.         "config_name": "config1",
  9.         "agent_id": "agent_id2"
  10.     }
  11.     ...
  12. ]

返回值

  • 如果没有错误，返回空
  • 如果有错误则返回相应错误

删除 runners

  1. POST /v1/api/runners/delete
  2. [
  3.     {
  4.         "config_name": "config1",
  5.         "agent_id": "agent_id1"
  6.     },
  7.     {
  8.         "config_name": "config1",
  9.         "agent_id": "agent_id2"
  10.     }
  11.     ...
  12. ]

返回值

  • 如果没有错误，返回空
  • 如果有错误则返回相应错误

Grok

验证 log 和相应的 Grok pattern 是否匹配

  1. POST /v1/api/grok/check
  2. Content-Type: application/json
  3. {
  4.   "log":"110.220.330.550 - - [12/Oct/2017:14:16:50 +0800]",
  5.   "pattern":base64("%{NOTSPACE:client_ip} %{USER:ident} %{USER:auth} \[%{HTTPDATE:ts:date}\]")
  6.   "custom_pattern":""
  7. }

返回值

  • 如果没有错误，返回解析后的匹配数据：
  1. {"auth":"-","client_ip":"110.220.330.550","grokInternalCustomSemantic":"110.220.330.550 - - [12/Oct/2017:14:16:50 +0800]","ident":"-","ts":"12/Oct/2017:14:16:50 +0800"}
  • 如果有错误则返回相应错误

参数说明

  • pattern 和 custom_pattern 前端传过来时都需要 base64 编码

Tags

获取 tag 列表

请求

  1. GET /v1/api/tags?name=<tagName>&agents=true&sort=sortKey&order=order&page=<pageNum>&size=<pageSize>&search=<search>

返回值

  • 如果没有错误，返回：
  1. {
  2.     "tags": [
  3.         {
  4.             "name": "<tag_name>",
  5.             "agent_ids": ["id1", "id2"],
  6.             "config_names1": ["name1", "name2"],
  7.             "note": "<tags 备注>"
  8.         },
  9.         "agents": {
  10.              "<agent_id>"":{
  11.                  "hostname": "<hostname>",
  12.                  "ip": "<ip>",
  13.                  ...
  14.              }
  15.         }
  16.     ],
  17.     "totalSize": <totalSize>
  18. }
  • 如果有错误则返回相应错误

添加 tag

  1. POST /v1/api/tags/<tag_name>
  2. Content-Type: application/json
  3. {
  4.    "name": "<tag_name>",
  5.    "note": "<tag 说明>",
  6.    "config_names": ["<config_name1>"],
  7.    "agent_ids": ["<agent_id1", "agent_id2"]
  8. }

返回值

  • 如果没有错误，返回空
  • 如果有错误则返回相应错误

参数说明

  • name 字段可有可无，最终会被链接中的 <tag_name> 替换掉

更新 tag

  1. PUT /v1/api/tags/<tag_name>/note
  2. Content-Type: application/json
  3. {
  4.    "note": "<tag 说明>"
  5. }

返回值

  • 如果没有错误，返回空
  • 如果有错误则返回相应错误

参数说明

  • 当前仅支持更新 note 字段

分配 tag 给 agents

  1. POST /v1/api/tags/<tag_name>/agentids
  2. Content-Type: application/json
  3. {
  4.    "agent_ids": ["<agent_id1>", "<agent_id2>"]
  5. }

返回值

  • 如果没有错误，返回空
  • 如果有错误则返回相应错误

解除 tag 与 agents 的关联

  1. DELETE /v1/api/tags/<tag_name>/agentids/batch?agentids=<agent_id1>,<agent_id2>

返回值

  • 如果没有错误，返回空
  • 如果有错误则返回相应错误

删除为 tags 分发的 configs

  1. DELETE /v1/api/tags/<tag_name>/configs/<config_name>

返回值

  • 如果没有错误，返回空
  • 如果有错误则返回相应错误

删除 tag

  1. DELETE /v1/api/tags/<tag_name>

返回值

  • 如果没有错误，返回空
  • 如果有错误则返回相应错误

删除多个 tag

  1. DELETE /v1/api/tags/batch?tag=<tag1>,<tag2>

返回值

  • 如果没有错误，返回空
  • 如果有错误则返回相应错误