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.

Build quick map

Use these docs for repository builds and deployable artefacts:

• Scripts — repo-wide build, packaging, SBOM, and helper script reference.
• Setup README — overall component and runtime map.
• Component Versioning — how git-derived version metadata is refreshed before packaging.
• MCP scripts and usage — MCP tool wheel, sdist, and SBOM flow.
• Standalone Packaging — standalone config-service packaging and SBOM flow.
• Cloud operator guide — provider-neutral lifecycle, retained evidence, cleanup, and workflow control.
• AWS deployment — command-line and GitHub Actions deployment of the two-instance regression environment.
• Azure deployment — ARM deployment of the equivalent two-VM regression environment.

Primary repository-wide build outputs now include independent artefacts for:

• provider
• consumer
• config-service
• catalog-service
• client-config-generator-service
• cli
• consumer-sim

Core guides

• Product installation — choose and install the core provider, standalone or embedded editors, catalog, agent configuration generator, wheel files, automation, and CLI tools.
• Setup README — full setup and run instructions.
• Features - spec alignment — feature notes and design direction.
• Roadmap — future ideas under consideration, without timeline commitments.
• UI examples - Some of the elements of the UI to illustrate the user experience.
• Client (consumer)_diagrams (as images) — rendered consumer diagrams with explanation per diagram panel.
• Consumer implementations — built-in consumer/client matrix with OpAMP capability support and upstream agent reference links.
• Server_(provider) diagrams (as images) — rendered provider/server diagrams plus links to auth, endpoints, and command docs.
• 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.
• Provider metrics reference — metric-by-metric explanation of the provider scrape endpoint and internal graph data.
• Prometheus and collector setup — how to scrape /metrics securely from Prometheus or the OpenTelemetry Collector.
• The provider-hosted Latest docs entry point is http://localhost:8080/doc-set, which redirects to the URL configured in provider.latest_docs_url.
• OpAMP JSON reference map — guide to which docs explain each top-level section of config/opamp.json.
• Provider config reference — dedicated reference for provider.* values, defaults, and UI editability.
• OTLP observability config — shared otlp-endpoints settings for logs, metrics, and traces export.
• OpAMP Config Catalog UI — configuration-driven catalog index page and help route details.
• 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.

Development guides

• Development docs index — implementation internals, extension points, build workflows, and source diagrams.
• 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.
• Server (provider)_server_diagrams (in Mermaid format) — provider/server Mermaid source diagrams.
• 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.
• OpAMP Config Catalog Service Prompt — implementation prompt and scope for the catalog service.
• UI Consistency Checklist — PR checklist for consistent UI architecture, libraries, routing, and verification.
• 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 — generated wheels, source distributions, manuals, and SBOM outputs
• 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 deployable artifact manifests.