Pinpoint Python Agent

The Python Agent for Pinpoint APM, an open-source Application Performance Management tool for large-scale distributed systems.

Pinpoint Python Agent enables you to monitor Python applications using Pinpoint. Name your application, start it through pinpoint-run, and 35 first-party integrations — web frameworks, HTTP clients, databases, caches, message queues — collect traces, analyze distributed call chains, and visualize service maps in the Pinpoint Web UI, with no changes to your code. The tracing hot path runs in the embedded pinpoint-cpp-agent.

Requirements

Wheels bundle the native extension, so nothing is compiled at install time. An sdist install builds it and additionally needs CMake ≥ 3.21 and a C++17 compiler.

Installation

pip install pinpoint-python-agent

Building from Source

Clone the repository with its submodules (the C++ agent lives in a git submodule):

git clone --recurse-submodules https://github.com/pinpoint-apm/pinpoint-python-agent.git

Or, if you already cloned without the flag:

git submodule update --init --recursive third_party/pinpoint-cpp-agent

Then install from the checkout:

pip install .

See the Development Guide for building the extension in place, running the test suite, and the dev shell that resolves the native libraries.

Getting Started

Zero-code: pinpoint-run

The launcher starts the agent before any of your code runs and activates auto-instrumentation for every supported library your application imports:

pinpoint-run --app-name my-app --service-name my-service --agent-name my-service-web \
    --collector localhost -- python my_app.py

Or drive it from a YAML config file, optionally selecting one of its profiles:

pinpoint-run --config-file pinpoint-config.yaml --active-profile production -- python my_app.py

In-code: init() + autoload()

Call init() early in startup, then activate auto-instrumentation. Libraries already imported are instrumented immediately; everything else the moment it is imported.

import pinpoint
import pinpoint.autoload

pinpoint.init(
    application_name="my-app",       # required
    service_name="my-service",       # required for v4 (the default)
    agent_name="my-service-web",     # optional display label
    server_info="Flask",             # server metadata shown in the UI
    collector_host="localhost",
)
pinpoint.autoload.autoload()

import flask
app = flask.Flask(__name__)

Configuration comes from init() kwargs, PINPOINT_PY_* environment variables, or a YAML config file — see the Configuration Guide for every option and the precedence rules.

Manual tracing

For code paths no integration covers — cron jobs, queue consumers, in-house workers — open a span or a span event with the decorators:

import pinpoint

@pinpoint.span("nightly_billing", rpc_point="/cron/billing")   # a new transaction
def nightly_billing():
    charge(100)

@pinpoint.spanevent("billing.charge")                          # a child of the current span
def charge(amount):
    ...

Both work on async def too. Background hand-offs, context managers, annotations and header propagation are covered in the Custom Instrumentation Guide.

Examples

The examples/ directory holds one subdirectory per integration — the demo application plus a run.sh that starts its backing container and smoke-tests the stack. Each demo's module docstring carries its exact pinpoint-run command and a curl to hit it.

• Web frameworks — flask_demo.py + flask_upstream.py (two services: distributed tracing over requests, plus four MySQL clients), django_demo.py, fastapi_demo.py (every supported PostgreSQL client), starlette_demo.py, pyramid_demo.py, falcon_demo.py (WSGI and ASGI), tornado_demo.py, aiohttp_demo.py (with elasticsearch)
• Framework-less apps — wsgi_demo.py, asgi_demo.py: wrapping an app in the Pinpoint middleware by hand
• Message queues — producer/consumer pairs for kafka, aiokafka, confluent_kafka, pika and aio_pika
• RPC — grpc: client and server, with context propagated across the call

Documentation

Contributing

We are looking forward to your contributions via pull requests.

To report bugs or request features, please create an Issue.

Community

• Pinpoint APM - Main Pinpoint project
• Pinpoint Documentation - Official documentation
• Pinpoint C++ Agent - The native core this agent embeds

License

Pinpoint Python Agent is licensed under the Apache License, Version 2.0. See LICENSE for full license text.