SLS 命令行控制台工具(CLI)来啦-阿里云开发者社区

开发者社区> 阿里云存储服务> 正文

SLS 命令行控制台工具(CLI)来啦

简介: 如果你遇到以下槽点, 那么CLI为你而生: 1. 线下创建项目后,线上又要重新配置 2. 一个区域创建好项目,复制到其他15个区域 3. 把日志查询结果批量导出 4. 批量配置与脚本化配置

作为日志服务(原SLS)用户,是否被以下槽点深深地伤害过:

  1. 线下创建项目后,线上环境又要重新配置一遍?
  2. 一个Region创建好项目,复制到其他15个Region?
  3. 希望能把日志查询结果批量导出?
  4. 希望批量创建配置,创机器组,修改设置?
  5. 在脚本中初始化SLS配置?
  6. 作为程序员,还是喜欢命令行多一些?

如果你遇到过以上任何一点,都可以继续往下看了:)

简介

日志服务(SLS)提供了Web和SDK的方式进行日志采集、管理、查询和分析。为了满足越来越多的的自动化日志配置查询分析的需求,现重磅发布SLS的命令行工具(Command Line Interface - CLI)。

基本介绍

日志服务命令行工具CLI支持几乎所有操作,日志查询支持完整性检查与自动分页、支持多账户与跨域复制。

主要功能

  • 支持大部分的日志服务REST接口。
  • 支持多账号,方便测试与跨域操作。
  • 日志查询完整性查询与自动分页。
  • 支持多种方式存储和配置秘钥,适用于各种情况。
  • 支持通过命令行或者文件的形式输入复杂参数,并校验参数内容格式。
  • 支持JMES过滤器对结果进行进一步处理,方便选择特定信息。
  • 跨平台(Windows/Linux和Mac)支持,基于Python(Py2.6+和Py3.3+平台友好),支持Pip安装。

安装

操作系统

日志服务CLI支持以下操作系统:

  • Windows
  • Mac OS
  • Linux

支持版本

Python 2.6、2.7、3.3、3.4、3.5、3.6、PyPy和PyPy3。

安装方式

执行以下命令安装日志服务CLI。

> pip install -U aliyun-log-cli

完整参数列表

执行以下命令查看日志服务CLI参数列表。

> aliyunlog --help

配置说明

参考SDK配置获得访问秘钥的ID和Key以及访问入口Endpoint,构建一个LogClient的客户端。

配置秘钥与服务入口

日志服务CLI支持通过以下三种方式配置访问秘钥与入口,如果同时配置多种方式, 优先顺序是: 参数, 环境变量, 最后是本地配置文件.

  • 参数
> aliyunlog log create_project ..... --access-id=<value> --access-key=<value> --region-endpoint=<value>

注意: 任意log子命令都支持以上方式定义特定的AK与Endpoint(覆盖后面的方式)

  • 环境变量

    • ALIYUN_LOG_CLI_ACCESSID
    • ALIYUN_LOG_CLI_ACCESSKEY
    • ALIYUN_LOG_CLI_ENDPOINT
  • 本地配置文件

将存储AK与Endpoint在~/.aliyunlogcli, 默认使用的块名是main

[main]
access-id=
access-key=
region-endpoint=

修改配置文件

Configure命令可以修改配置文件内容.

> aliyunlog configure access_id access_key cn-beijing.log.aliyuncs.com

多账户

  1. 存储于多个账户, 以便在特定情况下使用(例如测试):
> aliyunlog configure access_id1 access_key1 cn-beijing.log.aliyuncs.com
> aliyunlog configure access_id2 access_key2 cn-hangzhou.log.aliyuncs.com test

AK将存储为:

[main]
access-id=access_id1
access-key=access_key1
region-endpoint=cn-beijing.log.aliyuncs.com

[test]
access-id=access_id2
access-key=access_key2
region-endpoint=cn-hangzhou.log.aliyuncs.com
  1. 使用特定账户

任意命令都可以通过选项--client-name=<value>来使用特定配置的账户, 例如:

> aliyunlog log create_project ..... --client-name=test

将使用test的AK来进行操作.

  1. 其他情况

某些情况下也需要跨账户操作, 例如:

> aliyunlog log copy_project --from_project="p1" --to_project="p1" --to_client=test

main账户下对应的项目p1复制到账户test下的p1

输入输出

输入

  1. 一般输入
> aliyunlog log get_logs --request="{\"topic\": \"\", \"logstore\": \"logstore1\", \"project\": \"dlq-test-cli-123\", \"toTime\": \"2018-01-01 11:11:11\", \"offset\": \"0\", \"query\": \"*\", \"line\": \"10\", \"fromTime\": \"2018-01-01 10:10:10\", \"reverse\":\"false\"}"
  1. 文件输入

也可以将上面参数放到一个文件里面, 简化命令行, 需要义file://开头+文件路径即可:

