C Library API

Fluent Bit 库是用 C 语言编写的，可以在任何 C 或 C++ 应用程序中使用。在深入研究规范之前，建议您先了解运行时的工作流程。

工作流程

Fluent Bit 作为服务运行，这意味着为开发人员公开的 API 提供了用于创建和管理上下文，指定输入/输出，设置配置参数及事件/记录的路由路径的接口。该库的典型用法包括:

• 创建库实例/上下文并设置属性

• 启用 input 插件并设置相关属性

• 启用 output 插件并设置相关属性

• 启动库运行时

• 可选的手动提取记录

• 停止库运行时

• 销毁库实例/上下文

数据类型

从 Fluent Bit v0.9 开始，库仅公开一种数据类型，且约定前缀为 flb_。

Type	Description
flb_ctx_t	主库的上下文。它多用于引用 flb_create() 返回的上下文

API 参考

创建库上下文

如前所述，使用库的第一步是使用 flb_create() 创建它的上下文。

原型

flb_ctx_t *flb_create();

返回值

如果成功，flb_create() 返回库的上下文；如果出错，返回NULL。

用法

flb_ctx_t *ctx;

ctx = flb_create();
if (!ctx) {
    return NULL;
}

设置服务属性

使用 flb_service_set() 函数可以设置上下文属性

原型

int flb_service_set(flb_ctx_t *ctx, ...);

返回值

如果成功，返回 0；如果出错，则返回一个负数。

用法

flb_service_set() 支持以键值对的字符串形式设置一个或多个属性，如:

int ret;

ret = flb_service_set(ctx, "Flush", "1", NULL);

如上示例指定了 Flush 属性的值。请注意，参数值始终是字符串(char)，且一旦没有更多参数，必须在参数列表末尾添加 *NULL 参数。

启用输入插件实例

构建完成后，Fluent Bit 库包含一些内置的 input 插件。要启用 input 插件，可以用 flb_input() 函数创建它的实例。

对于插件来说，实例表示已启用的插件上下文。您可以创建同一个插件的多个实例。

原型

int flb_input(flb_ctx_t *ctx, char *name, void *data);

参数 ctx 表示由 flb_create() 创建的上下文，name 是要启用的输入插件名称。

第三个参数 data 可用于将自定义引用传递给插件实例，这通常由自定义或第三方插件使用，对于通用插件，一般传入 NULL。

返回值

如果成功，flb_input() 返回一个大于等于 0 的整型值(类似于文件描述符)；如果出错，返回一个负数。

用法

int in_ffd;

in_ffd = flb_input(ctx, "cpu", NULL);

设置输入插件属性

通过 flb_input() 创建的插件实例可能提供一些配置属性，使用 flb_input_set() 函数可以提供这些属性。

原型

int flb_input_set(flb_ctx_t *ctx, int in_ffd, ...);

返回值

如果成功，返回 0；如果出错，返回一个负数。

用法

The flb_input_set() 允许在键/值字符串模式下设置一个或多个属性，例如:

int ret;

ret = flb_input_set(ctx, in_ffd,
                    "tag", "my_records",
                    "ssl", "false",
                    NULL);

参数 ctx 表示由 flb_create() 创建的上下文。上面的示例指定了 tag 和 ssl 属性值，请注意，该值始终是字符串(char*)，一旦没有更多参数，则必须在参数列表的末尾添加 NULL 参数。

每个输入插件允许的属性在该插件的文档中指定。

启用输出插件实例

构建完成后，Fluent Bit 库包含一些内置的 output 插件。要启用 output 插件，可以用 flb_output() 函数创建它的实例。

对于插件来说，实例表示已启用的插件上下文。您可以创建同一个插件的多个实例。

原型

int flb_output(flb_ctx_t *ctx, char *name, void *data);

参数 ctx 表示由 flb_create() 创建的上下文，name 是要启用的输入插件名称。

第三个参数 data 可用于将自定义引用传递给插件实例，这通常由自定义或第三方插件使用，对于通用插件，一般传入 NULL。

返回值

如果成功，flb_output() 返回输出插件实例；如果出错，返回一个负数。

用法

int out_ffd;

out_ffd = flb_output(ctx, "stdout", NULL);

设置输出插件属性

通过 flb_output() 创建的插件实例可能提供一些配置属性，使用 flb_output_set() 函数可以提供这些属性。

原型

int flb_output_set(flb_ctx_t *ctx, int out_ffd, ...);

返回值

如果成功，返回大于等于 0 的整数；如果出错，返回一个负数。

用法

The flb_output_set() 允许在键/值字符串模式下设置一个或多个属性，例如:

int ret;

ret = flb_output_set(ctx, out_ffd,
                     "tag", "my_records",
                     "ssl", "false",
                     NULL);

参数 ctx 表示由 flb_create() 创建的上下文。上面的示例指定了 tag 和 ssl 属性值，请注意，该值始终是字符串(char*)，一旦没有更多参数，则必须在参数列表的末尾添加 NULL 参数。

每个输出插件允许的属性在该插件的文档中指定。

启动 Fluent Bit 引擎

创建库上下文并设置输入/输出插件实例后，下一步就是启动引擎。 启动后，引擎将在新线程(POSIX thread)内运行，而不会阻塞调用者应用程序。要启动引擎，请使用 flb_start() 函数。

原型

int flb_start(flb_ctx_t *ctx);

返回值

如果成功，返回 0；如果出错，则返回一个负数。

Usage

这个简单的调用仅需要 ctx 作为参数传入，它是对先前 flb_create() 创建的上下文的引用:

int ret;

ret = flb_start(ctx);

停止 Fluent Bit 引擎

我们提供了 flb_stop() 函数用于停止运行中的 Fluent Bit 引擎。

原型

int flb_stop(flb_ctx_t *ctx);

参数 ctx 是对先前 flb_create() 函数创建的且通过 flb_start() 函数启动的上下文的引用。

当我们调用此函数时，引擎将最多等待五秒钟以刷新缓冲区并释放正在使用的资源。停止的上下文可以随时重新启动，但没有任何数据。

返回值

如果成功，返回 0；如果出错，则返回一个负数。

Usage

int ret;

ret = flb_stop(ctx);

销毁库上下文

库上下文在不需要时必须被销毁。请注意，必须先执行之前的 flb_stop() 函数调用。销毁后，将释放所有与之关联的资源。

原型

void flb_destroy(flb_ctx_t *ctx);

参数 ctx 是对先前 flb_create() 创建的上下文的引用。

返回值

没有返回值。

用法

flb_destroy(ctx);

手动提取数据

在某些情况下，应用程序调用可能希望将数据摄取到 Fluent Bit中，为此目的，我们提供了 flb_lib_push() 函数。

原型

int flb_lib_push(flb_ctx_t *ctx, int in_ffd, void *data, size_t len);

第一个参数是先前通过 flb_create() 创建的上下文。 in_ffd 是输入插件的数字引用(在这种情况下，它应该是一个插件 lib 类型的输入)，data 是对输入消息的引用，len 是从消息中获取的字节数限定。

返回值

如果成功，它返回写入的字节数；如果出错，返回 -1。

用法

有关如何正确使用此功能的更多详细信息和示例，请参阅下一小节 - 手动提取记录。