rsyslog/rsyslog
1
0
Fork 0
mirror of https://github.com/rsyslog/rsyslog.git synced 2026-08-19 19:47:49 +02:00
Code Issues Packages Projects Releases Wiki Activity

core: streamline agent instructions with modular skills

Browse Source 
Modernize the rsyslog contribution workflow for AI agents to
improve policy compliance and reduce instruction verbosity.

Impact: Repository-wide reduction in AGENTS.md bloat.

Before: Fragmented and redundant procedural instructions in AGENTS.md.
After: Modular skills in .agent/skills/ with streamlined subtree guides.

This change encapsulates build, test, documentation, module authoring,
and commit policies into reusable skills. It introduces:
- A specialized AI memory lifecycle auditor.
- A boilerplate snippets library.
- The 'rsyslog_doc_dist' skill for doc/Makefile.am synchronization.
- YAML frontmatter 'triggers' for automatic skill activation.

The workflow is further optimized to skip redundant builds after stylistc
code formatting, ensuring faster iteration for AI-led development.

AI-Agent: Antigravity 2026-01
This commit is contained in:
Rainer Gerhards 2026-01-23 13:01:37 +01:00
parent 0c51bc3dde
commit 2f4ebd9a99
17 changed files with 530 additions and 788 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

49
.agent/skills/rsyslog_build/SKILL.md Normal file
View File

@ -0,0 +1,49 @@
---
name: rsyslog_build
description: Handles environment setup and high-performance incremental building for rsyslog.
---
# rsyslog_build
This skill standardizes the environment setup and build process for the rsyslog project. It ensures that agents use the most efficient build commands and handle bootstrap logic correctly.
## Quick Start
1. **Setup Environment**: Run `.agent/skills/rsyslog_build/scripts/setup.sh` to install dependencies.
2. **Efficient Build**: Use `make -j$(nproc) check TESTS=""` for incremental builds.
3. **Bootstrap**: Use `./autogen.sh --enable-debug [options]` if `Makefile` is missing or build configuration changes.
## Detailed Instructions
### 1. Environment Setup
The project requires a set of development libraries (C toolchain, libcurl, libfastjson, etc.).
- Use the provided script: `bash .agent/skills/rsyslog_build/scripts/setup.sh`
- This script wraps `devtools/codex-setup.sh` and ensures all CI-standard tools are present.
### 2. Bootstrapping (autogen.sh)
You MUST run `./autogen.sh` in the following cases:
- After a fresh checkout (no `Makefile` exists).
- If you modify `configure.ac`, any `Makefile.am`, or files under `m4/`.
- If you need to enable/disable specific modules (e.g., `--enable-imkafka`).
**Example**:
```bash
./autogen.sh --enable-debug --enable-testbench --enable-imdiag --enable-omstdout
```
### 3. High-Performance Build
Always prefer the incremental build-only command. It builds the core and all test dependencies without the overhead of running the full test suite.
**Command**:
```bash
make -j$(nproc) check TESTS=""
```
### 4. Runtime & Library Considerations
When modifying `runtime/` or exported symbols:
- Ensure the library version script (if touched) is consistent.
- Incremental builds handle `-M../runtime/.libs` correctly for dynamic loading.
## Related Skills
- `rsyslog_test`: For running validations after a successful build.
- `rsyslog_module`: For module-specific build flags.

20
.agent/skills/rsyslog_build/scripts/build.sh Executable file
View File

@ -0,0 +1,20 @@
#!/bin/bash
# .agent/skills/rsyslog_build/scripts/build.sh
# Efficient incremental build for rsyslog.
set -e
REPO_ROOT=$(git rev-parse --show-toplevel)
cd "$REPO_ROOT"
# 1. Auto-bootstrap if needed
if [ ! -f "Makefile" ]; then
echo ">>> Makefile missing. Bootstrapping..."
./autogen.sh --enable-debug --enable-testbench --enable-imdiag --enable-omstdout --enable-mmsnareparse --enable-omotel --enable-imhttp
fi
# 2. Run incremental build
echo ">>> Running incremental build (make -j$(nproc) check TESTS=\"\")..."
make -j$(nproc) check TESTS=""
echo ">>> Build successful."

28
.agent/skills/rsyslog_build/scripts/setup.sh Executable file
View File

@ -0,0 +1,28 @@
#!/bin/bash
# .agent/skills/rsyslog_build/scripts/setup.sh
# Standard environment setup for rsyslog agents.
set -e
REPO_ROOT=$(git rev-parse --show-toplevel)
echo ">>> Setting up rsyslog development environment..."
# 1. Run the official setup script if it exists
if [ -f "$REPO_ROOT/devtools/codex-setup.sh" ]; then
echo ">>> Running devtools/codex-setup.sh..."
bash "$REPO_ROOT/devtools/codex-setup.sh"
else
echo ">>> WARNING: devtools/codex-setup.sh not found. Ensure dependencies are installed manually."
echo ">>> Required: autoconf, automake, libtool, bison, flex, libcurl-dev, libfastjson-dev, etc."
fi
# 2. Check for critical tools
for tool in autoconf automake libtool bison flex; do
if ! command -v $tool >/dev/null 2>&1; then
echo ">>> ERROR: Required tool '$tool' is missing."
exit 1
fi
done
echo ">>> Setup complete."

46
.agent/skills/rsyslog_commit/SKILL.md Normal file
View File

