From b4bf6fd75d97d83aae42e808086340d1bbf421e0 Mon Sep 17 00:00:00 2001
From: 2han9wen71an <2han9wen71an@gmail.com>
Date: Sat, 4 Feb 2023 19:29:41 +0800
Subject: [PATCH] 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(-)
 create mode 100644 docs/en/faq/osgi.md

diff --git a/CHANGES.md b/CHANGES.md
index b3f28ffc9..0253fb882 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 000000000..ecad7535a
--- /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 1f3550594..e13aeadc0 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"