> aliyunlog log get_logs --request="file://./get_logs.json"

文件get_logs.json内容如下, 注意: 文件中不需要反斜杠\来转义.

{
  "topic": "",
  "logstore": "logstore1",
  "project": "project1",
  "toTime": "2018-01-01 11:11:11",
  "offset": "0",
  "query": "*",
  "line": "10",
  "fromTime": "2018-01-01 10:10:10",
  "reverse": "true"
}

参数校验

  • 必填的参数没有填写时会报错, 输出参数列表
  • 参数格式本身会进行校验, 例如int, bool, string list, 特定数据结构等
  • bool支持的形式有:

    • true (大小写不敏感), T, 1
    • false (大小写不敏感), F, 0
  • 字符串列表支持的形式为["s1", "s2"]

输出

  1. 对于Create, Update, Delete操作, 一般脚本无输出, exit code=0表示成功.
  2. 对于Get/List操作, 以json格式输出内容
  3. 错误情况下, 以如下格式返回错误:
{
  "errorCode":"...",
  "errorMessage":"..."
}

输出过滤

支持通过JMES过滤输出的结果.

例如:

> aliyunlog log get_logs ...

以上命令的输出是:

[ {"__source__": "ip1", "key": "log1"}, {"__source__": "ip2", "key": "log2"} ]

通过以下命令将日志分隔为每一行:

> aliyunlog log get_logs ... --jmes-filter="join('\n', map(&to_string(@), @))"

输出:

{"__source__": "ip1", "key": "log1"}
{"__source__": "ip2", "key": "log2"}

进一步处理


你可以使用>>来讲输出存储到一个文件. 某些时候, 你需要使用其他命令进行处理, 例如, 这里介绍另一个把json格式的日志分行打印的方法. 在Linux/Unix下, 你可以在命令后通过添加一个|来进一步处理.
| python2 -c "from __future__ import print_function;import json;map(lambda x: print(json.dumps(x).encode('utf8')), json.loads(raw_input()));"
or 
| python3 -c "import json;list(map(lambda x: print(json.dumps(x)), json.loads(input())));"

例如:

aliyunlog log get_log .... |  python2 -c "from __future__ import print_function;import json;map(lambda x: print(json.dumps(x).encode('utf8')), json.loads(raw_input()));" >> data.txt

命令参考

命令规范

1. aliyunlog log <subcommand> [parameters | global options]
2. aliyunlog configure <access_id> <access-key> <endpoint> [<client-name>]
3. aliyunlog [--help | --version]

命令别名


日志服务的CLI也有一个别名aliyunlog, 如果aliyun这个命令冲突了, 可以尝试使用aliyunlog:
1. aliyunlog log <subcommand> [parameters | global options]
2. aliyunlog configure <access_id> <access-key> <endpoint>
3. aliyunlog [--help | --version]

子命令与参数

日志服务命令行工具背后依赖于日志服务的Python SDK, 相关子命令对应于aliyun.log.LogClient的方法, 参数和可选参数也一一对应.
具体支持的API参数, 请参考映射的Python SDK API

例子:

def create_logstore(self, project_name, logstore_name, ttl=2, shard_count=30):

对应命令行:

> aliyunlog log create_logstore
  --project_name=<value>
  --logstore_name=<value>
  [--ttl=<value>]
  [--shard_count=<value>]

全局选项

所有命令都支持如下的全局选项:

    [--access-id=<value>]
    [--access-key=<value>]
    [--region-endpoint=<value>]
    [--client-name=<value>]
    [--jmes-filter=<value>]

命令类别

1. 项目组管理

  • list_project
  • create_project
  • get_project
  • delete_project
  • copy_project

    • 复制所有源project的logstore, logtail, machine group和index配置等到目标project中.
> aliyunlog log copy_project --from_project="p1" --to_project="p1" --to_client="account2"
  • 注意: to_client是通过aliyunlog configure配置的其他账户, 也可以不传或传main同域复制.
  • 参考跨域复制项目组配置了解如何跨域复制项目组配置.

2. 日志库管理

  • create_logstore
  • delete_logstore
  • get_logstore
  • update_logstore
  • list_logstore

3. 分区管理

  • list_shards
  • split_shard
  • merge_shard

4. 机器组管理

  • create_machine_group

    • 部分参数格式:
{
 "machine_list": [
   "machine1",
   "machine2"
 ],
 "machine_type": "userdefined",
 "group_name": "group_name2",
 "group_type": "Armory",
 "group_attribute": {
   "externalName": "ex name",
   "groupTopic": "topic x"
 }
}
  • delete_machine_group
  • update_machine_group
  • get_machine_group
  • list_machine_group
  • list_machines

5. Logtail配置管理

  • create_logtail_config

  • update_logtail_config
  • delete_logtail_config
  • get_logtail_config
  • list_logtail_config

