Skip to main content

Python Agent for Apache SkyWalking

Project description

SkyWalking Python Agent

Sky Walking logo

SkyWalking-Python: The Python Agent for Apache SkyWalking, which provides the native tracing abilities for Python project.

SkyWalking: an APM(application performance monitor) system, especially designed for microservices, cloud native and container-based (Docker, Kubernetes, Mesos) architectures.

GitHub stars Twitter Follow

Build

Install

From Pypi

The Python agent module is published to Pypi, from where you can use pip to install:

# Install the latest version
pip install apache-skywalking

# Install a specific version x.y.z
# pip install apache-skywalking==x.y.z
pip install apache-skywalking==0.1.0  # For example, install version 0.1.0 no matter what the latest version is

From Source Codes

Refer to the FAQ.

Set up Python Agent

SkyWalking Python SDK requires SkyWalking 8.0+ and Python 3.5+.

If you want to try out the latest features that're not released yet, please refer to the guide to build from sources.

from skywalking import agent, config

config.init(collector='127.0.0.1:11800', service='your awesome service')
agent.start()

Alternatively, you can also pass the configurations via environment variables and you don't need to call config.init.

The supported environment variables are as follows:

Environment Variable Description Default
SW_AGENT_NAME The name of the Python service Python Service Name
SW_AGENT_INSTANCE The name of the Python service instance Randomly generated
SW_AGENT_COLLECTOR_BACKEND_SERVICES The backend OAP server address 127.0.0.1:11800
SW_AGENT_PROTOCOL The protocol to communicate with the backend OAP, http or grpc, we highly suggest using grpc in production as it's well optimized than http grpc
SW_AGENT_AUTHENTICATION The authentication token to verify that the agent is trusted by the backend OAP, as for how to configure the backend, refer to the yaml. not set
SW_AGENT_LOGGING_LEVEL The logging level, could be one of CRITICAL, FATAL, ERROR, WARN(WARNING), INFO, DEBUG INFO
SW_AGENT_DISABLE_PLUGINS The name patterns in CSV pattern, plugins whose name matches one of the pattern won't be installed ''
SW_MYSQL_TRACE_SQL_PARAMETERS Indicates whether to collect the sql parameters or not False
SW_MYSQL_SQL_PARAMETERS_MAX_LENGTH The maximum length of the collected parameter, parameters longer than the specified length will be truncated 512
SW_IGNORE_SUFFIX If the operation name of the first span is included in this set, this segment should be ignored. .jpg,.jpeg,.js,.css,.png,.bmp,.gif,.ico,.mp3,.mp4,.html,.svg
SW_FLASK_COLLECT_HTTP_PARAMS This config item controls that whether the Flask plugin should collect the parameters of the request. false
SW_DJANGO_COLLECT_HTTP_PARAMS This config item controls that whether the Django plugin should collect the parameters of the request. false
SW_HTTP_PARAMS_LENGTH_THRESHOLD When COLLECT_HTTP_PARAMS is enabled, how many characters to keep and send to the OAP backend, use negative values to keep and send the complete parameters, NB. this config item is added for the sake of performance. 1024

Supported Libraries

There're some built-in plugins that support automatic instrumentation of Python libraries, the complete lists are as follow:

Library Plugin Name
http.server sw_http_server
urllib.request sw_urllib_request
requests sw_requests
Flask sw_flask
PyMySQL sw_pymysql
Django sw_django
redis-py sw_redis
kafka-python sw_kafka
tornado sw_tornado

API

Apart from the libraries that can be instrumented automatically, we also provide some APIs to enable manual instrumentation.

Create Spans

The code snippet below shows how to create entry span, exit span and local span.

from skywalking import Component
from skywalking.trace.context import SpanContext, get_context
from skywalking.trace.tags import Tag

context: SpanContext = get_context()  # get a tracing context
# create an entry span, by using `with` statement,
# the span automatically starts/stops when entering/exiting the context
with context.new_entry_span(op='https://github.com/apache') as span:
    span.component = Component.Flask
# the span automatically stops when exiting the `with` context

with context.new_exit_span(op='https://github.com/apache', peer='localhost:8080') as span:
    span.component = Component.Flask

with context.new_local_span(op='https://github.com/apache') as span:
    span.tag(Tag(key='Singer', val='Nakajima'))

Decorators

from time import sleep

from skywalking import Component
from skywalking.decorators import trace
from skywalking.trace.context import SpanContext, get_context

@trace()  # the operation name is the method name('some_other_method') by default
def some_other_method():
    sleep(1)


@trace(op='awesome')  # customize the operation name to 'awesome'
def some_method():
    some_other_method()


context: SpanContext = get_context()
with context.new_entry_span(op=str('https://github.com/apache/skywalking')) as span:
    span.component = Component.Flask
    some_method()

FAQs

Check the FAQ page or add the FAQs there.

For Developers

Steps to get an operational virtual environment:

  1. git clone https://github.com/apache/skywalking-python.git
  2. cd skywalking-python/tools/env (make sure you actually go into the directory since the scripts use relative paths)
  3. Run the script for your relevant OS to create a virtual environment folder in the project root (skywalking-python/venv) and install all the necessary requirements

Make sure that when the python command is executed on your workstation, the binary it references is python 3.5 or newer!

Steps after contributing

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:

  1. navigate to /path/to/skywalking/agent/tools/env
  2. Execute the build_requirements script relevant to your OS.
  3. Double check the requirements.txt file in the project root to ensure that the changes have been reflected.

License

Apache 2.0

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for apache-skywalking, version 0.2.0
Filename, size File type Python version Upload date Hashes
Filename, size apache_skywalking-0.2.0-py3-none-any.whl (108.0 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size apache-skywalking-0.2.0.tar.gz (34.6 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page