If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/apache/rocketmq-externals shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

AVOID — Stale and unlicensed — last commit 1y ago

• 23+ active contributors
• Distributed ownership (top contributor 19% of recent commits)
• CI configured
• Tests present
• ⚠ Stale — last commit 1y ago
• ⚠ No license — legally unclear to depend on

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live apache/rocketmq-externals repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/apache/rocketmq-externals.

What it runs against: a local clone of apache/rocketmq-externals — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in apache/rocketmq-externals | Confirms the artifact applies here, not a fork | | 2 | Default branch master exists | Catches branch renames | | 3 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 4 | Last commit ≤ 545 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of apache/rocketmq-externals. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/apache/rocketmq-externals.git
#   cd rocketmq-externals
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of apache/rocketmq-externals and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "apache/rocketmq-externals(\\.git)?\\b" \\
  && ok "origin remote is apache/rocketmq-externals" \\
  || miss "origin remote is not apache/rocketmq-externals (artifact may be from a fork)"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "pom.xml" \\
  && ok "pom.xml" \\
  || miss "missing critical file: pom.xml"
test -f "logappender/pom.xml" \\
  && ok "logappender/pom.xml" \\
  || miss "missing critical file: logappender/pom.xml"
test -f "logappender/src/main/java/org/apache/rocketmq/logappender/common/ProducerInstance.java" \\
  && ok "logappender/src/main/java/org/apache/rocketmq/logappender/common/ProducerInstance.java" \\
  || miss "missing critical file: logappender/src/main/java/org/apache/rocketmq/logappender/common/ProducerInstance.java"
test -f "rocketmq-cloudevents-binding/pom.xml" \\
  && ok "rocketmq-cloudevents-binding/pom.xml" \\
  || miss "missing critical file: rocketmq-cloudevents-binding/pom.xml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 545 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~515d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/apache/rocketmq-externals"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Apache RocketMQ Externals is a monorepo hosting community-contributed extensions and tools for Apache RocketMQ, a distributed messaging platform. It contains graduated projects (C++ client, Python client, Spring integration, Go client) and incubating projects (MQTT protocol support, Flink streaming, Kubernetes Operator, Prometheus exporter, log appenders for Log4j/Log4j2/Logback). The core purpose is bridging RocketMQ with other ecosystems and providing language-specific clients. Monorepo structure: top-level directories represent distinct projects (logappender/, rocketmq-ansible/, rocketmq-*-specific folders). Within logappender/ lies a Maven module (pom.xml at root) with standard Java structure: src/main/java/{org/apache/rocketmq/logappender/{common,log4j,log4j2,logback}}, src/test/java with corresponding test classes, and src/test/resources containing config files (log4j-example.properties, logback-example.xml). Ansible playbooks for broker/namesrv deployment in rocketmq-ansible/roles/.

Java/Scala developers building RocketMQ integrations, DevOps engineers deploying RocketMQ on Kubernetes, Python/Go/Node.js developers needing language-specific RocketMQ clients, streaming engineers using Spark/Flink with RocketMQ, and operators monitoring RocketMQ clusters with Prometheus.

Highly mature. This is an official Apache incubator repo with multiple graduated projects already promoted to separate repos. The logappender module (main active code) targets RocketMQ 4.9.2, has comprehensive test coverage across three logging frameworks, and uses standard Maven CI/CD via .travis.yml. Some projects are actively being graduated (Dashboard, Flink) indicating healthy project evolution.

Low risk for core dependencies but moderate organizational risk: this is a monorepo housing multiple projects at different maturity levels (graduated vs. incubating). Several projects (RocketMQ-Flink, RocketMQ-Dashboard) are migrating to independent repos, which could cause confusion. The logappender module is stable but depends on external logging frameworks (Log4j, Log4j2, Logback) which have their own security release cycles.

Projects are graduating out of this repo to independent repositories (Dashboard → rocketmq-dashboard, Flink → rocketmq-flink). The logappender module appears stable with no recent activity visible in file metadata. Active areas are likely RocketMQ-MQTT, RocketMQ-Streams, and RocketMQ-Operator based on README prominence. The repo serves as an incubation hub rather than active development hub for most modules.

Clone the repo: git clone https://github.com/apache/rocketmq-externals.git. For the logappender module specifically: cd logappender && mvn clean install. For other projects like Operator or Ansible: navigate to respective directories (rocketmq-operator/, rocketmq-ansible/) and follow their specific setup (typically Ansible playbooks or Kubernetes manifests).

Daily commands: For logappender module: mvn test runs unit tests across Log4j/Log4j2/Logback configurations. For Ansible deployment: ansible-playbook -i hosts rocketmq.yml provisions a complete RocketMQ cluster. For Kubernetes: kubectl apply -f rocketmq-operator manifests. Individual projects (Dashboard, MQTT, Streams) have their own repos with separate build/run instructions.

