Pinpoint C++ Agent

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

Pinpoint C++ Agent enables you to monitor C++ applications using Pinpoint. Developers can instrument C++ applications to collect traces, analyze distributed call chains, and visualize service maps in the Pinpoint Web UI.

Requirements

Requirement	Version
Pinpoint Collector	3.1.0+
C++ Compiler	C++17 (GCC 8+, Clang 6+)
Build System	Bazel 7.0+ or CMake 3.21+
OS	Linux, macOS

Building from Source

Clone the repository with its submodules (the Protobuf/gRPC service definitions live in a git submodule):

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

Or, if you already cloned without the flag:

git submodule update --init --recursive

Then build:

# CMake
cmake --preset default
cmake --build --preset default
ctest --preset default

# Bazel
bazel build //...
bazel test //test/...

See the Build Guide for submodule setup, vcpkg and FetchContent dependency builds, build options, coverage, sanitizers, and the integration tests.

Examples

Start the agent, then trace a request as a span and each unit of work within it as a span event (trimmed from proxy.cpp):

#include <cstdlib>
#include <iostream>

#include "pinpoint/tracer.h"

int main() {
    // Set the application name shown in the Pinpoint Web UI.
    setenv("PINPOINT_CPP_APPLICATION_NAME", "cpp-proxy", 0);

    // Start the agent. Configuration comes from a config file or
    // PINPOINT_CPP_* environment variables (see doc/config.md).
    if (!pinpoint::StartAgent()) {
        std::cerr << "failed to start the pinpoint agent: check the agent log" << std::endl;
    }

    // Create a span for an incoming request.
    auto span = pinpoint::GlobalAgent()->NewSpan("C++ Proxy", "/api/members");

    // Trace a unit of work within the request as a span event.
    auto event = span->NewSpanEvent("proxy.forward");
    // ... do the work ...
    event->EndEvent();

    // Finish the span; it is delivered to the collector asynchronously.
    span->EndSpan();

    pinpoint::GlobalAgent()->Shutdown();
}

The example/ directory contains complete working examples:

• proxy.cpp — HTTP proxy: client-side tracing and cross-process context propagation
• server.cpp — HTTP backend: server-side tracing, a MySQL span event, and an async span

More examples are in the pinpoint-cpp-examples repository.

Documentation

Document	Description
Getting Started Guide	Step-by-step setup with full examples
Configuration Guide	All configuration options, environment variables, and best practices
Instrumentation Guide	C++ API reference: spans, span events, annotations, distributed tracing
C API Instrumentation Guide	The same, for plain C via tracer_c.h (pt_* functions)
API Contracts	Threading, end-exactly-once, overflow and noop-span rules the agent enforces on spans, events and annotations
Pre-fork Integration Guide	Running the agent inside pre-fork servers (nginx, Apache prefork, uWSGI)
Build Guide	Building from source with Bazel and CMake, and linking the library
Troubleshooting	Startup contract, logging, common issues and solutions

Contributing

We are looking forward to your contributions via pull requests.

For tips on contributing code fixes or enhancements, please see the Contributing Guide.

The Development Guide covers the repository layout, the Docker and CI environments, the test suites, coverage, sanitizers, benchmarks, and the design decisions behind the implementation.

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

Community

• Pinpoint APM - Main Pinpoint project
• Pinpoint Documentation - Official documentation

License

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