index.md

Documentation

Welcome to the Fluent Bit & Fluentd OpAMP implementation docs. This page links to the core guides and outlines where to look for configuration, scripts, and feature notes.

Core guides

• Setup README — full setup and run instructions.
• Features - spec alignment — feature notes and design direction.
• UI examples - Some of the elements of the UI to illustrate the user experience.
• Design & Implementation principles — project architecture and engineering principles.
• Command_process_implementation_notes — command API/queue/dispatch implementation details.
• How to add_your_own_custom_action — how to implement and deploy a custom provider+consumer action using nullcommand as the baseline.
• Client (consumer)_diagram (in Mermaid format) — consumer client architecture and runtime relationship diagrams.
• Client (consumer)_diagrams (as images) — rendered consumer diagrams with explanation per diagram panel.
• Server (provider)_server_diagrams (in Mermaid format) — provider/server Mermaid source diagrams.
• Server_(provider) diagrams (as images) — rendered provider/server diagrams plus links to auth, endpoints, and command docs.
• Client (consumer) use of mixins — how consumer mixins are composed, dispatched, and overridden.
• Client (consumer) custom_handlers — built-in custom handlers, runtime discovery, and how to implement/deploy additional handlers.
• Client (consumer)_update_controllers — how full update controllers drive reporting flags and outbound message field cadence.
• Authentication — bearer token auth modes, static-token setup, Keycloak/JWT setup, and MCP token usage.
• Web Endpoints — provider endpoint inventory, including UI/API/tool/MCP routes and /doc-set.
• Self_signed_TLS_setup — generate local self-signed cert/key and apply config values for HTTPS testing.
• API_gateway_suggested use and requirements — recommended API gateway controls, internal vs external client profiles, and required auth/route hardening updates.
• Service_daemon_setup — running provider/consumer as systemd or Windows services, including Fluent Bit/Fluentd launch permissions.
• Client README — client/agent (aka consumer) configuration and CLI usage.
• Server README — server (aka provider) configuration and web UI notes.
• Server state persistence — snapshot naming, --restore usage, fallback behavior, and retention.
• MCP scripts and usage — MCP wrapper/canonical script behavior, FastMCP client role, command-line parameters, and verification.
• Agent broker README — optional standalone conversation broker overview and run steps.
• Agent broker docs index — broker runbooks (startup/shutdown/logging, Slack setup, architecture notes).
• Scripts — script reference table by platform.
• Component Versioning — git commit/date version metadata and where it appears in CLI/UI help.

Optional components

• agent_broker is optional and runs as a separate process.
• Provider/server and consumer/client do not require the broker to run.
• If used, start and stop the broker independently from provider and consumer.

Documentation Rules

• Treat dev-notes/ as internal working notes only.
• Do not cross reference dev-notes/ content from formal project documentation (README.md, docs/, component READMEs, broker docs, or UI help pages).

Project layout (quick view)

• agent_broker — optional standalone conversation broker package and docs.
• config — default configuration files (including opamp.json).
• consumer — the OpAMP consumer (client) package, tests, and config samples.
• dist — SBOM (Software Bill of Materials) and Wheel files
• docs — project documentation.
• logs — runtime logs created by scripts.
• server-state — state snapshot folder created when provider state persistence writes snapshots (folder name follows provider.state_persistence.state_file_prefix parent path).
• proto — protobuf definitions and generated artifacts.
• provider — the OpAMP provider (server) package, UI, and tests.
• scripts — helper run and shutdown scripts.
• shared — shared utilities used by provider/consumer.
• src — top-level Python package glue (if needed for tooling).
• tests — repository-level tests.

Reference 3rd Party Documents

• Open Agent Management Protocol (OpAMP) Specification
• Cloud Native Computing Foundation (CNCF)
• OpenTelemetry at CNCF
• Model Context Protocol (MCP) specification - optional feature
• Fluentd
• Fluent Bit
• Manning - Logging in Action — Fluentd-focused coverage with Kubernetes and related observability workflows.
• Manning - Logs and Telemetry — Fluent Bit, Kubernetes, streaming, and OpenTelemetry-oriented coverage.
• Quart (foundation of the implementation)
• HAProxy (optional feature, to support advanced security permutations)
• OpAMP posts on blog.mp3monster.org — external blog posts and updates.

3rd Party Development Tools

• pytest — unit and integration test execution.
• Ruff — linting/security checks (including --select S rules).
• detect-secrets — repository secret scanning during security checks.
• pip-audit — Python dependency vulnerability scanning.
• esbuild — JavaScript minification for provider UI compact assets.
• CycloneDX — SBOM format used for generated provider/consumer deployable artifact manifests.