mellanox/ufm-plugin-tfs

UFM Telemetry stream to Fluentd (TFS) 插件

概述

TFS UFM插件旨在从配置的UFM Telemetry HTTP端点提取计数器数据，并将其实时流式传输到配置的Fluentd收集器。NVIDIA UFM Telemetry平台提供网络性能和状态监控工具，捕获并流式传输丰富的实时网络遥测信息及应用工作负载使用情况至本地或云数据库以进行进一步分析。作为网络管理器，UFM Telemetry持有网络拓扑的实时遥测信息，TFS插件通过流式传输这些数据至Fluentd，确保信息随时间变化能及时反映到遥测控制台。

!https://raw.githubusercontent.com/Mellanox/ufm_sdk_3.0/main/plugins/fluentd_telemetry_plugin/TFS_Architecture.png

发布说明

最新版本 (1.1.0-0)

1. 移除对Prometheus格式遥测数据获取的支持。
2. 新增telemetry_request_timeout选项，默认值为60秒。

1.0.15-1

1. 增加对XDR技术的支持。
2. 新增enable_cached_stream_on_telemetry_fail选项（默认：true）：当遥测端点不可用时，允许流式传输上次成功迭代的缓存数据，以提升遥测端点故障期间的用户体验。
3. 修复多个bug。

1.0.0-14

1. 将默认Fluent流式传输协议从HTTP更改为FORWARD。
2. 集成c-forward流传输库。
3. 提升CSV处理性能。
4. 修复多个bug。

部署

在UFM-SDN Appliance上部署插件

• 以admin身份登录
• 运行以下命令：

  bash
  enable
  

  bash
  config terminal
  

• 确保UFM正在运行：

  bash
  show ufm status
  

  • 若UFM未运行，启动UFM：

    bash
    ufm start
    

• 确保Docker正在运行：

  bash
  no docker shutdown
  

• 加载最新插件Docker镜像
  • 若为HA环境，需在备用节点也加载插件。
  • 若设备已联网，直接运行：

    bash
    docker pull docker.xuanyuan.run/mellanox/ufm-plugin-tfs
    

  • 若设备未联网，需离线加载镜像：
    • 在联网机器上保存Docker镜像：

      bash
      docker save mellanox/ufm-plugin-tfs:latest | gzip > ufm-plugin-tfs.tar.gz
      

    • 将文件移至设备可访问的SCP共享位置。
    • 获取镜像到设备：

      bash
      image fetch scp://user@hostname/path-to-file/ufm-plugin-tfs.tar.gz
      

    • 加载镜像：

      bash
      docker load ufm-plugin-tfs.tar.gz
      

• 启用并启动插件：

  bash
  ufm plugin tfs add
  

• 检查插件状态：

  bash
  show ufm plugin
  

在UFM Enterprise（裸金属/Docker）上部署插件

• 加载最新插件容器
  • 若为HA环境，需在备用节点也加载插件。
  • 若机器已联网，直接运行：

    bash
    docker pull docker.xuanyuan.run/mellanox/ufm-plugin-tfs
    

  • 若UFM机器未联网，需离线加载镜像：
    • 在联网机器上保存Docker镜像：

      bash
      docker save mellanox/ufm-plugin-tfs:latest | gzip > ufm-plugin-tfs.tar.gz
      

    • 将文件移至UFM机器可访问的共享位置。
    • 加载镜像到UFM机器：

      bash
      docker load -i </[some-shared-location]/ufm-plugin-tfs.tar.gz
      

• 启用并启动插件
  • UFM裸金属安装：

    bash
    /opt/ufm/scripts/manage_ufm_plugins.sh add -p tfs
    

  • UFM Docker安装：

    bash
    docker exec ufm /opt/ufm/scripts/manage_ufm_plugins.sh add -p tfs
    

• 检查插件状态
  • UFM裸金属安装：

    bash
    /opt/ufm/scripts/manage_ufm_plugins.sh show
    

  • UFM Docker安装：

    bash
    docker exec ufm /opt/ufm/scripts/manage_ufm_plugins.sh show
    