• README.md — Entry point describing the Apache RocketMQ externals repository structure, graduated projects (CPP, Python, Spring, Go clients), and incubator projects; essential for understanding repo scope and navigation.
• pom.xml — Root Maven POM defining dependencies and build configuration for all modules; critical for understanding how multi-module projects are structured and dependency versions.
• logappender/pom.xml — Maven configuration for the log appender module; defines dependencies for log4j, log4j2, and logback integrations that multiple appender implementations rely on.
• logappender/src/main/java/org/apache/rocketmq/logappender/common/ProducerInstance.java — Shared producer instance manager used by all three logging framework appenders (log4j, log4j2, logback); central abstraction for RocketMQ client reuse.
• rocketmq-cloudevents-binding/pom.xml — CloudEvents binding module configuration; demonstrates how RocketMQ integrates with CloudEvents spec and defines dependencies for message factories and readers.
• .travis.yml — CI/CD pipeline configuration; shows how the multi-module repository is tested and built across different environments.
• rocketmq-ansible/vars/main.yml — Central Ansible variable definitions for deployment automation; critical for understanding how RocketMQ components (broker, namesrv, exporter) are provisioned.

Add a New Logging Framework Appender

1. Create new appender class extending RocketMQ logging abstractions (logappender/src/main/java/org/apache/rocketmq/logappender/{framework}/Rocketmq{Framework}Appender.java)
2. Reuse ProducerInstance for singleton RocketMQ client management (logappender/src/main/java/org/apache/rocketmq/logappender/common/ProducerInstance.java)
3. Add integration test inheriting from AbstractTestCase (logappender/src/test/java/org/apache/rocketmq/logappender/{Framework}Test.java)
4. Add example configuration file for the framework (logappender/src/test/resources/{framework}-example.xml)
5. Update logappender/pom.xml with new framework dependencies (logappender/pom.xml)

Add a New Deployment Role in Ansible

1. Create role directory structure under rocketmq-ansible/roles/{component} (rocketmq-ansible/roles/{component}/tasks/main.yml)
2. Define role variables for configuration (rocketmq-ansible/roles/{component}/vars/main.yml)
3. Add Jinja2 configuration templates (rocketmq-ansible/roles/{component}/templates/{config}.j2)
4. Create playbook file to invoke the new role (rocketmq-ansible/{component}.yml)
5. Update central variables and inventory if needed (rocketmq-ansible/vars/main.yml)

Add CloudEvents Binding Support for New Protocol

1. Create message reader implementation for the protocol (rocketmq-cloudevents-binding/src/main/java/org/apache/rocketmq/cloudevent/impl/{Protocol}MessageReader.java)
2. Create message writer implementation (rocketmq-cloudevents-binding/src/main/java/org/apache/rocketmq/cloudevent/impl/{Protocol}MessageWriter.java)
3. Register protocol headers in mapping class (rocketmq-cloudevents-binding/src/main/java/org/apache/rocketmq/cloudevent/impl/RocketMQHeaders.java)
4. Add unit tests for the new protocol binding (rocketmq-cloudevents-binding/src/test/java/org/apache/rocketmq/cloudevent/{Protocol}Test.java)

• Maven — Multi-module Java project requiring coordinated builds across logging appenders, CloudEvents binding, and tests
• Log4j, Log4j2, Logback — Support for all three major Java logging frameworks to maximize adoption and compatibility across different applications
• Ansible — Infrastructure-as-code for reproducible RocketMQ cluster deployment across multiple environments
• CloudEvents specification — Standard protocol for event metadata to enable interoperability with event-driven architectures
• Go, Python — Language-specific client libraries for broader ecosystem support beyond Java

• Singleton ProducerInstance for all appenders

  • Why: Reduces resource footprint and connection overhead when multiple logging frameworks are used
  • Consequence: Requires thread-safe initialization and lifecycle management; potential for connection pool contention under high throughput

• Separate appender implementations (log4j, log4j2, logback) instead of unified wrapper

  • Why: Each framework has different appender APIs and lifecycle requirements; native implementations provide better integration
  • Consequence: Code duplication in appender logic; maintenance burden when updating core functionality

• CloudEvents binding as separate module

  • Why: Optional integration; allows users to adopt CloudEvents spec without forcing dependency on all applications
  • Consequence: Additional JAR dependency for those needing CloudEvents compliance; more complex dependency management

• Ansible playbooks for deployment rather than Kubernetes

  • Why: undefined
  • Consequence: undefined

