Skip to content

Latest commit

 

History

History
95 lines (63 loc) · 4.76 KB

CONTRIBUTING.md

File metadata and controls

95 lines (63 loc) · 4.76 KB

Contributing to Python solarwinds-apm

Thank you for contributing and helping us improve Python solarwinds-apm.

Issues

Security issues

Please report any security issues privately to the SolarWinds Product Security Incident Response Team (PSIRT) at [email protected].

All other issues

For non-security issues, please submit your ideas, questions, or problems as GitHub issues. Please add as much information as you can, such as: Python version, platform, installed dependencies and their version numbers, hosting, code examples or gists, steps to reproduce, stack traces, and logs. SolarWinds project maintainers may ask for clarification or more context after submission.

Contributing

Any changes to this project must be made through a pull request to main. Major changes should be linked to an existing GitHub issue. Smaller contributions like typo corrections don't require an issue.

A PR is ready to merge when all tests pass, any major feedback has been resolved, and at least one SolarWinds maintainer has approved. Once ready, a PR can be merged by a SolarWinds maintainer.

Development

Prerequisites

  • docker
  • docker-compose

Build Containers

The build containers are based on the PyPA image for manylinux_2_28_x86_64 or manylinux_2_28_aarch64. Each uses SWIG to compile required C/C++ libraries into a C-extension dependency.

To create and run a Docker container for testing and builds, run one of the following:

docker-compose run x86_64
docker-compose run aarch64

Regression Tests

Automated testing of this repo uses tox and runs in Python 3.8, 3.9, 3.10, 3.11 and/or 3.12 because these are the versions supported by OTel Python. Testing can be run inside a build container which provides all dependencies and a compiled C-extension. Here is how to set up then run unit and integration tests locally:

  1. Create and run a Docker build container as described above.
  2. Inside the build container: make wrapper. This downloads the version of a C/C++ dependency defined in extension/VERSION from SolarWinds Cloud and builds SWIG bindings.
  3. To run all tests for a specific version, provide tox options as a string. For example, to run in Python 3.9 against AO prod: make tox OPTIONS="-e py39-nh-staging".
  4. (WARNING: slow!) To run all tests for all supported Python environments, as well as linting and formatting: make tox

Other regular tox arguments can be included in OPTIONS. Some examples:

# Recreate tox environment for Python 3.8 pointed at AO prod
make tox OPTIONS="--recreate -e py38-ao-prod"

# Run only the Scenario 8 integration test, in all environments
make tox OPTIONS="-- tests/integration/test_scenario_1.py"

The unit and integration tests are also run on GitHub with the Run tox tests workflow.

Formatting and Linting

Code formatting and linting are run using black, isort, flake8, and pylint via tox. First, create and run a Docker build container as described above. Then use the container to run formatting and linting in one of these ways:

# Run formatting and linting tools for Python 3.12,
# without trying to fix issues:
./run_docker_dev.sh
make tox OPTIONS="-e py312-lint -- --check-only"

# Run formatting and linting tools for Python 3.8,
# and automatically fix issues if possible:
./run_docker_dev.sh
make tox OPTIONS="-e py38-lint"

Remotely, CodeQL can be run on GitHub with the CodeQL Analysis workflow.

Install locally and instrument a test app

solarwinds-apm can be installed and used to instrument a Python app running on your local:

  1. Create and run a Docker build container as described above.
  2. Inside the build container: make wrapper. This downloads the version of a C/C++ dependency defined in extension/VERSION from SolarWinds Cloud and builds SWIG bindings.
  3. In your Python app's environment/container, install your local solarwinds-apm. For example, if you've saved it to ~/gitrepos then you could do: pip install -Ie ~/gitrepos/apm-python/
  4. Install all relevant Opentelemetry Python instrumentation libraries: opentelemetry-bootstrap --action=install
  5. Run your application with the prefix opentelemetry-instrument to wrap all common Python frameworks: opentelemetry-instrument <command_to_run_your_service>