docs: honest fork-safety guidance; test gunicorn --preload; review fixes

Review follow-ups:
- Explicit os.fork() with a live gRPC channel is documented (and warned
  at runtime, outside the Gunicorn prefork path) as unreliable on
  grpcio >= 1.80 — background reporters enter gRPC independent of
  requests, upstream races grpc/grpc#43055/#43062 remain open; forking
  applications are directed to SW_AGENT_PROTOCOL=http/kafka. Gunicorn
  via `sw-python run -p` is called out as the supported channel-after-
  fork model.
- The asyncio enhancement + prefork incompatibility is now documented in
  the Gunicorn FAQ, AsyncEnhancement.md and the config reference.
- sw_grpc plugin note states the effective grpcio floor (>= 1.83 via the
  agent package) alongside the 1.* instrumentation range.
- __fini is registered once per process lineage (atexit registrations
  are fork-inherited), mirroring the at-fork hook guard.
- The sw_gunicorn provider now runs with --preload and performs an
  instrumented call at module import, covering the agent.started()
  no-op guard in the instrumentation-only master.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: wu-sheng

docs/en/setup/CLI.md

@@ -71,9 +71,13 @@ Note that `sw-python` also work with spawned subprocess (os.exec*/subprocess) as
 
 Additionally, `sw-python` started agent works well with `os.fork` when your application forks workers, 
 as long as the `SW_AGENT_EXPERIMENTAL_FORK_SUPPORT` is turned on. (It will be automatically turned on when gunicorn is detected)
