github pinpoint-apm/pinpoint v4.0.0
4.0.0 release
on GitHub

latest release: latest
5 hours ago

Pinpoint 4.0.0 is a major release that opens the 4.x line. It has three highlights:

  • Service, now on by default, groups applications so that each team can focus on its own service.
  • OpenTelemetry Trace Support brings applications instrumented with OpenTelemetry into Pinpoint without the Pinpoint agent.
  • Service Alarm is a renewed alarm system built around services. New Alarm Templates make it easy to set up the same alarms for many applications.

It also adds Spring Boot 4.1 / Spring Framework 7.0 support and includes the agent-stability work that shipped in 3.1.1.

This release changes defaults and removes several legacy code paths, so please read the Upgrade guide before upgrading in place from 3.1.x.

Highlights

Service (enabled by default)

Service model

Pinpoint 4.0.0 introduces the Service feature.
You can group several applications into one service and see how services call each other on the Service Map.
Screens that support the service feature show only the data of the applications in the selected service.

  • Monitoring: Focus on the data of the service you own and find the cause of a problem faster.
  • Operations: As applications grow, group them by service to keep the monitoring targets clear.

Monitoring targets form a Service → Application → Agent hierarchy. The demo-shop-commerce service of the demo shopping mall looks like this: 

Service: demo-shop-commerce          products and orders
├─ Application: Shopping-Order       order processing
│  ├─ Agent: shop-order-01
│  └─ Agent: shop-order-02
└─ Application: Shopping-Product     product lookup
   └─ Agent: shop-product-01

Data that is not assigned to a service, such as data collected before the upgrade or sent by agents older than 4.0.0, stays in the DEFAULT service. Creating a new service does not move existing data into it. To use the service feature, create the service in the Web first, then set pinpoint.serviceName on the agents (see Agent). See the Service guide for details.

OpenTelemetry Trace Support

image

