pinpoint-apm / pinpoint-apm/pinpoint-cpp-agent

Support ObjectName UID version (v1/v3/v4) for agent self-identity

Open
#87 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
C++
Stars
2
Forks
2
PR merge metrics
No merged PRs in 30d

Description

Background

The Pinpoint Java Agent generates the agent's self-identity (ObjectName) in one of three formats — v1 / v3 / v4 — based on the pinpoint.modules.uid.version setting. This issue ports the same capability to the C++ Agent.

Configuration property

  • Key: UidVersion (env: PINPOINT_CPP_UID_VERSION)
  • Allowed values: v1, v3, v4 (case-insensitive); default v3; unknown/missing → v3
  • v4-only: ServiceName (PINPOINT_CPP_SERVICE_NAME), ApiKey (PINPOINT_CPP_API_KEY)

Version differences

v1 v3 (default) v4
ObjectName version 1 1 4
agentId user input, else auto base64(UUIDv7) same as v1 always auto UUIDv7 (input ignored)
applicationName max length 24 254 254
serviceName / apiKey unused unused required
gRPC protocol.version header 100 100 400
gRPC servicename / apikey headers not sent not sent sent

v1 and v3 are identical on the wire (protocol.version=100); the only difference is the applicationName length limit (24 vs 254).

Requirements

  • Parse UidVersion / ServiceName / ApiKey (YAML + env), with default/fallback handling
  • ID validator (charset [a-zA-Z0-9._-], per-version length constants)
  • v1/v3/v4 resolver — abort startup (noop agent) with a log when a required value is missing
  • UUIDv7 generation (RFC 9562) + URL-safe Base64 encoding (22 chars, byte-compatible with Java Base64Utils)
  • gRPC header builder version branching (protocol.version, plus servicename/apikey for v4)
  • Mask apiKey in logs / serialization
  • Unit tests: version parsing, length boundaries (24 vs 254), v4 missing-required-value, UUID→base64 golden vectors, per-version header sets

Notes: corrections vs. the Java spec

  • protocol.version wire value is 100 / 400 (ProtocolVersion.V1(1_00) / V4(4_00))
  • The start-time header key is starttime (matches the existing C++ value)
  • v4 regenerates the agentId (UUIDv7) on every restart (same as Java)

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by locating the existing C++ configuration parsing, ObjectName/agentId resolution, and gRPC header-building paths. Trace their current tests, then cover version parsing, validation, UUID-to-Base64 vectors, required v4 values, masked ApiKey handling, and the per-version header sets until all listed boundaries pass.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp, grpc
Domain
networking, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.