6. 机器组与Logtail配置关联

  • apply_config_to_machine_group
  • remove_config_to_machine_group
  • get_machine_group_applied_configs
  • get_config_applied_machine_groups

7. 索引管理

  • create_index

    • 部分参数格式:
{
 "keys": {
   "f1": {
     "caseSensitive": false,
     "token": [
       ",",
       " ",
       "\"",
       "\"",
       ";",
       "=",
       "(",
       ")",
       "[",
       "]",
       "{",
       "}",
       "?",
       "@",
       "&",
       "<",
       ">",
       "/",
       ":",
       "\n",
       "\t"
     ],
     "type": "text",
     "doc_value": true
   },
   "f2": {
     "doc_value": true,
     "type": "long"
   }
 },
 "storage": "pg",
 "ttl": 2,
 "index_mode": "v2",
 "line": {
   "caseSensitive": false,
   "token": [
     ",",
     " ",
     "\"",
     "\"",
     ";",
     "=",
     "(",
     ")",
     "[",
     "]",
     "{",
     "}",
     "?",
     "@",
     "&",
     "<",
     ">",
     "/",
     ":",
     "\n",
     "\t"
   ]
 }
}
  • update_index
  • delete_index
  • get_index_config
  • list_topics

8. 游标操作

  • get_cursor
  • get_cursor_time
  • get_previous_cursor_time
  • get_begin_cursor
  • get_end_cursor

9. 日志读写与消费

  • put_logs

    • 参数格式:
{
"project": "dlq-test-cli-35144",
"logstore": "logstore1",
"topic": "topic1",
"source": "source1",
"logtags": [
  [
    "tag1",
    "v1"
  ],
  [
    "tag2",
    "v2"
  ]
],
"hashKey": "1231231234",
"logitems": [
  {
    "timestamp": 1510579341,
    "contents": [
      [
        "key1",
        "v1"
      ],
      [
        "key2",
        "v2"
      ]
    ]
  },
  {
    "timestamp": 1510579341,
    "contents": [
      [
        "key3",
        "v3"
      ],
      [
        "key4",
        "v4"
      ]
    ]
  }
]
}
  • get_logs

    • 参数格式:
{
"topic": "",
"logstore": "logstore1",
"project": "dlq-test-cli-35144",
"toTime": "2018-01-01 11:11:11",
"offset": "0",
"query": "*",
"line": "10",
"fromTime": "2018-01-01 10:10:10",
"reverse": "true"
}
  • 但参数line传入-1时, 就回获取所有. 但是当数据量很大, 超过1GB时, 最好使用get_log_all
  • get_log_all

    • get_logs一样, 但是迭代式获取数据并输出, 适合大容量的数据获取.
  • get_histograms
  • pull_logs
  • pull_log

    • pull_logs类似, 但是迭代式获取数据并输出, 适合大容量的数据获取.

10. 投递管理

  • create_shipper

    • 部分参数格式:
{
"oss_bucket": "dlq-oss-test1",
"oss_prefix": "sls",
"oss_role_arn": "acs:ram::1234:role/aliyunlogdefaultrole",
"buffer_interval": 300,
"buffer_mb": 128,
"compress_type": "snappy"
}
  • update_shipper
  • delete_shipper
  • get_shipper_config
  • list_shipper
  • get_shipper_tasks
  • retry_shipper_tasks

11. 消费组管理

  • create_consumer_group
  • update_consumer_group
  • delete_consumer_group
  • list_consumer_group
  • update_check_point
  • get_check_point

最佳实践

错误诊断

CLI默认把执行过程中的警告和错误存储在~/aliyunlogcli.log中, 也可以配置~/.aliyunlogcli中__loggging__来调整错误存储位置和格式:

[__logging__]
filename=  # 默认是: ~/aliyunlogcli.log
filemode=  # 默认是: a, 可以是: w, a
format=    # 默认是: %(asctime)s %(levelname)s %(filename)s:%(lineno)d %(funcName)s %(message)s
datefmt=   # 默认是: "%Y-%m-%d %H:%M:%S", 可以是strftime()兼容的日期/时间格式化字符串
level=     # 默认是: warn, 可以是info, error, fatal, critical, debug

其他资源

  1. 日志服务产品介绍:http://www.aliyun.com/product/sls/
  2. 日志服务文档: http://aliyun-log-cli.readthedocs.io/
  • 扫码加入官方钉钉群 (11775223):
    image

版权声明:本文内容由阿里云实名注册用户自发贡献,版权归原作者所有,阿里云开发者社区不拥有其著作权,亦不承担相应法律责任。具体规则请查看《阿里云开发者社区用户服务协议》和《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容,填写侵权投诉表单进行举报,一经查实,本社区将立刻删除涉嫌侵权内容。

分享:

阿里云存储基于飞天盘古2.0分布式存储系统,产品多种多样,充分满足用户数据存储和迁移上云需求。

官方博客
链接