There are many ways you can contribute to the SkyWalking community.
dev@skywalking.apache.org. Mail to dev-subscribe@skywalking.apache.org, and follow the instructions in the reply to subscribe to the mail list.All of the following channels are open to the community.
dev-subscribe@skywalking.apache.org. Follow the instructions in the reply to subscribe to the mail list.The PMC assesses the contributions of every contributor, including their code contributions. It also promotes, votes on, and invites new committers and PMC members according to the Apache guides. See Become official Apache SkyWalking Committer for more details.
For developers, the starting point is the Compiling Guide. It guides developers on how to build the project in local and set up the environment.
After setting up the environment and writing your codes, to facilitate integration with the SkyWalking project, you'll need to run tests locally to verify that your codes would not break any existing features, as well as write some unit test (UT) codes to verify that the new codes would work well. This will prevent them from being broken by future contributors. If the new codes involve other components or libraries, you should also write integration tests (IT).
SkyWalking leverages the plugin maven-surefire-plugin to run the UTs and uses maven-failsafe-plugin to run the ITs. maven-surefire-plugin excludes ITs (whose class name starts with IT) and leaves them for maven-failsafe-plugin to run, which is bound to the verify goal and CI-with-IT profile. Therefore, to run the UTs, try ./mvnw clean test, which only runs the UTs but not the ITs.
If you would like to run the ITs, please activate the CI-with-IT profile as well as the the profiles of the modules whose ITs you want to run. E.g. if you would like to run the ITs in oap-server, try ./mvnw -Pbackend,CI-with-IT clean verify, and if you would like to run all the ITs, simply run ./mvnw -Pall,CI-with-IT clean verify.
Please be advised that if you're writing integration tests, name it with the pattern IT* so they would only run with the CI-with-IT profile.
Since version 6.3.0, we have introduced more automatic tests to perform software quality assurance. E2E is an integral part of it.
End-to-end testing is a methodology used to test whether the flow of an application is performing as designed from start to finish. The purpose of carrying out end-to-end tests is to identify system dependencies and to ensure that the right information is passed between various system components and systems.
The E2E test involves some/all of the OAP server, storage, coordinator, webapp, and the instrumented services, all of which are orchestrated by docker-compose. Besides, there is a test controller (JUnit test) running outside of the container that sends traffic to the instrumented service, and then verifies the corresponding results after those requests have been made through GraphQL API of the SkyWalking Web App.
The E2E test is a separate project under the SkyWalking root directory and the IDEA cannot recognize it by default. Right click on the file test/e2e/pom.xml and click Add as Maven Project. We recommend opening the directory skywalking/test/e2e in a separate IDE window for better experience, since there may be shaded classes issues.
The goal of the E2E tests is to test the SkyWalking project as a whole, including the OAP server, storage, coordinator, webapp, and even the frontend UI (not for now), on the single node mode as well as the cluster mode. Therefore, the first step is to determine what case we are going to verify, and orchestrate the components.
To make the orchestration process easier, we're using a docker-compose that provides a simple file format (docker-compose.yml) for orchestrating the required containers, and offers an opportunity to define the dependencies of the components.
Follow these steps:
docker-compose.yml, and carefully specify the dependencies, starting orders, and most importantly, link them together, e.g. set the correct OAP address on the agent end, and set the correct coordinator address in OAP, etc.As for the final step, we have a user-friendly framework to help you get started more quickly. This framework provides the annotation @DockerCompose("docker-compose.yml") to load/parse and start up all the containers in the proper order. @ContainerHost/@ContainerPort obtains the real host/port of the container. @ContainerHostAndPort obtains both. @DockerContainer obtains the running container.
Put it simply, test controllers are tests that can be bound to the maven integration-test/verify phase. They send design requests to the instrumented services, and anticipate corresponding traces/metrics/metadata from the SkyWalking webapp GraphQL API.
In the test framework, we provide a TrafficController that periodically sends traffic data to the instrumented services. You can simply enable it by providing a url and traffic data. Refer to this.
We expose all logs from all containers to the stdout in the non-CI (local) mode, but save and upload them to the GitHub server. You can download them (only when the tests have failed) at “Artifacts/Download artifacts/logs” (see top right) for debugging.
NOTE: Please verify the newly-added E2E test case locally first. However, if you find that it has passed locally but failed in the PR check status, make sure that all the updated/newly-added files (especially those in the submodules) are committed and included in the PR, or reset the git HEAD to the remote and verify locally again.
The SkyWalking project supports various extensions of existing features. If you are interesting in writing extensions, read the following guides.
This guides you in developing SkyWalking agent plugins to support more frameworks. Developers for both open source and private plugins should read this.
config/oal/*.oal. You could modify them and reboot the OAP server. Read Observability Analysis Language Introduction to learn more about OAL scripts.Our UI consists of static pages and the web container.
apm-webapp module. This is a simple zuul proxy which hosts static resources and sends GraphQL query requests to the backend.This section is only applicable to dependencies of the backend module.
As one of the Top Level Projects of The Apache Software Foundation (ASF), SkyWalking must follow the ASF 3RD PARTY LICENSE POLICY. So if you're adding new dependencies to the project, you should make sure that the new dependencies would not break the policy, and add their LICENSE and NOTICE to the project.
We have a simple script to help you make sure that you haven't missed out any new dependencies:
dist.apm-dist/release-docs/{LICENSE,NOTICE} file.tools/dependencies/known-oap-backend-dependencies.txt file (in alphabetical order). check-LICENSE.sh should pass in the next run.The performance profile is an enhancement feature in the APM system. We use thread dump to estimate the method execution time, rather than adding multiple local spans. In this way, the cost would be significantly reduced compared to using distributed tracing to locate the slow method. This feature is suitable in the production environment. The following documents are key to understanding the essential parts of this feature.
If you‘re a committer, read the Apache Release Guide to learn about how to create an official Apache version release in accordance with avoid Apache’s rules. As long as you keep our LICENSE and NOTICE, the Apache license allows everyone to redistribute.