You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
[Fluent Bit](http://fluentbit.io) library is written in C language and can be used from any C or C++ application. Before digging into the specification it is recommended to understand the workflow involved in the runtime.
3
+
Fluent Bitis written in C and can be used from any C or C++ application.
4
4
5
5
## Workflow
6
6
7
-
[Fluent Bit](http://fluentbit.io) runs as a service, meaning that the API exposed for developers provide interfaces to create and manage a context, specify inputs/outputs, set configuration parameters and set routing paths for the event/records. A typical usage of the library involves:
7
+
Fluent Bit runs as a service, which means that the exposed API provides interfaces to create and manage contexts, specify inputs and outputs, set configuration parameters, and set routing paths for events or records. A typical usage of this library involves:
8
8
9
-
*Create library instance/context and set properties.
10
-
*Enable _input_ plugin\(s\) and set properties.
11
-
*Enable _output_ plugin\(s\) and set properties.
12
-
*Start the library runtime.
13
-
* Optionally ingest records manually.
14
-
*Stop the library runtime.
15
-
*Destroy library instance/context.
9
+
*Creating library instance and contexts and setting their properties.
10
+
*Enabling input plugins and setting their properties.
11
+
*Enabling output plugins and setting their properties.
12
+
*Starting the library runtime.
13
+
* Optionally ingesting records manually.
14
+
*Stopping the library runtime.
15
+
*Destroying library instances and contexts.
16
16
17
-
## Data Types
17
+
## Data types
18
18
19
-
Starting from Fluent Bit v0.9, there is only one data type exposed by the library, by conventionprefixed with **flb\_**.
19
+
There is only one data type exposed by the library. By convention, this data type is prefixed with `flb_`.
20
20
21
21
| Type | Description |
22
22
| :--- | :--- |
23
-
|flb\_ctx\_t| Main library context. It aims to reference the context returned by _flb\_create\(\);_|
23
+
|`flb_ctx_t`| Main library context. This references the context returned by `flb_create();`.|
24
24
25
-
## API Reference
25
+
## API reference
26
26
27
-
### Library Context Creation
27
+
### Library context creation
28
28
29
-
As described earlier, the first step to use the library is to create a context of it, for the purpose the function **flb\_create\(\)** is used.
29
+
Use the `flb_create()` function to create library context.
30
30
31
-
**Prototype**
31
+
#### Prototype
32
32
33
33
```c
34
34
flb_ctx_t *flb_create();
35
35
```
36
36
37
-
**Return Value**
37
+
#### Return value
38
38
39
-
On success, **flb\_create\(\)**returns the library context; on error, it returns NULL.
39
+
On success, this function returns the library context. On error, it returns `NULL`.
40
40
41
-
**Usage**
41
+
#### Usage
42
42
43
43
```c
44
44
flb_ctx_t *ctx;
@@ -49,77 +49,79 @@ if (!ctx) {
49
49
}
50
50
```
51
51
52
-
### Set Service Properties
52
+
### Set service properties
53
53
54
-
Using the **flb\_service\_set\(\)** function is possible to set context properties.
54
+
Use the `flb_service_set()` function to set context properties.
55
55
56
-
**Prototype**
56
+
#### Prototype
57
57
58
58
```c
59
59
intflb_service_set(flb_ctx_t *ctx, ...);
60
60
```
61
61
62
-
**Return Value**
62
+
#### Return value
63
63
64
-
On success it returns 0; on error it returns a negative number.
64
+
On success, this function returns `0`. On error, it returns a negative number.
65
65
66
-
**Usage**
66
+
#### Usage
67
67
68
-
The **flb\_service\_set\(\)** allows to set one or more properties in a key/value string mode, e.g:
68
+
This function sets one or more properties as a key/value string. For example:
69
69
70
70
```c
71
71
int ret;
72
72
73
73
ret = flb_service_set(ctx, "Flush", "1", NULL);
74
74
```
75
75
76
-
The above example specified the values for the properties **Flush** , note that the value is always a string \(char \*\) and once there is no more parameters a NULL argument must be added at the end of the list.
76
+
This example specified the values for the property `Flush`. Its value is always a string (`char *`), and after all parameters are listed, you must add a `NULL` argument at the end of the list.
77
77
78
-
### Enable Input Plugin Instance
78
+
### Enable input plugin instance
79
79
80
-
When built, [Fluent Bit](http://fluentbit.io) library contains a certain number of built-in _input_plugins. In order to enable an _input_ plugin, the function **flb\_input**\(\) is used to create an instance of it.
80
+
The Fluent Bit library contains several input plugins. To enable an input plugin, use the `flb_input()` function to create an instance of it.
81
81
82
-
> For plugins, an _instance_ means a context of the plugin enabled. You can create multiples instances of the same plugin.
82
+
{% hint style="info" %}
83
+
For plugins, an _instance_ means a context of the plugin enabled. You can create multiple instances of the same plugin.
The argument **ctx** represents the library context created by **flb\_create\(\)**, then **name** is the name of the input plugin that is required to enable.
92
+
The argument `ctx` represents the library context created by `flb_create()`, and `name` is the name of the input plugin to enable.
91
93
92
-
The third argument **data** can be used to pass a custom reference to the plugin instance, this is mostly used by custom or thirdparty plugins, for generic plugins passing _NULL_ is OK.
94
+
The argument `data` can be used to pass a custom reference to the plugin instance. This is mostly used by custom or third-party plugins. For generic plugins, it's okay to pass `NULL`.
93
95
94
-
**Return Value**
96
+
#### Return value
95
97
96
-
On success, **flb\_input\(\)** returns an integer value >= zero \(similar to a file descriptor\); on error, it returns a negative number.
98
+
On success, this function returns an integer value greater than or equal to zero, similar to a file descriptor. On error, it returns a negative number.
97
99
98
-
**Usage**
100
+
#### Usage
99
101
100
102
```c
101
103
int in_ffd;
102
104
103
105
in_ffd = flb_input(ctx, "cpu", NULL);
104
106
```
105
107
106
-
### Set Input Plugin Properties
108
+
### Set input plugin properties
107
109
108
-
A plugin instance created through **flb\_input\(\)**, may provide some configuration properties. Using the **flb\_input\_set\(\)** function is possible to set these properties.
110
+
A plugin instance created through `flb_input()` can include configuration properties. Use the `flb_input_set()` function to set these properties.
109
111
110
-
**Prototype**
112
+
#### Prototype
111
113
112
114
```c
113
115
intflb_input_set(flb_ctx_t *ctx, int in_ffd, ...);
114
116
```
115
117
116
-
**Return Value**
118
+
#### Return value
117
119
118
-
On success it returns 0; on error it returns a negative number.
120
+
On success, this function returns `0`. On error, it returns a negative number.
119
121
120
-
**Usage**
122
+
#### Usage
121
123
122
-
The **flb\_input\_set\(\)** allows to set one or more properties in a key/value string mode, e.g:
124
+
This function sets one or more properties as a key/value string. For example:
123
125
124
126
```c
125
127
int ret;
@@ -130,55 +132,57 @@ ret = flb_input_set(ctx, in_ffd,
130
132
NULL);
131
133
```
132
134
133
-
The argument **ctx** represents the library context created by **flb\_create\(\)**. The above example specified the values for the properties **tag** and **ssl**, note that the value is always a string \(char \*\) and once there is no more parameters a NULL argument must be added at the end of the list.
135
+
The argument `ctx` represents the library context created by `flb_create()`. The previous example specified the values for the properties `tag` and `ssl`. Its value is always a string (`char *`), and after all parameters are listed, you must add a `NULL` argument at the end of the list.
134
136
135
-
The properties allowed per input plugin are specified on each specific plugin documentation.
137
+
The properties allowed per input plugin are specified in the documentation for each plugin.
136
138
137
-
### Enable Output Plugin Instance
139
+
### Enable output plugin instance
138
140
139
-
When built, [Fluent Bit](http://fluentbit.io) library contains a certain number of built-in _output_plugins. In order to enable an _output_ plugin, the function **flb\_output**\(\) is used to create an instance of it.
141
+
The Fluent Bit library contains several output plugins. To enable an output plugin, use the `flb_output()` function to create an instance of it.
140
142
141
-
> For plugins, an _instance_ means a context of the plugin enabled. You can create multiples instances of the same plugin.
143
+
{% hint style="info" %}
144
+
For plugins, an _instance_ means a context of the plugin enabled. You can create multiple instances of the same plugin.
The argument **ctx** represents the library context created by **flb\_create\(\)**, then **name** is the name of the output plugin that is required to enable.
153
+
The argument `ctx` represents the library context created by `flb_create()`, and `name` is the name of the output plugin to enable.
150
154
151
-
The third argument **data** can be used to pass a custom reference to the plugin instance, this is mostly used by custom or thirdparty plugins, for generic plugins passing _NULL_ is OK.
155
+
The argument `data` can be used to pass a custom reference to the plugin instance. This is mostly used by custom or third-party plugins. For generic plugins, it's okay to pass `NULL`.
152
156
153
-
**Return Value**
157
+
#### Return value
154
158
155
-
On success, **flb\_output\(\)** returns the output plugin instance; on error, it returns a negative number.
159
+
On success, this function returns the output plugin instance. On error, it returns a negative number.
156
160
157
-
**Usage**
161
+
#### Usage
158
162
159
163
```c
160
164
int out_ffd;
161
165
162
166
out_ffd = flb_output(ctx, "stdout", NULL);
163
167
```
164
168
165
-
### Set Output Plugin Properties
169
+
### Set output plugin properties
166
170
167
-
A plugin instance created through **flb\_output\(\)**, may provide some configuration properties. Using the **flb\_output\_set\(\)** function is possible to set these properties.
171
+
A plugin instance created through `flb_output()` can include configuration properties. Use the `flb_output_set()` function to set these properties.
168
172
169
-
**Prototype**
173
+
#### Prototype
170
174
171
175
```c
172
176
intflb_output_set(flb_ctx_t *ctx, int out_ffd, ...);
173
177
```
174
178
175
-
**Return Value**
179
+
#### Return value
176
180
177
-
On success it returns an integer value >= zero \(similar to a file descriptor\); on error it returns a negative number.
181
+
On success, this function returns and integer value greater than or equal to zero, similar to a file descriptor. On error, it returns a negative number.
178
182
179
-
**Usage**
183
+
#### Usage
180
184
181
-
The **flb\_output\_set\(\)** allows to set one or more properties in a key/value string mode, e.g:
185
+
This function sets one or more properties as a key/value string. For example:
182
186
183
187
```c
184
188
int ret;
@@ -189,99 +193,98 @@ ret = flb_output_set(ctx, out_ffd,
189
193
NULL);
190
194
```
191
195
192
-
The argument **ctx** represents the library context created by **flb\_create\(\)**. The above example specified the values for the properties **tag** and **ssl**, note that the value is always a string \(char \*\) and once there is no more parameters a NULL argument must be added at the end of the list.
196
+
The argument `ctx` represents the library context created by `flb_create()`. The previous example specified the values for the properties `tag` and `ssl`. Its value is always a string (`char *`), and after all parameters are listed, you must add a `NULL` argument at the end of the list.
193
197
194
-
The properties allowed per output plugin are specified on each specific plugin documentation.
198
+
The properties allowed per output plugin are specified in the documentation for each plugin.
195
199
196
-
## Start Fluent Bit Engine
200
+
## Start Fluent Bit engine
197
201
198
-
Once the library context has been created and the input/output plugin instances are set, the next step is to start the engine. When started, the engine runs inside a new thread \(POSIX thread\) without blocking the caller application. To start the engine the function **flb\_start\(\)** is used.
202
+
After you create the library context and set input and output plugin instances, use the `flb_start()` function to start the engine. After the engine has started, it runs inside a new thread (POSIX thread) without blocking the caller application.
199
203
200
-
**Prototype**
204
+
### Prototype
201
205
202
206
```c
203
207
intflb_start(flb_ctx_t *ctx);
204
208
```
205
209
206
-
**Return Value**
210
+
### Return value
207
211
208
-
On success it returns 0; on error it returns a negative number.
212
+
On success, this function returns `0`. On error, it returns a negative number.
209
213
210
-
**Usage**
214
+
### Usage
211
215
212
-
This simple call only needs as argument **ctx** which is the reference to the context created at the beginning with **flb\_create\(\)**:
216
+
This function uses the `ctx` argument, which is a reference to the context created by `flb_create()`.
213
217
214
218
```c
215
219
int ret;
216
220
217
221
ret = flb_start(ctx);
218
222
```
219
223
220
-
## Stop Fluent Bit Engine
224
+
## Stop Fluent Bit engine
221
225
222
-
To stop a running Fluent Bit engine, we provide the call **flb\_stop\(\)** for that purpose.
226
+
To stop a running Fluent Bit engine, use `flb_stop()`.
223
227
224
-
**Prototype**
228
+
### Prototype
225
229
226
230
```c
227
231
intflb_stop(flb_ctx_t *ctx);
228
232
```
229
233
230
-
The argument **ctx** is a reference to the context created at the beginning with **flb\_create\(\)** and previously started with **flb\_start\(\)**.
234
+
The argument `ctx` is a reference to the context created by `flb_create()` and started by `flb_start()`.
231
235
232
-
When the call is invoked, the engine will wait a maximum of five seconds to flush buffers and release the resources in use. A stopped context can be re-started any time but without any data on it.
236
+
When the call is invoked, the engine waits a maximum of five seconds to flush buffers and release any resources in use. A stopped context can be restarted at any time, but without any data on it.
233
237
234
-
**Return Value**
238
+
### Return value
235
239
236
-
On success it returns 0; on error it returns a negative number.
240
+
On success, this function returns `0`. On error, it returns a negative number.
237
241
238
-
**Usage**
242
+
### Usage
239
243
240
244
```c
241
245
int ret;
242
246
243
247
ret = flb_stop(ctx);
244
248
```
245
249
246
-
## Destroy Library Context
250
+
## Destroy library context
247
251
248
-
A library context must be destroyed after is not longer necessary, note that a previous **flb\_stop\(\)** call is mandatory. When destroyed all resources associated are released.
252
+
You can destroy a library context after it's no longer necessary. A previous `flb_stop()` call is mandatory. After a library context is destroyed, all associated resources are released.
249
253
250
-
**Prototype**
254
+
### Prototype
251
255
252
256
```c
253
257
voidflb_destroy(flb_ctx_t *ctx);
254
258
```
255
259
256
-
The argument **ctx** is a reference to the context created at the beginning with **flb\_create\(\)**.
260
+
The argument `ctx` is a reference to the context created by `flb_create()`.
257
261
258
-
**Return Value**
262
+
### Return value
259
263
260
-
No return value.
264
+
This function doesn't return a value.
261
265
262
-
**Usage**
266
+
### Usage
263
267
264
268
```c
265
269
flb_destroy(ctx);
266
270
```
267
271
268
-
## Ingest Data Manually
272
+
## Ingest data manually
269
273
270
-
There are some cases where the caller application may want to ingest data into Fluent Bit, for this purpose exists the function **flb\_lib\_push\(\)**.
274
+
In some cases, the caller application might want to ingest data into Fluent Bit. You can use the `flb_lib_push()` function to do so.
271
275
272
-
**Prototype**
276
+
### Prototype
273
277
274
278
```c
275
279
intflb_lib_push(flb_ctx_t *ctx, int in_ffd, void *data, size_t len);
276
280
```
277
281
278
-
The first argument is the context created previously through **flb\_create\(\)**. **in\_ffd** is the numeric reference of the input plugin \(for this case it should be an input of plugin **lib** type\), **data** is a reference to the message to be ingested and **len** the number of bytes to take from it.
282
+
The first argument is the context created through `flb_create()`. The `in_ffd` argument is the numeric reference of the input plugin, which in this case is a `lib` input plugin. The `data` argument is a reference to the message to be ingested, and the `len` argument is the number of bytes to take from it.
279
283
280
-
**Return Value**
284
+
### Return value
281
285
282
-
On success, it returns the number of bytes written; on error it returns -1.
286
+
On success, this function returns the number of bytes written. On error, it returns `-1`.
283
287
284
-
**Usage**
285
-
286
-
For more details and an example about how to use this function properly please refer to the next section [Ingest Records Manually](ingest-records-manually.md).
288
+
### Usage
287
289
290
+
For more information about how to use this function, including examples, see [Ingest Records Manually](ingest-records-manually.md).
0 commit comments