Skip to content

Commit 66ffbe4

Browse files
edsiperedsiper
committed
agents: add initial AGENTS.md
Signed-off-by: Eduardo Silva <eduardo@chronosphere.io>
1 parent 36f8a9b commit 66ffbe4

1 file changed

Lines changed: 155 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
# Repository Guidelines
2+
3+
## Preferred Commands
4+
- Configure: `cmake -S . -B build -DFLB_TESTS_RUNTIME=On -DFLB_TESTS_INTERNAL=On`
5+
- Build: `cmake --build build -j8`
6+
- Test: `ctest --test-dir build --output-on-failure`
7+
- Prefer targeted tests with `ctest --test-dir build -R <name> --output-on-failure`
8+
when the affected area is known, because the full enabled suite can be slow.
9+
- Run a focused integration test with
10+
`ctest --test-dir build -R flb-it-opentelemetry --output-on-failure`
11+
- Run locally with `./build/bin/fluent-bit -c conf/fluent-bit.conf`
12+
13+
## Project Structure & Module Organization
14+
Fluent Bit is a C/C++ monorepo built with CMake.
15+
16+
- `src/`: core engine/runtime (`flb_*` components, schedulers, routing, I/O).
17+
- `include/fluent-bit/`: public/internal headers used by core and plugins.
18+
- `plugins/`: input/filter/processor/output plugins (`in_*`, `filter_*`, `processor_*`, `out_*`).
19+
- `lib/`: bundled libraries (e.g., `cprofiles`, `ctraces`, `cmetrics`, `chunkio`).
20+
- `tests/`: integration/runtime tests and fixtures.
21+
- `conf/`: sample configurations for local validation.
22+
23+
Keep changes scoped: plugin logic in its plugin directory, shared behavior in `src/` or `lib/`.
24+
25+
## Build, Test, and Development Commands
26+
- `cmake -S . -B build -DFLB_TESTS_RUNTIME=On -DFLB_TESTS_INTERNAL=On`: configure with runtime + internal tests.
27+
- `cmake --build build -j8`: compile Fluent Bit and tests.
28+
- `ctest --test-dir build --output-on-failure`: run enabled tests.
29+
- `ctest --test-dir build -R flb-it-opentelemetry --output-on-failure`: run a focused integration test.
30+
- `./build/bin/fluent-bit -c conf/fluent-bit.conf`: run locally with a config.
31+
32+
## Coding Style & Naming Conventions
33+
- Follow Apache-style C conventions used by Fluent Bit.
34+
- Use 4-space tabs/indentation and target 100 chars per line; 120 chars max.
35+
- Always use braces for `if/else/while/do` blocks.
36+
- Put function opening braces on the next line:
37+
`int fn(void)\n{ ... }`
38+
- Keep short boolean conditions on one line when they fit within 100 chars.
39+
- Wrap conditions only when needed, and break at logical operators (`&&`, `||`);
40+
do not force one operand per line when readability does not improve.
41+
- Keep short function calls on one line when they fit; avoid splitting each
42+
argument into separate lines unless line length or clarity requires it.
43+
- Declare variables at the start of functions, not mid-block.
44+
- Prefer descriptive `snake_case` for functions/variables and `flb_*`/`cprof_*` prefixes.
45+
- Use `/* ... */` comments (single or multiline), with wrapped long comments.
46+
47+
## Testing Guidelines
48+
- Add or update tests for behavior changes, especially protocol parsing and encoder/decoder paths.
49+
- Prefer targeted tests close to the changed module (`tests/internal`, plugin runtime tests).
50+
- Prefer focused `ctest -R ...` runs or specific test binaries when the touched area is known.
51+
- Run broader test coverage when changing shared lifecycle, routing, storage, or accounting code.
52+
- Validate both success and failure paths (invalid payloads, boundary sizes, null/missing fields).
53+
- You can also run specific binaries from `build/bin` (e.g., `./bin/flb-it-opentelemetry`).
54+
55+
## Commit & Pull Request Guidelines
56+
- Prefix commit subjects with the component/plugin name in lowercase, e.g.:
57+
- `engine: fix flush buffer handling`
58+
- `in_opentelemetry: profiles: fix ingestion path`
59+
- Keep subject/body lines <= 80 chars.
60+
- Keep each commit scoped to one component/prefix; avoid mixed-area commits.
61+
- Sign commits with DCO: `git commit -s`.
62+
- PRs should include: problem statement, scope, test evidence (`ctest` output), and compatibility notes.
63+
- If behavior changes user output/config, include a short before/after example.
64+
- Target `master` for next major by default; open backport PRs to release branches (`1.x`) when needed.
65+
66+
## Commit Pattern (Branch Practice)
67+
- Follow observed local history style:
68+
- component/plugin: `component: short imperative description`
69+
- internal tests: `tests: internal: short imperative description`
70+
- runtime tests: `tests: runtime: short imperative description`
71+
- Keep one interface per commit. If an interface touches both `.c` and `.h`,
72+
commit them together in the same commit.
73+
- Do not mix unrelated interfaces in one commit.
74+
- Prefer concise one-line subjects unless extra context is required.
75+
76+
## Agent Action Limits
77+
- Do not open issues, pull requests, or remote branches unless the user explicitly asks.
78+
- Do not rewrite git history, amend commits, or force-push unless the user explicitly asks.
79+
- Do not revert user changes outside the requested scope.
80+
- Prefer minimal patches that avoid unrelated formatting or refactoring churn.
81+
82+
## Agent Playbook (Pipeline Architecture Primer)
83+
84+
### Runtime model (mental map)
85+
- Fluent Bit moves data through: input -> chunk -> router -> task ->
86+
filter/processor -> output -> engine result handling.
87+
- Routing is per output instance; one chunk can fan out to many routes.
88+
- Route state is independent (success/retry/drop can differ per output).
89+
90+
### Data units and boundaries
91+
- A **signal** is the high-level type: logs, metrics, traces, profiles, blobs.
92+
- A **record/event** is the logical payload unit inside a signal.
93+
- A **chunk** is the persisted/queued container (often MessagePack-backed).
94+
- A **task** is the engine execution unit for a chunk across routes.
95+
- Never assume "one chunk = one route" or "one serialized event = one log
96+
record" in shared code.
97+
98+
### Component responsibilities
99+
- Inputs (`plugins/in_*`) create/append data and trigger ingestion.
100+
- Input chunk layer (`src/flb_input_chunk.c`) manages lifecycle, routing masks,
101+
storage pressure, and drop/release behavior.
102+
- Router (`src/flb_router*.c`) resolves tag/signal matches to outputs.
103+
- Task layer (`src/flb_task.c`) tracks per-route state and retries.
104+
- Filters (`plugins/filter_*`) run on matching streams before output flush.
105+
- Processors (`plugins/processor_*`) can run in input/output contexts depending
106+
on configuration and may mutate/drop payloads.
107+
- Outputs (`plugins/out_*`) serialize/protocol-encode and return flush result.
108+
- Engine (`src/flb_engine.c`) applies final retry/drop accounting and task
109+
teardown.
110+
111+
### Signal-aware behavior rules
112+
- Shared paths must branch correctly by `event_type` (logs vs non-logs).
113+
- Some logic is meaningful only for logs (record-level semantics), while
114+
metrics/traces/profiles/blobs may follow different serialization/counting.
115+
- Group/metadata markers can exist as serialized events; treat them as
116+
transport/data-shape artifacts unless the interface explicitly requires them.
117+
118+
### Counting and metrics guidance
119+
- Separate these concepts when reviewing code:
120+
- serialized events in a buffer
121+
- logical records after processing
122+
- per-route processed/retry/drop counters
123+
- byte accounting (chunk bytes vs route-effective bytes)
124+
- Prefer route-aware values when updating route metrics.
125+
- Preserve explicit zero values; use clear sentinel values for "unknown".
126+
127+
### Retry/drop semantics
128+
- `FLB_OK`: route succeeded.
129+
- `FLB_RETRY`: route keeps task/chunk for retry scheduling.
130+
- `FLB_ERROR`: route failure/drop path.
131+
- Final chunk release happens only when all active routes are resolved.
132+
133+
### Storage/backlog interaction
134+
- In-memory and filesystem backlog paths may use different code paths; validate
135+
both when touching chunk/task lifecycle.
136+
- Backlog-loaded chunks must preserve route state and accounting parity with
137+
live-ingested chunks.
138+
139+
### Review checklist before patching
140+
- Trace one full path for affected signals: input -> chunk -> task -> output ->
141+
engine completion.
142+
- Verify fan-out behavior (single chunk, multiple outputs).
143+
- Verify processing behavior (drop/modify/no-op) in both input and output
144+
processor contexts.
145+
- Verify empty payload behavior (outputs should not crash on zero records).
146+
- Verify metrics/counters for success, retry, and drop paths.
147+
148+
### Testing strategy
149+
- Use `tests/internal` for core lifecycle/accounting logic.
150+
- Use `tests/runtime` for plugin-level behavior and end-to-end semantics.
151+
- Add regression tests for:
152+
- mixed signals
153+
- processor drop/modify paths
154+
- multi-route fan-out
155+
- backlog + live ingestion parity

0 commit comments

Comments
 (0)