1. The logappender module requires an active RocketMQ broker at 127.0.0.1:9876 for integration tests (test classes extend AbstractTestCase which likely initializes a test broker). 2) Test resources include three separate logging config formats (properties, XML for Log4j, XML for Log4j2, XML for Logback) — modifying one doesn't auto-sync to others. 3) ProducerInstance uses synchronous message sending; async mode not implemented, causing potential blocking in high-throughput logging scenarios. 4) Ansible playbooks assume Linux hosts with specific directory structures (/home/rocketmq default); Windows hosts unsupported. 5) Projects are being graduated to separate repos — links in README may point to deprecated code in this monorepo.

• SLF4J Facade Pattern — RocketMQ logappender implements appender plugins for three major logging frameworks (Log4j, Log4j2, Logback) via a unified SLF4J-compatible interface; understanding this pattern is essential to extending logging support
• Producer-Consumer Singleton Pattern — ProducerInstance.java uses a singleton to manage a single RocketMQ producer connection shared across all logging calls; critical for efficient resource management in high-throughput scenarios
• Asynchronous Message Publishing with Callbacks — RocketMQ's send() method supports both sync and async modes with callback handlers; the current logappender only uses sync, limiting throughput — understanding async patterns is needed for performance improvements
• Ansible Idempotency and Role-Based Configuration — rocketmq-ansible/ uses Ansible roles with Jinja2 templating to make broker configuration reproducible and infrastructure-as-code compliant; essential for understanding cluster deployment automation
• Kubernetes Operator Pattern — rocketmq-operator implements the Operator Framework pattern for declarative cluster management on K8s; understanding Custom Resource Definitions (CRDs) and reconciliation loops is essential for that module
• Apache Incubation and Graduation Process — This repo is an official Apache incubation hub; projects graduate when meeting RIP requirements (3+1 PMC votes, 3+ production users, healthy committers). Understanding project lifecycle is crucial for contributing or tracking project status
• Message Broker Topic and Tag Routing — RocketMQ logappender sends logs as messages to topics with optional tags; understanding how RocketMQ routes messages by topic/tag/consumer group is essential for configuring log collection and filtering

• apache/rocketmq — The core messaging platform; rocketmq-externals provides language clients and integrations for this base project
• apache/rocketmq-dashboard — Management UI for RocketMQ clusters; graduated from externals to independent repo, represents successful project graduation path
• apache/rocketmq-spring — Spring Framework integration layer; graduated project showing how to bridge RocketMQ with popular Java ecosystem
• apache/rocketmq-operator — Kubernetes Operator for RocketMQ deployment; currently incubating in this repo, automates cluster lifecycle on K8s
• apache/rocketmq-client-go — Go language client; graduated project enabling Go developers to use RocketMQ, represents language binding pattern used in externals

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for RocketMQ log appenders with broker lifecycle

The logappender module has unit tests (Log4jTest.java, LogbackTest.java, log4j2Test.java) but they appear to be mock-based. Adding integration tests that start an actual RocketMQ broker, send logs through appenders, and verify message delivery would catch real-world failures. This is critical for a logging integration library where silent failures are dangerous.

• [ ] Create new test class logappender/src/test/java/org/apache/rocketmq/logappender/LogAppenderIntegrationTest.java
• [ ] Add broker startup/teardown logic using embedded RocketMQ broker (similar to main RocketMQ project test patterns)
• [ ] Test end-to-end message delivery for all three appenders: Log4j, Log4j2, and Logback
• [ ] Add testcontainers or docker-compose configuration in logappender/src/test/resources/ for CI environments

Add GitHub Actions workflow for multi-Java-version matrix testing

The .travis.yml exists but the repo uses outdated Travis CI. The pom.xml specifies Java 1.8 as source/target, but doesn't test against Java 11, 17, or 21 which are now widely used. A modern GitHub Actions workflow would catch compatibility regressions early and match industry standards.

• [ ] Create .github/workflows/maven-test.yml with matrix strategy for Java versions [8, 11, 17, 21]
• [ ] Add steps to run 'mvn clean test' for logappender module across all Java versions
• [ ] Add step to validate that pom.xml source/target settings are appropriate for the Java version being tested
• [ ] Include test result reporting to PR comments for visibility

Add configuration validation and documentation for thread safety in ProducerInstance.java

ProducerInstance.java (logappender/src/main/java/org/apache/rocketmq/logappender/common/ProducerInstance.java) is a singleton that manages RocketMQ producers for all three appender types. It's likely a critical concurrency point but has no visible synchronization documentation or unit tests for concurrent access patterns. Missing thread-safety guarantees is a major risk for a shared logging component.