@ -0,0 +1,46 @@
---
name: rsyslog_commit
description: Ensures compliance with rsyslog's strict commit message and branching policies.
---
# rsyslog_commit
This skill standardizes the final step of the development workflow: committing and contributing.
## Quick Start
1. **Format First**: Run `devtools/format-code.sh`.
2. **Commit Message**: Follow the 62/72 rule and the mandatory "Why" structure.
3. **Attribution**: Include the AI-Agent footer.
## Detailed Instructions
### 1. Pre-Commit Checklist
- **Code Style**: Run `bash devtools/format-code.sh`. This is mandatory.
- **Validation**: Ensure `make -j$(nproc) check TESTS=""` passes and relevant tests are run.
- **Note**: If you already successfully built and tested your changes immediately *before* formatting, you do NOT need to re-run the build/test cycle. Formatting is a normalization step and does not affect functionality.
### 2. Commit Message Structure
Rsyslog requires rich, structured commit messages (plain ASCII).
- **Title**: `<component>: <action>` (Max 62 characters).
- **Body**: Max 72 characters per line.
- **GitHub Issues**: Use **full URLs** (e.g., `https://github.com/rsyslog/rsyslog/issues/883`) instead of shorthand `#883`.
- **Mandatory Sections**:
- **Why**: Brief non-technical rationale.
- **Impact**: One line if behavior/tests changed.
- **Before/After**: One-line summary.
- **Technical Overview**: 4–12 lines describing the change conceptually.
- **AI Footer**: `With the help of AI-Agents: <agent-name>`
### 3. Using the Assistant
- **Offline/Agents**: Use the base prompt at `ai/rsyslog_commit_assistant/base_prompt.txt`.
- **Web**: [rsyslog.com/tool_rsyslog-commit-assistant](https://www.rsyslog.com/tool_rsyslog-commit-assistant)
### 4. Branching & PRs
- **Base Branch**: Always target `main`.
- **Naming**: `i-<issue-number>` or `<agent-name>-i-<issue-number>`.
- **Target**: PRs must target `rsyslog/rsyslog` directly.
## Related Skills
- `rsyslog_build`: To verify the code before committing.
- `rsyslog_test`: To provide validation metrics for the commit message.

59
.agent/skills/rsyslog_doc/SKILL.md Normal file
View File

@ -0,0 +1,59 @@
name: rsyslog_doc
description: Guidelines for maintaining structured, RAG-optimized documentation and module metadata.
triggers:
- doc/source/**/*.rst
---
# rsyslog_doc
This skill ensures that all documentation is consistent, discoverable, and optimized for both human readers and AI ingestion systems.
## Quick Start
1. **Metadata Block**: Every `.rst` must have a `.. meta::` block.
2. **Summary Slices**: Wrap intros in `.. summary-start` and `.. summary-end`.
3. **Cross-Link**: Update `index.rst` and `doc/ai/module_map.yaml`.
## Detailed Instructions
### 1. Structured Requirements
Every documentation page must include:
- **Meta Block**:
```rst
.. meta::
:description: Brief description for SEO and RAG.
:keywords: rsyslog, module, config, ...
```
- **Summary Slices**: Essential for RAG (Retrieval-Augmented Generation).
```rst
.. summary-start
Concise summary of what this module/feature does.
.. summary-end
```
---
> [!IMPORTANT]
> **Trigger Side-Effect**: If you add, move, or remove any `.rst` file, YOU MUST follow the [`rsyslog_doc_dist`](../rsyslog_doc_dist/SKILL.md) skill to update `doc/Makefile.am`.
### 2. Module Documentation
- **Parameters**: Use the `include` directive to pull parameter details from `doc/source/reference/parameters/`.
- **Anchors**: Use explicit anchors (e.g., `.. _parameter_name:`) for consistent linking.
- **Templates**: Reference `doc/ai/templates/template-module.rst`.
### 3. Metadata Files
- **Plugins/Contrib**: Maintain `MODULE_METADATA.yaml` in the module directory.
- **Built-in Tools**: Update `tools/MODULE_METADATA.json`.
- **Required Keys**: `support_status`, `maturity_level`, `primary_contact`, `last_reviewed`.
### 4. Validation
- **Build Docs**: Run `./doc/tools/build-doc-linux.sh --clean --format html`.
- **json-formatter**: Run `make -j16 json-formatter` to update the RAG knowledge base.
- **Mermaid**: Ensure Mermaid diagrams have a blank line after the directive and quoted labels.
### 5. Style & Tone
- Follow the **Doc Assistant Prompt**: `ai/rsyslog_doc_assistant/base_prompt.txt`.
- Use canonical terminology from `doc/ai/terminology.md`.
## Related Skills
- `rsyslog_module`: For technical details to include in docs.
- `rsyslog_commit`: For doc-only commit message rules.

43
.agent/skills/rsyslog_doc_dist/SKILL.md Normal file
View File

@ -0,0 +1,43 @@
---
name: rsyslog_doc_dist
description: Ensures doc/Makefile.am stays in sync with changes to documentation files.
triggers:
- doc/source/**/*.rst
condition: "on create, move, or delete" # Do not trigger for content-only edits
---
# rsyslog_doc_dist
This skill ensures that all documentation files are correctly registered for distribution in the build system.
## Quick Start
1. **Add File**: If you add a `*.rst` file in `doc/source/`, add it to `EXTRA_DIST` in `doc/Makefile.am`.
2. **Move/Rename**: If you move or rename a file, update the corresponding path in `doc/Makefile.am`.
3. **Remove**: If you delete a file, remove its entry from `doc/Makefile.am`.
## Detailed Instructions
### 1. The EXTRA_DIST Guard
The rsyslog distribution tarball is created using `make dist`. For documentation to be included, every source file must be listed in the `EXTRA_DIST` variable within `doc/Makefile.am`.
### 2. Synchronization Rule
Whenever you perform a filesystem operation on documentation:
- **Addition**: Insert the new path (relative to `doc/`) into the `EXTRA_DIST` list. Try to maintain the existing logical grouping (e.g., `source/configuration/modules/`).
- **Renaming/Moving**: Locate the old path in `doc/Makefile.am` and replace it with the new one.
- **Deletion**: Locate and remove the entry to avoid build failures during `make dist`.
### 3. Verification
You can verify synchronization by checking if the number of `.rst` files in `doc/source` matches the count in `doc/Makefile.am` (adjusting for non-rst files in `EXTRA_DIST`).
**Command to find unregistered files**:
```bash
# Run from the doc/ directory
find source -name "*.rst" | sort > /tmp/rst_files
grep "source/.*\.rst" Makefile.am | sed 's/^[ \t]*//;s/[ \t]*\\$//' | sort > /tmp/makefile_files
diff /tmp/rst_files /tmp/makefile_files
```
## Related Skills
- `rsyslog_doc`: For documentation content and metadata standards.
- `rsyslog_build`: For verifying that the build system (including `Makefile.am`) is still functional after changes.

49
.agent/skills/rsyslog_module/SKILL.md Normal file
View File

@ -0,0 +1,49 @@
---
name: rsyslog_module
description: Encodes technical requirements for rsyslog modules, including concurrency, metadata, and initialization.
---
# rsyslog_module
This skill captures the essential technical patterns for authoring and maintaining rsyslog modules (plugins/contrib).
## Quick Start
1. **Locking**: Follow the "Belt and Suspenders" rule (`assert()` + `if`).
2. **State**: `pData` (shared) vs `WID` (per-worker).
3. **Boilerplate**: Use `BEGINmodInit`, `CODESTARTmodInit`, etc.
- *Resource*: See [Common Snippets](./resources/snippets.md) for boilerplate code.
## Detailed Instructions
### 1. Concurrency & Locking
Rsyslog v8 has a high-concurrency worker model.
- **Shared State (`pData`)**: Mutable state shared across workers MUST be protected by a mutex in `pData`.
- **Per-Worker State (`WID`)**: Never share `wrkrInstanceData_t`.
- **Belt and Suspenders**:
```c
assert(pData != NULL);
if (pData == NULL) {
// Handle error gracefully
}
```
- **Headers**: Every output module should have a "Concurrency & Locking" header block.
### 2. Module Lifecycle
Every module must implement and register standard entry points:
- `modInit()`: Initialize static data and registry interfaces.
- `modExit()`: Finalize and cleanup.
- `beginTransaction()` / `commitTransaction()`: For efficient batch-based output.
### 3. Metadata Consistency
- **Location**: `MODULE_METADATA.yaml` in the module directory.
- **Synchronization**: Keep `doc/ai/module_map.yaml` in sync with locking and concurrency changes.
### 4. Build Configuration
- Update `plugins/Makefile.am` and `configure.ac` when adding new modules.
- Use `MODULE_TYPE(eMOD_OUT)` and other macros from `runtime/module-template.h`.
## Related Skills
- `rsyslog_build`: For compiling the module.
- `rsyslog_test`: For creating module-specific smoke tests.
- `rsyslog_doc`: For documentation requirements.

66
.agent/skills/rsyslog_module/resources/snippets.md Normal file
View File

@ -0,0 +1,66 @@
# rsyslog Module Snippets
Use these common boilerplate patterns to accelerate module development and ensure consistency with the v8 worker model.
## 1. Concurrency & Locking Header
Place this at the top of your module file (e.g., `ommodule.c`) to signal locking intention to AI agents and maintainers.
```c
/* Concurrency & Locking Checklist:
* - pData (per-action) is shared across workers.
* - Mutable state in pData MUST be guarded by a mutex.
* - WID (wrkrInstanceData_t) is per-worker; no locking needed for WID internal state.
* - Always use the "Belt and Suspenders" rule: assert(ptr != NULL); if(ptr == NULL)...
*/
```
## 2. Mandatory Entry Points (modInit)
Modularize global initialization.
```c
BEGINmodInit
CODESTARTmodInit
*ipIFVersProvided = CURR_MOD_IF_VERSION; /* 2.2.1 is current */
CODEOKORPFAILmodInit
```
## 3. Transaction Skeletons (Output Modules)
For high-performance batching.
```c
/* Preferred Transaction Pattern */
static rsRetVal
beginTransaction(void *pWID) {
DEFiRet;
// Setup batch buffer or remote connection
RETiRet;
}
static rsRetVal
commitTransaction(void *pWID) {
DEFiRet;
// Flush batch, handle remote acknowledgement
RETiRet;
}
```
## 4. Parameter Definition
Using the modern `rsconf` interface.
```c
static struct c_option pblk[] = {
{ "server", eCmdHdlrGetWord, 0 },
{ "port", eCmdHdlrInt, 0 },
{ "template", eCmdHdlrGetWord, 0 }
};
```
## 5. Metadata Template (MODULE_METADATA.yaml)
Every module directory MUST contain this.
```yaml
support_status: code-supported
maturity_level: fully-mature
primary_contact: "rsyslog mailing list <https://lists.adiscon.net/mailman/listinfo/rsyslog>"
last_reviewed: 2026-01-23
```

52
.agent/skills/rsyslog_test/SKILL.md Normal file
View File

@ -0,0 +1,52 @@
---
name: rsyslog_test
description: Standardizes testing and validation for rsyslog using the diag.sh framework.
---
# rsyslog_test
This skill provides guidelines and tools for running tests efficiently. It emphasizes direct test script execution to avoid the overhead and opacity of the full `make check` harness.
## Quick Start
1. **Build First**: Ensure the project is built (use `rsyslog_build`).
2. **Run Specific Test**: `./tests/<test-name>.sh`
3. **Run with Valgrind**: `./tests/<test-name>-vg.sh`
## Detailed Instructions
### 1. Direct Execution Rule
**NEVER** use `make check` during routine development. It is slow (runs 1000+ tests) and hides failure details.
- **Rule**: Run individual shell scripts directly from the `tests/` directory.
- **Benefit**: Immediate feedback and visible stdout/stderr.
### 2. Using diag.sh Helpers
All tests source `tests/diag.sh`. You should use its standardized helpers:
- `cmp_exact`: Verify file content matches.
- `require_plugin`: Skip test if a module is not built.
- `command_deny`: Ensure a specific command fails.
### 3. Valgrind Testing
For memory leak and race condition detection:
- Use scripts ending in `-vg.sh`.
- These are wrappers that set `USE_VALGRIND=1` and source the base test.
### 4. Debugging Failed Tests
If a test fails, you can inspect logs by:
- Enabling debug: Uncomment `RSYSLOG_DEBUG` exports in `tests/diag.sh`.
- Disabling cleanup: Comment out `exit_test` at the end of the script.
- Output files: Look for `rstb_*.out.log` and `log`.
### 5. Integration Test Policy
Certain modules (Kafka, Elasticsearch, Journald) have heavy integration tests requiring external services.
- **Policy**: Skip these in restricted environments (like AI sandboxes) unless build-only validation is insufficient.
- Check module-specific `AGENTS.md` or `MODULE_METADATA.yaml`.
### 6. Memory Lifecycle Validation (Mental Audit)
Before committing C changes, agents SHOULD perform a self-audit of memory ownership and lifecycle.
- **Rule**: Use the [Memory Lifecycle Prompt](../../ai/rsyslog_memory_auditor/base_prompt.txt) to review your diff.
- **Focus**: Pay special attention to `RS_RET` error paths and `strdup` calls in configuration parsing.
## Related Skills
- `rsyslog_build`: Required before running tests.
- `rsyslog_module`: Documentation on module-specific test dependencies.

643
AGENTS.md
View File

@ -1,619 +1,54 @@
# AGENTS.md – rsyslog Repository Agent Guide
This file defines guidelines and instructions for AI assistants (e.g., Codex, GitHub Copilot Workspace, ChatGPT agents) to understand and contribute effectively to the rsyslog codebase.
This file defines the high-level roadmap for AI assistants to understand and contribute to the rsyslog codebase. Technical workflows are now modularized into **Skills**.
## AI Agent Skills
To ensure consistency and high-quality contributions, AI agents SHOULD use the following standardized skills located in `.agent/skills/`:
| Skill | Purpose |
|-------|---------|
| [`rsyslog_build`](.agent/skills/rsyslog_build/SKILL.md) | Environment setup and incremental parallel builds. |
| [`rsyslog_test`](.agent/skills/rsyslog_test/SKILL.md) | Standardized validation and debugging via `diag.sh`. |
| [`rsyslog_doc`](.agent/skills/rsyslog_doc/SKILL.md) | Structured, RAG-optimized documentation and metadata. |
| [`rsyslog_doc_dist`](.agent/skills/rsyslog_doc_dist/SKILL.md) | Syncing documentation files in `doc/Makefile.am`. |
| [`rsyslog_module`](.agent/skills/rsyslog_module/SKILL.md) | Technical patterns for concurrency and module authoring. |
| [`rsyslog_commit`](.agent/skills/rsyslog_commit/SKILL.md) | Compliant commit messages and branching policies. |
## Agent Quick Start: The "Happy Path"
Follow these three steps for a typical development task. This workflow is the recommended starting point for any new session.
Follow these three steps for a typical development task:
### Step 1: Set Up the Environment (If Needed)
For some agents, like Jules, the development environment is often Debian/Ubuntu-based. If you are in such an environment and need to install dependencies, the following command provides a complete set for building and testing.
**Warning:** Only run this command if you are on a Debian-based system (like Ubuntu) and have `sudo` privileges. Do not run this in an unknown CI or containerized environment, as it may cause unintended changes.
```bash
# Optional: For Debian/Ubuntu-based environments
sudo apt-get update && sudo apt-get install -y \
autoconf autoconf-archive automake autotools-dev \
bison flex gcc \
libcurl4-gnutls-dev libdbi-dev libgcrypt20-dev \
libglib2.0-dev libgnutls28-dev \
libtool libtool-bin libzstd-dev make \
libestr-dev python3-docutils libfastjson-dev \
librelp-dev liblognorm-dev libaprutil1-dev libcivetweb-dev \
valgrind clang-format
```
### Step 2: Build the Project
Build the project efficiently. The following command builds the core and all test dependencies without running any tests (`TESTS=""` is build-only).
```bash
make -j$(nproc) check TESTS=""
```
**Note:** If `configure` or `Makefile.in` is missing, or you changed `configure.ac`, any `Makefile.am`, or files under `m4/`, run the full bootstrap sequence first. `autogen.sh` runs `configure` internally, so pass configure flags directly to it:
```bash
./autogen.sh --enable-debug --enable-testbench --enable-imdiag --enable-omstdout --enable-mmsnareparse --enable-omotel --enable-imhttp
make -j$(nproc) check TESTS=""
```
### Step 3: Run Tests
Run a relevant test to verify your changes. Use direct test scripts only; do not use the `make check` harness in agent workflows. `imtcp-basic.sh` serves as a good general-purpose smoke test. See “Validate Code Changes” below for the full validation checklist.
```bash
./tests/imtcp-basic.sh
```
### Step 4: Format Code
Before committing, run the normalization script to ensure code style consistency. This script wraps clang-format and applies project-specific rules. See “Pre-Commit Checklist” below for the final gate.
```bash
devtools/format-code.sh
```
1. **Build**: Use the `rsyslog_build` skill to set up and compile.
2. **Validate**: Use the `rsyslog_test` skill to run relevant shell tests.
3. **Commit**: Use the `rsyslog_commit` skill to format code and draft your message.
- *Tip*: You do NOT need to re-run your build/test cycle after formatting if you already validated the code immediately before.
## Repository Overview
- **Primary Language**: C
- **Build System**: autotools (`autogen.sh`, `configure`, `make`)
- **Architecture**: Microkernel-like core (`runtime/`) with loadable plugins (`plugins/`)
- **Modules**: Dynamically loaded from `plugins/` (note: legacy modules like `omfile` reside in `tools/`)
- **Contrib Modules**: Community-contributed under `contrib/`
- **Contributions**: Additional modules and features are placed in `contrib/`, which contains community-contributed plugins not actively maintained by the core rsyslog team. These are retained in `contrib/` even if adopted later, to avoid disruptions in dependent software.
- **Documentation**: Maintained in the doc/ subdirectory
- **AI module map**: `doc/ai/module_map.yaml` (per-module paths & locking hints)
- **docker definitions**: Maintained in the packaging/docker/ subdirectory
- **Side Libraries** (each in its own repo within the rsyslog GitHub org):
- [`liblognorm`](https://github.com/rsyslog/liblognorm)
- [`librelp`](https://github.com/rsyslog/librelp)
- [`libestr`](https://github.com/rsyslog/libestr)
- [`libfastjson`](https://github.com/rsyslog/libfastjson): A fork of libfastjson by the rsyslog project, optimized for speed.
This library is used by multiple external projects.
- **Primary Language**: C (v8 worker model)
- **Architecture**: Microkernel core (`runtime/`) + Loadable Plugins (`plugins/`)
- **Metadata**: Every module directory contains `MODULE_METADATA.yaml`.
- **Knowledge Base**: `doc/ai/` contains canonical patterns for RAG ingestion.
-----
## Context Discovery (Subtree Guides)
## Quick links for agents
Each major subtree contains a specialized `AGENTS.md` that points to area-specific context and requirements:
- **Documentation subtree guide:** [`doc/AGENTS.md`](./doc/AGENTS.md)
- **Coding practices reference (patterns & antipatterns for AI seeding):**
[`doc/source/development/coding_practices.rst`](./doc/source/development/coding_practices.rst)
- **Core plugin subtree guide:** [`plugins/AGENTS.md`](./plugins/AGENTS.md)
- **Contrib module subtree guide:** [`contrib/AGENTS.md`](./contrib/AGENTS.md)
- **Built-in tools subtree guide:** [`tools/AGENTS.md`](./tools/AGENTS.md)
- **Runtime core guide:** [`runtime/AGENTS.md`](./runtime/AGENTS.md)
- **Testbench guide:** [`tests/AGENTS.md`](./tests/AGENTS.md)
- **Inline comment conventions:** [`COMMENTING_STYLE.md`](./COMMENTING_STYLE.md)
- **Module author checklist:** [`MODULE_AUTHOR_CHECKLIST.md`](./MODULE_AUTHOR_CHECKLIST.md)
- **Developer overview:** [`DEVELOPING.md`](./DEVELOPING.md)
- **Architecture overview:** [`doc/source/development/architecture.rst`](./doc/source/development/architecture.rst)
- **Commit prompt template:** [`ai/rsyslog_commit_assistant/base_prompt.txt`](./ai/rsyslog_commit_assistant/base_prompt.txt)
- **Doc builder prompt template:** [`ai/rsyslog_code_doc_builder/base_prompt.txt`](./ai/rsyslog_code_doc_builder/base_prompt.txt)
- **Doc assistant prompt template:** [`ai/rsyslog_doc_assistant/base_prompt.txt`](./ai/rsyslog_doc_assistant/base_prompt.txt)
Use these jump points together with this file to locate the workflow and
component notes that apply to your task.
-----
- **Documentation**: [`doc/AGENTS.md`](./doc/AGENTS.md)
- **Core Plugins**: [`plugins/AGENTS.md`](./plugins/AGENTS.md)
- **Contrib Modules**: [`contrib/AGENTS.md`](./contrib/AGENTS.md)
- **Runtime Core**: [`runtime/AGENTS.md`](./runtime/AGENTS.md)
- **Testbench**: [`tests/AGENTS.md`](./tests/AGENTS.md)
- **Built-in Tools**: [`tools/AGENTS.md`](./tools/AGENTS.md)
## Agent Chat Keywords
The following chat codewords instruct AI assistants to perform standardized actions in this repository.
### `FINISH`
When the user says the codeword "FINISH", do the following:
- Perform a final review of all proposed code changes for correctness and style before concluding the session.
### `SUMMARIZE`
When the user says the codeword "SUMMARIZE", do the following:
- Create and print the following summaries in the Agent chat, each in a copy-ready TEXTBOX field:
- A summary for the pull request
- A summary for a squashed commit message
### `SETUP`
When the user says the codeword "SETUP", do the following:
- Follow the instructions in the "Step 1: Set Up the Environment" section of the "Agent Quick Start" guide at the top of this file to install all necessary development dependencies.
### `BUILD [configure-options]`
When the user says the codeword "BUILD" optionally followed by configure options, do the following:
1. **Check for existing build configuration**:
- If `configure` and `Makefile` exist, no new configure options are provided, and you did not change `configure.ac`, `Makefile.am`, or files under `m4/`, **SKIP** to Step 3.
2. **Generate and Configure** (if Makefile is missing or options provided):
```bash
./autogen.sh --enable-debug
```
`autogen.sh` accepts configure options and runs `configure`. Pass any module or test flags directly to `autogen.sh`.
- If configure options are provided, run:
```bash
./autogen.sh --enable-debug [user-provided-options]
```
- If no options are provided, run:
```bash
./autogen.sh --enable-debug --enable-testbench --enable-imdiag --enable-omstdout --enable-mmsnareparse --enable-omotel --enable-imhttp
```
3. **Build the project**:
Use the build-only command that prepares all test binaries without running tests:
```bash
make -j$(nproc) check TESTS=""
```
Examples:
- `BUILD` (Makefile exists) - Runs `make -j$(nproc) check TESTS=""` directly.
- `BUILD` (First run) - Runs autogen, default configure, then make.
- `BUILD --enable-imkafka` - Runs autogen, custom configure, then make.
### `TEST [test-script-names]`
When the user says the codeword "TEST" optionally followed by test script names, do the following:
1. **Ensure the project is built** (if not already built, run BUILD first)
2. **Run tests**:
- If test script names are provided after "TEST", run those specific tests:
```bash
./tests/<test-script-name>.sh
```
For multiple tests, run each one:
```bash
./tests/<test-script-1>.sh
./tests/<test-script-2>.sh
```
- If no test names are provided, run the default smoke test:
```bash
./tests/imtcp-basic.sh
```
Examples:
- `TEST` - Runs the default smoke test (`imtcp-basic.sh`)
- `TEST mmsnareparse-sysmon.sh` - Runs the mmsnareparse-sysmon test
- `TEST mmsnareparse-sysmon.sh mmsnareparse-trailing-extradata.sh` - Runs multiple specific tests
Note: Tests are run directly (not via `make check`) to provide unfiltered stdout/stderr output.
-----
## Priming a fresh AI session
When starting a new AI-assisted coding session (for example after a PR merges or
the workspace is reset):
1. Share this repository-level guide and the relevant subtree `AGENTS.md`
files (`plugins/`, `contrib/`, `doc/`, `tools/`, etc.) so the agent absorbs
the area-specific build and testing workflows.
2. Provide the module metadata (`MODULE_METADATA.yaml` or `tools/MODULE_METADATA.json`)
for components being modified so ownership, support channels, and maturity
are clear.
3. Supply the commit assistant or doc builder prompt that matches the task type
(see the quick links above) to keep commit messages and documentation edits
consistent.
4. Include any recent design or review notes that are not yet in the repository
so the agent understands outstanding context.
These steps mirror how the existing sandbox is configured and make it more
likely that rebuild/bootstrap reminders (such as running `./autogen.sh --enable-debug` before
the first compile) are followed.
-----
## Automated Formatting Normalization Strategy
We treat formatting as a normalization step, not a developer-side constraint.
AI agents should follow this process:
1. Canonical formatting via clang-format
Use the Google-style base with 4-space indentation in .clang-format.
2. Helper-based normalization
Run devtools/format-code.sh to run clang-format and potential helper scripts.
3. Developer freedom & accessibility
Local formatting is unrestricted; only normalized output matters.
4. CI enforcement & maintainer assist
CI checks formatting; maintainers may edit PRs directly.
5. Git blame hygiene
Formatting-only commits listed in .git-blame-ignore-revs.
AI Agent Note: run devtools/format-code.sh as the final formatting step before commit.
-----
## Development Workflow
### Base Repository
- URL: https://github.com/rsyslog/rsyslog
- **Default base branch: `main`**
> The `main` branch is now the canonical base for all development.
> Some older references to `master` may still exist in documentation
> or tooling and will be updated as needed.
### Contributor Workflow
1. Fork the repository (for personal development)
2. Create a feature/fix branch
3. Push changes to your fork
4. Open a **pull request directly into `rsyslog/rsyslog:main`**
> **Important**: AI-generated PRs must target the `rsyslog/rsyslog` repository directly.
-----
## Branch Naming Conventions
There are no strict naming rules, but these conventions are used frequently:
- For issue-based work: `i-<issue-number>` (e.g., `i-2245`)
- For features or refactoring: free-form is acceptable
- For AI-generated work: prefix the branch name with the AI tool name
(e.g., `gpt-i-2245-json-stats-export`)
-----
## Coding Standards
- Commit messages **must include all relevant information**, not just in the PR
- Commit message titles **must not exceed 62 characters**
- commit message text must be plain US ASCII, line length must not exceed 72 characters
- When referencing GitHub issues, use the **full GitHub URL** to assist in `git log`-based reviews
- Favor **self-documenting code** over excessive inline comments
- Public functions should use Doxygen-style comments
- See `COMMENTING_STYLE.md` for detailed Doxygen guidelines
- Modules must implement and register `modInit()` and `modExit()`
When fixing compiler warnings like `stringop-overread`, explain in the commit message:
- Why the warning occurred
- What part of the code was changed
- How the fix prevents undefined behavior or aligns with compiler expectations
- Optionally link: https://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html#index-Wstringop-overread
-----
## Defensive Coding and Assertions
Use `assert()` to signal "impossible" states to Static Analyzers and AI agents. Whenever feasible and low-complexity, follow with a defensive `if` check to prevent production crashes. See [Defensive Coding Practice](doc/source/development/coding_practices/defensive_coding.rst) for full details.
- **Mandatory**: `assert()` for invariants (allows SA/AI to reason about code).
- **Recommended**: Defensive `if` check (optional if fallback logic is excessively complex).
- **Prohibited**: `__builtin_unreachable()` (causes Undefined Behavior).
-----
## Editor & Formatting Configuration
The repository includes:
- `.editorconfig`: Editor-agnostic indent, whitespace, EOL, and file-type rules.
- Project `.vimrc`/`.exrc`: Vim settings when `set exrc secure` is enabled.
- `.clang-format`: Canonical C/C++ style; run `clang-format -i -style=file`.
- `devtools/format-code.sh`: Runs clang-format plus helper fixups.
Editors and IDEs with EditorConfig support (VS Code, JetBrains, Sublime, Vim, Emacs)
will automatically apply these rules.
-----
## Build & Test Expectations
Whenever `.c` or `.h` files are modified, a build should be performed using `make -j$(nproc) check TESTS=""` when possible.
If new functionality is introduced, at least a basic test should be created and run.
### Generating the autotools build system
The `configure` script and `Makefile.in` files are **not** stored in git. After a
fresh checkout—or any time `configure.ac`, `Makefile.am`, or macros under `m4/`
change—you **must** run:
```bash
./autogen.sh --enable-debug
```
`autogen.sh` accepts configure options and runs `configure`; pass any additional module or test flags directly to `autogen.sh`.
This bootstraps autotools, downloads any required macros, and generates
`configure`. `make` may rerun `config.status` when `configure` or `Makefile.in`
change, but it does **not** regenerate `configure` or `Makefile.in` from
`configure.ac` or `m4/`—that still requires `autogen.sh`.
Skipping this step is the most common reason for messages such as
`configure: error: cannot find install-sh, install.sh, or shtool` or `make:
*** No targets specified and no makefile found`. If a cleanup removed the
generated files (e.g., `git clean -xfd`), re-run `./autogen.sh --enable-debug` before
configuring again.
If `./autogen.sh --enable-debug` fails, run `./devtools/codex-setup.sh` first to install the
toolchain dependencies inside the sandbox, then retry `./autogen.sh --enable-debug`.
### Configure & build
If possible, agents should:
- Build the project using `make -j$(nproc) check TESTS=""`
- Run an individual test using the instructions below
- After building, run `./tests/imtcp-basic.sh` as a smoke test unless another test is more appropriate
Build trigger reminders:
- If `configure` is missing or when `configure.ac`, `Makefile.am`, or files under `m4/` change, run `./autogen.sh --enable-debug [configure-flags]` with any required module/test options.
- If only source files change, re-run `make -j$(nproc) check TESTS=""`.
> In restricted environments, a build may not be possible. In such cases, ensure the
> generated code is clear and well-commented to aid review.
-----
## Testing & Validation
All test definitions live under the `tests/` directory and are driven by the `tests/diag.sh` framework. **AI agents must use direct test scripts only**; never use the `make check` harness. Direct invocation keeps stdout/stderr visible and avoids the 10+ minute runtime of the harness.
Avoiding the harness matters because `make check`:
- Wraps tests in a harness that hides stdout/stderr on failure
- Requires parsing `tests/test-suite.log` for details
- Consumes significant resources on large suites
Instead, AI agents should invoke individual test scripts directly. This yields unfiltered output and immediate feedback, without the CI harness. The `diag.sh` framework builds required test support automatically, but the build-only step is still required when code changes warrant it.
-----
## Documentation Requirements
When introducing new configuration parameters, features, or significant behavior changes, you **must** update the user-facing documentation in the `doc/` subtree.
1. **Locate the relevant guide**: Most module documentation is in `doc/source/configuration/modules/<module>.rst`.
2. **Update parameter references**: If adding a parameter, create or update the corresponding file in `doc/source/reference/parameters/` and include it in the module's `.rst` file.
3. **Cross-link**: Ensure new documentation is discoverable from the module's main page and appropriate `index.rst`.
4. **Validate**: If possible, run `./doc/tools/build-doc-linux.sh --clean --format html` to catch Sphinx errors.
-----
### Running Individual Tests (AI-Agent Best Practice)
1. **Configure the project** (once per session, if `configure` is missing):
```bash
./autogen.sh --enable-debug --enable-imdiag --enable-testbench
```
2. **Invoke your test**:
```bash
./tests/<test-script>.sh
```
For example:
```bash
./tests/manytcp-too-few-tls-vg.sh > /tmp/test.log && tail -n20 /tmp/test.log
```
3. **Why this works**
- Each test script transparently finds and loads the test harness
- You get unfiltered stdout/stderr without any CI wrapper
- No manual `cd` or log-file parsing required
-----
### Validate Code Changes (AI Agents)
Run these checks after code changes, before you consider the work ready:
1. **Build** (required):
```bash
make -j$(nproc) check TESTS=""
```
2. **Run relevant tests** (required):
```bash
./tests/<test-script>.sh
```
3. **Run Cubic review** (best-effort):
```bash
cubic review --json --base main
```
If `cubic` is unavailable in the current session, skip this step. If it runs, address any reported issues.
### Pre-Commit Checklist (AI Agents)
Complete these steps when the change is ready to commit:
1. **Format code** (required):
```bash
devtools/format-code.sh
```
Skipping this step can cause CI failures.
2. **Confirm validation** (required): ensure the steps in “Validate Code Changes” are complete.
3. **Use commit prompt** (required): generate commit messages using `ai/rsyslog_commit_assistant/base_prompt.txt`.
-----
### Test Environment
Human developers can replicate CI conditions using the official container images available on **Docker Hub**. For single-test runs, we recommend `rsyslog/rsyslog_dev_base_ubuntu:24.04`. It is **recommended** that AI agents use the standard workflow within their existing environment to avoid potential complications, but they may use container images if necessary to reproduce a specific environment.
-----
-----
## Module-Specific Capabilities
### `omelasticsearch`
- Buildable: Yes, even in minimal environments
- Depends on: `libcurl`
- Testable: No. Tests require a running Elasticsearch instance and are skipped in Codex or constrained environments
### `imjournal`
- Buildable: Yes
- Depends on: `libsystemd`
- Testable: No. Requires journald-related libraries and a systemd journal service context not present in the Codex container
### `imkafka` and `omkafka`
- Depends on: `librdkafka` (plus `liblz4` when linking statically)
### `fmpcre`
- Buildable: Yes when `libpcre3-dev` (or equivalent) is installed
- Testable: Yes, simple regression test `ffmpcre-basic.sh` exercises `pcre_match()`
### `omhiredis` and `imhiredis`
- Depends on: `hiredis`; `imhiredis` also needs `libevent`
### `ommongodb`
- Depends on: `libmongoc-1.0`
### `omamqp1` and `omazureeventhubs`
- Depends on: `libqpid-proton` (Azure module additionally needs `libqpid-proton-proactor`)
### `imhttp`
- Depends on: `civetweb` and `apr-util`
### `imdocker`
- Depends on: `libcurl` (>= 7.40.0)
### `impcap`
- Depends on: `libpcap`
### `imczmq` and `omczmq`
- Depends on: `libczmq` (>= 4.0.0)
### `omrabbitmq`
- Depends on: `librabbitmq` (>= 0.2.0)
### `omdtls` and `imdtls`
- Depends on: `openssl` (>= 1.0.2 for output, >= 1.1.0 for input)
### `omhttp`
- Depends on: `libcurl`
### `omhttpfs`
- Depends on: `libcurl`
### `mmnormalize`
- Depends on: `liblognorm` (>= 2.0.3)
### `mmkubernetes`
- Depends on: `libcurl` and `liblognorm` (>= 2.0.3)
### `mmgrok`
- Depends on: `grok` and `glib-2.0`
### `mmdblookup`
- Depends on: `libmaxminddb` (dummy module built if absent)
### `omlibdbi`
- Depends on: `libdbi`
### `ommysql`
- Depends on: `mysqlclient` via `mysql_config`
### `ompgsql`
- Depends on: `libpq` via `pg_config`
### `omsnmp`
- Depends on: `net-snmp`
### `omgssapi`
- Depends on: `gssapi` library
-----
## AI-Specific Hints
- The `plugins/` directory contains dynamically loaded input/output plugins
- `contrib/` contains external contributions (e.g., plugins) that are not core-maintained
- `statsobj.c` implements the statistics interface
- Documentation resides in the monorepo’s doc/ directory
- Discovery order for AI agents: start with this file, follow the per-tree
`AGENTS.md` (for docs, `doc/AGENTS.md`), then ingest the coding practices
reference at `doc/source/development/coding_practices.rst` to prime RAG
seeding before planning or reviews.
- You may reference `rsyslog-docker` for dev/test environment setup
- Side libraries are external GitHub repos, not subdirectories
- **Shell Script Documentation**
Use shdoc-style comments (`##`, `###`) in new and updated Bash scripts to enable automatic Markdown extraction. Many existing scripts lack these; it's **strongly recommended** to add them when modifying or creating scripts.
When generating or editing code, prefer:
- Clean modular design
- Compatibility and backward safety
- Updating structured comments (e.g., Doxygen for C code)
-----
## AI Agent Commit Convention
If you are an AI agent contributing code or documentation:
- Use the same rich commit message text as your PR description.
- Avoid generating multiple PRs for retries — reuse and update the original PR when possible.
- Follow the same **commit message policy** as human contributors:
- Describe **what changed** and **why** (as far as known to the agent).
- Note any impact on existing versions or behaviors (especially for bug fixes).
- Commit message descriptions should clearly identify that they were generated or co-authored by an AI tool.
- Include a line in the commit footer like `With the help of AI-Agents: <agent-name>`
- **When crafting commit messages, you must use the canonical commit-message base prompt** located at `ai/rsyslog_commit_assistant/base_prompt.txt`. Do not draft commit messages without the prompt. This template ensures the final commit adheres to the project's formatting rules: a title of **62 characters or less** and body lines wrapped at **72 characters**.
- **Commit-first:** ensure the substance is in the commit body (not only the PR). If needed, amend before opening the PR (`git commit --amend`).
-----
## Privacy, Trust & Permissions
- AI agents **must not** push changes directly to user forks — always open PRs against `rsyslog/rsyslog`
- Do not install third-party dependencies unless explicitly approved
- PRs must pass standard CI and review checks
- All code **must be reviewed manually**; AI output is subject to full review
-----
## Quickstart for AI coding agents (v8 concurrency & state)
**Read these first:**
* [`DEVELOPING.md`](./DEVELOPING.md) — v8 worker model & locking rules
* [`MODULE_AUTHOR_CHECKLIST.md`](./MODULE_AUTHOR_CHECKLIST.md) — one-screen checklist
* [doc/ai/module_map.yaml](./doc/ai/module_map.yaml) — seed list of modules, paths, and known locking needs
**Rules you must not break**
1. The framework may run **multiple workers per action**.
2. `wrkrInstanceData_t` (WID) is **per-worker**; never share it.
3. Shared mutable state lives in **pData** (per-action) and **must be protected**
by the module (mutex/rwlock). Do **not** rely on `mutAction` for this.
4. **Inherently serial resources** (e.g., a shared stream) must be serialized
inside the module via a mutex in **pData**.
5. **Direct queues** do not remove the need to serialize serial resources.
**Common agent tasks**
* Consult `doc/ai/module_map.yaml` to understand module paths and known locking.
* Add a “Concurrency & Locking” block at the top of output modules.
* Ensure serial modules guard stream/flush with a **pData** mutex.
* For modules with a library I/O thread (e.g., Proton), verify read/write locks
are taken on **all** callback paths.
- `SETUP`: Triggers the `rsyslog_build` setup workflow.
- `BUILD`: Triggers the `rsyslog_build` incremental build workflow.
- `TEST`: Triggers the `rsyslog_test` validation workflow.
- `SUMMARIZE`: Generates PR and commit summaries using `rsyslog_commit` templates.
- `FINISH`: Final review of code and style before conclusion.
---
*For human-facing guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md) and [DEVELOPING.md](DEVELOPING.md).*

2
CONTRIBUTING.md
View File

@ -21,7 +21,7 @@ https://www.rsyslog.com/tool_good-first-issues
- **Maintain infrastructure**: Help with project websites, CI, or packaging.
- **Develop code**: Implement new features, improve existing ones, or fix bugs.
- the rsyslog project welcomes AI generated patches, we have no friction with them. Qualitiy is ensured by CI and maitainer guidance and review.
- AI-assisted contributions should follow [AGENTS.md](AGENTS.md) for setup and workflow guidance.
- AI-assisted contributions should follow [AGENTS.md](AGENTS.md) and use the standardized skills in [.agent/skills/](.agent/skills/).
---

25
ai/rsyslog_memory_auditor/base_prompt.txt Normal file
View File

@ -0,0 +1,25 @@
You are a senior C security and performance auditor. Analyze the following rsyslog module code specifically for memory lifecycle and ownership issues.
Check for the following common rsyslog patterns/antipatterns:
1. **Error Path Leaks**:
- Trace every `RS_RET` return path.
- Ensure that any memory allocated via `malloc`, `calloc`, or `strdup` (common in `setInstParam`) is freed before an error return.
- Check if `pData` or `WID` sub-elements are leaked during partial initialization failure.
2. **Ownership Ambiguity**:
- Determine if memory passed to a function is "owned" (caller must free) or "transferred" (callee must free).
- In rsyslog, `pData` is typically freed in `freeInstance`, and `WID` in `freeWrkrInstance`. Ensure no double-frees occur during HUP or teardown.
3. **String Handling**:
- Look for `strdup()` calls. Are they matched by a `free()`?
- Check for buffer overflows in `snprintf` or `strcpy` (though `format-code.sh` helps, logic errors remain).
4. **Module Lifecycle**:
- Verify `modInit` and `modExit` balance global resource allocations.
- Ensure `createInstance` results in a fully initialized `pData` that `freeInstance` can safely clean up (even if only partially initialized).
**Output**:
- List any identified risks.
- Provide a summary of "Clean" vs "At Risk" allocations.
- Suggest specific `free()` placements for identified leaks.

72
contrib/AGENTS.md
View File

@ -2,69 +2,19 @@
These instructions apply to everything under `contrib/`.
## Expectations for contrib work
- Contrib modules are not part of the core support contract. Changes should
preserve backward compatibility for existing users and clearly call out
behavior shifts in commit messages and documentation.
- Many contrib modules depend on third-party SDKs or services that are not
available in CI. Document any manual setup that reviewers must perform.
## Workflow & Skills
## Build & bootstrap reminders
- **Efficient Build:** Use `make -j$(nproc) check TESTS=""` to incrementally build the core and all test dependencies. This is the primary build command.
- **Bootstrap/Configure:** Only run `./autogen.sh` and `./configure` if:
1. The `Makefile` is missing (first run).
2. You have modified `configure.ac`, `Makefile.am`, or `m4/` files.
3. You need to change build options (e.g., enabling a new contrib module).
4. You need to enable a module that requires specific flags (check `MODULE_METADATA.yaml`).
- **Run Tests:** Execute the most relevant smoke/regression test directly (e.g., `./tests/imtcp-basic.sh`). Direct invocation keeps stdout/stderr visible. Use `make check` only when mirroring CI.
AI agents working in `contrib/` MUST follow the standardized skills in `.agent/skills/`:
## Metadata required for every module
Each contrib module directory (for example `contrib/mmkubernetes/`) must contain
`MODULE_METADATA.yaml`. Contrib metadata uses the same schema as core plugins,
with different default expectations.
- **Build**: Use [`rsyslog_build`](../.agent/skills/rsyslog_build/SKILL.md) for incremental parallel builds.
- **Test**: Use [`rsyslog_test`](../.agent/skills/rsyslog_test/SKILL.md) for `diag.sh` based validation.
- **Doc**: Use [`rsyslog_doc`](../.agent/skills/rsyslog_doc/SKILL.md) for metadata and documentation.
- **Module**: Use [`rsyslog_module`](../.agent/skills/rsyslog_module/SKILL.md) for `MODULE_METADATA.yaml` requirements.
### Required keys
```yaml
support_status: contributor-supported | stalled
maturity_level: fully-mature | mature | fresh | experimental | deprecated
primary_contact: "GitHub Discussions & Issues <https://github.com/rsyslog/rsyslog/discussions>"
last_reviewed: YYYY-MM-DD
```
## Contrib Expectations
- Default `support_status` is `contributor-supported` unless the core team has
formally adopted the module.
- Use `stalled` if no maintainer is known. Do not set `core-supported` unless
the module has moved to `plugins/`.
- Changes SHOULD preserve backward compatibility.
- Use `MODULE_METADATA.yaml` to document third-party dependencies and manual setup.
### Optional keys
Use the optional keys from the template to document build/runtime
requirements, CI coverage, and reviewer notes. Copy
`contrib/MODULE_METADATA_TEMPLATE.yaml` when creating the file.
- `build_dependencies`: List library or tool requirements (match configure
options when possible).
- `runtime_dependencies`: Libraries or services the module needs at runtime.
- `ci_targets`: Names of CI jobs or scripts that exercise this module.
- `documentation`: Links into `doc/` or external references.
- `support_channels`: Overrides or supplements the default GitHub Discussions
and Issues flow when a module has a bespoke support process.
- `notes`: Free-form guidance for reviewers and contributors.
Replace `primary_contact` with a specific maintainer string when a contrib
module has an active owner outside the standard GitHub Discussions and Issues
queue, and record any bespoke escalation path via the optional
`support_channels` array if needed.
## Testing expectations
- Prefer smoke tests that can run directly via `./tests/<script>.sh` without
proprietary services. If that is impossible, provide script stubs in `tests/`
that mock or skip the integration but keep API coverage verifiable, and note
any CI limitations in the metadata.
- Record any external test environments (container images, cloud resources) in
the module metadata so reviewers understand the manual steps required.
## Documentation touchpoints
- Update `doc/` to mention new or changed contrib modules, especially when the
module has prerequisites or manual installation steps.
- When a contrib module becomes core-supported, move it under `plugins/`, update
the metadata accordingly, and inform maintainers via the changelog.
---
*For human-facing guidelines, see [CONTRIBUTING.md](../CONTRIBUTING.md).*

76
doc/AGENTS.md
View File

@ -2,73 +2,19 @@
This guide applies to everything under `doc/`.
## Purpose & scope
- The `doc/` tree contains all **Sphinx documentation sources**, helper tools, and the **AI knowledge base** under `doc/ai/`.
- Use this file together with the top-level `AGENTS.md` or `CONTRIBUTING.md` instructions.
## Workflow & Skills
## Editing guidelines
- Prefer **reStructuredText (`*.rst`)** for content.
Markdown files are reserved for meta-docs such as `/doc/ai/` and other authoring guides.
- Follow existing heading levels and section names from `doc/README.md`.
- Cross-link new pages from the appropriate `index.rst` (or local `.. toctree::`) so they appear in navigation.
- Keep the `source/development/coding_practices.rst` page discoverable; it is
the canonical source for patterns and antipatterns that AI agents must
ingest.
- When touching shared style guidance, also review `doc/STRATEGY.md`.
AI agents working on documentation MUST use the standardized skills in `.agent/skills/`:
### For AI-driven documentation work
- Prime new contributors or agents with the base prompt at
**`ai/rsyslog_code_doc_builder/base_prompt.txt`**.
This defines the model’s role, tone, and default workflow.
- Use the supplemental **knowledge base** in `doc/ai/`:
- `authoring_guidelines.md` — required blocks, tone, and section order.
- `mermaid_rules.md` — syntax rules (blank line after directive, quoted node labels, `<br>` for line breaks).
- `templates/` — standard concept/tutorial RST templates.
- `terminology.md` — canonical rsyslog vocabulary.
- Prime code-generation agents with the `source/development/coding_practices.rst`
page so RAG pipelines can inject the right patterns and antipatterns into
their context.
- Keep discoverability explicit for AI agents: this file is linked from the
top-level `AGENTS.md`, and `coding_practices.rst` sits in the development
toctree. When you move or rename that page, update the links here and in the
base prompts so automated seeding does not break.
- Every new or materially edited page must include anchors, meta, and summary
blocks per `authoring_guidelines.md`. If an existing page lacks them, add
the blocks as part of the update.
- Module docs should include an explicit module metadata header (module name,
author/maintainer, introduced/version when known) and an `.. index::`
directive. Use `doc/ai/templates/template-module.rst` as the reference
structure when updating module pages.
- Keep sections short for human scanning and RAG chunking: prefer 1–3 short
paragraphs per section and split long pages into subpages when they exceed
the size guidance in `doc/ai/chunking_and_embeddings.md`.
- **Doc**: Use [`rsyslog_doc`](../.agent/skills/rsyslog_doc/SKILL.md) for metadata blocks, summary slices, and Sphinx validation.
- **Dist**: Use [`rsyslog_doc_dist`](../.agent/skills/rsyslog_doc_dist/SKILL.md) for `doc/Makefile.am` synchronization.
- **Commit**: Use [`rsyslog_commit`](../.agent/skills/rsyslog_commit/SKILL.md) for doc-specific commit trailers.
## Build & validation
- Run `./doc/tools/build-doc-linux.sh --clean --format html` after changes to catch Sphinx errors early.
- For RAG Knowledge Base updates, use `make -j16 json-formatter`. This builds the doctrees and runs the extraction script to generate `doc/build/rag/rsyslog_rag_db.json`.
- For quick linting, use `make -C doc html` (uses the repo’s virtualenv if present).
- Verify Mermaid diagrams render correctly; invalid syntax halts the build.
- Documentation-only commits generally do **not** require the full C test suite.
## Subtree Specifics
## Commit messaging
- Summarize the **reader impact** (new topic, restructure, typo fix, etc.) in the commit body.
- Include the `AI-Agent: ChatGPT` trailer as requested by repository guidelines.
- If a change updates or regenerates the KB, mention the **KB version** in the message.
- **Knowledge Base**: `doc/ai/` contains canonical guides for Mermaid, Terminology, and authoring.
- **Prompting**: Use `ai/rsyslog_code_doc_builder/base_prompt.txt` for tone and style guidance.
- **Build**: Use `./doc/tools/build-doc-linux.sh --clean --format html` for validation.
## Coordination
- When editing module-specific docs, consult `doc/ai/module_map.yaml` for component ownership.
- Mention any **locking or runtime considerations** in the relevant module page.
- If the change alters common terms (e.g., *log pipeline*), update both the glossary and `/doc/ai/terminology.md`.
## Quick reference
| Task | Location |
|------|-----------|
| Base prompt (AI agent seed) | `ai/rsyslog_code_doc_builder/base_prompt.txt` |
| AI knowledge base | `doc/ai/` |
| Mermaid rules | `doc/ai/mermaid_rules.md` |
| Authoring guide | `doc/ai/authoring_guidelines.md` |
| Concept/tutorial templates | `doc/ai/templates/` |
| Build scripts | `doc/tools/` |
| RAG Knowledge Base script | `doc/build_rag_db.py` |
| RAG Knowledge Base (Output) | `doc/build/rag/rsyslog_rag_db.json` |
| Strategy and style | `doc/STRATEGY.md` |
---
*For detailed authoring rules, see [doc/ai/AGENTS.md](./ai/AGENTS.md).*

33
plugins/omkafka/AGENTS.md
View File

@ -1,28 +1,17 @@
# AGENTS.md – omkafka output module
## Module overview
- Ships events to Apache Kafka topics via librdkafka.
- User documentation: `doc/source/configuration/modules/omkafka.rst`.
- Support status: contributor-supported. Maturity: mature.
## Workflow & Skills
## Build & dependencies
- **Efficient Build:** Use `make -j$(nproc) check TESTS=""` to build the module and test dependencies.
- **Configure:** Run `./configure --enable-omkafka` (and `--enable-imkafka` if needed).
- **Bootstrap:** Only run `./autogen.sh` if you touch `configure.ac`, `Makefile.am`, or `m4/`.
AI agents working on `omkafka` MUST follow the standardized skills in `.agent/skills/`:
## Local testing
- **Skip the Kafka integration tests for routine agent tasks.** They download and run Kafka plus ZooKeeper, which exceeds the sandbox resource budget.
- Build validation is sufficient. Run the efficient build command above.
- Maintainers who must exercise the suite can enable `--enable-kafka-tests` and run scripts such as `./tests/omkafka.sh`, but expect multi-minute startup time for the embedded Kafka cluster.
- **Build**: Use [`rsyslog_build`](../../.agent/skills/rsyslog_build/SKILL.md) (requires `--enable-omkafka`).
- **Test**: Use [`rsyslog_test`](../../.agent/skills/rsyslog_test/SKILL.md).
- **Policy**: Skip heavy integration tests (e.g., `./tests/omkafka.sh`) in sandboxes as they require a local Kafka cluster.
- **Doc**: Use [`rsyslog_doc`](../../.agent/skills/rsyslog_doc/SKILL.md).
- **Module**: Use [`rsyslog_module`](../../.agent/skills/rsyslog_module/SKILL.md) and keep `MODULE_METADATA.yaml` current.
## Diagnostics & troubleshooting
- `impstats` exposes the `omkafka` counter set (submitted, failed, retry metrics); enable the module and inspect `impstats` output for delivery issues.
- Kafka-side diagnostics live in the working directory under `.dep_wrk/`; the helper `./tests/diag.sh dump-kafka-topic <topic>` extracts queued messages for debugging.
## Module Specifics
## Cross-component coordination
- Changes to shared Kafka helpers in `runtime/` or `tests/diag.sh` must also be reviewed by `imkafka` maintainers.
- Align parameter documentation with `doc/source/configuration/modules/omkafka.rst` and update examples when defaults change.
## Metadata & housekeeping
- Keep `plugins/omkafka/MODULE_METADATA.yaml` current (support status, maturity, contacts).
- Update `doc/ai/module_map.yaml` if the concurrency model or locking guidance changes.
- **Dependencies**: Ships events via `librdkafka`.
- **Diagnostics**: `impstats` exposes counters (submitted, failed, retry).
- **Review**: Changes to shared Kafka helpers in `runtime/` must be coordinated with `imkafka`.

24
plugins/omotel/AGENTS.md
View File

@ -1,18 +1,16 @@
# AGENTS.md – omotel output module
These instructions apply to files inside `plugins/omotel/`.
## Workflow & Skills
## Development notes
- Keep the module pure C unless the optional gRPC shim is enabled.
- Update `MODULE_METADATA.yaml` and the user documentation when adding new
configuration parameters or behavioral changes.
- Refresh the concurrency note in `omotel.c` if locking expectations change.
- Run `devtools/format-code.sh` before committing.
AI agents working on `omotel` MUST follow the standardized skills in `.agent/skills/`:
## Build & dependencies
- **Efficient Build:** Use `make -j$(nproc) check TESTS=""`.
- **Configure:** Use `--enable-omotel` to enable this module.
- **Build**: Use [`rsyslog_build`](../../.agent/skills/rsyslog_build/SKILL.md) (requires `--enable-omotel`).
- **Test**: Use [`rsyslog_test`](../../.agent/skills/rsyslog_test/SKILL.md).
- **Policy**: Run `tests/omotel-http-batch.sh` to exercise the HTTP batching path.
- **Doc**: Use [`rsyslog_doc`](../../.agent/skills/rsyslog_doc/SKILL.md).
- **Module**: Use [`rsyslog_module`](../../.agent/skills/rsyslog_module/SKILL.md) and keep `MODULE_METADATA.yaml` current.
## Testing
- Run `tests/omotel-http-batch.sh` to exercise the HTTP batching, gzip, and
retry path.
## Module Specifics
- **Dependencies**: Keep the module pure C unless gRPC is enabled.
- **Normalization**: Run `devtools/format-code.sh` before committing (see `rsyslog_commit`).

31
plugins/omruleset/AGENTS.md
View File

@ -1,28 +1,15 @@
# AGENTS.md – omruleset compatibility module
## Module overview
- Historical helper that forwards a message to another ruleset.
- Replaced by the RainerScript `call` statement; retained only for backward compatibility.
- User documentation: `doc/source/configuration/modules/omruleset.rst`.
- Support status: core-supported. Maturity: deprecated.
## Workflow & Skills
## Build & dependencies
- Built automatically when plugins are enabled; no extra configure flags or external dependencies.
- **Efficient Build:** Use `make -j$(nproc) check TESTS=""`.
- **Bootstrap:** Run `./autogen.sh` only when autotools inputs change.
AI agents working on `omruleset` MUST follow the standardized skills in `.agent/skills/`:
## Local testing
- There is no standalone test suite for `omruleset`. Building rsyslog with `make` is sufficient validation.
- When refactoring, rely on configuration-level tests that exercise ruleset chaining rather than new module-specific scripts.
- **Build**: Use [`rsyslog_build`](../../.agent/skills/rsyslog_build/SKILL.md).
- **Test**: Use [`rsyslog_test`](../../.agent/skills/rsyslog_test/SKILL.md).
- **Module**: Use [`rsyslog_module`](../../.agent/skills/rsyslog_module/SKILL.md).
## Diagnostics & troubleshooting
- Failures typically stem from queueing semantics or recursion in user configurations. Encourage migrating to the `call` statement where possible.
- Review `doc/source/configuration/modules/omruleset.rst` for historical caveats around queue saturation and message loss.
## Module Specifics
## Cross-component coordination
- Document any behavior-affecting changes in `doc/source/configuration/modules/omruleset.rst` and update migration notes that point to the `call` statement.
- Audit related examples in `doc/source/configuration/modules/omfile.rst` and `doc/source/rainerscript/` if you touch shared queue guidance.
## Metadata & housekeeping
- Keep `plugins/omruleset/MODULE_METADATA.yaml` marked as `deprecated` and refresh the review date when compatibility fixes land.
- If the module is ever removed, update the documentation and release notes to highlight the required migration.
- **Status**: Maturity is **deprecated**. Replaced by RainerScript `call` statement.
- **Testing**: No standalone suite; rely on configuration-level tests.
- **Coordination**: Update migration notes in documentation when fixing compatibility issues.