观测云集成

本文档主要介绍使用脚本市场中「观测云云同步」系列脚本包同步阿里云、AWS 平台相关数据的接入处理。

请始终使用最新版 DataFlux Func 进行操作

本脚本包会不断加入新功能，请随时关注本文档页

1. 前置条件

1. 登录 观测云 并注册账号。

1.1 如果开通 Func 托管版

一切前置条件都自动安装，没有多余前置工作了，请跳至脚本安装

1.2 如果自行部署 Func

• 在云主机中安装 DataFlux Func，具体系统要求可以参考：部署和维护 / 系统要求

• 在云主机上下载安装 DataFlux Func GSE 版：

# 下载 DataFlux Func GSE
/bin/bash -c "$(curl -fsSL func.guance.com/download)" -- --for=GSE

# 安装 DataFlux Func
sudo /bin/bash {安装文件所在目录}/run-portable.sh

更多信息可以参考：快速开始

• 安装结束后新建连接器，类型选择观测云，把观测云空间的 ak sk 配置到连接器里。

2. 脚本安装

这里，假设需要对阿里云监控的数据进行采集并写入观测云。

请提前准备好符合要求的阿里云 AK（简单起见，可直接授予全局只读权限 ReadOnlyAccess）

2.1 安装具体的采集器

同步云资源的监控数据，我们一般情况下要安装两个脚本，一个采集对应云资产基本信息的脚本，一个是采集云监控信息的脚本。

如果要采集对应的日志，还要开启相应的日志采集脚本。如果要采集账单，要开启云账单采集脚本。

以阿里云 ECS 采集为例，分别在「管理 / 脚本市场」中，依次点击并按照对应的脚本包：

• 「观测云集成（阿里云-云监控）」(ID：guance_aliyun_monitor)
• 「观测云集成（阿里云-ECS）」(ID：guance_aliyun_ecs)

点击【安装】后，输入相应的参数：阿里云 AK、阿里云账户名。

点击【部署启动脚本】，系统会自动创建 Startup 脚本集，并自动配置相应的启动脚本。

此外，在「管理 / 定时任务（旧版：自动触发配置）」里看到对应的定时任务（旧版：自动触发配置）。点击【执行】，即可立即执行一次，无需等待定期时间。稍等片刻，可以查看执行任务记录以及对应日志。

2.2 验证同步状态

1. 在「管理 / 定时任务（旧版：自动触发配置）」确认对应的任务是否已存在对应的定时任务（旧版：自动触发配置），同时可以查看对应任务记录及日志检查是否有异常
2. 在观测云平台，「基础设施 / 自定义」中查看是否存在资产信息
3. 在观测云平台，「指标」查看是否有对应监控数据

3. 代码详解

以下为本例中代码的分步解释。

实际上，所有的「观测云集成」类脚本的使用都可以使用类似的方法实现。

import 部分

为了正常使用脚本市场提供的脚本，在安装脚本包后，需要通过 import 方式来引入这些组件。

from guance_integration__runner import Runner
import guance_aliyun_monitor__main as aliyun_monitor

Runner 是所有采集器的实际启动器，任何情况下都需要引入 Runner 来完成对采集器的启动。 aliyun_monitor 即为本示例中所需的「阿里云-云监控」采集器

账号配置部分

为了能够正常调用云平台的 API，用户也需要提供对应平台的 AK 供采集器使用。

account = {
    'ak_id'    : '<具有合适权限的阿里云 AK ID>',
    'ak_secret': '<具有合适权限的阿里云 AK Secret>',

    'extra_tags': {
        'account_name': '我的阿里云账号',
    }
}

阿里云创建 AK/SK 参考：创建 AccessKey

除了最基本的 ak_id、ak_secret 外，部分云平台账号可能同时需要提供额外的内容，如 AWS 使用 iam 角色时需要配置 assume_role_arn、role_session_name 等，具体可以参考 亚马逊（AWS）代码示例。

最后，每个账号还允许添加一个 extra_tags 的字段，允许用户为采集的数据统一添加相同的标签，方便在观测云中辨认不同的数据所属的账号。

extra_tags 的 Key、Value 都为字符串，内容不限，且支持多个 Key、Value。

