Of course! Here's a comprehensive guide to using SkyWalking with Python applications.

What is SkyWalking?

SkyWalking is an Application Performance Monitoring (APM) system. It helps you understand how your distributed applications are performing by providing:

• Distributed Tracing: See the flow of a single request as it travels through different services (e.g., a web server -> a Python backend -> a database).
• Metrics Collection: Collect performance data like latency, throughput, and error rates.
• Logging Integration: Correlate logs with traces.
• Topology Mapping: Visualize the architecture of your microservices.
• Alerting: Get notified when performance degrades or errors occur.

Core Concepts for SkyWalking in Python

To use SkyWalking, you need to understand its key components:

1. Agent: A small piece of code that you instrument your application with. It's responsible for collecting data (spans, logs) and sending it to the backend.
2. Backend (OAP Server - Observability Analysis Platform): The central server that receives data from agents, processes it, stores it, and provides APIs for querying. It also powers the UI.
3. UI (User Interface): A web-based dashboard where you visualize your traces, metrics, and topology.

How to Instrument a Python Application with SkyWalking

The primary tool for instrumenting Python is the Apache SkyWalking Python Agent. It works by "wrapping" your code, automatically creating traces for common operations (like HTTP requests, database calls, etc.) without you having to write any tracing code yourself.

Step 1: Set up the SkyWalking Backend (OAP Server & UI)

You need a running OAP server to receive data from your agent. The easiest way to start is with Docker.

# Download the latest docker-compose.yml file
curl -s https://raw.githubusercontent.com/apache/skywalking/master/docker/docker-compose.yml -o docker-compose.yml
# Start the OAP server and UI
docker-compose up -d

This will start two containers:

• oap: The backend server.
• ui: The web dashboard.

You can access the UI at http://localhost:8080. The default username/password is admin/123456.

Step 2: Instrument Your Python Application

Let's instrument a simple Flask application.

Install the SkyWalking Agent Library:

pip install apache-skywalking

Modify Your Python Code:

You need to initialize the agent at the very beginning of your application's entry point (e.g., app.py, main.py).

Here's a complete example of a Flask app:

# app.py
from flask import Flask, jsonify
import time
import logging
# --- SkyWalking Agent Initialization ---
# This must be imported and called before any other application code.
from skywalking import agent
agent.start(
    service_name='my-flask-service',  # The name of your service in the UI
    collector_addresses=['http://localhost:11800'],  # The OAP server's gRPC port
    # agent_authentication='your-secret-key', # Optional, for secure communication
    # sampling_n_per_3_sec=100 # Optional, control the tracing rate
)
# --- End of SkyWalking Initialization ---
app = Flask(__name__)
# Configure basic logging to see correlation
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
@app.route('/')
def hello():
    # The agent will automatically create a span for this request
    logger.info("Handling a request on the root path")
    return "Hello, SkyWalking!"
@app.route('/delay/<int:seconds>')
def delay(seconds):
    # This operation will be timed and recorded as part of the main request span
    logger.info(f"Simulating a delay of {seconds} seconds")
    time.sleep(seconds)
    return jsonify(message=f"Slept for {seconds} seconds")
if __name__ == '__main__':
    # The agent will automatically trace requests made by this server
    app.run(port=5000)

Run Your Application:

python app.py

Your Flask service is now running on http://localhost:5000 and is fully instrumented by SkyWalking.

Step 3: Generate Traffic and View Traces

1. Open your web browser and go to the SkyWalking UI: http://localhost:8080.
2. In the top-left corner, you should see your service name, my-flask-service.
3. Click on it. You will see a "Traces" tab.
4. Generate some traffic to your application:

   # In a new terminal
   curl http://localhost:5000/
   curl http://localhost:5000/delay/2
   curl http://localhost:5000/delay/1

5. Go back to the SkyWalking UI and refresh the Traces page. You should now see the traces for the requests you just made!

You can click on a single trace to see a detailed view of the "span tree," showing how long each part of your application took.

Advanced: Manual Instrumentation

While the agent provides auto-instrumentation, you sometimes need to create your own custom spans to track specific business logic.

You can do this using the trace_context and span modules.

Example: Manually tracing a function

from skywalking import agent, trace_context
from skywalking.trace.span import Span
# ... (agent.start() from before) ...
def process_data(data_id):
    # Get the current active span from the trace context.
    # This will be the span created by the Flask request.
    parent_span = trace_context.get_current_span()
    if parent_span is None:
        # If there's no active span, create a new root one.
        # This is useful for background tasks.
        with agent.start_span('process_data_root') as span:
            return _do_work(span, data_id)
    # If there is a parent span, create a child span.
    # This links the work to the original request.
    with parent_span.create_local_span('process_data') as span:
        span.tag('data_id', data_id) # Add a custom tag
        return _do_work(span, data_id)
def _do_work(span: Span, data_id):
    # This code is now part of the 'process_data' span
    logger.info(f"Processing data {data_id}")
    time.sleep(0.5)
    span.log.info(f"Finished processing data {data_id}")
    return {"status": "ok", "id": data_id}
@app.route('/process/<int:data_id>')
def process_endpoint(data_id):
    result = process_data(data_id)
    return jsonify(result)
# ... (rest of the app) ...

Now, when you call http://localhost:5000/process/123, you'll see a process_data span nested inside the main request span in the UI.

Integrating with Other Frameworks

The process is very similar for other Python web frameworks. You just need to ensure the agent is initialized before the application starts.

• Django:

  • Install: pip install apache-skywalking
  • Add to settings.py:

    MIDDLEWARE = [
        # ... other middlewares ...
        'skywalking.middleware.DjangoMiddleware', # Add this
    ]
    SKYWALKING = {
        'SERVICE_NAME': 'my-django-app',
        'COLLECTOR_ADDRESS': 'http://localhost:11800',
    }

  • No need to manually start the agent; the middleware handles it.

• FastAPI:

  • Install: pip install apache-skywalking

  • Initialize the agent at the start of your main.py:

    from skywalking import agent
    from fastapi import FastAPI
    agent.start(
        service_name='my-fastapi-service',
        collector_addresses=['http://localhost:11800'],
    )
    app = FastAPI()
    # ... your app code ...

Configuration Options

The agent.start() call has many useful options:

Troubleshooting

• No traces appearing in the UI:
  1. Check that the OAP server is running: docker-compose logs oap.
  2. Verify the COLLECTOR_ADDRESS in your agent configuration matches the OAP server's gRPC port (default is 11800).
  3. Check the agent's logs. If you're running in a terminal, you should see output from the agent. It will often print errors if it can't connect to the collector.
  4. Check your firewall or network settings to ensure the agent can reach the OAP server.
• Sampling is too aggressive:
  • If you feel like you're not seeing enough traces, try increasing the sampling_n_per_3_sec value or setting it to 0 to sample all traces (for debugging purposes). Be careful, as this can generate a lot of data.