Pinpoint 4.0.0 receives OpenTelemetry traces directly. Applications instrumented with the OpenTelemetry Java agent, any OTel SDK, or the OpenTelemetry Collector appear in the same server map, transaction list and call tree as agent-collected data, without the Pinpoint agent.

  • OTLP over gRPC and HTTP
    Traces are accepted over gRPC and over HTTP in both protobuf and JSON, with gzip and standard OTLP responses. Span time keeps nanosecond precision (#13923).

  • URL Statistic and Error Analysis
    URL Statistic is built from OTel server spans using the route template (#14229). Exceptions recorded on OTel spans flow into Error Analysis with multi-language stacktrace parsing (JVM, Go, Node.js, Python) and grouping by route (#14233). SQL text is shown in the call tree.

  • Server map and service map links
    Caller → callee edges between OTel-instrumented applications are drawn from a pp entry in the W3C tracestate header, written by the sender via pinpoint-otel-extension (OpenTelemetry Java agent extension, plus guides for Java SDK, Python, Go and Node.js). When the caller cannot propagate it, the collector and a batch job join the two sides and fill in the edge (#14453). OTel span links open the linked transaction (#13596).

  • Error log collection
    The collector also receives OTLP logs. Exceptions that were caught and only logged are stored in Error Analysis and linked to the span they were logged in (#14299).

  • Other changes

    • GenAI spans are summarized in the call tree: the model that served the request, input/output token usage including cached tokens, and time to first token.
    • Sensitive span attributes are never stored: HTTP headers, credentials and tokens are dropped, and URL query strings and command-line arguments are stripped before the span is written.

Service Alarm

Service Alarm
Alarm Rules

Alarms are rebuilt around services (#14282). The team that owns a service manages its rules and notification channels in one place. Alerts can be tuned to how serious a problem is, and each one leads straight to where you can investigate. Rules can watch response quality (slow and error rates, Apdex), calls to another application, agent resources (heap, CPU, connection pool) and deadlocks.

Alarm Templates are sets of rules that you apply to many applications at once. Start from a built-in preset for agent health or response quality, or make your own. When you change a template, every application that uses it updates automatically.

Legacy Alarm Service Alarm
Conditions One metric per rule Several metrics combined with AND / OR, so you can cut noisy alerts
Severity None WARNING / CRITICAL
Timing Fixed 5-minute window, checked every 3 minutes Window, check interval and repeat interval set per rule
Setup Rules registered one application at a time Templates and built-in presets apply a rule set to many applications
Channels Configured on each rule Email, SMS and webhook (Slack included) registered once per service and shared
After an alert No history in the UI Rule status and firing history in the UI; notifications link to the Service Map or Inspector

See the full Alarm comparison in the Alarm guide. Existing alarm rules are not migrated automatically, but a template lets you apply the same alarms to many applications at once. See Upgrade guide → Service Alarm before you switch.

Agent

  • Service name is now required (#14379). Every agent starts with a service name that has been registered in the Web, and the agent ID is generated automatically instead of being set by hand. Agents configured the 3.x way do not start until a service name is added; the 3.1.x identifiers can still be chosen by configuration.
  • Application type for services (#14455). Applications in a service are shown as JAVA rather than as the detected server such as TOMCAT or JETTY, so icons and per-type statistics on the server map change. The previous behavior can be restored by configuration.
  • Compressed transport (#14477). Spans and statistics are sent compressed by default, reducing network traffic to the collector with no collector change.
  • More reliable async tracing (#14391). Async spans are no longer lost or reported as corrupted call stacks when their scope ends early.
  • Spring Boot 4.1 / Spring Framework 7.0 are supported; Spring Framework 3.x and 4.x are no longer supported.
  • New plugins: Apache Pekko HTTP (#13818) and Ktor client.
  • okhttp 4.x and 5.x are supported (#14221).
  • Tomcat 9 to 11 are supported (#14481); Tomcat 8 is no longer supported.

Security

  • Webhook host allowlist (#13857): configured hosts may resolve into otherwise-rejected private ranges, closing the gap left by the 3.1.1 SSRF validation. Carries the 3.1.1 basic-login hardening (required JWT secret, HttpOnly cookie).

Removals & cleanup

  • Legacy server map v2 support removed (#13905).
  • Legacy application & agent list table (ApplicationIndex) support removed (#14028).
  • Legacy trace index table (ApplicationTraceIndex) support removed (#14028).
  • The emptied pinpoint-plugins-bom module removed and plugin library versions declared explicitly (#14486); the otlptrace-otel-extension module removed in favor of pinpoint-apm/pinpoint-otel-extension.

Upgrade guide

Defaults that changed

  • The service feature is on by default. To restore 3.1.x behavior, set the three switches back to false: 

    # web
experimental.enableServiceMap.value=false
pinpoint.modules.web.servicemap.enabled=false
# collector
pinpoint.collector.service.lookup.enabled=false

    With the service feature off, the collector stores all data in the DEFAULT service, whatever service name the agent reports, and does not check that the service is registered. 4.0.0 agents still need pinpoint.serviceName to start: set it to DEFAULT so that the application type is detected as in 3.1.x (TOMCAT, JETTY, ...) instead of JAVA.

  • Default pinpoint.modules.uid.version / NameVersion is now v4 (#14379). If the agent reports to a collector older than 4.0.0, pin it explicitly: 

    pinpoint.modules.uid.version=v3

  • Agent gRPC compression is on by default. It is backward compatible, but to disable it: 

    profiler.transport.grpc.span.batch-sender.compression=none
profiler.transport.grpc.stat.sender.compression=none

Service Alarm

  • Service Alarm is evaluated and sent by the new alarm-batch-starter process. It needs MySQL, Spring Batch metadata, HBase and Pinot. The agent statistics table settings (alarm.agent-stat.table.prefix, padding-length, count) are required, or startup fails.
  • The legacy alarm still runs in the batch module, for the DEFAULT service only.
  • Legacy alarm rules are not migrated automatically. Re-register them as Service Alarm rules; the Alarm guide maps each legacy checker to its Service Alarm equivalent.
  • Legacy SMS, email and webhook settings are not migrated either. If you enable the same condition in both systems, you get duplicate notifications.
  • Service Alarm requires the service feature. With pinpoint.modules.web.servicemap.enabled=false, only the legacy alarm screen appears.
  • The alarm API has @PreAuthorize hooks for a custom permission evaluator. Open-source Web does not enable method security, so these hooks are not enforced by default: anyone who can access the Web can view and change the rules, channels and templates of every service.

Schema

Upgrading to 4.0.0 requires the schema changes below. See Schema changes in 4.0.0.

  • MySQL 5.x is no longer supported. 4.0.0 requires MySQL 8.4+; upgrade MySQL before upgrading Pinpoint if you run 5.7 (end of life since October 2023).
  • Pinot: add the serviceName column (STRING, default DEFAULT) to the exceptionTrace table (pinot-exceptionTrace-schema.json).
  • MySQL (8.4+, configuration columns use the JSON type):
    • Create the service table with Service-Schema.sql.
    • Create the alarm tables with CreateTableStatement-mysql.sql: alarm_template, alarm_template_item, alarm_rule_v2, alarm_rule_local_config, alarm_notification_channel, alarm_channel_binding, alarm_state, alarm_history_v2, alarm_notification_outbox.
    • Create the Spring Batch metadata for Alarm Batch with SpringBatchJobRepositorySchema-mysql.sql; Alarm Batch does not create it automatically.
  • HBase: add the tables listed in HBase table changes for 3.1.0 (MapAppSelf, MapAgentSelf, MapAppOut, MapAppIn, MapAppHost, TraceIndex, Application, AgentId) if they do not exist yet. Downgrading a 4.0.0 collector back to 3.1.x in place is not supported.

Removed configuration

  • The deprecated XML batch configuration and EnableBatchProcessing are removed — batch runs on the annotation-based config only (#13830).

Build

  • Build JDK is 17; minimum Maven is 3.9.0 (the bundled mvnw is unaffected).

Compatibility

Component Requirement Notes
Agent JDK 8+ verified on 8 / 11 / 17 / 21 / 25
Collector / Web / Batch JDK 17+
Collector for agent 4.0.0 4.0.0+ with the default uid.version=v4; pin v3 for older collectors
MySQL 8.4+ new service and alarm tables
Pinot schema migration serviceName column added to exceptionTrace
HBase schema migration add tables (MapApp*, MapAgentSelf, TraceIndex, Application, AgentId)
Build Maven 3.9.0+

Downloads

Binaries are attached to this release:

  • pinpoint-agent-4.0.0.tar.gz
  • pinpoint-batch-4.0.0-exec.jar
  • pinpoint-alarm-batch-starter-4.0.0-exec.jar
  • pinpoint-collector-4.0.0-exec.jar
  • pinpoint-collector-starter-4.0.0-exec.jar
  • pinpoint-web-4.0.0-exec.jar
  • pinpoint-web-starter-4.0.0-exec.jar

What's Changed

New Contributors

Full Changelog: v3.1.1...v4.0.0

Check out latest releases or
releases around pinpoint-apm/pinpoint v4.0.0

Don't miss a new pinpoint release

NewReleases is sending notifications on new releases.

Get notifications