You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+9-9Lines changed: 9 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -39,17 +39,17 @@ pip install apache-skywalking==0.1.0 # For example, install version 0.1.0 no ma
39
39
SkyWalking Python agent provides convenient dockerfile and images for easy integration utilizing its auto-bootstrap
40
40
capability. You can build your Python application image based on our agent-enabled Python images and start
41
41
your applications with SkyWalking agent enabled for you. Please refer to our
42
-
[dockerfile guide](docker/README.md) for further instructions on building and configurations.
42
+
[dockerfile guide](docs/en/setup/Container.md) for further instructions on building and configurations.
43
43
44
44
### From Source Codes
45
45
46
-
Refer to the [FAQ](docs/FAQ.md#q-how-to-build-from-sources).
46
+
Refer to the [FAQ](docs/en/setup/faq/How-to-build-from-sources.md).
47
47
48
48
## Set up Python Agent
49
49
50
50
SkyWalking Python SDK requires SkyWalking 8.0+ and Python 3.5+.
51
51
52
-
> If you want to try out the latest features that are not released yet, please refer to [the guide](docs/FAQ.md#q-how-to-build-from-sources) to build from sources.
52
+
> If you want to try out the latest features that are not released yet, please refer to [the guide](docs/en/setup/faq/How-to-build-from-sources.md) to build from sources.
53
53
54
54
By default, SkyWalking Python agent uses gRPC protocol to report data to SkyWalking backend,
55
55
in SkyWalking backend, the port of gRPC protocol is `11800`, and the port of HTTP protocol is `12800`,
@@ -62,7 +62,7 @@ SkyWalking Python agent supports running and attaching to your awesome applicati
62
62
project. The package installation comes with a new command-line script named `sw-python`, which you can use to run your Python-based
63
63
applications and programs in the following manner `sw-python run python abc.py` or `sw-python run program arg0 arg1`
64
64
65
-
Please do read the [CLI Guide](docs/CLI.md) for a detailed introduction to this new feature before using in production.
65
+
Please do read the [CLI Guide](docs/en/setup/CLI.md) for a detailed introduction to this new feature before using in production.
66
66
67
67
You can always fall back to our traditional way of integration as introduced below,
68
68
which is by importing SkyWalking into your project and starting the agent.
@@ -112,17 +112,17 @@ agent.start()
112
112
113
113
Alternatively, you can also pass the configurations via environment variables (such as `SW_AGENT_NAME`, `SW_AGENT_COLLECTOR_BACKEND_SERVICES`, etc.) so that you don't need to call `config.init`.
114
114
115
-
All supported environment variables can be found [here](docs/EnvVars.md)
115
+
All supported environment variables can be found in the [Environment Variables List](docs/en/setup/EnvVars.md)
116
116
117
117
## Report logs with Python Agent
118
118
119
119
The Python agent is capable of reporting collected logs to the backend(SkyWalking OAP), enabling Log & Trace Correlation.
120
120
121
-
Please refer to the [Log Reporter Doc](docs/LogReporter.md) for a detailed guide.
121
+
Please refer to the [Log Reporter Doc](docs/en/setup/advanced/LogReporter.md) for a detailed guide.
122
122
123
123
## Supported Libraries
124
124
125
-
There are some built-in plugins (such as `http.server`, `Flask`, `Django` etc.) that support automatic instrumentation of Python libraries, the complete lists can be found [here](docs/Plugins.md)
125
+
There are some built-in plugins (such as `http.server`, `Flask`, `Django` etc.) that support automatic instrumentation of Python libraries, the complete lists can be found [here](docs/en/setup/Plugins.md)
126
126
127
127
## API
128
128
@@ -206,11 +206,11 @@ with context.new_entry_span(op=str('https://github.com/apache/skywalking')) as s
206
206
207
207
## Contributing
208
208
209
-
Before submitting a pull request or push a commit, please read our [contributing](CONTRIBUTING.md) and [developer guide](docs/Developer.md).
209
+
Before submitting a pull request or push a commit, please read our [contributing](CONTRIBUTING.md) and [developer guide](docs/en/contribution/Developer.md).
210
210
211
211
## FAQs
212
212
213
-
Check [the FAQ page](docs/FAQ.md)or add the FAQs there.
213
+
Check the FAQ page in our official documentation site or contribute FAQs to the doc folder.
Before submitting a pull request or push a commit, please read our [contributing](https://github.com/apache/skywalking-python/blob/master/CONTRIBUTING.md) and [developer guide](en/contribution/Developer.md).
Copy file name to clipboardExpand all lines: docs/en/contribution/Developer.md
+6-6Lines changed: 6 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,8 +9,8 @@
9
9
10
10
## Developing a new plugin
11
11
12
-
You can always take [the existing plugins](../skywalking/plugins) as examples, while there are some general ideas for all plugins.
13
-
1. A plugin is a module under directory [`skywalking/plugins/`](../skywalking/plugins) with an `install` method;
12
+
You can always take [the existing plugins](../setup/Plugins.md) as examples, while there are some general ideas for all plugins.
13
+
1. A plugin is a module under the directory `skywalking/plugins` with an `install` method;
14
14
1. Inside the `install` method, you find out the relevant method(s) of the libraries that you plan to instrument, and create/close spans before/after those method(s).
15
15
1. You should also provide version rules in the plugin module, which means the version of package your plugin support. You should init a dict with keys `name` and `rules`. the `name` is your plugin's corresponding package's name, the `rules` is the version rules this package should follow.
16
16
@@ -27,12 +27,12 @@ You can always take [the existing plugins](../skywalking/plugins) as examples, w
27
27
"rules": [">=2.0 <=2.3 !=2.2.1", ">3.0"]
28
28
}
29
29
```
30
-
1. Every plugin requires a corresponding test under [`tests/plugin`](../tests/plugin) before it can be merged, refer to [the plugin test guide](PluginTest.md) when writing a plugin test.
31
-
1. Update [the supported list](Plugins.md).
32
-
1. Add the environment variables to [the list](EnvVars.md) if any.
30
+
1. Every plugin requires a corresponding test under `tests/plugin` before it can be merged, refer to [the plugin test guide](PluginTest.md) when writing a plugin test.
31
+
1. Update the [Supported Plugin List](../setup/Plugins.md).
32
+
1. Add the environment variables to [Environment Variable list](../setup/EnvVars.md) if any.
33
33
34
34
## Steps after coding
35
35
36
36
If your PR introduces the need for a new non-standard library which needs to be pulled via pip or if it removes the need for a previously-used library:
37
-
1. Execute the [`build_requirements` script](../tools/env/build_requirements_linux.sh) relevant to your OS.
37
+
1. Execute the `build_requirements` script relevant to your OS.
38
38
1. Double check the `requirements.txt` file in the project root to ensure that the changes have been reflected.
Copy file name to clipboardExpand all lines: docs/en/contribution/How-to-release.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,7 +5,7 @@ This documentation guides the release manager to release the SkyWalking Python i
5
5
## Prerequisites
6
6
7
7
1. Close (if finished, or move to next milestone otherwise) all issues in the current milestone from [skywalking-python](https://github.com/apache/skywalking-python/milestones) and [skywalking](https://github.com/apache/skywalking/milestones), create a new milestone if needed.
8
-
2. Update [CHANGELOG.md](../CHANGELOG.md) and `version` in [setup.py](../setup.py).
Plugin tests are required and should pass before a new plugin is able to merge into the master branch.
4
+
5
+
## Mock Collector
6
+
7
+
Mock Collector respects the same protocol as the SkyWalking backend, and thus receives the report data from the agent side,
8
+
besides, it also exposes some HTTP endpoints for verification.
9
+
10
+
## Tested Service
11
+
12
+
A tested service is a service involving the plugin that is to be tested, and exposes some endpoints to trigger the instrumentation
13
+
and report data to the mock collector.
14
+
15
+
## Docker Compose
16
+
17
+
`docker-compose` is used to orchestrate the mock collector and the tested service(s), the `docker-compose.yml` should be
18
+
able to run with `docker-compose -f docker-compose.yml up` in standalone mode, which can be used in debugging too.
19
+
20
+
## Expected Data
21
+
22
+
The `expected.data.yml` file contains the expected segment data after we have triggered the instrumentation and report to mock collector,
23
+
since the mock collector received the segment data then, we can post the expected data to the mock collector and verify whether
24
+
they match. This can be done through the `/dataValidate` of the mock collector, say `http://collector:12800/dataValidate`, for example.
25
+
26
+
## Example
27
+
28
+
If we want to test the plugin for the built-in library `http`, we will:
29
+
30
+
1. Build a tested service, which sets up an HTTP server by `http` library, and exposes an HTTP endpoint to be triggered in the test codes, say `/trigger`,
31
+
take this [provider service](https://github.com/apache/skywalking-python/blob/master/tests/plugin/sw_http/services/provider.py) as example.
32
+
2. Compose a `docker-compose.yml` file, orchestrating the service built in step 1 and the mock collector,
33
+
take this [docker-compose.yml](https://github.com/apache/skywalking-python/blob/master/tests/plugin/sw_http/docker-compose.yml) as an example.
34
+
3. Write test codes to trigger the endpoint int step 1, and send the expected data file to the mock collector to verify,
35
+
take this [test](https://github.com/apache/skywalking-python/blob/master/tests/plugin/sw_http/test_http.py) as example.
36
+
37
+
## Notes
38
+
39
+
Remember to add the library/module into the `setup.py` - `extras_require/test`
40
+
so that other developers can have it installed after pulling your commits, and run tests locally.
0 commit comments