DOCA 遥测数据导出器
本指南概述了 DOCA 遥测数据导出器 API，并提供了配置说明。
DOCA 遥测数据导出器 API 提供了一种快速便捷的方式，将用户定义的数据传输到 DOCA 遥测服务 (DTS)。此外，该 API 还为用户提供了多种内置输出，包括将数据直接保存到存储、NetFlow、Fluent Bit 转发和 Prometheus 端点。
下图概述了遥测数据导出器 API。基于遥测数据导出器 API 的遥测数据导出器客户端侧，收集用户定义的遥测数据并将其发送到 DTS，DTS 作为容器在 BlueField 上运行。DTS 执行进一步的数据路由，包括带过滤的导出。DTS 可以处理多个用户定义的遥测数据导出器客户端，并且可以自行收集预定义的计数器。此外，遥测数据导出器 API 具有内置的数据输出，可以从遥测数据导出器客户端应用程序中使用。
以下场景可用
通过 IPC 传输将数据发送到 DTS。有关 IPC，请参阅进程间通信。
将数据作为二进制文件写入存储（用于调试数据格式）。
使用以下选项直接从 DOCA 遥测数据导出器 API 应用程序导出数据
Fluent Bit 通过转发导出数据
NetFlow 从 NetFlow API 导出数据。可从 API 和 DTS 获取。有关详细信息，请参阅数据输出。
Prometheus 创建 Prometheus 端点并保留最新数据以供 Prometheus 抓取。
用户可以启用或禁用上述任何数据输出。请参阅数据输出，了解如何启用每个输出。
库将数据存储在内部缓冲区中，并在以下场景中将其刷新到 DTS/导出器
一旦缓冲区已满。缓冲区大小可通过不同的属性进行配置。
当调用
doca_telemetry_exporter_source_flush(void *doca_source)函数时。当遥测数据导出器客户端终止时。如果缓冲区中有数据，则会在库的上下文清理之前对其进行处理。
DOCA 遥测数据导出器 API 从根本上围绕四个主要部分构建
DOCA 模式 – 定义遥测数据的可重用结构（请参阅doca_telemetry_exporter_type），可供多个源使用
源 – 定期报告遥测数据的遥测数据导出器源的唯一标识符。
报告 – 将信息导出到 DTS
完成 – 释放所有资源
DOCA 遥测数据导出器 API 详解
NVIDIA DOCA 遥测数据导出器 API 的定义可以在 doca_telemetry_exporter.h 文件中找到。
以下是使用 DOCA 遥测数据导出器 API 所需步骤的基本详解。
创建
doca_schema。使用默认属性初始化空模式
struct doca_telemetry_exporter_schema *doca_schema; doca_telemetry_exporter_schema_init(
"example_doca_schema_name", &doca_schema);如果需要，设置以下属性
doca_telemetry_exporter_schema_set_buffer_*(…)doca_telemetry_exporter_schema_set_file_write_*(…)doca_telemetry_exporter_schema_set_ipc_*(…)
添加用户事件类型
事件类型 (
struct doca_telemetry_exporter_type) 是用户定义的数据结构，描述事件字段。允许用户向事件类型添加多个字段。每个字段都有其自己的属性，可以设置这些属性（请参阅示例）。每个事件类型都分配有一个索引 (doca_telemetry_exporter_type_index_t)，该索引可用于在将来的 API 调用中引用事件类型。struct doca_telemetry_exporter_type *doca_type; struct doca_telemetry_exporter_field *field1; doca_telemetry_exporter_type_create(&doca_type); doca_telemetry_exporter_field_create(&field1); doca_telemetry_exporter_field_set_name(field1,
"sport"); doca_telemetry_exporter_field_set_description(field1,"Source port") doca_telemetry_exporter_field_set_type_name(field1, DOCA_TELEMETRY_EXPORTER_FIELD_TYPE_UINT16); doca_telemetry_exporter_field_set_array_length(field1,1);/* The user loses ownership on field1 after a successful invocation of the function */doca_telemetry_exporter_type_add_field(type, field1);/* Add more fields if needed *//* The user loses ownership on doca_type after a successful invocation of the function */doca_telemetry_exporter_schema_add_type(doca_schema,"example_event", doca_type, &type_index);应用属性和类型以开始使用模式
doca_telemetry_exporter_schema_start(doca_schema)
创建
doca_source初始化
struct doca_telemetry_exporter_source *doca_source; doca_telemetry_exporter_source_create(doca_schema, &doca_source);
设置源 ID 和标签
doca_telemetry_exporter_source_set_id(doca_source,
"example id"); doca_telemetry_exporter_source_set_tag(doca_source,"example tag");应用属性以开始使用源
doca_telemetry_exporter_source_start(doca_source)
如果需要，您可以选择添加更多
doca_sources。收集每个源的数据并使用
doca_telemetry_exporter_source_report(source, type_index, &my_app_test_ev1, num_events)
完成
对于每个源
doca_telemetry_exporter_source_destroy(source)
销毁
doca_telemetry_exporter_schema_destroy(doca_schema)
示例实现可以在 telemetry_export DOCA 示例 (telemetry_export_sample.c) 中找到。
DOCA 遥测数据导出器 NetFlow API 详解
DOCA 遥测数据导出器 API 还支持使用 DOCA 遥测数据导出器 NetFlow API 的 NetFlow。此 API 旨在让客户可以轻松地在端点侧支持 NetFlow 协议。一旦端点使用 API 生成 NetFlow 数据，就可以使用相应的导出器将数据发送到 NetFlow 收集器。
NVIDIA DOCA 遥测数据导出器 Netflow API 的定义可以在 doca_telemetry_exporter_netflow.h 文件中找到。
以下是使用 NetFlow API 的步骤
使用适当的源 ID 启动 API
doca_telemetry_exporter_netflow_init(source_id)
设置相关属性
doca_telemetry_exporter_netflow_set_buffer_*(…)doca_telemetry_exporter_netflow_set_file_write_*(…)doca_telemetry_exporter_netflow_set_ipc_*(…)doca_telemetry_exporter_netflow_source_set_*()
启动 API 以使用配置的属性
doca_telemetry_exporter_netflow_start();
形成所需的 NetFlow 模板和相应的 NetFlow 记录。
收集 NetFlow 数据。
doca_telemetry_exporter_netflow_send(…)
（可选）刷新 NetFlow 数据以立即发送数据，而不是等待缓冲区填满
doca_telemetry_exporter_netflow_flush()
清理 API
doca_telemetry_exporter_netflow_destroy()
示例实现可以在 telemetry_export_netflow DOCA 示例 (telemetry_export_netflow_sample.c) 中找到。
有关 DOCA 遥测数据导出器 API 的更多详细信息，请参阅DOCA 库 API。
DOCA 遥测数据导出器库的 pkg-config (*.pc 文件) 是 doca-telemetry-exporter。
以下各节提供有关库 API 的更多详细信息。
某些属性是可选的，因为它们使用默认值初始化。有关更多信息，请参阅各个属性的 setter 函数的文档。
DOCA 遥测数据导出器缓冲区属性
缓冲区属性用于设置模式中所有 DOCA 源使用的内部缓冲区大小和数据根目录。
配置属性是可选的，因为它们使用默认值初始化。
doca_telemetry_exporter_schema_set_buffer_size(doca_schema, 16 * 1024); /* 16KB - arbitrary value */
doca_telemetry_exporter_schema_set_buffer_data_root(doca_schema, "/opt/mellanox/doca/services/telemetry/data/");
buffer_size [in]– 内部缓冲区的大小，用于累积数据，然后再将其发送到输出。数据在内部缓冲区满时自动发送。较大的缓冲区意味着较少的数据传输，反之亦然。data_root [in]– 存储数据的路径（如果file_write_enabled设置为 true）。请参阅“DOCA 遥测数据导出器文件写入属性”部分。
DOCA 遥测数据导出器文件写入属性
文件写入属性用于启用和配置以二进制格式将数据存储到文件系统。
配置属性是可选的，因为它们使用默认值初始化。
doca_telemetry_exporter_schema_set_file_write_enabled(doca_schema);
doca_telemetry_exporter_schema_set_file_write_max_size(doca_schema, 1 * 1024 * 1024); /* 1 MB */
doca_telemetry_exporter_schema_set_file_write_max_age(doca_schema, 60 * 60 * 1000000L); /* 1 Hour */
file_write_enable [in]– 使用此函数启用存储。默认情况下，存储/文件写入处于禁用状态。file_write_max_size [in]– 创建新文件之前的最大文件大小（以字节为单位）。file_write_max_age [in]– 创建新文件之前的最大文件生存时间（以微秒为单位）。
DOCA 遥测数据导出器 IPC 属性
IPC 属性用于启用和配置 IPC 传输。默认情况下，IPC 处于禁用状态。
配置属性是可选的，因为它们使用默认值初始化。
请务必确保 IPC 位置与 DTS 使用的 IPC 位置匹配，否则 IPC 通信将失败。
doca_telemetry_exporter_schema_set_ipc_enabled(doca_schema);
doca_telemetry_exporter_schema_set_ipc_sockets_dir(doca_schema, "/path/to/sockets/");
doca_telemetry_exporter_schema_set_ipc_reconnect_time(doca_schema, 100); /* 100 milliseconds */
doca_telemetry_exporter_schema_set_ipc_reconnect_tries(doca_schema, 3);
doca_telemetry_exporter_schema_set_ipc_socket_timeout(doca_schema, 3 * 1000) /* 3 seconds */
ipc_enabled [in]– 使用此函数启用通信。默认情况下，IPC 处于禁用状态。ipc_sockets_dir [in]– 包含 IPC 消息的 UDS 的目录。遥测数据导出器程序和 DTS 都必须使用相同的文件夹。在 BlueField 上作为容器运行的 DTS 具有默认文件夹/opt/mellanox/doca/services/telemetry/ipc_sockets。ipc_reconnect_time [in]– 最大重连时间（以毫秒为单位），超过此时间后，客户端被视为断开连接。ipc_reconnect_tries [in]– 最大重连尝试次数。ipc_socket_timeout [in]– IPC 套接字的超时时间。
DOCA 遥测数据导出器源属性
源属性用于创建正确的文件夹结构。从同一主机收集的所有数据都写入数据根目录下的 source_id 文件夹。
源属性是强制性的，必须在调用 doca_telemetry_exporter_source_start() 之前配置。
doca_telemetry_exporter_source_set_id(doca_source, "example_source");
doca_telemetry_exporter_source_set_tag(doca_source, "example_tag");
source_id [in]– 描述数据的来源。建议将其设置为主机名。在以后的数据流步骤中，数据从多个主机/DPU 聚合，source_id有助于在其中导航。source_tag [in]– 唯一的数据标识符。建议将其设置为描述应用程序中收集的数据。可以在单个节点（主机/DPU）上部署多个遥测数据导出器应用程序。在这种情况下，每个遥测数据都将具有唯一的标签，并且它们都将共享单个source_id。
DOCA 遥测数据导出器 Netflow 收集器属性
DOCA 遥测数据导出器 NetFlow API 属性是可选的，仅应用于调试目的。它们表示在本地工作时 NetFlow 收集器的地址，有效地启用了本地 NetFlow 导出器。
doca_telemetry_exporter_netflow_set_collector_addr("127.0.0.1");
doca_telemetry_exporter_netflow_set_collector_port(6343);
collector_addr [in]– NetFlow 收集器的地址（IP 或名称）。默认值为NULL。collector_port [in]– NetFlow 收集器的端口。默认值为DOCA_NETFLOW_DEFAULT_PORT (2055)。
doca_telemetry_exporter_source_report
源报告函数是与 DTS 通信的核心。报告操作会导致事件数据被分配到内部缓冲区。一旦缓冲区已满，数据将根据设置的配置向前转发。
doca_error_t doca_telemetry_exporter_source_report(struct doca_telemetry_exporter_source *doca_source,
doca_telemetry_exporter_type_index_t index,
void *data,
int count);
doca_source [in]– 指向报告事件的doca_telemetry_exporter_source的指针index [in]– 创建模式时收到的事件类型索引data [in]– 指向需要发送的数据缓冲区的指针count [in]– 要写入内部缓冲区的事件数
如果成功，该函数返回 DOCA_SUCCESS；如果发生错误，则返回 doca_error_t。如果发生与内存相关的错误，请尝试更大的缓冲区大小，使其与事件的大小相匹配。
doca_telemetry_exporter_schema_add_type
此函数允许添加可重用的遥测数据结构，也称为模式。该模式允许将预定义的数据结构发送到遥测服务。请注意，必须定义模式才能使库正常运行。添加模式后，需要调用模式启动函数。
doca_error_t doca_telemetry_exporter_schema_add_type(struct doca_telemetry_exporter_schema *doca_schema,
const char *new_type_name,
struct doca_telemetry_exporter_type *type,
doca_telemetry_exporter_type_index_t *type_index);
doca_schema [in]– 指向要向其中添加类型的模式的指针new_type_name [in]– 新类型的名称fields [in]– 用于模式的用户定义字段。可以（并且应该）添加多个字段。type_index [out]– 创建类型的类型索引写入到此输出变量
如果成功，该函数返回 DOCA_SUCCESS；如果发生错误，则返回 doca_error_t。
内部数据格式由 2 个部分组成：包含元数据的模式和实际的二进制数据。当数据写入存储时，数据模式以 JSON 格式写入，数据以二进制文件形式写入。在 IPC 传输的情况下，模式和二进制数据都发送到 DTS。在导出的情况下，数据将转换为导出器所需的格式。
可以使用 doca_telemetry_exporter_schema_add_type API 调用将自定义事件类型添加到模式。
请参阅 doca_telemetry_exporter.h 中的可用 DOCA_TELEMETRY_EXPORTER_FIELD_TYPE。请参阅 /opt/mellanox/doca/samples/doca_telemetry_exporter/telemetry_export/telemetry_export_sample.c 中的用法示例。
强烈建议将时间戳字段作为第一个字段，因为大多数数据库都需要它。要以正确的格式获取当前时间戳，请使用
doca_error_t doca_telemetry_exporter_get_timestamp(doca_telemetry_exporter_timestamp_t *timestamp);
本节介绍可用的导出器
IPC
NetFlow
Fluent Bit
Prometheus
API 和 DTS 中都提供了 Fluent Bit 和 Prometheus 导出器。即使 DTS 导出是首选的，API 也具有相同的开发灵活性。
进程间通信
IPC 传输自动将数据从基于遥测数据导出器的程序传输到 DTS 服务。
它实现为 UNIX 域套接字 (UDS) 套接字（用于短消息）和共享内存（用于数据）。DTS 和基于遥测数据导出器的程序必须共享相同的 ipc_sockets 目录。
启用 IPC 传输后，数据将通过共享内存从基于 DOCA 遥测数据导出器的应用程序发送到 DTS 进程。
要启用 IPC，请使用 doca_telemetry_exporter_schema_set_ipc_enabled API 函数。
IPC 传输依赖于系统文件夹。对于主机的使用，请使用 sudo 运行基于 DOCA 遥测数据导出器 API 的应用程序，以便能够将 IPC 与系统文件夹结合使用。
要检查当前上下文的 IPC 状态，请使用
doca_error_t doca_telemetry_exporter_check_ipc_status(struct doca_telemetry_exporter_source *doca_source,
doca_telemetry_exporter_ipc_status_t *status)
如果启用了 IPC 并且由于某种原因连接丢失，它将在每次报告的函数调用时尝试自动重新连接。
将 IPC 与非容器应用程序结合使用
在开发和测试非容器 DOCA 遥测数据导出器程序及其与 DTS 的 IPC 交互时，需要在 DTS 的部署中进行一些修改，以便程序可以通过 IPC 与 DTS 交互
应删除共享内存映射：
telemetry-ipc-shm应启用主机 IPC：
hostIPC
更改前的文件
spec:
hostNetwork: true
volumes:
- name: telemetry-service-config
hostPath:
path: /opt/mellanox/doca/services/telemetry/config
type: DirectoryOrCreate
...
- name: telemetry-ipc-shm
hostPath:
path: /dev/shm/telemetry
type: DirectoryOrCreate
containers:
...
volumeMounts:
- name: telemetry-service-config
mountPath: /config
...
- name: telemetry-ipc-shm
mountPath: /dev/shm
更改后的文件
spec:
hostNetwork: true
hostIPC: true
volumes:
- name: telemetry-service-config
hostPath:
path: /opt/mellanox/doca/services/telemetry/config
type: DirectoryOrCreate
...
containers:
...
volumeMounts:
- name: telemetry-service-config
mountPath: /config
这些更改确保在容器外部运行的基于 DOCA 的程序能够通过 IPC 与 DTS 通信。
NetFlow
启用 NetFlow 导出器（设置 NetFlow 收集器属性）后，它会将 NetFlow 数据发送到属性指定的 NetFlow 收集器：地址和端口。使用 DOCA 遥测数据导出器 NetFlow API 时，必须使用此导出器。
Fluent Bit
Fluent Bit 导出基于 fluent_bit_configs，每个目标都有 .exp 文件。每个导出文件对应于 Fluent Bit 的一个目标。所有找到并启用的 .exp 文件都用作单独的导出目标。可以在运行 DTS 容器后在其配置文件夹 (/opt/mellanox/doca/services/telemetry/config/fluent_bit_configs/) 下找到示例。
所有 .exp 文件都已就地记录。
DPU# ls -l /opt/mellanox/doca/services/telemetry/config/fluent_bit_configs/
/opt/mellanox/doca/services/telemetry/config/fluent_bit_configs/:
total 56
-rw-r--r-- 1 root root 528 Oct 11 07:52 es.exp
-rw-r--r-- 1 root root 708 Oct 11 07:52 file.exp
-rw-r--r-- 1 root root 1135 Oct 11 07:52 forward.exp
-rw-r--r-- 1 root root 719 Oct 11 07:52 influx.exp
-rw-r--r-- 1 root root 571 Oct 11 07:52 stdout.exp
-rw-r--r-- 1 root root 578 Oct 11 07:52 stdout_raw.exp
-rw-r--r-- 1 root root 2137 Oct 11 07:52 ufm_enterprise.fset
Fluent Bit .exp 文件具有 2 级数据路由
.exp文件中的source_tags（就地记录）由
.fset文件控制的基于令牌的过滤（记录在ufm_enterprise.fset中）
要使用 Fluent Bit 导出器运行，请在所需的 .exp 文件中设置 enable=1，并在运行应用程序之前设置环境变量
export FLUENT_BIT_EXPORT_ENABLE=1
export FLUENT_BIT_CONFIG_DIR=/path/to/fluent_bit_configs
export LD_LIBRARY_PATH=/opt/mellanox/collectx/lib
Prometheus
Prometheus 导出器设置端点 (HTTP 服务器)，该端点将最新的事件数据作为文本记录保存。
Prometheus 服务器可以在基于 DOCA 遥测数据导出器 API 的应用程序保持活动状态时从端点抓取数据。
查看 Prometheus 记录的通用示例
event_name_1{label_1="label_1_val", label_2="label_2_val", label_3="label_3_val", label_4="label_4_val"} counter_value_1 timestamp_1
event_name_2{label_1="label_1_val", label_2="label_2_val", label_3="label_3_val", label_4="label_4_val"} counter_value_2 timestamp_2
...
标签是可自定义的元数据，可以从数据文件设置。事件名称可以根据 .fset 文件通过基于令牌的名称匹配进行过滤。
在运行之前设置以下环境变量。
# Set the endpoint host and port to enable export.
export PROMETHEUS_ENDPOINT=http://0.0.0.0:9101
# Set indexes as a comma-separated list to keep data for every index field. In
# this example most recent data will be kept for every record with unique
# `port_num`. If not set, only one data per source will be kept as the most
# recent.
export PROMETHEUS_INDEXES=Port_num
# Set path to a file with Prometheus custom labels. Use labels to store
# information about data source and indexes. If not set, the default labels
# will be used.
export CLX_METADATA_FILE=/path/to/labels.txt
# Set the folder which contains fset-files. If set, Prometheus will scrape
# only filtered data according to fieldsets.
export PROMETHEUS_CSET_DIR=/path/to/prometheus_cset
要在没有 Prometheus 服务器的情况下抓取数据，请使用
curl -s http://0.0.0.0:9101/metrics
或
curl -s http://0.0.0.0:9101/{fset_name}
本节提供基于 BlueField DPU 的 DOCA 遥测数据导出器示例实现。
本文档中的遥测数据导出器示例演示了涵盖两种用例的初始建议配置
标准 DOCA 遥测数据导出器数据
DOCA 遥测数据导出器用于 NetFlow 数据
遥测数据导出器示例在 BlueField 上运行。如果启用了写入文件，则遥测数据将存储到 BlueField 的存储。如果启用了进程间通信 (IPC)，则数据将发送到在同一 BlueField 上运行的 DOCA 遥测服务 (DTS)。
有关初始化和配置 DTS 的信息，请参阅DOCA 遥测服务指南。
本节中描述的所有 DOCA 示例均受 BSD-3 软件许可协议管辖。
运行示例
请参阅以下文档
DOCA Linux 安装指南，了解如何安装 BlueField 相关软件的详细信息。
DOCA 故障排除，了解您在 DOCA 示例的安装、编译或执行中可能遇到的任何问题。
要构建给定的示例
cd /opt/mellanox/doca/samples/doca_telemetry_exporter/<sample_name> meson /tmp/build ninja -C /tmp/build
信息二进制文件
doca_<sample_name>将在/tmp/build/下创建。示例（例如，
telemetry_export）用法Usage: doca_telemetry_export [DOCA Flags] DOCA Flags: -h, --help Print a help synopsis -v, --version Print program version information -l, --log-level Set the (numeric) log level
forthe program <10=DISABLE,20=CRITICAL,30=ERROR,40=WARNING,50=INFO,60=DEBUG,70=TRACE> --sdk-log-level Set the SDK (numeric) log levelforthe program <10=DISABLE,20=CRITICAL,30=ERROR,40=WARNING,50=INFO,60=DEBUG,70=TRACE> -j, --json <path> Parse all command flags from an input json file有关每个示例的更多信息，请使用
-h选项/tmp/build/doca_<sample_name> -h
示例
遥测数据导出
此示例说明如何使用遥测数据导出器 API。该示例使用自定义模式进行遥测数据导出。
示例逻辑包括
配置模式属性。
初始化模式。
创建遥测数据导出器源。
创建示例事件。
通过 DOCA 遥测数据导出器报告示例事件。
销毁源和模式。
参考
/opt/mellanox/doca/samples/doca_telemetry_exporter/telemetry_export/telemetry_export_sample.c/opt/mellanox/doca/samples/doca_telemetry_exporter/telemetry_export/telemetry_export_main.c/opt/mellanox/doca/samples/doca_telemetry_exporter/telemetry_export/meson.build
遥测数据导出 NetFlow
此示例说明如何使用遥测数据导出器 API 的 NetFlow 功能。
示例逻辑包括
配置 NetFlow 属性。
初始化 NetFlow。
创建遥测数据导出器源。
启动 NetFlow。
创建示例事件。
通过 DOCA 遥测数据导出器报告示例事件。
销毁 NetFlow。
参考
/opt/mellanox/doca/samples/doca_telemetry_exporter/telemetry_export_netflow/telemetry_export_netflow_sample.c/opt/mellanox/doca/samples/doca_telemetry_exporter/telemetry_export_netflow/telemetry_export_netflow_main.c/opt/mellanox/doca/samples/doca_telemetry_exporter/telemetry_export_netflowt/meson.build