在本例中，我们通过为 extra_tags 配置 { 'account_name': '我的阿里云账号' }，将所有本账号的数据都加上了 account_name="我的阿里云账号" 标签

函数定义部分

在 DataFlux Func 中，所有代码都必须包含在某个被 @DFF.API(...) 装饰的函数中。

@DFF.API('执行云资产同步')
def run():
    # 具体代码略 ...

@DFF.API(...) 装饰器第一个参数为标题，内容随意。

对于观测云集成的脚本来说，最终都是通过「定时任务（旧版：自动触发配置）」方式运行脚本，只有添加了 @DFF.API(...) 装饰器的函数才能够被创建为「定时任务（旧版：自动触发配置）」。

采集器配置部分

除了配置对应云平台的账号，还需要对采集器进行配置。

采集器的配置可以在具体采集器的文档中找到，本文此处仅作使用提示

基础配置

collector_configs = {
    'targets': [
        {
            'namespace': 'acs_ecs_dashboard', # 云监控的 namespace
            'metrics'  : ['*cpu*', '*mem*'],  # 云监控指标中包含 cpu, mem 的指标数据
        },
    ],
}
collectors = [
    aliyun_monitor.DataCollector(account, collector_configs),
]

阿里云监控需要配置采集的目标。在本例中，我们指定了只采集有关 ECS 中，和 CPU、内存有关的指标。

高级配置

# Metric filter
def filter_ecs_metric(instance, namespace='acs_ecs_dashboard'):
    '''
    采集 instance_id 在 ['xxxx'] 范围内指标数据
    '''
    # return True
    instance_id = instance['tags'].get('InstanceId')
    if instance_id in ['xxxx']:
        return True
    return False

def after_collect_metric(point):
    '''
    为采集获取到的数据补充 tags
    '''
    if point['tags']['name'] == 'xxx':
        point['tags']['custom_tag'] = 'c1'
    return point

collector_configs = {
    'targets': [
        {
            'namespace': 'acs_ecs_dashboard', # 云监控的 namespace
            'metrics'  : ['*cpu*', '*mem*'],  # 云监控指标中包含 cpu, mem 的指标数据
        },
    ],
}
collectors = [
    aliyun_monitor.DataCollector(account, collector_configs, filters=filter_ecs_metric, after_collect=after_collect_metric)),
]

• filters：过滤器函数。过滤采集到的数据（不是每个采集器都支持过滤器，请到具体采集器文档中查看「配置过滤器」）。当定义好过滤的条件后，函数返回 True 表示满足条件需要采集，返回 False 表示满足条件的不需要采集。请根据自己的业务灵活配置。
• after_collect：自定义 after_collect 函数对采集到的数据二次加工。使用场景：日志数据切割、为 field/tags 添加额外字段等。注意：该函数的返回值是作为待上报数据而存在的，建议您只是修改传入的 point 或者按照原 point 结构新增一系列 points，如果您返回空或者 False 等逻辑否的数据意味着该采集器采集的所有 point 不会被上报。

最后，需要使用上文中的账号配置以及这里的采集器配置，生成具体的「采集器实例」。

启动运行部分

采集器的运行需要统一的 Runner 启动器来运行。

启动器需要使用在上文中生成的具体「采集器实例」初始化，并调用 run() 函数启动运行。

启动器会遍历所有传入的采集器并依次将采集后的数据上报至 DataKit（默认 DataKit 的连接器 ID 为 datakit）。

Runner(collectors).run()

在代码编写完成后，如果不确定配置是否正确，可以为启动器添加 debug=True 参数使其在调试模式下运行。

在调试模式下运行的启动器，会正常进行数据采集操作，但最终不会写入 DataKit，如下：

Runner(collectors, debug=True).run()

如果需要写入的 DataKit 的连接器 ID 不为默认的 datakit，那么，可以为启动器添加 datakit_id="<DataKit ID>" 来指定 DataKit 的连接器 ID，如下：

Runner(collectors, datakit_id='<DataKit ID>').run()

4. 其他云厂商代码参考

其他云厂商的配置方式与阿里云类似

亚马逊（AWS）

以采集「EC2 实例对象」及「EC2 相关的监控指标」为例：

