kezhenxu94 commented on a change in pull request #156: URL: https://github.com/apache/skywalking-python/pull/156#discussion_r694429523
########## File path: cli.py ########## @@ -0,0 +1,26 @@ +# +# Licensed to the Apache Software Foundation (ASF) under one or more +# contributor license agreements. See the NOTICE file distributed with +# this work for additional information regarding copyright ownership. +# The ASF licenses this file to You under the Apache License, Version 2.0 +# (the "License"); you may not use this file except in compliance with +# the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# + +""" Just an entry point script +python -m cli run command Review comment: Is this name `cli` (and the file name `cli.py`) too generous? What about using `sw-python` to make it consistent with our standalone command? ########## File path: docs/CLI.md ########## @@ -0,0 +1,87 @@ +# SkyWalking Python Agent Command-Line Interface(CLI) + +You would at least need to add the following lines to your applications in previous releases to get the agent attached and running. Review comment: What about putting the condition at the beginning? In case the users just read a half of the sentence 🤣 and let's be clear about since which version we support this ```suggestion In earlier releases than 0.7.0, you would at least need to add the following lines to your applications to get the agent attached and running. ``` ########## File path: docs/CLI.md ########## @@ -0,0 +1,87 @@ +# SkyWalking Python Agent Command-Line Interface(CLI) + +You would at least need to add the following lines to your applications in previous releases to get the agent attached and running. + +```python +from skywalking import agent +agent.start() +``` + + +Now the SkyWalking Python agent implements a command-line interface that can be utilized to attach the agent to your +awesome applications during deployment **without changing any application code**, +just like the [SkyWalking Java Agent](https://github.com/apache/skywalking). + +## Usage + +Upon successful installation of the SkyWalking Python agent via pip, Review comment: ```suggestion Upon successful [installation of the SkyWalking Python agent via pip](../README.md#install), ``` ########## File path: docs/CLI.md ########## @@ -0,0 +1,87 @@ +# SkyWalking Python Agent Command-Line Interface(CLI) + +You would at least need to add the following lines to your applications in previous releases to get the agent attached and running. + +```python +from skywalking import agent +agent.start() +``` + + +Now the SkyWalking Python agent implements a command-line interface that can be utilized to attach the agent to your +awesome applications during deployment **without changing any application code**, +just like the [SkyWalking Java Agent](https://github.com/apache/skywalking). + +## Usage + +Upon successful installation of the SkyWalking Python agent via pip, +a command-line script `sw-python` is installed in your environment(virtual env preferred). + +### The run option Review comment: ```suggestion ### The `run` option ``` ########## File path: docs/CLI.md ########## @@ -0,0 +1,87 @@ +# SkyWalking Python Agent Command-Line Interface(CLI) + +You would at least need to add the following lines to your applications in previous releases to get the agent attached and running. + +```python +from skywalking import agent +agent.start() +``` + + +Now the SkyWalking Python agent implements a command-line interface that can be utilized to attach the agent to your +awesome applications during deployment **without changing any application code**, +just like the [SkyWalking Java Agent](https://github.com/apache/skywalking). + +## Usage + +Upon successful installation of the SkyWalking Python agent via pip, +a command-line script `sw-python` is installed in your environment(virtual env preferred). + +### The run option + +Currently, the `sw-python` CLI provides a `run` option, which you can use to execute your applications +(either begins with the `python` command or Python-based programs like `gunicorn` on your path) +just like you invoke them normally, plus a prefix, the following example demonstrates the usage. + +If your previous command to run your gunicorn application is: + +`gunicorn app.wsgi` + +Please change it to: + +`sw-python run gunicorn app.wsgi` + +The SkyWalking Python agent will startup along with your application shortly. + +Note that the command does work with multiprocessing and subprocess as long as the `PYTHONPATH` is inherited, +please configure the environment variables configuration accordingly based on the general documentation. + +When executing commands with `sw-python run command`, your command's Python interpreter will pick up the SkyWalking loader module. + +It is not safe to attach SkyWalking Agent to those commands that resides in another Python installation +because incompatible Python versions and mismatched SkyWalking versions can cause problems. +Therefore, any attempt to pass a command that uses a different Python interpreter/ environment will not bring up +SkyWalking Python Agent even if another SkyWalking Python agent is installed there(no matter the version), +and will force exit with an error message indicating the reasoning. + +#### Disabling child processes from starting new agents + +Sometimes you don't actually need the agent to monitor anything in a child process. + +If you do not need the agent to get loaded for application child processes, you can turn off the behavior by setting an environment variable. + +`SW_PYTHON_BOOTSTRAP_PROPAGATE` to `False` + +Note the auto bootstrap depends on the environment inherited by child processes, +thus prepending a new sitecustomize path to or removing the loader path from the `PYTHONPATH` could prevent the agent from loading in a child process. + +### Configuring the agent + +You would normally want to provide additional configurations other than the default ones. + +#### Through environment variables + +The currently supported method is to provide the environment variables listed +in [EnvVars Doc](EnvVars.md) as instructed in the [README](../README.md). + +#### Through a sw-config.yaml Review comment: One thing we should note when implementing this is that we've been trying to minimize our dependencies as an agent, so we'd better choose a reasonable file format that Python built-in libs can parse, instead of bringing another library, to avoid version conflicts with user applications, `yaml` is a common case where users may already use and we should not require dependency upgrade or downgrade. ########## File path: skywalking/bootstrap/__init__.py ########## @@ -0,0 +1,37 @@ +# +# Licensed to the Apache Software Foundation (ASF) under one or more +# contributor license agreements. See the NOTICE file distributed with +# this work for additional information regarding copyright ownership. +# The ASF licenses this file to You under the Apache License, Version 2.0 +# (the "License"); you may not use this file except in compliance with +# the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# + +""" This sub-package is for the convenience of deployment and automation +A CLI for running Python scripts and programs with SkyWalking Python Agent automatically attached. +`loader/sitecustomize.py` is invoked by the Python interpreter at startup. +""" + +__version__ = '0.6.0' Review comment: Is there any means we can bump up this version automatically together with the version in `setup.py` when releasing? -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
