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
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+53-15Lines changed: 53 additions & 15 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,7 +5,7 @@
5
5
6
6
First of all, thanks for taking the time to read this guide. The fact that you're here means you're interested in contributing to Fluent Bit, and we greatly appreciate your time.
7
7
8
-
This repository contains the files for the [Fluent Bit documentation library](https://docs.fluentbit.io/). Keeping these docs separate from the [main Fluent Bit repository](https://github.com/fluent/fluent-bit) helps reduce the number of commits to the Fluent Bit source code and makes it easier to maintain both projects.
8
+
This repository contains the files for the [Fluent Bit documentation library](https://docs.fluentbit.io/manual/). Keeping these docs separate from the [main Fluent Bit repository](https://github.com/fluent/fluent-bit) helps reduce the number of commits to the Fluent Bit source code and makes it easier to maintain both projects.
9
9
10
10
Fluent Bit has a group of dedicated maintainers who oversee this repository, including several technical writers. These writers will review any pull requests you open, so don't be afraid to contribute, even if you're not a writer by trade. Your suggestions are valuable, and we'll help you wrangle any stray commas.
11
11
@@ -15,7 +15,6 @@ Before you contribute to the Fluent Bit docs, review these critical tips:
15
15
16
16
-[Sign off](#sign-off-your-git-commits) your Git commits.
17
17
- Use [soft line wraps](#line-wraps) in Markdown files.
18
-
- To link between pages, use [absolute file paths](#links).
19
18
- Review the results of [linters](#linters) for style and formatting guidance.
20
19
21
20
## Review process
@@ -67,15 +66,7 @@ The active [linters](#linters) in this repository flag certain style errors and,
67
66
68
67
## Formatting guidelines
69
68
70
-
The Fluent Bit docs library is built and hosted through [GitBook](https://docs.gitbook.com/). Unfortunately, GitBook doesn't support local previews for contributors, but a Fluent Bit maintainer with a dedicated GitBook account can verify that things are formatted correctly after you open a new pull request.
71
-
72
-
### Links
73
-
74
-
When cross-linking between in this repository, use a full absolute path whenever possible. For example:
75
-
76
-
```text
77
-
[LTSV](../pipeline/parsers/ltsv.md) and [Logfmt](../pipeline/parsers/logfmt.md)
78
-
```
69
+
The Fluent Bit docs library is built and hosted through [GitBook](https://gitbook.com/docs/). Unfortunately, GitBook doesn't support local previews for contributors, but a Fluent Bit maintainer with a dedicated GitBook account can verify that things are formatted correctly after you open a new pull request.
79
70
80
71
### Line wraps
81
72
@@ -119,24 +110,71 @@ When you create a new `.md` file for a new page, you must add an entry to this r
119
110
120
111
Similarly, if you update the `# h1` title header of an existing page, be sure to update that page's `SUMMARY.md` entry to match. `SUMMARY.md` entries takes precedence over in-page headers, which means that if you update a page's `# h1` title without updating `SUMMARY.md`, the unchanged `SUMMARY.md` title will persist in both the rendered page and the table of contents.
121
112
113
+
## Plugin documentation
114
+
115
+
When documenting a Fluent Bit plugin, follow these standards to keep plugin pages consistent.
116
+
117
+
### Configuration parameters table
118
+
119
+
-**Sort parameters alphabetically** by key name.
120
+
-**List all parameters** defined in the plugin's `config_map`, plus the common `workers` parameter.
121
+
-**Use `_none_` in the Default cell** when the parameter's default is `NULL` in the source `config_map`. Leave the cell empty only when the parameter has no entry in `config_map` at all (for example, `host` and `port`, which come from the network defaults).
122
+
- Use this table header format:
123
+
124
+
```markdown
125
+
| Key | Description | Default |
126
+
| --- | ----------- | ------- |
127
+
```
128
+
129
+
### Configuration examples
130
+
131
+
Every plugin page should include both a YAML and a classic configuration example, presented as tabs:
132
+
133
+
```markdown
134
+
{% tabs %}
135
+
{% tab title="fluent-bit.yaml" %}
136
+
...
137
+
{% endtab %}
138
+
{% tab title="fluent-bit.conf" %}
139
+
...
140
+
{% endtab %}
141
+
{% endtabs %}
142
+
```
143
+
144
+
### Key casing in examples
145
+
146
+
Key casing differs between the two configuration formats:
147
+
148
+
-**YAML** (`fluent-bit.yaml`): All keys are lowercase. For example: `api_key`, `log_level`, `match`.
149
+
-**Classic** (`fluent-bit.conf`): Keys use Title_Case — capitalize the first letter of every underscore-separated word. For example: `Api_Key`, `Log_Level`, `Match`.
150
+
151
+
| YAML key | Classic key |
152
+
| --- | --- |
153
+
|`api_key`|`Api_Key`|
154
+
|`log_group_name`|`Log_Group_Name`|
155
+
|`match`|`Match`|
156
+
|`name`|`Name`|
157
+
158
+
This applies to all keys in every section (`[SERVICE]`, `[INPUT]`, `[OUTPUT]`, and so on).
159
+
122
160
## Linters
123
161
124
162
This repository runs linters as GitHub Actions for each pull request. If a linter finds errors or makes suggested changes, you can view these results in the **Files changed** tab.
125
163
126
164
<details>
127
165
<summary>:mag: Examples: linter results</summary>
128
166
129
-
167
+
130
168
131
-
169
+
132
170
133
-
171
+
134
172
135
173
</details>
136
174
137
175
### Vale
138
176
139
-
[Vale](https://vale.sh/docs/) lints prose for style and clarity. In addition to reviewing the results of each Vale test in GitHub, you can use the [Vale plugin for VSCode](https://marketplace.visualstudio.com/items?itemName=ChrisChinchilla.vale-vscode) to view errors and suggestions locally.
177
+
[Vale](https://vale.sh/docs) lints prose for style and clarity. In addition to reviewing the results of each Vale test in GitHub, you can use the [Vale plugin for VSCode](https://marketplace.visualstudio.com/items?itemName=ChrisChinchilla.vale-vscode) to view errors and suggestions locally.
140
178
141
179
Vale tests for the Fluent Bit docs are stored in the [`/vale-styles`](https://github.com/fluent/fluent-bit-docs/tree/master/vale-styles) folder. Most Vale tests are at the `suggestion` or `warning` level and won't block pull requests from merging. However, tests at the `error` level will block merging until the associated issue is fixed.
[Fluent Bit](http://fluentbit.io) is a fast and lightweight telemetry agent for logs, metrics, and traces for Linux, macOS, Windows, and BSD family operating systems. Fluent Bit has been made with a strong focus on performance to allow the collection and processing of telemetry data from different sources without complexity.
9
+
[Fluent Bit](https://fluentbit.io) is a fast and lightweight telemetry agent for logs, metrics, and traces for Linux, macOS, Windows, and BSD family operating systems. Fluent Bit has been made with a strong focus on performance to allow the collection and processing of telemetry data from different sources without complexity.
10
10
11
11
## Features
12
12
@@ -16,7 +16,7 @@ description: High Performance Telemetry Agent for Logs, Metrics and Traces
16
16
- Metrics support: Prometheus and OpenTelemetry compatible
-[Data buffering](administration/buffering-and-storage.md) in memory and file system
19
+
-[Data buffering](./pipeline/buffering.md) in memory and file system
20
20
- Networking
21
21
- Security: Built-in TLS/SSL support
22
22
- Asynchronous I/O
@@ -27,7 +27,7 @@ description: High Performance Telemetry Agent for Logs, Metrics and Traces
27
27
- Wasm: [Wasm Filter Plugins](development/wasm-filter-plugins.md) or [Wasm Input Plugins](development/wasm-input-plugins.md)
28
28
- Write [Filters in Lua](pipeline/filters/lua.md) or [Output plugins in Golang](development/golang-output-plugins.md)
29
29
-[Monitoring](administration/monitoring.md): Expose internal metrics over HTTP in JSON and [Prometheus](https://prometheus.io/) format
30
-
-[Stream Processing](stream-processing/introduction.md): Perform data selection and transformation using basic SQL queries
30
+
-[Stream Processing](stream-processing/overview.md): Perform data selection and transformation using basic SQL queries
31
31
- Create new streams of data using query results
32
32
- Aggregation windows
33
33
- Data analysis and prediction: Time series forecasting
@@ -37,8 +37,14 @@ description: High Performance Telemetry Agent for Logs, Metrics and Traces
37
37
38
38
For more details about changes in each release, refer to the [official release notes](https://fluentbit.io/announcements/).
39
39
40
+
If you are upgrading from the Fluent Bit `4.2` series, start with [What's new in Fluent Bit v5.0](installation/whats-new-in-fluent-bit-v5.0.md) and [Upgrade notes](installation/upgrade-notes.md).
41
+
40
42
## Fluent Bit, Fluentd, and CNCF
41
43
42
-
[Fluent Bit](http://fluentbit.io) is a [CNCF](https://cncf.io) graduated sub-project under the umbrella of [Fluentd](http://fluentd.org). Fluent Bit is licensed under the terms of the [Apache License v2.0](http://www.apache.org/licenses/LICENSE-2.0).
44
+
Fluent Bit is a [CNCF](https://www.cncf.io/) graduated sub-project under the umbrella of [Fluentd](https://www.fluentd.org).
43
45
44
46
Fluent Bit was originally created by [Eduardo Silva](https://www.linkedin.com/in/edsiper/) and is now sponsored by [Chronosphere](https://chronosphere.io/). As a CNCF-hosted project, it's a fully vendor-neutral and community-driven project.
47
+
48
+
## License
49
+
50
+
Fluent Bit, including its core, plugins, and tools, is distributed under the terms of the [Apache License v2.0](https://github.com/fluent/fluent-bit?tab=Apache-2.0-1-ov-file#readme).
0 commit comments