-Avoid calling `os.fork()` while the agent is actively talking to the collector (e.g. immediately at startup, during
-registration): a fork during an in-flight gRPC call can trip gRPC's own at-fork handling (see grpc/grpc#43055) and
-hang the child. Forking a moment after startup, or between requests, is safe.
+
+**Important**: with the default gRPC reporter, explicit `os.fork()` is NOT reliable on grpcio >= 1.80: the agent's
+background reporters enter gRPC at any time (heartbeat, segment flush) independent of application requests, and a
+fork while a channel is live is subject to open upstream races (grpc/grpc#43055, grpc/grpc#43062) that can silently
+break reporting in either process. Applications that fork should use `SW_AGENT_PROTOCOL=http` (or `kafka`).
+Gunicorn via `sw-python run -p` is NOT affected: there the agent creates its channels only after the fork,
+which is gRPC's supported model.
 
 ## Configuring the agent 
 

docs/en/setup/Configuration.md

@@ -40,7 +40,7 @@ export SW_AGENT_YourConfiguration=YourValue
 | agent_instance_properties_json | SW_AGENT_INSTANCE_PROPERTIES_JSON | <class 'str'> |  | A custom JSON string to be reported as service instance properties, e.g. `{"key": "value"}` |
 | agent_experimental_fork_support | SW_AGENT_EXPERIMENTAL_FORK_SUPPORT | <class 'bool'> | False | The agent will restart itself in any os.fork()-ed child process. Important Note: it's not suitable for short-lived processes as each one will create a new instance in SkyWalking dashboard in format of `service_instance-child(pid)`. When the sw-python CLI detects a pre-forking server (Gunicorn), only worker processes run a full agent; the master installs instrumentation only. |
 | agent_queue_timeout | SW_AGENT_QUEUE_TIMEOUT | <class 'int'> | 1 | DANGEROUS - This option controls the interval of each bulk report from telemetry data queues Do not modify unless you have evaluated its impact given your service load. |
-| agent_asyncio_enhancement | SW_AGENT_ASYNCIO_ENHANCEMENT | <class 'bool'> | False | Replace the threads to asyncio coroutines to report telemetry data to the OAP. This option is experimental and may not work as expected. |
+| agent_asyncio_enhancement | SW_AGENT_ASYNCIO_ENHANCEMENT | <class 'bool'> | False | Replace the threads to asyncio coroutines to report telemetry data to the OAP. This option is experimental and may not work as expected. Not compatible with pre-forking servers (`sw-python run -p`): the agent refuses to start under a Gunicorn master. |
 ###  SW_PYTHON Auto Instrumentation CLI
 | Configuration | Environment Variable | Type | Default Value | Description |
 | :------------ | :------------ | :------------ | :------------ | :------------ |

docs/en/setup/Plugins.md

@@ -60,6 +60,8 @@ in SkyWalking currently. Celery clients can use whatever protocol they want.
 Hug is believed to be abandoned project, use this plugin with a bit more caution.
 Instead of Hug, plugin test should move to test actual Falcon.
 - Falcon 3.x/4.x plugin. For legacy hug-based instrumentation, see sw_falcon.
+- The agent package itself depends on grpcio >= 1.83, which is therefore the
+effective minimum version of the instrumented library as well.
 - The Neo4j plugin integrates neo4j python driver 5.x.x versions which
 support both Neo4j 5 and 4.4 DBMS.
 - Sanic 21.9+ plugin using signal listeners.

docs/en/setup/advanced/AsyncEnhancement.md

@@ -6,6 +6,10 @@ Since `1.1.0`, the Python agent supports asynchronous reporting of ALL telemetry
 export SW_AGENT_ASYNCIO_ENHANCEMENT=true
 ```
 
+> Limitation: this option is incompatible with pre-forking servers via `sw-python run -p` (e.g. Gunicorn) —
+> the asyncio agent has no fork support, so the agent refuses to start and the application runs without
+> observability. See the [Gunicorn FAQ](../faq/How-to-use-with-gunicorn.md).
+
 ## Why we need this feature
 
 Before version `1.1.0`, SkyWalking Python agent had only an implementation with the Threading module to provide data reporters. Yet with the growth of the Python agent, it is now fully capable and requires more resources than when only tracing was supported (we start many threads and gRPC itself creates even more threads when streaming).

docs/en/setup/faq/How-to-use-with-gunicorn.md

@@ -46,6 +46,12 @@ and can silently hang workers. Tracing generally keeps working — the errors co
 engine and are unrelated to the OAP version. Workarounds on old agents: pin `grpcio<1.80` or use `SW_AGENT_PROTOCOL=http`.
 Fixed agent versions require `grpcio >= 1.83` and never create a gRPC channel in the master.
 
+### Incompatible with the asyncio enhancement
+
+`SW_AGENT_ASYNCIO_ENHANCEMENT=true` is incompatible with `sw-python run -p gunicorn`: the asyncio agent has no
+fork support, so the agent refuses to start (an error is logged) and the application serves WITHOUT observability.
+Remove the asyncio enhancement option, or run Gunicorn without `-p`.
+
 ## Manual Approach (only use when sw-python doesn't work)
 
 **Limitation**: Using normal postfork hook will not add observability to the master process.

skywalking/agent/__init__.py

@@ -115,6 +115,7 @@ def __init__(self):
         # True only after __bootstrap() in the current process; stays False in a pre-fork master
         self.__reporting: bool = False
         self.__at_fork_registered: bool = False
+        self.__fini_registered: bool = False
 
     def __bootstrap(self):
         # when forking, already instrumented modules must not be instrumented again
@@ -273,6 +274,12 @@ def start(self) -> None:
             # see https://github.com/apache/skywalking/issues/13958
             os.environ['GRPC_ENABLE_FORK_SUPPORT'] = 'true'  # must precede `import grpc`
 
+            if not os.getenv('prefork'):  # Gunicorn prefork creates channels only after fork() and is safe
+                logger.warning('Explicit os.fork() with a live gRPC channel is unreliable on '
+                               'grpcio >= 1.80 (see grpc/grpc#43055) and may silently break '
+                               'reporting in either process; prefer SW_AGENT_PROTOCOL=http or '
+                               'kafka for forking applications.')
+
         if not self.__started:
             # if not already started, start the agent
             logger.info(f'SkyWalking sync agent instance {config.agent_instance_name} starting in pid-{os.getpid()}.')
@@ -305,7 +312,11 @@ def start(self) -> None:
 
         self.__bootstrap()  # calls init_threading
 
-        atexit.register(self.__fini)
+        # atexit registrations are fork-inherited; register once per lineage so a
+        # fork-restarted child does not stack a duplicate __fini
+        if not self.__fini_registered:
+            self.__fini_registered = True
+            atexit.register(self.__fini)
 
         if config.agent_experimental_fork_support:
             self.__register_fork_hooks()
@@ -387,6 +398,7 @@ def stop(self) -> None:
         Stops the agent and reset the started flag.
         """
         atexit.unregister(self.__fini)
+        self.__fini_registered = False
         self.__fini()
         self.__reporting = False
         self.__started = False

skywalking/config.py

@@ -102,7 +102,8 @@
 # Do not modify unless you have evaluated its impact given your service load.
 agent_queue_timeout: int = int(os.getenv('SW_AGENT_QUEUE_TIMEOUT', '1'))
 # Replace the threads to asyncio coroutines to report telemetry data to the OAP.
-# This option is experimental and may not work as expected.
+# This option is experimental and may not work as expected. Not compatible with pre-forking
+# servers (`sw-python run -p`): the agent refuses to start under a Gunicorn master.
 agent_asyncio_enhancement: bool = os.getenv('SW_AGENT_ASYNCIO_ENHANCEMENT', '').lower() == 'true'
 
 # BEGIN: SW_PYTHON Auto Instrumentation CLI

skywalking/plugins/sw_grpc.py

@@ -27,7 +27,8 @@
 
 link_vector = ['https://grpc.io/docs/languages/python']
 support_matrix = {'grpcio': {'>=3.8': ['1.*']}}
-note = """"""
+note = """The agent package itself depends on grpcio >= 1.83, which is therefore the
+effective minimum version of the instrumented library as well."""
 
 
 def _get_factory_and_method(rpc_handler: Any) -> Tuple[Callable[..., Any], Callable[..., Any]]:

tests/plugin/web/sw_gunicorn/docker-compose.yml

@@ -29,7 +29,7 @@ services:
       file: ../../docker-compose.base.yml
     volumes:
       - .:/app
-    command: ['bash', '-c', 'pip install flask gunicorn && pip install -r /app/requirements.txt && cd /app/services && sw-python run -p gunicorn provider:app --workers 2 --threads 2 --bind 0.0.0.0:9091']
+    command: ['bash', '-c', 'pip install flask gunicorn && pip install -r /app/requirements.txt && cd /app/services && sw-python run -p gunicorn provider:app --preload --workers 2 --threads 2 --bind 0.0.0.0:9091']
     depends_on:
       collector:
         condition: service_healthy

tests/plugin/web/sw_gunicorn/services/provider.py

@@ -14,8 +14,17 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
+import requests
 from flask import Flask, jsonify
 
+try:
+    # under gunicorn --preload this module imports in the PRE-FORK master, where the
+    # agent is instrumentation-only: this instrumented call must silently noop
+    # (NoopSpan via agent.started() guard) instead of crashing the master
+    requests.get('http://collector:12800/receiveData', timeout=5)
+except Exception:  # noqa
+    pass
+
 app = Flask(__name__)