Fork me on GitHub

用户手册

Documentation Status Pypi Version Travis CI Development Status Python version License

README in English

内容

简介

日志服务(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。

# pypy3
> pypy3 -m pip install aliyun-log-python-sdk aliyun-log-cli -U --no-cache

# pip3
> pip3 install aliyun-log-python-sdk aliyun-log-cli -U --no-cache

pypy/pypy3与pip安装

如果使用copy_data、pull_log_dump等需要大量下载、传输数据的命令，为了获得更好的性能，推荐使用pypy或pypy3来安装。 这里下载和安装。如果是Mac可以使用brew install pypy3来安装。 默认pip会附带，如果没有配套的pip，可以这里获取：https://github.com/pypa/get-pip/blob/master/get-pip.py 下载后运行：pypy3 get-pip.py后即可安装pip，但后续在pypy3上安装时，需要将pip/pip3修改为：pypy3 -m pip instal .... 也可以查看现有pip的路径: which pip，修改第一行命令行指向pypy3的绝对路径即可。

Mac相关

Mac上推荐使用pip3安装CLI，首选需要安装Python3或pypy3：

# Pypy3
> brew install pypy3
> pypy3 -m pip install aliyun-log-python-sdk aliyun-log-cli -U --no-cache

# Python3
> brew install python3
> pip/pip3 install -U aliyun-log-cli --no-cache

Mac上如果你安装时遇到了权限相关的错误，如：OSError: [Errno 1] Operation not permitted，尝试使用如下命令安装：

> pip/pip3 install -U aliyun-log-cli --user

外网访问受限的阿里云ECS

因为安全策略等原因，某些云服务器可能无法访问Pypi服务器，可以尝试使用本地Pypi镜像，例如阿里云服务器可以尝试:

pip/pip3 install -U aliyun-log-cli --index http://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com

Note：也可以使用清华的索引-i https://pypi.tuna.tsinghua.edu.cn/simple

离线安装

从 0.1.12开始, 我们为Linux x64和MacOS x64提供离线的安装包.

如下步骤安装:

  1. 从release页面下载对应离线安装包.
  2. 解压到本地目录, 例如cli_packages, 可以看到许多whl文件在里面.
  3. 如果还没有pip, 可以如下安装:
python pip-10.0.1-py2.py3-none-any.whl/pip install --no-index cli_packages/pip-10.0.1-py2.py3-none-any.whl
  1. 安装CLI:
pip/pip3 install aliyun-log-cli --no-index --find-links=cli_packages

  1. 验证:

    > aliyunlog --version

常见安装问题

  1. 安装时报TLSV1_ALERT_PROTOCOL_VERSION错误
> pip/pip3 install aliyun-log-cli

Collecting aliyun-log-cli
  Could not fetch URL https://pypi.python.org/simple/aliyun-log-cli/: There was a problem confirming the ssl certificate: [SSL: TLSV1_ALERT_PROTOCOL_VERSION] tlsv1 alert protocol version (_ssl.c:590) - skipping
  Could not find a version that satisfies the requirement aliyun-log-cli (from versions: )
No matching distribution found for aliyun-log-cli

解答： 请先升级pip：

pip/pypy3 install pip -U
  1. 找不到命令aliyunlog?

Linux/Mac下, 因为某种原因创建脚本aliyunlog链接时未成功, 可以手工创建一个, 如下:

2.1. 找到Python路径:

在linux或mac, 执行命令可以看到:

which python

2.2. 创建一个叫做aliyunlog文件, 赋予执行权限, 内容如下, 并放到PATH目录下 :

#!<python路径放这里,注意有一个感叹号!>
import re
import sys
from pkg_resources import load_entry_point

if __name__ == '__main__':
    sys.argv[0] = re.sub(r'(-script\.pyw?|\.exe)?$', '', sys.argv[0])
    sys.exit(
        load_entry_point('aliyun-log-cli', 'console_scripts', 'aliyunlog')()
    )

对于linux或mac, 可以考虑放到/usr/bin/目录下

2.3. 验证, 执行如试下命令看一下是否成功. ```shell > aliyunlog –version

  1. Regex模块安装失败? 如果存在安装Regex失败的错误, 可以参考使用yun/apt-get或者手动安装一下python-devel https://rpmfind.net/linux/rpm2html/search.php?query=python-devel

完整参数列表

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

> aliyunlog --help

注意: 命令aliyun已经废弃(为了避免与通用阿里云CLI冲突).

会显示完整命令。

Note aliyunlog和aliyun都可以，推荐使用aliyunlog以防冲突。

配置说明

参考配置CLI

输入输出

输入

  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. 项目组管理
  2. 日志库管理
  3. 分区管理
  4. 机器组管理
  5. Logtail配置管理
  6. 机器组与Logtail配置关联
  7. 索引管理
  8. 游标操作
  9. 日志读写与消费
  10. 投递管理
  11. 消费组管理
  12. Elasticsearch 数据迁移

  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同域复制.
  • 参考跨域复制项目组配置了解如何跨域复制项目组配置.

  1. 日志库管理

  • create_logstore
  • delete_logstore
  • get_logstore
  • update_logstore
  • list_logstore

  1. 分区管理

  • list_shards
  • split_shard
  • merge_shard

  1. 机器组管理

  • 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

  1. Logtail配置管理

  • create_logtail_config
  • 参考创建Logtail配置了解如何创建各种格式的Logtail配置.
  • update_logtail_config
  • delete_logtail_config
  • get_logtail_config
  • list_logtail_config

  1. 机器组与Logtail配置关联

  • apply_config_to_machine_group
  • remove_config_to_machine_group
  • get_machine_group_applied_configs
  • get_config_applied_machine_groups

  1. 索引管理

  • 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

  1. 游标操作

  • get_cursor
  • get_cursor_time
  • get_previous_cursor_time
  • get_begin_cursor
  • get_end_cursor

  1. 日志读写与消费

  • 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类似, 但是迭代式获取数据并输出, 适合大容量的数据获取.
  • pull_log_dump
  • 并发下载大量日志直接到本地文件，并一行一个日志。

  1. 投递管理

  • 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

  1. 消费组管理

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

  1. Elasticsearch 数据迁移

  1. 其他配置管理

  • 报警管理
  • 快速查询管理
  • 报表管理
  • 外部存储管理

参考命令行帮助

  1. ETL数据转换

最佳实践

错误诊断

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

[__logging__]
filename=  # 默认是: ~/aliyunlogcli.log, 进行轮转
filebytes=   # 默认是104857600 (100MB), 单个文件大小, 单位Byte
backupcount= # 默认是5个, 轮转文件的个数
#filemode=  # 废弃
format=    # 默认是: %(asctime)s %(threadName)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. 日志服务产品文档：https://help.aliyun.com/product/28958.html
  3. 日志服务Python SDK文档: http://aliyun-log-python-sdk.readthedocs.io/
  4. 其他问题请提工单