feat: S14.10 custom-SD integrator guide + example (#549)#562
Merged
Conversation
Add BddTargetCustomSd (Bdd/Targets/Common) — a minimal worked custom SD-ELEMENT emitting [example@32473 detail="..."], the detail value containing ", \ and ] so the upcoming oracle round-trip BDD can prove the library applies RFC 5424 PARAM-VALUE escaping. Wire a 'send-custom' interactive command that emits it via SolidSyslog_LogWithSd, so all four BDD targets (Linux/Windows/FreeRtos/ FreeRtosLwip) expose it from the one shared Common runner. Registered in every target build + BddTargetTests. Unit tests: the SD's escaped output and the command dispatch/count. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Author docs/structured-data.md — the custom-SD integrator guide: the two-type writer model (SdElement + SdValue), implementing a Format vtable with the embed-base downcast for stateful data, SD-IDs / enterprise numbers, registering via Config.Sd[] and SolidSyslog_LogWithSd (with the reentrancy note), and what the library owns vs the integrator. Written around the real BddTargetCustomSd. Simplify the worked custom SD to detail="Hello World" (per review — a clear example, not muddied by escaped data). Add custom_sd.feature + a send-custom/detail step pair (run_example gains a command arg) proving the custom element round-trips through the oracle. Per David: the dedicated escape round-trip oracle BDD is dropped — value escaping is already covered by the SdValue unit tests, and the syslog-ng/OTEL oracles re-render an escaped value differently, so an oracle assertion there tests the oracle, not the library. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
📝 WalkthroughWalkthroughThis PR introduces a custom structured data example and integrator guide. A new BDD target module ( ChangesCustom Structured Data Example & Documentation
Sequence DiagramsequenceDiagram
participant User
participant BDD
participant Interactive as BddTarget<br/>Interactive
participant SolidSyslog
participant Formatter
participant Oracle
User->>BDD: run custom_sd.feature
BDD->>Interactive: send-custom 1
Interactive->>SolidSyslog: LogWithSd(msg, custom_sd)
SolidSyslog->>Formatter: CustomSd_Format()
Formatter->>Formatter: emit example@32473<br/>detail="Hello World"
SolidSyslog->>Oracle: deliver syslog message
BDD->>Oracle: assert detail="Hello World"
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related issues
Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@DEVLOG.md`:
- Around line 14749-14752: Update the DEVLOG entry for custom_sd by replacing
the “authored but not yet run” status with the actual executed state (or append
an explicit runtime context): locate the paragraph referencing
custom_sd.feature, behave, and the `@udp` custom_sd scenario and either change the
phrase to indicate it "passed" (e.g., "custom_sd.feature — executed and passed
on <date>") or add a parenthetical note with the run date, environment (WSL),
and confirmation of the detail "Hello World" round-trip so the release notes
aren’t stale.
In `@docs/structured-data.md`:
- Around line 6-8: The fenced code block containing the example line
[example@32473 detail="Hello World"] is missing a language tag and triggers
MD040; add a language identifier (e.g., text or syslog) to the opening fence so
it reads ```text (or ```syslog) before the line and keep the closing ```
unchanged to satisfy the linter and preserve the example content.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 49dcd2b6-f0f0-47c3-83ff-5781eea7e3a4
📒 Files selected for processing (13)
Bdd/Targets/CMakeLists.txtBdd/Targets/Common/BddTargetCustomSd.cBdd/Targets/Common/BddTargetCustomSd.hBdd/Targets/Common/BddTargetInteractive.cBdd/Targets/FreeRtos/CMakeLists.txtBdd/Targets/FreeRtosLwip/CMakeLists.txtBdd/features/custom_sd.featureBdd/features/steps/syslog_steps.pyDEVLOG.mdTests/Bdd/Targets/BddTargetCustomSdTest.cppTests/Bdd/Targets/BddTargetInteractiveTest.cppTests/Bdd/Targets/CMakeLists.txtdocs/structured-data.md
Comment on lines
+14749
to
+14752
| ### Pending → WSL | ||
| - The `custom_sd.feature` oracle round-trip is **authored but not yet run** — `behave` needs | ||
| the docker/syslog-ng oracle, which runs from WSL, not the devcontainer. Next step: pull the | ||
| branch in WSL, run the `@udp` `custom_sd` scenario, confirm `detail "Hello World"` round-trips. |
Contributor
There was a problem hiding this comment.
Update validation status to avoid stale release notes.
This “not yet run” note conflicts with the PR objective/status context indicating custom_sd.feature already passed. Please align this section with the final executed state (or add explicit run date/context if it was pending at entry time).
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@DEVLOG.md` around lines 14749 - 14752, Update the DEVLOG entry for custom_sd
by replacing the “authored but not yet run” status with the actual executed
state (or append an explicit runtime context): locate the paragraph referencing
custom_sd.feature, behave, and the `@udp` custom_sd scenario and either change the
phrase to indicate it "passed" (e.g., "custom_sd.feature — executed and passed
on <date>") or add a parenthetical note with the run date, environment (WSL),
and confirmation of the detail "Hello World" round-trip so the release notes
aren’t stale.
Comment on lines
+6
to
+8
| ``` | ||
| [example@32473 detail="Hello World"] | ||
| ``` |
Contributor
There was a problem hiding this comment.
Add a language tag to the fenced example block.
This code fence is missing a language identifier and triggers MD040. Add text (or syslog) to keep lint green.
Proposed fix
-```
+```text
[example@32473 detail="Hello World"]</details>
<!-- suggestion_start -->
<details>
<summary>📝 Committable suggestion</summary>
> ‼️ **IMPORTANT**
> Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
```suggestion
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 6-6: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/structured-data.md` around lines 6 - 8, The fenced code block containing
the example line [example@32473 detail="Hello World"] is missing a language tag
and triggers MD040; add a language identifier (e.g., text or syslog) to the
opening fence so it reads ```text (or ```syslog) before the line and keep the
closing ``` unchanged to satisfy the linter and preserve the example content.
Source: Linters/SAST tools
Contributor
☀️ Quality Summary 🚦 build-linux-gcc: 100% successful (✔️ 1521 passed) Created by Quality Monitor v1.14.0 (#f3859fd). More details are shown in the GitHub Checks Result. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Purpose
Closes #549 — the user-facing payoff of the E14 (#64) foundation wave, and E14's
last story. Documents and demonstrates authoring a custom SD-ELEMENT with the
safe two-type SD writer API (
SolidSyslogSdElement/SolidSyslogSdValue) addedearlier in the epic, attached per-message via
SolidSyslog_LogWithSd(S14.09).Change Description
docs/structured-data.md— fleshed out into a full custom-SD integrator guide:implementing
Format(base, element), registering an SD inConfig.Sd[], thecustom SD-ID
name@enterpriseconvention + enterprise-number guidance, valueescaping/streaming, the JSON-in-value pattern, and fail-loud name validation.
Bdd/Targets/Common/BddTargetCustomSd.{c,h}emits[example@32473 detail="Hello World"]. Lives in Common so all four BDDtargets expose it (not Linux-only), registered in each target build +
BddTargetTests.send-custominteractive command (BddTargetInteractive.c) emits the workedelement via
SolidSyslog_LogWithSd.Bdd/features/custom_sd.feature(@udp, one scenario)syslog_steps.py: the custom element reaches syslog-ng anddetaildecodes to
Hello World.The dedicated escape round-trip oracle BDD (originally folded in from S07.04 #68) was
dropped — see the note on #549. Escaping is unit-tested at the
SolidSyslogSdValuelevel; an oracle assertion on escaped output tests how syslog-ng (vs OTEL) re-renders
the value, not the library.
Test Evidence
BddTargetTests68/68 green (includes newBddTargetCustomSdTest.cppand theBddTargetInteractiveTest.cppsend-customcase).gccdocker compose service;custom_sd.featurepasses against the real syslog-ng oracle (1 feature / 1 scenario / 3 steps green).
Areas Affected
docs/structured-data.md,Bdd/Targets/Common/, the four BDD target builds,Bdd/features/(feature + steps),Tests/Bdd/Targets/. Tier-3 BDD-target code +docs only — no Core/Platform changes.
Summary by CodeRabbit
New Features
Documentation
Tests