Fluentd部署配置

• 拉取Fluentd Docker镜像：

  bash
  docker pull docker.xuanyuan.run/fluent/fluentd
  

• 运行Fluentd容器：

  bash
  docker run -ti --rm --network host -v /tmp/fluentd:/fluentd/etc docker.xuanyuan.run/fluentd -c /fluentd/etc/fluentd.conf -v
  

• 提供https://github.com/Mellanox/ufm_sdk_3.0/blob/main/plugins/fluentd_telemetry_plugin/conf/fluentd.conf%E4%BD%9C%E4%B8%BA%E9%85%8D%E7%BD%AE%E7%A4%BA%E4%BE%8B%E3%80%82
• TFS支持通过FORWARD和HTTP协议向Fluent目标发送数据，FORWARD为默认协议；若需切换至HTTP协议，需启用https://github.com/Mellanox/ufm_sdk_3.0/blob/main/plugins/fluentd_telemetry_plugin/conf/fluentd_telemetry_plugin.cfg#L16%E3%80%82

IPv6配置

TFS支持通过IPv6向Fluent目标流式传输数据，需确保Fluent监听IPv6接口，将https://github.com/Mellanox/ufm_sdk_3.0/blob/main/plugins/fluentd_telemetry_plugin/conf/fluentd.conf#L4%EF%BC%88***d 0.0.0.0）替换为（***d ::）。

日志文件位置：主机上日志文件位于/opt/ufm/files/log/plugins/tfs/tfs.log；对于低于6.17.0版本的UFM，日志文件位于/opt/ufm/files/log/tfs.log。

使用方法

TFS配置参数详情

设置/更新插件配置

提供以下REST API用于设置插件配置：

方法：POST
URL：https://[HOST-IP]/ufmRest/plugin/tfs/conf

cURL示例：

curl
curl --location 'https://<UFM_IP>/ufmRest/plugin/tfs/conf' \
--header 'Content-Type: application/json' \
--data '{
    "fluentd-endpoint": {
        "host": "<FLUENT_RECIEVER_IP>",
        "port": 24224,
        "timeout": 120
    },
    "streaming": {
        "enabled": true,
        "stream_only_new_samples": false
    },
    "ufm-telemetry-endpoint": [
        {
            "host": "127.0.0.1",
            "interval": <COLLECTING_INTERVAL_SECONDS, e.g. 30>,
            "port": <TELEMETRY_HTTP_PORT, e.g. 9001>,
            "url": <TELEMETRY_CSET_URL, e.g. csv/metrics OR csv/cset/converted_enterprise>
        }
    ]
}' -k -u <UFM_USERNAME>:<UFM_PASSWORD>

完整Payload示例：

json
{
    "ufm-telemetry-endpoint": [{
        "host": "127.0.0.1",
        "url": "csv/metrics",
        "port": 9001,
        "interval": 30,
        "message_tag_name": "high_freq_endpoint"
    }],
    "fluentd-endpoint": {
        "host": "10.209.36.68",
        "port": 24226
    },
    "streaming": {
        "compressed_streaming": false,
        "bulk_streaming": true,
        "enabled": true,
        "stream_only_new_samples": true
    },
    "logs-config": {
        "log_file_backup_count": 5,
        "log_file_max_size": 10485760,
        "logs_file_name": "/log/tfs.log",
        "logs_level": "INFO"
    },
    "meta-fields":{
        "alias_node_description": "node_name",
        "alias_node_guid": "AID",
        "add_type":"csv"
    }
}

获取插件配置

提供以下REST API用于获取当前插件配置：

方法：GET
URL：https://[HOST-IP]/ufmRest/plugin/tfs/conf

cURL示例：

curl
curl --location 'https://<UFM_IP>/ufmRest/plugin/tfs/conf' -k -u <UFM_USERNAME>:<UFM_PASSWORD>

响应示例：

