# Pinpoint — Open Source APM for Large-Scale Distributed Systems

> An open-source application performance management tool for large-scale distributed systems providing transaction tracing, topology maps, and real-time diagnostics.

## Install

Save in your project root:

# Pinpoint

## Quick Use
```bash
# Run Pinpoint with Docker Compose
git clone https://github.com/pinpoint-apm/pinpoint-docker.git
cd pinpoint-docker
docker compose pull && docker compose up -d
```

## Introduction
Pinpoint is an open-source APM tool designed for large-scale distributed systems written in Java, Python, and PHP. Developed by Naver, it provides distributed transaction tracing with minimal performance overhead and a rich web UI for real-time service topology visualization.

## What Pinpoint Does
- Traces distributed transactions across microservices with automatic instrumentation
- Visualizes service topology maps showing real-time dependencies and call flows
- Monitors JVM metrics including heap usage, GC, and thread counts per instance
- Provides call stack analysis for slow transactions down to the method level
- Supports Java, PHP, and Python agents with bytecode instrumentation

## Architecture Overview
Pinpoint uses a collector-agent architecture. Lightweight agents instrument application bytecode at startup and send trace spans to the Collector via UDP and TCP. The Collector writes spans and metadata to HBase for storage. The Web UI queries HBase and renders topology maps, scatter plots, and call trees. A separate Flink module handles real-time alarm processing and statistical aggregation.

## Self-Hosting & Configuration
- Deploy with the official Docker Compose setup for quick evaluation
- Install HBase as the primary storage backend for trace and metadata persistence
- Attach the Java agent by adding the javaagent JVM argument to your application
- Configure the agent with pinpoint-root.config for collector addresses and sampling rates
- Use the Web UI at port 8080 to browse traces and configure alert rules

## Key Features
- Automatic bytecode instrumentation with no code changes required
- Sub-5% performance overhead even at high request volumes
- Real-time server map showing service dependencies and traffic flow
- Deep call stack inspection for diagnosing slow or failed transactions
- Built-in alarm system for response time, error rate, and resource thresholds

## Comparison with Similar Tools
- **Jaeger** — CNCF tracing focused on OpenTelemetry; Pinpoint includes topology maps and JVM monitoring
- **Zipkin** — lightweight tracing with simpler UI; Pinpoint offers richer visualization and auto-instrumentation
- **SkyWalking** — similar APM scope with broader language support; Pinpoint has deeper Java bytecode analysis
- **Datadog** — commercial SaaS APM; Pinpoint is fully self-hosted and free
- **New Relic** — commercial with a free tier; Pinpoint gives full data ownership on your infrastructure

## FAQ
**Q: What languages does Pinpoint support?**
A: Java is the primary target with full bytecode instrumentation. PHP and Python agents are also available.

**Q: How much overhead does the agent add?**
A: Typically under 3-5% CPU overhead with sampling enabled, verified across large-scale production deployments.

**Q: What storage backend does it use?**
A: HBase is the primary store. The project provides configuration guides for single-node and clustered setups.

**Q: Can I use it with Kubernetes?**
A: Yes. Helm charts and Docker images are provided for Kubernetes deployment.

## Sources
- https://github.com/pinpoint-apm/pinpoint
- https://pinpoint-apm.github.io/pinpoint

---
Source: https://tokrepo.com/en/workflows/asset-aef218c5
Author: AI Open Source