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

Requirement	Version
Pinpoint Collector	3.1.0+
Python	3.11+ (CPython)
OS	Linux, macOS (Windows is not supported)

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-service --agent-name my-service-web \
    --collector localhost -- 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-service",   # required
    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

Document	Description
Getting Started Guide	Step-by-step setup: install, configure, first traced request
Configuration Guide	Every option, as an init() kwarg, environment variable and config-file key, with precedence rules
Auto-Instrumentation Catalog	The 35 supported libraries, what each records, and how to turn one off
Custom Instrumentation Guide	Python API reference: spans, span events, annotations, async hand-offs, distributed tracing
API Contracts	Threading, end-exactly-once and overflow rules the agent enforces on spans, events and annotations
Pre-fork Integration Guide	Running the agent under gunicorn, uWSGI and multiprocessing
Troubleshooting	Startup verification, agent logs, common issues and solutions
Development Guide	Contributors: building the native extension from source, running the tests, and adding a bundled integration

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.