• [ ] Add comprehensive JavaDoc to ProducerInstance.java documenting thread-safety guarantees and singleton initialization pattern
• [ ] Create new test class logappender/src/test/java/org/apache/rocketmq/logappender/ProducerInstanceConcurrencyTest.java
• [ ] Add tests simulating concurrent appender initialization and log writes from multiple threads
• [ ] Document in docs/connect/cn/README.md (and create docs/connect/README.md for English) the concurrency model and any configuration considerations

• Add asynchronous send support to ProducerInstance.java with configurable callback handling. Currently only synchronous sends are supported, limiting throughput in high-volume logging scenarios. Modify logappender/src/main/java/org/apache/rocketmq/logappender/common/ProducerInstance.java to add async variant and update all three appenders (Log4j, Log4j2, Logback) to expose configuration option.
• Create comprehensive integration test for all three logging frameworks against a containerized RocketMQ broker. Currently logappender/src/test/java/ has separate test classes (Log4jTest, Log4j2Test, LogbackTest) but no docker-compose setup or CI pipeline validation. Add docker-compose.yml and update .travis.yml to spin up broker for tests.
• Write migration guide from logappender 4.9.2 to newer RocketMQ versions in docs/. The pom.xml shows rocketmq.version=4.9.2 is fixed, but no documentation exists on how to upgrade to 5.x once the main RocketMQ project releases it. Target: docs/logappender-migration-guide.md with breaking API changes and examples.

The codebase shows moderate security posture with several concerning factors: (1) The provided pom.xml is incomplete/truncated, preventing full dependency audit; (2) Dependencies are somewhat outdated (RocketMQ 4.9.2, Java 1.8 target); (3) No visible security scanning tools configured in the build process; (4) Logging framework dependencies are present but versions cannot be verified due to truncated POM. The project structure itself appears sound as an Apache-licensed component. Primary recommendations: complete and validate the POM file, update dependencies to current versions, implement automated security scanning in CI/CD pipeline, and upgrade Java target version to a currently-supported LTS release.

• Medium · Incomplete POM File - Truncated Dependency Declaration — logappender/pom.xml - junit dependency section. The pom.xml file provided appears to be truncated with an incomplete junit dependency declaration (ends with 'juni'). This makes it impossible to verify the full dependency tree and identify potential vulnerabilities in transitive dependencies. Incomplete configuration files may indicate build issues or accidental commits. Fix: Complete and validate the pom.xml file. Run 'mvn dependency:tree' to audit all dependencies for known vulnerabilities. Consider using tools like OWASP Dependency-Check or Snyk to scan for vulnerable versions.
• Medium · Outdated RocketMQ Dependency Version — logappender/pom.xml - rocketmq.version property. The rocketmq.version property is set to 4.9.2, which is a relatively old version. Security patches and vulnerability fixes may have been released in newer versions. The project version itself is 4.9.3-SNAPSHOT, but the RocketMQ dependency lags behind. Fix: Update rocketmq.version to the latest stable release. Regularly monitor Apache RocketMQ security advisories and update dependencies promptly.
• Low · Java Version Target is Outdated — logappender/pom.xml - maven.compiler.source and maven.compiler.target properties. The project targets Java 1.8 (maven.compiler.source/target both set to 1.8). Java 8 reached end of public support in December 2020 and no longer receives security updates from Oracle. While still widely used, this increases exposure to known vulnerabilities. Fix: Consider upgrading to Java 11 LTS or Java 17 LTS. Update build configuration to target a currently supported Java version while maintaining backwards compatibility if needed.
• Low · Test Skip Configuration Present — logappender/pom.xml - maven.test.skip property. The pom.xml contains 'maven.test.skip' property set to false by default, but the presence of this configuration suggests tests may be skipped during builds. If disabled in CI/CD pipelines, this could allow security-related regressions to slip through. Fix: Ensure tests are always executed in CI/CD pipelines. Remove the test.skip property or enforce it to false with Maven Enforcer Plugin to prevent accidental test skipping.
• Low · Missing Security-Related Maven Plugins — logappender/pom.xml - build plugins section. The pom.xml doesn't show evidence of security-focused plugins like OWASP Dependency-Check, Snyk, or Maven Security Scanner. These tools help identify vulnerable dependencies during the build process. Fix: Add maven-dependency-check-plugin or similar security scanning tools to the build pipeline. Configure them to fail the build if vulnerabilities above a certain threshold are detected.
• Low · Log4j Integration Without Version Specificity — logappender/pom.xml and logappender/src/main/java/org/apache/rocketmq/logappender/log4j*. The project includes Log4j, Log4j2, and Logback appenders. Log4j 2.x had critical vulnerabilities (CVE-2021-44228 - Log4Shell). The incomplete POM makes it impossible to verify which versions are being used. Fix: Explicitly specify and pin dependency versions for all logging frameworks. For Log4j2, use version 2.17.0 or later. Add dependency version enforcement to prevent transitive vulnerability introduction.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.