Troubleshooting Apache Felix Log: Common Errors and FixesApache Felix is a popular OSGi runtime that many Java developers use to build modular applications. Logging is a crucial tool for diagnosing issues in an OSGi environment, but Felix’s logging behavior and integration with different logging frameworks can sometimes be confusing. This article walks through common Apache Felix logging problems, explains their causes, and gives practical fixes and examples.
Overview of Apache Felix logging
Apache Felix supports OSGi logging through the OSGi Log Service (org.osgi.service.log) and provides its own simple logging implementation. In many setups, you’ll integrate Felix with other logging frameworks such as Log4j2, Logback, or java.util.logging. Understanding where logs originate and which layer handles them is the first step in troubleshooting.
Key facts
- Felix uses the OSGi Log Service (org.osgi.service.log).
- Bundles can use the OSGi LogService, SLF4J, or framework-specific APIs.
- Bridging/adapters are often required to route bundle logging to a single framework.
Common problems and fixes
1) No logs appearing from bundles
Symptoms: Your application seems unresponsive or silent; no bundle-specific log entries appear in the console or file.
Causes:
- The bundle isn’t registering a LogService consumer or isn’t configured to use a logging facade.
- The runtime log level is higher than the bundle’s logging level.
- Logging implementation (service) is not installed or active.
Fixes:
- Ensure a Log Service implementation is installed (e.g., org.apache.felix.log or an SLF4J/Log4j adapter).
- Verify the bundle uses a supported logging API (SLF4J, OSGi LogService). If using java.util.logging or other frameworks, add appropriate bridges/adapters.
- Check configuration for log level. For Felix’s built-in logger, set system property or configuration in config.properties:
org.osgi.framework.log.level=INFO - Confirm the bundle is active and that its logging code executes (add a simple System.out.println temporarily to validate).
Example: Install Felix Log and SLF4J bridge bundles:
bundle:install -s mvn:org.apache.felix/org.apache.felix.log/1.0.6 bundle:install -s mvn:org.slf4j/slf4j-api/1.7.36 bundle:install -s mvn:org.slf4j/org.slf4j.jdk14/1.7.36 2) Duplicate or repeated log entries
Symptoms: Same log message appears multiple times, possibly with different timestamps or sources.
Causes:
- Multiple logging services/adapters are present and each receives the same event.
- Bundles are logging to both a facade (SLF4J) and the underlying implementation directly.
- Event handlers or log listeners are registered more than once.
Fixes:
- Inspect active bundles for multiple logging implementations (Log4j, SLF4J bridge, JUL bridge). Remove or disable redundant ones.
- Ensure only one bridge is active to forward logs to the chosen backend.
- Audit bundle code for direct logging calls in addition to facade usage.
How to list logging bundles in the Felix Gogo shell:
g! lb | grep -i log Then stop/uninstall duplicates:
g! stop <id> g! uninstall <id> 3) Missing stack traces or truncated messages
Symptoms: Exceptions are logged but stack traces are missing or truncated; long messages get cut off.
Causes:
- The logging implementation or OSGi log formatter trims messages.
- Configured maximum message length in the logging service.
- Log consumers that serialize events (remote log collectors) may limit size.
Fixes:
- Configure the logging implementation to include full stack traces. For example, Log4j2’s pattern layout should include %ex or %throwable.
- Check Felix Log configuration properties for max length (some custom implementations may impose limits).
- If using log serialization (remote), increase the transmission size or switch to file-based logs for full details.
Example Log4j2 pattern for full stack trace:
%d{ISO8601} %-5p [%t] %c{1} - %m%n%throwable 4) Log levels not respected (e.g., DEBUG logs missing)
Symptoms: Lower-level logs (DEBUG/TRACE) are not shown even after setting desired levels.
Causes:
- Global framework log level overrides bundle settings.
- Logging backend configuration (Log4j, Logback) has a higher threshold.
- OSGi Log Admin or Config Admin provides different settings per bundle.
Fixes:
- Set bundle-specific logger levels in the concrete logging backend config (logback.xml, log4j2.xml).
- For Felix built-in logging, adjust:
org.osgi.framework.log.level=DEBUG - Use OSGi Config Admin to update specific bundle loggers when supported by the logging implementation/bundle.
Example Logback logger entry:
<logger name="com.example.mybundle" level="DEBUG"/> 5) Logs from embedded libraries not visible
Symptoms: Third-party libraries used inside bundles produce no logs.
Causes:
- Libraries use java.util.logging (JUL) or Log4j directly but no bridge exists.
- Classloader isolation in OSGi prevents libraries from seeing the logging implementation.
Fixes:
- Add appropriate bridge bundles (e.g., jul-to-slf4j, log4j-over-slf4j) to route library logs to the main backend.
- Expose logging API packages from a common fragment or shared bundle so library classloaders can access the facade.
- Use OSGi Boot Delegation or DynamicImport-Package cautiously to let libraries find logging classes.
Example bundles:
bundle:install -s mvn:org.slf4j/jul-to-slf4j/1.7.36 bundle:install -s mvn:org.slf4j/log4j-over-slf4j/1.7.36 6) Remote/centralized logging issues
Symptoms: Logs are not forwarded to a central ELK/Graylog/Splunk server or appear incomplete.
Causes:
- Network or authentication issues between Felix runtime and collector.
- Incorrect appender/handler configuration in your logging backend.
- Formatting/serialization mismatches.
Fixes:
- Test connectivity from the host to the collector (telnet, curl).
- Verify appender configuration in Logback/Log4j2 (host, port, protocol). Enable internal debug logging for Log4j2 with -Dlog4j2.debug=true to see appender initialization issues.
- Ensure log events include necessary metadata (bundle, service) for filtering on the collector.
7) Felix framework logs (framework events) missing
Symptoms: Framework-level events (bundle lifecycle, resolver errors) aren’t visible.
Causes:
- Framework log level is too high or the framework logger is disabled.
- The console/log file is showing only application logs from a different logger.
Fixes:
- Set framework-level logging in config.properties:
org.osgi.framework.log.level=DEBUG - Ensure org.apache.felix.framework bundle is active and not suppressed by configuration.
- Use the Gogo shell to view framework events:
g! us (for unresolved services) g! ss (for bundle status)
Tools and techniques for diagnosis
- Use the Felix Gogo shell for interactive diagnosis:
- lb: list bundles
- log: show log entries (if the log bundle provides it)
- diag
: show bundle resolution problems
- Enable backend debug flags (Log4j2 debug, Logback status) to see startup and appender issues.
- Temporarily add System.out.println or plain java.util.logging to isolate whether the problem is OSGi-related or code-related.
- Capture thread dumps and heap dumps if logs indicate potential deadlock or memory issues.
Example: end-to-end setup with SLF4J + Logback
- Install SLF4J API bundle and an OSGi-friendly Logback bundle (or embed Logback in a bundle).
- Add jul-to-slf4j and log4j-over-slf4j bridges to unify logging.
- Provide a logback.xml in a bundle or in the classpath that configures appenders (console, file, remote).
- Ensure bundles import org.slf4j packages rather than bundling their own SLF4J classes.
Minimal logback.xml snippet:
<configuration> <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> <encoder> <pattern>%date %-5level [%thread] %logger{36} - %msg%n</pattern> </encoder> </appender> <root level="INFO"> <appender-ref ref="STDOUT" /> </root> </configuration> Quick checklist for troubleshooting
- Is a Log Service implementation installed and active?
- Are there multiple logging bridges causing duplicates?
- Is the framework/bundle log level set correctly?
- Do third-party libs need logging bridges?
- Are appenders/remote endpoints reachable and correctly configured?
- Can you reproduce the issue with a simple test bundle?
When to gather diagnostic data
If you still can’t resolve the problem, gather:
- Felix console logs (full)
- list of installed bundles and states (lb output)
- logging configuration files (logback.xml, log4j2.xml)
- system properties related to logging and OSGi
- a small reproducible test case (bundle) that demonstrates logging failure
Share these artifacts with teammates or on community forums for targeted help.
Troubleshooting logging in Apache Felix is largely about understanding which layer (OSGi Log Service, facade, backend) is handling messages and ensuring there’s a single, correctly configured pipeline from the bundle to the sink. With the checklist and fixes above you should be able to resolve most common issues and get reliable, readable logs from your OSGi-based applications.
Leave a Reply