Pinpoint APM Overview and PHP Full‑Stack Monitoring Setup

As micro‑service architectures grow, the number of services and inter‑service calls become increasingly complex, prompting the need for an Application Performance Management (APM) solution; after evaluating several options, the team selected Pinpoint.

Pinpoint is an open‑source APM designed for large‑scale Java distributed systems. It requires only an agent attached at startup, incurs minimal performance overhead (around 3%), and avoids any code modifications.

Key features of Pinpoint include:

① Distributed transaction tracing across applications; ② Automatic detection of application topology; ③ Horizontal scalability for large server clusters; ④ Code‑level visibility to pinpoint failures and bottlenecks; ⑤ Bytecode instrumentation that adds functionality without source changes; ⑥ Intuitive UI matching project needs; ⑦ Java‑based implementation facilitating future code changes; ⑧ Active community with rapid responses.

Architecture diagram: Pinpoint consists of a Collector that gathers performance data, an Agent that instruments Java applications (e.g., Tomcat), a Web UI for visualization, and HBase for persistent storage.

Data model: The system records three main entities – Span (the basic trace unit, optionally containing SpanEvent ), Trace (a collection of related Spans forming a hierarchical tree), and TraceId (a composite of TransactionId, SpanId, and ParentSpanId). TransactionId uniquely identifies a distributed transaction across the entire system.

Code injection: Pinpoint uses an AOP‑like mechanism; when a class is loaded, interceptors inject before and after logic, capture runtime state, create a Trace via TraceContext , and send it to the Pinpoint server.

Running Pinpoint:

1. Configuration‑file startup (Tomcat):

# Add the following lines to catalina.sh
CATALINA_OPTS="$CATALINA_OPTS -javaagent:/home/webapps/service/pp-agent/pinpoint-bootstrap-1.6.2.jar"
CATALINA_OPTS="$CATALINA_OPTS -Dpinpoint.agentId=pp32tomcattest"
CATALINA_OPTS="$CATALINA_OPTS -Dpinpoint.applicationName=32tomcat"

2. SpringBoot startup:

java -javaagent:/home/webapps/pp-agent/pinpoint-bootstrap-1.6.2.jar -Dpinpoint.agentId=pp32tomcattest -Dpinpoint.applicationName=32tomcat -jar 32tomcat-0.0.1-SNAPSHOT.jar

PHP full‑stack monitoring with Pinpoint:

Preparation: ensure the environment meets requirements and clone the Pinpoint C‑agent repository.

git clone https://github.com/pinpoint-apm/pinpoint-c-agent.git

Build and install the PHP extension:

cd /usr/local/src/pinpoint-c-agent
phpize
./configure
make
make install

Configure php.ini with the extension and collector address, e.g.:

extension=pinpoint_php.so
pinpoint_php.CollectorHost=Tcp:127.0.0.1:9997
pinpoint_php.SendSpanTimeOutMs=0
pinpoint_php.TraceLimit=-1
pinpoint_php.DebugReport=true
error_reporting=E_ALL
log_errors=On
error_log=/tmp/php_fpm_error.log

In the application, add Pinpoint PHP‑AOP via Composer and initialize constants such as APPLICATION_NAME , APPLICATION_ID , AOP_CACHE_DIR , and include the auto‑loader:

# ------------------------------------------------
define('APPLICATION_NAME','APP-2');
define('APPLICATION_ID','app-2');
define('AOP_CACHE_DIR',__DIR__.'/Cache/');
define('PLUGINS_DIR',__DIR__.'/Plugins/');
define('PINPOINT_USE_CACHE','YES');
require_once __DIR__.'/vendor/pinpoint-apm/pinpoint-php-aop/auto_pinpointed.php';
# ------------------------------------------------

Finally, copy the appropriate plugin directory for the chosen framework (e.g., ThinkPHP5 or Yii2) into the project and ensure Composer autoloads the plugins.

Conclusion: Pinpoint provides comprehensive macro‑level monitoring of service chains, CPU, memory, and other metrics, with an active community for support; integrating it—whether via Java agents or the PHP extension—significantly speeds up issue diagnosis and improves overall system reliability.