fix: never create a gRPC channel in the Gunicorn prefork master

With grpcio >= 1.80 (EventEngine) a gRPC channel that lives across
fork() breaks: continuous `Kick Failure (eventfd_write: Bad file
descriptor)` stderr spam and a racy silent deadlock of forked workers
inside gRPC's own at-fork handlers; grpcio 1.83.0 removed the last
legacy-poller opt-out (grpc/grpc#42828; upstream reports grpc/grpc#43055
and grpc/grpc#43062, both open and unfixed).

- `sw-python run -p gunicorn`: the master now only installs
  instrumentation (start_prefork_master) and arms the fork hooks;
  queues, reporter threads and the gRPC channel are created in each
  forked worker only (the model uWSGI has always used). The master no
  longer registers as a service instance.
- New agent.started() guard: instrumented code no-ops (NoopSpan,
  dropped logs/meters) in a process whose reporters are not active,
  protecting `gunicorn --preload` app imports in the master.
- GRPC_POLL_STRATEGY is no longer set; the grpcio floor is raised to
  >= 1.83 (generated stubs already require it at import) and codegen
  grpcio-tools is pinned in lockstep so future wheels cannot silently
  raise the runtime floor.
- Gunicorn prefork + SW_AGENT_ASYNCIO_ENHANCEMENT is rejected instead
  of starting an unsafe pre-fork agent.
- New plugin tests: sw_gunicorn (full consumer -> gunicorn-provider
  trace with CrossProcess ref, exact worker-boot-count and
  no-Kick-Failure log assertions, async-rejection case) and
  sw_fork_support (explicit os.fork() with a continuous cross-fork
  trace via SW_AGENT_EXPERIMENTAL_FORK_SUPPORT).

Validated in Docker on grpcio 1.80.0 / 1.82.1 / 1.83.0 x 8-10 boots
each: zero error spam, zero worker deadlocks, all segments delivered;
fd-level inspection confirms the master holds no collector connection
while each worker holds exactly one.

Fixes apache/skywalking#13958

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

Author: wu-sheng

Makefile

@@ -50,14 +50,16 @@ else
 	-curl -sSL https://install.python-poetry.org | python3 -
 endif
 
+# grpcio-tools pinned: generated stubs refuse grpcio older than the tools version,
+# keep in sync with the grpcio floor declared in pyproject.toml
 .PHONY: gen
 gen:
-	poetry run pip install 'grpcio-tools>=1.68.0' packaging
+	poetry run pip install 'grpcio-tools~=1.83.0' packaging
 	poetry run python3 tools/grpc_code_gen.py
 
 .PHONY: gen-basic
 gen-basic:
-	python3 -m pip install 'grpcio-tools>=1.68.0' packaging
+	python3 -m pip install 'grpcio-tools~=1.83.0' packaging
 	python3 tools/grpc_code_gen.py
 
 .PHONY: install

docs/en/setup/CLI.md

@@ -53,7 +53,7 @@ or
 
 `uwsgi --die-on-term --http 0.0.0.0:5000 --http-manage-expect --master --workers 3 --enable-threads --threads 3 --manage-script-name --mount /=main:app`
 
-Please change it to (**the `-p` option starts one agent in each process, which is the correct behavior**):
+Please change it to (**the `-p` option starts one agent in each worker process and none in the master, which is the correct behavior**):
 
 **Important:** if the call to uwsgi/gunicorn is prefixed with other commands, this approach will fail 
 since agent currently looks for the command line input at index 0 for safety as an experimental feature.
@@ -71,6 +71,9 @@ 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.
 
 ## Configuring the agent 
 

docs/en/setup/Configuration.md

@@ -38,7 +38,7 @@ export SW_AGENT_YourConfiguration=YourValue
 | agent_collector_heartbeat_period | SW_AGENT_COLLECTOR_HEARTBEAT_PERIOD | <class 'int'> | 30 | The agent will exchange heartbeat message with SkyWalking OAP backend every `period` seconds |
 | agent_collector_properties_report_period_factor | SW_AGENT_COLLECTOR_PROPERTIES_REPORT_PERIOD_FACTOR | <class 'int'> | 10 | The agent will report service instance properties every `factor * heartbeat period` seconds default: 10*30 = 300 seconds |
 | 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)`. This feature may not work when a precise combination of gRPC + Python 3.7 + subprocess (not fork) is used together. The agent will output a warning log when using on Python 3.7 for such a reason. |
+| 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. |
 ###  SW_PYTHON Auto Instrumentation CLI

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

@@ -14,7 +14,7 @@ serves requests.
 
 > Note: Python 3.10+ is required. Earlier versions (3.7-3.9) are no longer supported.
 
-**TL;DR:** specify `-p` or `--prefork` in `sw-python run -p` and all Gunicorn workers and master will get their own working agent.
+**TL;DR:** specify `-p` or `--prefork` in `sw-python run -p` and every Gunicorn worker will get its own working agent (the master is instrumented only and runs no agent).
 
 **Important:** if the call to gunicorn is prefixed with other commands, this approach will fail 
 since agent currently looks for the command line input at index 0 for safety as an experimental feature.
@@ -29,17 +29,28 @@ sw-python run -p gunicorn gunicorn_consumer_prefork:app --workers 2 --worker-cla
 By specifying the -p or --prefork option in sw-python CLI, the `agent_experimental_fork_support` agent option will be turned on automatically. 
 
 Startup flow:
-sw-python -> gunicorn -> master process (agent starts) -> fork -> worker process (agent restarts due to os.register_at_fork)
+sw-python -> gunicorn -> master process (instrumentation only) -> fork -> worker process (full agent starts due to os.register_at_fork)
 
-The master process will get its own agent, although it won't report any trace, since obviously it doesn't take requests, 
-it still reports metrics that is useful for debugging
+The master process does not run a full agent: it only installs instrumentation, and the reporters plus the
+gRPC channel are created in each forked worker. Therefore the master does not appear as a service instance
+(it takes no requests anyway). A gRPC channel created before fork() is unsafe with grpcio >= 1.80, see
+[apache/skywalking#13958](https://github.com/apache/skywalking/issues/13958).
 
 > A runnable example can be found in the demo folder of skywalking-python GitHub repository
 
+### Known issue with agent <= 1.2.0 and grpcio >= 1.80
+
+Agent versions up to 1.2.0 started a full agent (including a gRPC channel) in the Gunicorn master before forking.
+With grpcio >= 1.80 this produces continuous `Kick Failure (eventfd_write: Bad file descriptor)` errors
+and can silently hang workers. Tracing generally keeps working — the errors come from the gRPC client polling
+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.
+
 ## Manual Approach (only use when sw-python doesn't work)
 
-**Limitation**: Using normal postfork hook will not add observability to the master process, you could also define a prefork hook to
-start an agent in the master process, with a instance name like `instance-name-master(<pid>)`
+**Limitation**: Using normal postfork hook will not add observability to the master process.
+Do NOT start an agent in the master process (e.g. from a prefork hook): a gRPC channel created before
+fork() is unsafe with grpcio >= 1.80 and can deadlock workers.
 
 The following is just an example, since Gunicorn's automatic injection approach is likely to work in many situations.
 

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

@@ -13,8 +13,8 @@ Some of the original discussion can be found here:
 > You can always fall back to the manual approach. 
 > (although it's also possible to pass postfork hook without changing code, which is essentially how sw-python is implemented)
 
-> Limitation: regardless of the approach used, uWSGI master process cannot be safely monitored. Since it doesn't take any requests, it is generally acceptable.
-> Alternatively, you could switch to Gunicorn, where its master process can be monitored properly along with all child workers.
+> Limitation: regardless of the approach used, the uWSGI master process is not monitored. Since it doesn't take any requests, it is generally acceptable.
+> Gunicorn behaves the same way — only worker processes are monitored, which is the fork-safe design.
 
 **Important**: The `--enable-threads` and `--master` option must be given to allow the usage of post_fork hooks and threading in workers. 
 In the `sw-python` CLI, these two options will be automatically injected for you in addition to the post_fork hook.