# Library API

[Fluent Bit](http://fluentbit.io) library it's written in C language and can be used from any C or C++ application. Before to digging into the specification is recommended to understand the workflow involved in the runtime.

## Workflow

[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:

* Create library instance/context and set properties.
* Enable *input* plugin(s) and set properties.
* Enable *output* plugin(s) and set properties.
* Start the library runtime.
* Optionally ingest records manually.
* Stop the library runtime.
* Destroy library instance/context.

## Data Types

Starting from Fluent Bit v0.9, there is only one data type exposed by the library, by convention prefixed with **flb\_**.

| Type        | Description                                                                         |
| ----------- | ----------------------------------------------------------------------------------- |
| flb\_ctx\_t | Main library context. It aims to reference the context returned by *flb\_create();* |

## API Reference

### Library Context Creation

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.

**Prototype**

```c
flb_ctx_t *flb_create();
```

**Return Value**

On success, **flb\_create()** returns the library context; on error, it returns NULL.

**Usage**

```c
flb_ctx_t *ctx;

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

### Set Service Properties

Using the **flb\_service\_set()** function is possible to set context properties.

**Prototype**

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

**Return Value**

On success it returns 0; on error it returns a negative number.

**Usage**

The **flb\_service\_set()** allows to set one or more properties in a key/value string mode, e.g:

```c
int ret;

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

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.

### Enable Input Plugin Instance

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.

> For plugins, an *instance* means a context of the plugin enabled. You can create multiples instances of the same plugin.

**Prototype**

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

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.

The third 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 passing *NULL* is OK.

**Return Value**

On success, **flb\_input()** returns an integer value >= zero (similar to a file descriptor); on error, it returns a negative number.

**Usage**

```c
int in_ffd;

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

### Set Input Plugin Properties

A plugin instance created through **flb\_input()**, may provide some configuration properties. Using the **flb\_input\_set()** function is possible to set these properties.

**Prototype**

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

**Return Value**

On success it returns 0; on error it returns a negative number.

**Usage**

The **flb\_input\_set()** allows to set one or more properties in a key/value string mode, e.g:

```c
int ret;

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

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.

The properties allowed per input plugin are specified on each specific plugin documentation.

### Enable Output Plugin Instance

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.

> For plugins, an *instance* means a context of the plugin enabled. You can create multiples instances of the same plugin.

**Prototype**

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

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.

The third 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 passing *NULL* is OK.

**Return Value**

On success, **flb\_output()** returns the output plugin instance; on error, it returns a negative number.

**Usage**

```c
int out_ffd;

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

### Set Output Plugin Properties

A plugin instance created through **flb\_output()**, may provide some configuration properties. Using the **flb\_output\_set()** function is possible to set these properties.

**Prototype**

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

**Return Value**

On success it returns an integer value >= zero (similar to a file descriptor); on error it returns a negative number.

**Usage**

The **flb\_output\_set()** allows to set one or more properties in a key/value string mode, e.g:

```c
int ret;

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

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.

The properties allowed per output plugin are specified on each specific plugin documentation.

## Start Fluent Bit Engine

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.

**Prototype**

```c
int flb_start(flb_ctx_t *ctx);
```

**Return Value**

On success it returns 0; on error it returns a negative number.

**Usage**

This simple call only needs as argument **ctx** which is the reference to the context created at the beginning with **flb\_create()**:

```c
int ret;

ret = flb_start(ctx);
```

## Stop Fluent Bit Engine

To stop a running Fluent Bit engine, we provide the call **flb\_stop()** for that purpose.

**Prototype**

```c
int flb_stop(flb_ctx_t *ctx);
```

The argument **ctx** is a reference to the context created at the beginning with **flb\_create()** and previously started with **flb\_start()**.

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.

**Return Value**

On success it returns 0; on error it returns a negative number.

**Usage**

```c
int ret;

ret = flb_stop(ctx);
```

## Destroy Library Context

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.

**Prototype**

```c
void flb_destroy(flb_ctx_t *ctx);
```

The argument **ctx** is a reference to the context created at the beginning with **flb\_create()**.

**Return Value**

No return value.

**Usage**

```c
flb_destroy(ctx);
```

## Ingest Data Manually

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()**.

**Prototype**

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

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.

**Return Value**

On success, it returns the number of bytes written; on error it returns -1.

**Usage**

For more details and an example about how to use this function properly please refer to the next section [Ingest Records Manually](https://docs.fluentbit.io/manual/1.0/development/ingest_records_manually).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.fluentbit.io/manual/1.0/development/library_api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.