[skywalking-java] branch main updated: How to make SkyWalking agent works in `OSGI` environment? (#450)

[wu...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

wusheng pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/skywalking-java.git


The following commit(s) were added to refs/heads/main by this push:
     new b4bf6fd75d How to make SkyWalking agent works in `OSGI` environment? (#450)
b4bf6fd75d is described below

commit b4bf6fd75d97d83aae42e808086340d1bbf421e0
Author: 2han9wen71an <2h...@gmail.com>
AuthorDate: Sat Feb 4 19:29:41 2023 +0800

    How to make SkyWalking agent works in `OSGI` environment? (#450)
---
 CHANGES.md          |  2 +-
 docs/en/faq/osgi.md | 30 ++++++++++++++++++++++++++++++
 docs/menu.yml       |  2 ++
 3 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index b3f28ffc94..0253fb8823 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -16,7 +16,7 @@ Release Notes.
 #### Documentation
 * Update docs of Tracing APIs, reorganize the API docs into six parts.
 * Correct missing package name in native manual API docs.
-
+* Add a FAQ doc about "How to make SkyWalking agent works in `OSGI` environment?"
 
 All issues and pull requests are [here](https://github.com/apache/skywalking/milestone/168?closed=1)
 
diff --git a/docs/en/faq/osgi.md b/docs/en/faq/osgi.md
new file mode 100644
index 0000000000..ecad7535a3
--- /dev/null
+++ b/docs/en/faq/osgi.md
@@ -0,0 +1,30 @@
+## How to make SkyWalking agent works in `OSGI` environment?
+
+`OSGI` implements its own set of [modularity](https://www.osgi.org/resources/modularity/), which means that each `Bundle` has its own unique class loader for isolating different versions of classes.
+By default, OSGI runtime uses the boot classloader for the bundle codes, which makes the `java.lang.NoClassDefFoundError` exception in the booting stage.
+```
+java.lang.NoClassDefFoundError: org/apache/skywalking/apm/agent/core/plugin/interceptor/enhance/EnhancedInstance
+	at ch.qos.logback.classic.Logger.buildLoggingEventAndAppend(Logger.java:419)
+	at ch.qos.logback.classic.Logger.filterAndLog_0_Or3Plus(Logger.java:383)
+	at ch.qos.logback.classic.Logger.log(Logger.java:765)
+	at org.apache.commons.logging.impl.SLF4JLocationAwareLog.error(SLF4JLocationAwareLog.java:216)
+	at org.springframework.boot.SpringApplication.reportFailure(SpringApplication.java:771)
+	at org.springframework.boot.SpringApplication.handleRunFailure(SpringApplication.java:748)
+	at org.springframework.boot.SpringApplication.run(SpringApplication.java:314)
+	at org.springframework.boot.SpringApplication.run(SpringApplication.java:1118)
+	at org.springframework.boot.SpringApplication.run(SpringApplication.java:1107)
+	at by.kolodyuk.osgi.springboot.SpringBootBundleActivator.start(SpringBootBundleActivator.java:21)
+	at org.apache.felix.framework.util.SecureAction.startActivator(SecureAction.java:849)
+	at org.apache.felix.framework.Felix.activateBundle(Felix.java:2429)
+	at org.apache.felix.framework.Felix.startBundle(Felix.java:2335)
+	at org.apache.felix.framework.Felix.setActiveStartLevel(Felix.java:1566)
+	at org.apache.felix.framework.FrameworkStartLevelImpl.run(FrameworkStartLevelImpl.java:297)
+	at java.base/java.lang.Thread.run(Thread.java:829)
+```
+
+### How to resolve this issue?
+1. we need to set the parent classloader in `OSGI` to `AppClassLoader`, through the specific parameter `org.osgi.framework.bundle.parent=app`.
+   The list of parameters can be found in the [OSGI API](https://docs.osgi.org/specification/osgi.core/7.0.0/framework.api.html)
+2. Load the `SkyWalking` related classes to the bundle parent class loader, `AppClassLoader`, with the parameter `org.osgi.framework.bootdelegation=org.apache.skywalking.apm.*`
+   or `org.osgi.framework.bootdelegation=*`. This step is optional. Some OSGi implementations (i.e. Equinox) enable them by default
+
diff --git a/docs/menu.yml b/docs/menu.yml
index 1f35505949..e13aeadc0e 100644
--- a/docs/menu.yml
+++ b/docs/menu.yml
@@ -96,6 +96,8 @@ catalog:
     catalog:
       - name: "Why is java.ext.dirs not supported?"
         path: "/en/faq/ext-dirs"
+      - name: "How to make SkyWalking agent works in `OSGI` environment?"
+        path: "/en/faq/osgi"
   - name: "Contribution"
     catalog:
       - name: "Compiling Guidance"