from guance_integration__runner import Runner
import guance_aws_ec2__main as aws_ec2
import guance_aws_cloudwatch__main as aws_cloudwatch

# 账号配置
# AWS 支持用户带入 iam 角色的方式采集资源
# 如果需要使用角色请配置：assume_role_arn、role_session_name
# 如果开启了多重身份验证（MFA）请配置：serial_number、token_code
account = {
    'ak_id'            : '<具有合适权限的 AWS AK ID>',
    'ak_secret'        : '<具有合适权限的 AWS AK Secret>',
    'assume_role_arn'  : '<所需带入角色的资源名（ARN）>',
    'role_session_name': '<角色会话名称>',
    'serial_number'    : '<MFA 设备的标识符>',
    'token_code'       : '<MFA 设备提供的一次性代码，可选>',
    'extra_tags': {
        'account_name': '我的 AWS 账号',
    }
}

@DFF.API('执行云资产同步')
def run():
    regions = ['cn-northwest-1']

    # 采集器配置
    ec2_configs = {
        'regions': regions,
    }
    cloudwatch_configs = {
        'regions': regions,
        'targets': [
            {
                'namespace': 'AWS/EC2',
                'metrics'  : ['*cpu*'],
            },
        ],
    }
    collectors = [
        aws_ec2.DataCollector(account, ec2_configs),
        aws_cloudwatch.DataCollector(account, cloudwatch_configs),
    ]

    # 启动执行
    Runner(collectors).run()

关于 AWS account 配置，参考：AWS 客户端的多种认证方式

腾讯云

以采集「CVM 实例对象」及「CVM 相关的监控指标」为例：

from guance_integration__runner import Runner
import guance_tencentcloud_cvm__main as tencentcloud_cvm
import guance_tencentcloud_monitor__main as tencentcloud_monitor

# 账号配置
account = {
    'ak_id'    : '<具有合适权限的腾讯云 Secret ID>',
    'ak_secret': '<具有合适权限的腾讯云 Secret Key>',

    'extra_tags': {
        'account_name': '我的腾讯云账号',
    }
}

@DFF.API('执行云资产同步')
def run():
    regions = ['ap-shanghai']

    # 采集器配置
    cvm_configs = {
        'regions': regions,
    }
    monitor_configs = {
        'regions': regions,
        'targets': [
            {
                'namespace': 'QCE/CVM',
                'metrics'  : ['*cpu*'],
            },
        ],
    }
    collectors = [
        tencentcloud_cvm.DataCollector(account, cvm_configs),
        tencentcloud_monitor.DataCollector(account, monitor_configs),
    ]

    # 启动执行
    Runner(collectors).run()

微软云

以采集「CVM 实例对象」及「CVM 相关的监控指标」为例：

from guance_integration__runner import Runner
import guance_azure_vm__main as vm_main
import guance_azure_monitor__main as monitor_main

# 账号配置
account = {
    "client_id"     : "<Azure Client Id>",
    "client_secret" : "<Azure Client Secret>",
    "tenant_id"     : "<Azure Tenant Id>",
    "authority_area": "<Azure Area, Default global>",
    "extra_tags": {
        "account_name": "<Your Account Name>",
    }
}

subscriptions = "<Azure Subscriptions (Multiple needs to be separated by  ',')>"
subscriptions = subscriptions.split(',')

# 采集器配置
collector_configs = {
    'subscriptions': subscriptions,
}

monitor_configs = {
    'targets': [
        {
            'namespace': 'Microsoft.Compute/virtualMachines',
            'metrics'  : [
                'CPU*'
            ],
        },
    ],
}

@DFF.API('执行微软云 VM 资源采集')
def run():
    collectors = [
        vm_main.DataCollector(account, collector_configs),
        monitor_main.DataCollector(account, monitor_configs),
    ]

    Runner(collectors).run()

微软云 account 参数提示：

• client_id：租户 ID
• client_secret：应用注册 Client ID
• tenant_id：客户端密码值，注意不是 ID
• authority_area：区域，包括 global（全球区，海外区）、china（中国区，世纪互联）等，可选参数，默认为 global

Client Id、Client Secret、Tenant Id 的获取，可参考 Azure 文档：从本地托管的 Python 应用向 Azure 资源进行身份验证