json
{
    "ufm-telemetry-endpoint": [{
        "host": "127.0.0.1",
        "url": "csv/metrics",
        "port": 9001,
        "interval": 30,
        "message_tag_name": "high_freq_endpoint"
    }],
    "fluentd-endpoint": {
        "host": "10.209.36.68",
        "port": 24226
    },
    "streaming": {
        "compressed_streaming": false,
        "bulk_streaming": true,
        "enabled": true,
        "stream_only_new_samples": true
    },
    "logs-config": {
        "log_file_backup_count": 5,
        "log_file_max_size": 10485760,
        "logs_file_name": "/log/tfs.log",
        "logs_level": "INFO"
    },
    "meta-fields":{
        "alias_node_description": "node_name",
        "alias_node_guid": "AID",
        "add_type":"csv"
    }
}

从多个UFM Telemetry端点流式传输数据

可配置TFS插件从多个端点轮询指标，每个端点有独立的轮询/流传输间隔。通过conf API添加遥测端点配置即可。

多UFM Telemetry端点Payload示例：

json
{
    "ufm-telemetry-endpoint": [{
        "host": "127.0.0.1",
        "url": "csv/metrics",
        "port": 9001,
        "interval": 10,
        "message_tag_name": "high_freq_endpoint"
    },{
        "host": "127.0.0.1",
        "url": "csv/metrics",
        "port": 9002,
        "interval": 60,
        "message_tag_name": "low_freq_endpoint"
    }],
    "fluentd-endpoint": {
        "host": "10.209.36.68",
        "port": 24226
    }
}

UFM Telemetry中的分片功能

UFM Telemetry内置的分片功能支持从多个遥测指标端点高效轮询数据，适用于数据量大或带宽有限的网络环境。

如何在TFS中使用分片

需在配置的遥测端点URL中添加特定参数：num_shards（分片总数）、shard（当前分片索引）、sharding_field（分片字段）。

分片配置Payload示例：

json
{
    "ufm-telemetry-endpoint": [{
        "host": "127.0.0.1",
        "url": "csv/xcset/ib_basic_debug?num_shards=3&shard=0&sharding_field=port_guid",
        "port": 9002,
        "interval": 120
    },{
        "host": "127.0.0.1",
        "url": "csv/xcset/ib_basic_debug?num_shards=3&shard=1&sharding_field=port_guid",
        "port": 9002,
        "interval": 120
    },{
        "host": "127.0.0.1",
        "url": "csv/xcset/ib_basic_debug?num_shards=3&shard=2&sharding_field=port_guid",
        "port": 9002,
        "interval": 120
    }],
    "fluentd-endpoint": {
        "host": "10.209.36.68",
        "port": 24226
    }
}

分片调优

为获得最佳性能，建议调整分片使单个分片传输时间约为10-15秒，以避免遥测服务器超时。可根据网络状况调整分片数量（如网络较慢时增加分片数）。

向TFS消息添加自定义元字段记录

元字段是可添加到TFS流传输记录中的自定义字段，分为别名（Aliases）和常量（Constants）。

别名（Aliases）

重命名记录中已有的字段，仅匹配精确字段名。
语法：alias_originalFieldName=aliasName
示例：将"node_guid"重命名为"AID"：alias_node_guid=AID

常量（Constants）

添加具有固定值的新字段。
语法：add_newFieldName=constantValue
示例：添加"type"字段，值为"csv"：add_type=csv

配置示例

json
{
    "meta-fields": {
        "alias_node_description": "node_name",
        "alias_node_guid": "AID",
        "add_type": "csv"
    }
}

预期输出

json
{
    "timestamp": "1644411135311315",
    "source_id": "0xe41d2d030003e450",
    "node_guid": "e41d2d030003e450",
    "port_guid": "e41d2d030003e450",
    "port_num": "10",
    "node_description": "SwitchIB Mellanox Technologies",
    "node_name": "SwitchIB Mellanox Technologies",
    "AID": "e41d2d030003e450",
    "type": "csv"
}