From 4e03d422b3aae84691d68f8d8fb00e5aba3c7be8 Mon Sep 17 00:00:00 2001 From: Jaroslav Bachorik Date: Fri, 13 Nov 2026 14:19:12 +0100 Subject: [PATCH 1/8] Serialize ROOT_ENUM_ERROR accurately in reference-chain abandonment events The reference-chain termination ladder (MAX_CONSECUTIVE_ENUM_ERRORS) can abandon a search with SearchAbandonReason::ROOT_ENUM_ERROR, but the datadog.ReferenceChainAbandoned reason table stopped at canary_stuck, so that abandonment serialized as "unknown" and misattributed the cause in the JFR event. The table now covers the whole enum: an "unknown" slot at RECORDING_END (never enqueued, keeps ROOT_ENUM_ERROR at its enum index), "root_enum_error" at 5, and a size-based bounds check. A root-enum JVMTI error also increments the reference_chain_root_enum_errors counter, and the stale termination ladder and abandonment-reason list in doc/ now describe the ROOT_ENUM_ERROR branch. Debug-build-only seam setRootEnumErrorInjection0 plus a native serialization gtest and a Java end-to-end test pin the reason string. --- ddprof-lib/src/main/cpp/counters.h | 6 + ddprof-lib/src/main/cpp/flightRecorder.cpp | 16 +- ddprof-lib/src/main/cpp/javaApi.cpp | 11 ++ .../src/main/cpp/referenceChainTraversal.cpp | 13 +- ddprof-lib/src/main/cpp/referenceChains.h | 14 ++ .../com/datadoghq/profiler/JavaProfiler.java | 12 ++ .../cpp/referenceChainJfrRoundtrip_ut.cpp | 73 +++++++++ .../profiler/ReferenceChainTestHooks.java | 4 + .../ReferenceChainRootEnumErrorTest.java | 149 ++++++++++++++++++ doc/ReferenceChainsCollectionSummary.md | 2 +- .../LiveHeapReferenceChainsImplementation.md | 4 +- 11 files changed, 297 insertions(+), 7 deletions(-) create mode 100644 ddprof-test/src/test/java/com/datadoghq/profiler/referencechains/ReferenceChainRootEnumErrorTest.java diff --git a/ddprof-lib/src/main/cpp/counters.h b/ddprof-lib/src/main/cpp/counters.h index fb7fd16388..71412402f0 100644 --- a/ddprof-lib/src/main/cpp/counters.h +++ b/ddprof-lib/src/main/cpp/counters.h @@ -277,6 +277,12 @@ * release is retried on a later call rather than proceeding, but this \ * counts how often that retry path is taken. */ \ X(REFERENCE_CHAIN_TAG_RELEASE_FAILED, "reference_chain_tag_release_failed") \ + /* ReferenceChainTracker::runPassManualWalk()'s root/stack-ref enumeration \ + * (IterateOverReachableObjects) failed with a JVMTI error - the attempt \ + * learned nothing about roots and _root_enum_incomplete holds the terminal \ + * ladder; MAX_CONSECUTIVE_ENUM_ERRORS consecutive failures abandon the \ + * search with SearchAbandonReason::ROOT_ENUM_ERROR. */ \ + X(REFERENCE_CHAIN_ROOT_ENUM_ERRORS, "reference_chain_root_enum_errors") \ /* The profiler-side reference-chain writer could not acquire a \ * sample-record lock within its bounded retry budget and dropped the \ * already-dequeued datadog.ReferenceChain event for this dump - not \ diff --git a/ddprof-lib/src/main/cpp/flightRecorder.cpp b/ddprof-lib/src/main/cpp/flightRecorder.cpp index d3826685db..f7c4bd0017 100644 --- a/ddprof-lib/src/main/cpp/flightRecorder.cpp +++ b/ddprof-lib/src/main/cpp/flightRecorder.cpp @@ -2666,9 +2666,19 @@ void Recording::recordReferenceChainAbandoned( buf->putVar64(event->_start_time); // SearchAbandonReason (the engine's reason enum) - kept as a small fixed table // here rather than a T_XXX enum type, mirroring NativeSocketEvent's - // _operation -> kOpNames string mapping above. - static const char *const kReasons[] = {"none", "frontier_cap", "ttl", "canary_stuck"}; - buf->putUtf8(event->_reason < 4 ? kReasons[event->_reason] : "unknown"); + // _operation -> kOpNames string mapping above. Indexed directly by the + // SearchAbandonReason value; the "unknown" slot at RECORDING_END (4) exists + // only to keep ROOT_ENUM_ERROR (5) at its enum index - RECORDING_END is never + // enqueued as an abandonment event (see its own comment), so that slot's + // string is never actually written. Without its entry, ROOT_ENUM_ERROR - a + // genuinely distinct, engine-reported abandonment - would serialize as + // "unknown" and misattribute the cause in the JFR event. + static const char *const kReasons[] = {"none", "frontier_cap", "ttl", + "canary_stuck", "unknown", + "root_enum_error"}; + buf->putUtf8(event->_reason < (u8)(sizeof(kReasons) / sizeof(kReasons[0])) + ? kReasons[event->_reason] + : "unknown"); buf->putVar32(event->_passes_run); buf->putVar32(event->_frontier_size); buf->putVar32(event->_hop_cap); diff --git a/ddprof-lib/src/main/cpp/javaApi.cpp b/ddprof-lib/src/main/cpp/javaApi.cpp index b2605d22d9..debe68888c 100644 --- a/ddprof-lib/src/main/cpp/javaApi.cpp +++ b/ddprof-lib/src/main/cpp/javaApi.cpp @@ -1228,6 +1228,13 @@ Java_com_datadoghq_profiler_JavaProfiler_runReferenceChainPass0( return ReferenceChainTracker::instance()->runPassSerialized(jvmti, env); } +extern "C" DLLEXPORT void JNICALL +Java_com_datadoghq_profiler_JavaProfiler_setRootEnumErrorInjection0( + JNIEnv *env, jclass unused, jboolean enabled) { + ReferenceChainTracker::instance()->setRootEnumErrorInjectionForTest( + enabled == JNI_TRUE); +} + extern "C" DLLEXPORT void JNICALL Java_com_datadoghq_profiler_JavaProfiler_pollReferenceChainTargets0( JNIEnv *env, jclass unused) { @@ -1586,6 +1593,10 @@ Java_com_datadoghq_profiler_JavaProfiler_runReferenceChainPass0( return JNI_FALSE; } +extern "C" DLLEXPORT void JNICALL +Java_com_datadoghq_profiler_JavaProfiler_setRootEnumErrorInjection0( + JNIEnv *env, jclass unused, jboolean enabled) {} + extern "C" DLLEXPORT void JNICALL Java_com_datadoghq_profiler_JavaProfiler_pollReferenceChainTargets0( JNIEnv *env, jclass unused) {} diff --git a/ddprof-lib/src/main/cpp/referenceChainTraversal.cpp b/ddprof-lib/src/main/cpp/referenceChainTraversal.cpp index e7badba940..252a7764df 100644 --- a/ddprof-lib/src/main/cpp/referenceChainTraversal.cpp +++ b/ddprof-lib/src/main/cpp/referenceChainTraversal.cpp @@ -209,7 +209,17 @@ void ReferenceChainTracker::runPassManualWalk(jvmtiEnv *jvmti, JNIEnv *jni, ctx.frontier_cap_hit = false; u64 root_enum_start_ns = OS::nanotime(); - jvmtiError root_err = jvmti->IterateOverReachableObjects( + jvmtiError root_err; +#ifdef DEBUG + // Debug-build-only error injection (setRootEnumErrorInjectionForTest()): forces this attempt + // to fail with JVMTI_ERROR_OUT_OF_MEMORY without touching the real JVMTI call - a failed + // call makes no progress and leaves user_data unmodified, so skipping it is faithful to the + // failure being simulated. Release builds never set the flag. + if (_root_enum_error_injection.load(std::memory_order_acquire)) { + root_err = JVMTI_ERROR_OUT_OF_MEMORY; + } else +#endif + root_err = jvmti->IterateOverReachableObjects( heapRootCallback, stackRefCallback, /*object_ref_callback=*/nullptr, &ctx); u64 root_enum_safepoint_ns = OS::nanotime() - root_enum_start_ns; @@ -232,6 +242,7 @@ void ReferenceChainTracker::runPassManualWalk(jvmtiEnv *jvmti, JNIEnv *jni, // count feeds the ladder's ROOT_ENUM_ERROR abandon; any successful attempt resets it. _root_enum_incomplete = true; _consecutive_enum_errors++; + Counters::increment(REFERENCE_CHAIN_ROOT_ENUM_ERRORS); *truncated = true; *frontier_cap_hit = false; return; diff --git a/ddprof-lib/src/main/cpp/referenceChains.h b/ddprof-lib/src/main/cpp/referenceChains.h index 3eb616d53b..ce3d9ea705 100644 --- a/ddprof-lib/src/main/cpp/referenceChains.h +++ b/ddprof-lib/src/main/cpp/referenceChains.h @@ -796,6 +796,13 @@ class ReferenceChainTracker { // ladder abandons the search (ROOT_ENUM_ERROR) - the only bound when ttl=0. u32 _consecutive_enum_errors = 0; + // Debug-build-only test seam flag: when true, runPassManualWalk()'s root/stack-ref enumeration + // attempt fails with JVMTI_ERROR_OUT_OF_MEMORY without touching the real JVMTI call (see + // setRootEnumErrorInjectionForTest()). Written by a JNI test thread, read on the BFS thread, so + // atomic with release/acquire ordering - a torn/relaxed read could let one pass run without the + // injection the test counted on. + std::atomic _root_enum_error_injection{false}; + ReferenceChainTracker() : _enabled(false), _frontier(nullptr), _configured_frontier_cap(0), @@ -1306,6 +1313,13 @@ class ReferenceChainTracker { : OS::nanotime() - (u64)ms_since_last_enum * 1000000ULL; _last_root_enum_safepoint_ms = last_enum_cost_ms; } + // Debug-build-only test seam (javaApi.cpp's setRootEnumErrorInjection0()): see + // _root_enum_error_injection's own comment. No engine lock: the flag is atomic; seeding it + // while a driven pass is in flight only shifts which pass sees the injection, which no test + // depends on. + void setRootEnumErrorInjectionForTest(bool enabled) { + _root_enum_error_injection.store(enabled, std::memory_order_release); + } bool shouldRunRootEnumForTest(u64 now_ns, bool manual_first_pass) const { MutexLocker engine_guard(_engine_lock); return shouldRunRootEnum(now_ns, manual_first_pass); diff --git a/ddprof-lib/src/main/java/com/datadoghq/profiler/JavaProfiler.java b/ddprof-lib/src/main/java/com/datadoghq/profiler/JavaProfiler.java index f0b3f5f428..04aab9f192 100644 --- a/ddprof-lib/src/main/java/com/datadoghq/profiler/JavaProfiler.java +++ b/ddprof-lib/src/main/java/com/datadoghq/profiler/JavaProfiler.java @@ -667,6 +667,18 @@ private static native void setTraceContext0( */ static native boolean runReferenceChainPass0(); + /** + * Test seam (debug native builds only): when {@code enabled}, forces every reference-chain + * root/stack-ref enumeration attempt ({@code IterateOverReachableObjects}) to fail with a JVMTI + * error, without touching the real JVMTI call. With the injection active the tracker counts + * consecutive failed attempts and abandons with the {@code ROOT_ENUM_ERROR} reason after {@code + * MAX_CONSECUTIVE_ENUM_ERRORS} attempts, so a test can drive the {@code + * datadog.ReferenceChainAbandoned} event's {@code root_enum_error} reason deterministically. + * Restore with {@code enabled = false} before the next test in this shared JVM: the flag is + * process-wide singleton state. + */ + static native void setRootEnumErrorInjection0(boolean enabled); + /** * Test seam (debug native builds only): runs one poll of ReferenceChainTracker's * LivenessTracker-to-chain-reconstruction bridging step synchronously - for each current leak diff --git a/ddprof-lib/src/test/cpp/referenceChainJfrRoundtrip_ut.cpp b/ddprof-lib/src/test/cpp/referenceChainJfrRoundtrip_ut.cpp index 2f56827d37..91e3cd664e 100644 --- a/ddprof-lib/src/test/cpp/referenceChainJfrRoundtrip_ut.cpp +++ b/ddprof-lib/src/test/cpp/referenceChainJfrRoundtrip_ut.cpp @@ -73,6 +73,7 @@ #include "engine.h" #include "flightRecorder.h" #include "jfrMetadata.h" +#include "referenceChainFrontier.h" #include "profiler.h" #include "tsc.h" #include "vmEntry.h" @@ -535,3 +536,75 @@ TEST_F(ReferenceChainJfrRoundtripTest, DefaultLivenessEventHasZeroLeakTag) { EXPECT_EQ(0, event.leak_tag); EXPECT_EQ(0u, event.leak_tag_incarnation); } + +// recordReferenceChainAbandoned()'s kReasons[] table must map every +// SearchAbandonReason value to a distinct string, indexed directly by the +// enum value - a stale table silently serializes a genuinely-distinct +// abandonment as "unknown", misattributing the cause in the +// datadog.ReferenceChainAbandoned event. ROOT_ENUM_ERROR (5) pins the +// table's tail - without its entry, the engine's enum-error abandonment +// (referenceChainTraversal.cpp's error branch) serializes as "unknown"; +// an out-of-range value pins the bounds check. +TEST_F(ReferenceChainJfrRoundtripTest, + AbandonedEventSerializesRootEnumErrorReason) { + Arguments args; + ASSERT_FALSE(args.parse("referencechains=true:hops=64:budget=1000")); + args._jfr_options = JFR_SYNC_OPTS; + + // Own file, NOT the companion JMC round-trip path - this test's events use + // reason values only (no class dictionary entries), and leaving them on + // the companion path would make the Java parser test resolve unrelated + // state. + const std::string path = chainRoundtripJfrPath() + ".abandoned"; + int fd = open(path.c_str(), O_CREAT | O_RDWR | O_TRUNC, 0644); + ASSERT_GE(fd, 0) << "could not open " << path << " for writing"; + + Recording rec(fd, args); + Buffer *buf = rec.buffer(/*lock_index=*/0); + rec.flushIfNeeded(buf, /*limit=*/0); + + // Both events carry _start_time = 0 (single-byte var64) so the reason + // field's offset is computable without decoding the timestamp. + struct ReasonCase { + u8 reason; + const char *expected; + }; + const ReasonCase cases[] = { + {SearchAbandonReason::ROOT_ENUM_ERROR, "root_enum_error"}, + {250, "unknown"}, // out of table range - bounds check + }; + for (const ReasonCase &c : cases) { + ReferenceChainAbandonedEvent event; + event._reason = c.reason; + event._start_time = 0; + + int offset_before = buf->offset(); + rec.recordReferenceChainAbandoned(buf, &event); + int offset_after = buf->offset(); + EXPECT_LE(offset_after, RECORDING_BUFFER_LIMIT); + EXPECT_GT(offset_after, offset_before); + + // Field order (recordReferenceChainAbandoned): 1-byte size prefix + // (writeEventSizePrefix patches one byte - this event is always < + // 128 bytes), var64 type id, var64 startTime, then the reason putUtf8 + // = 1 encoding-tag byte + var32 length + payload. _start_time = 0 + // makes the timestamp var64 exactly one byte. + const char *data = buf->data() + offset_before; + int off = 1; // size prefix + off += sizeOfVar64((u64)T_REFERENCE_CHAIN_ABANDONED); + off += sizeOfVar64(0); + EXPECT_EQ(3, data[off]) + << "reason putUtf8's encoding-tag byte must precede its length"; + off += 1; + u32 len = decodeVar32(data, &off); + u32 expected_len = (u32)strlen(c.expected); + ASSERT_EQ(expected_len, len) + << "reason " << (int)c.reason << " must serialize as " + << c.expected; + EXPECT_EQ(0, memcmp(data + off, c.expected, expected_len)) + << "reason " << (int)c.reason << " must serialize as " + << c.expected; + } + + unlink(path.c_str()); +} diff --git a/ddprof-test/src/test/java/com/datadoghq/profiler/ReferenceChainTestHooks.java b/ddprof-test/src/test/java/com/datadoghq/profiler/ReferenceChainTestHooks.java index 0d3d12c213..7a2adee3bf 100644 --- a/ddprof-test/src/test/java/com/datadoghq/profiler/ReferenceChainTestHooks.java +++ b/ddprof-test/src/test/java/com/datadoghq/profiler/ReferenceChainTestHooks.java @@ -50,6 +50,10 @@ public static boolean runReferenceChainPass0() { return JavaProfiler.runReferenceChainPass0(); } + public static void setRootEnumErrorInjection0(boolean enabled) { + JavaProfiler.setRootEnumErrorInjection0(enabled); + } + public static void setReferenceChainPassSpacingForTest0(long msSinceLastPass, long cadenceMs) { JavaProfiler.setReferenceChainPassSpacingForTest0(msSinceLastPass, cadenceMs); } diff --git a/ddprof-test/src/test/java/com/datadoghq/profiler/referencechains/ReferenceChainRootEnumErrorTest.java b/ddprof-test/src/test/java/com/datadoghq/profiler/referencechains/ReferenceChainRootEnumErrorTest.java new file mode 100644 index 0000000000..ca5584ca13 --- /dev/null +++ b/ddprof-test/src/test/java/com/datadoghq/profiler/referencechains/ReferenceChainRootEnumErrorTest.java @@ -0,0 +1,149 @@ +/* + * Copyright 2026, Datadog, Inc. + * SPDX-License-Identifier: Apache-2.0 + */ + +package com.datadoghq.profiler.referencechains; + +import static com.datadoghq.profiler.referencechains.ReferenceChainAssertions.assumeDebugBuild; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import com.datadoghq.profiler.AbstractProfilerTest; +import com.datadoghq.profiler.JfrEvent; +import com.datadoghq.profiler.JfrEvents; +import com.datadoghq.profiler.Platform; +import com.datadoghq.profiler.ReferenceChainTestHooks; +import java.nio.file.Files; +import java.nio.file.Path; +import org.junit.jupiter.api.Test; + +/** + * Drives the {@code datadog.ReferenceChainAbandoned} event's {@code root_enum_error} reason end to + * end: with the debug-build error-injection seam active ({@link + * ReferenceChainTestHooks#setRootEnumErrorInjection0(boolean)}), every root/stack-ref enumeration + * attempt fails with a JVMTI error, the tracker counts the consecutive failures, and {@code + * runPass()}'s termination ladder abandons the search with {@code ROOT_ENUM_ERROR} once {@code + * MAX_CONSECUTIVE_ENUM_ERRORS} attempts have errored - queued as an abandonment event that {@code + * Profiler.dump()} writes into a real JFR chunk. + * + *

Accurate serialization is the point: the ladder's other conditions (deferred TTL, held + * no-progress counter) also hold at that mark, so this test pins that the event reports {@code + * reason = "root_enum_error"} rather than the {@code "ttl"} a stale reason table could only + * misattribute this failure as. The byte-level reason-string mapping is asserted separately by the + * native {@code AbandonedEventSerializesRootEnumErrorReason} gtest; the abandon mechanics + * themselves by {@code ConsecutiveEnumErrorsAbandonSearch}. + * + *

Only runs under the debug native build ({@code testdebug}) - the backing native method does + * not exist in a release build (see javaApi.cpp's {@code #ifdef DEBUG} guard), same pattern as + * {@link ReferenceChainTestSeamsTest}. + */ +public class ReferenceChainRootEnumErrorTest extends AbstractProfilerTest { + + @Override + protected String getProfilerCommand() { + // memory=64:l:1.0 is load-bearing (same rationale as + // ReferenceChainTrackingTest.shouldReportAbandonedSearchOnTinyFrontierCap): + // Profiler::start() only starts the ReferenceChainTracker when allocation + // sampling activated. ttl=0 leaves ROOT_ENUM_ERROR as the ladder's only + // termination bound; framecap=2000000 keeps the real heap's ambient root + // count from hitting FRONTIER_CAP first. + return "memory=64:l:1.0,referencechains=true:hops=32:budget=500:ttl=0:framecap=2000000"; + } + + @Override + protected boolean isPlatformSupported() { + // Same HotSpot-shaped JVMTI heap-walk assumption as + // ReferenceChainTrackingTest (memleak/LivenessTrackingTest's guard). + return !(Platform.isJavaVersion(8) || Platform.isJ9() || Platform.isZing()); + } + + // Java mirror of referenceChains.h's MAX_CONSECUTIVE_ENUM_ERRORS - no seam + // exposes it. The abandon fires on the attempt that reaches the cap. + private static final int MAX_CONSECUTIVE_ENUM_ERRORS = 3; + + // msSinceLastEnum seeded before every driven pass: root/stack-ref enumeration re-runs only once + // the adaptive interval floor (>= ROOT_ENUM_MIN_INTERVAL_NS = 2s) has elapsed since the last + // attempt, so each driven pass must see the last attempt comfortably in the past. Same seeding + // shape the native ConsecutiveEnumErrorsAbandonSearch gtest drives. + private static final long ENUM_LONG_AGO_MS = 100_000; + + // Driven attempts plus slack: once the search is terminal, + // {@link ReferenceChainTestHooks#runReferenceChainPass0()} keeps returning (no-op), so the + // extra calls are harmless and the exact cap is deliberately not hardcoded here. + private static final int MAX_DRIVEN_PASSES = MAX_CONSECUTIVE_ENUM_ERRORS + 4; + + @Test + public void shouldReportRootEnumErrorOnAbandonedSearch() throws Exception { + assumeDebugBuild(); + + // Shared-JVM hygiene: the tracker is a process-wide singleton whose search may have been + // exhausted by an earlier test - establish this test's own fresh search (also zeroes the + // consecutive-error count a prior search could have left behind). + ReferenceChainTestHooks.resetReferenceChainSearchForTest0(); + + ReferenceChainTestHooks.setRootEnumErrorInjection0(true); + try { + // Driven synchronously, bypassing the background thread's shouldRunPass() gate: each call + // runs exactly one pass whose root enumeration inject-fails. No candidate seeding is + // needed - the injection makes every attempt errored, so the ladder's completion gate + // (no pending work) cannot fire and the error cap is the only bound when ttl=0. + for (int i = 0; i < MAX_DRIVEN_PASSES; i++) { + // Enumeration re-runs only past the adaptive interval floor - backdate the last + // attempt so each driven pass runs a real (inject-failing) enumeration attempt. + ReferenceChainTestHooks.setReferenceChainRootEnumStateForTest0( + ENUM_LONG_AGO_MS, /* lastEnumCostMs= */ 0); + if (i == 0) { + assertTrue( + ReferenceChainTestHooks.runReferenceChainPass0(), + "Expected the first driven pass to run (reference chains enabled)"); + } else { + ReferenceChainTestHooks.runReferenceChainPass0(); + } + } + + // The abandonment event reached the pending queue on the cap-reaching pass; a real + // dump() drains and writes it. A concurrent restart by the background thread would not + // lose it - the queue survives until dump() drains it. + Path dumpPath = Files.createTempFile("referencechains-rootenum-error-test-", ".jfr"); + Files.deleteIfExists(dumpPath); + try { + JfrEvents abandoned = null; + for (int attempt = 0; attempt < 8; attempt++) { + dump(dumpPath); + abandoned = verifyEvents(dumpPath, "datadog.ReferenceChainAbandoned", false); + if (abandoned.hasItems() && sawRootEnumErrorReason(abandoned)) { + break; + } + Thread.sleep(1000); + } + assertTrue( + abandoned != null && abandoned.hasItems(), + "Expected at least one datadog.ReferenceChainAbandoned event after " + + MAX_DRIVEN_PASSES + + " inject-failing passes"); + assertTrue( + sawRootEnumErrorReason(abandoned), + "Expected the abandonment event's reason to be \"root_enum_error\" " + + "(not \"ttl\" - the ladder's deferred-TTL and held no-progress conditions " + + "also hold at the abandon mark, so serializing them would misattribute a " + + "search whose enumeration keeps failing)"); + } finally { + Files.deleteIfExists(dumpPath); + } + } finally { + // Restore before the next test in this shared JVM: the flag is process-wide + // singleton state, and a leftover injection would fail every later search's + // root enumeration. + ReferenceChainTestHooks.setRootEnumErrorInjection0(false); + } + } + + private static boolean sawRootEnumErrorReason(JfrEvents events) { + for (JfrEvent item : events) { + if ("root_enum_error".equals(item.getString("reason"))) { + return true; + } + } + return false; + } +} diff --git a/doc/ReferenceChainsCollectionSummary.md b/doc/ReferenceChainsCollectionSummary.md index 8c643c4089..2cb3e803e3 100644 --- a/doc/ReferenceChainsCollectionSummary.md +++ b/doc/ReferenceChainsCollectionSummary.md @@ -154,7 +154,7 @@ The abandonment reasons are: during urgency or when incomplete enumeration suppresses the earlier no-progress exit. Abandonment events use a separate queue. The current writer maps `ROOT_ENUM_ERROR` to -`unknown`. Recording stop does not enqueue a `RECORDING_END` abandonment event. +`root_enum_error`. Recording stop does not enqueue a `RECORDING_END` abandonment event. A restart requires released search tags, cleared safepoint-cost debt, the root-enumeration interval, and a current leak candidate. A running search does not restart itself. diff --git a/doc/architecture/LiveHeapReferenceChainsImplementation.md b/doc/architecture/LiveHeapReferenceChainsImplementation.md index 32d3bd7318..de7d67b244 100644 --- a/doc/architecture/LiveHeapReferenceChainsImplementation.md +++ b/doc/architecture/LiveHeapReferenceChainsImplementation.md @@ -219,8 +219,8 @@ emitted for this reason. The base candidate-stall limit is 30 passes. Consecutive `CANARY_STUCK` restarts can double this limit, up to eight doublings. Other terminal outcomes reset that escalation. Abandonments use a separate queue of at most 16 events. Dump drains it once per occurrence; -queue overflow increments `REFERENCE_CHAIN_EVENTS_DROPPED`. The current JFR writer maps -`ROOT_ENUM_ERROR` to `unknown`, rather than a distinct reason string. +queue overflow increments `REFERENCE_CHAIN_EVENTS_DROPPED`. The JFR writer maps +`ROOT_ENUM_ERROR` to the reason string `root_enum_error`. ## Cost control From 8892642381fab7ebb1319b2c7deb45084d8fe006 Mon Sep 17 00:00:00 2001 From: Jaroslav Bachorik Date: Fri, 13 Nov 2026 15:13:57 +0100 Subject: [PATCH 2/8] Pin reference_chain_root_enum_errors in ConsecutiveEnumErrorsAbandonSearch Each errored root-enumeration attempt must bump the exported reference_chain_root_enum_errors counter; assert +1 after the first errored attempt and MAX_CONSECUTIVE_ENUM_ERRORS at the abandon pass so removing or retargeting the increment fails the test. PROF-16662 --- .../src/test/cpp/referenceChainsBfsTests.inc | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/ddprof-lib/src/test/cpp/referenceChainsBfsTests.inc b/ddprof-lib/src/test/cpp/referenceChainsBfsTests.inc index 56191a6492..1264085763 100644 --- a/ddprof-lib/src/test/cpp/referenceChainsBfsTests.inc +++ b/ddprof-lib/src/test/cpp/referenceChainsBfsTests.inc @@ -351,11 +351,20 @@ TEST_F(ReferenceChainsBfsTest, ConsecutiveEnumErrorsAbandonSearch) { std::pair saved = ReferenceChainsTestAccessor::setRootEnumRawStateForTest(0, 0); active_fixture->ior_error = JVMTI_ERROR_OUT_OF_MEMORY; + // Pin the errored-attempt accounting: each failed root enumeration must bump the exported + // reference_chain_root_enum_errors counter (runPassManualWalk's error path). Delta-based: + // the counter is process-global and earlier tests in this binary may have incremented it. + long long enum_errors_before = Counters::getCounter(REFERENCE_CHAIN_ROOT_ENUM_ERRORS); + // Pass 1 (manual): the enumeration attempt errors - incomplete, counter 1, still RUNNING. bool truncated = true; ASSERT_TRUE(tracker->runPass(&mock_jvmti, &mock_jni, &truncated)); EXPECT_TRUE(truncated); EXPECT_EQ(SearchState::RUNNING, tracker->searchState()); + EXPECT_EQ(enum_errors_before + 1, + Counters::getCounter(REFERENCE_CHAIN_ROOT_ENUM_ERRORS)) + << "the first errored enumeration attempt must increment " + "reference_chain_root_enum_errors"; // Passes 2..MAX: backdate the floor so each pass runs a real enumeration attempt that errors // again; the ladder must abandon when the counter reaches MAX_CONSECUTIVE_ENUM_ERRORS. @@ -373,6 +382,13 @@ TEST_F(ReferenceChainsBfsTest, ConsecutiveEnumErrorsAbandonSearch) { ASSERT_TRUE(tracker->runPass(&mock_jvmti, &mock_jni, &truncated)); EXPECT_EQ(SearchState::ABANDONED, tracker->searchState()); EXPECT_EQ(SearchAbandonReason::ROOT_ENUM_ERROR, ReferenceChainsTestAccessor::searchAbandonReasonForTest()); + // Every one of the MAX_CONSECUTIVE_ENUM_ERRORS errored attempts - including this cap-reaching + // one - must have been counted, so removing or retargeting the increment in the error path + // fails here. + EXPECT_EQ(enum_errors_before + (long long)ReferenceChainTracker::MAX_CONSECUTIVE_ENUM_ERRORS, + Counters::getCounter(REFERENCE_CHAIN_ROOT_ENUM_ERRORS)) + << "each of the " << ReferenceChainTracker::MAX_CONSECUTIVE_ENUM_ERRORS + << " consecutive errored attempts must increment reference_chain_root_enum_errors"; ReferenceChainsTestAccessor::setRootEnumRawStateForTest(saved.first, saved.second); tracker->stop(); From 9a5f47691b7944afa547146375a8990e756e449b Mon Sep 17 00:00:00 2001 From: Jaroslav Bachorik Date: Mon, 16 Nov 2026 10:33:04 +0100 Subject: [PATCH 3/8] Reset reference-chain test state after injected errors --- .../referencechains/ReferenceChainRootEnumErrorTest.java | 1 + 1 file changed, 1 insertion(+) diff --git a/ddprof-test/src/test/java/com/datadoghq/profiler/referencechains/ReferenceChainRootEnumErrorTest.java b/ddprof-test/src/test/java/com/datadoghq/profiler/referencechains/ReferenceChainRootEnumErrorTest.java index ca5584ca13..86a8842422 100644 --- a/ddprof-test/src/test/java/com/datadoghq/profiler/referencechains/ReferenceChainRootEnumErrorTest.java +++ b/ddprof-test/src/test/java/com/datadoghq/profiler/referencechains/ReferenceChainRootEnumErrorTest.java @@ -135,6 +135,7 @@ public void shouldReportRootEnumErrorOnAbandonedSearch() throws Exception { // singleton state, and a leftover injection would fail every later search's // root enumeration. ReferenceChainTestHooks.setRootEnumErrorInjection0(false); + ReferenceChainTestHooks.resetReferenceChainSearchForTest0(); } } From ec61b5dab52f5ce78427e616c13743e9b8f6c3ce Mon Sep 17 00:00:00 2001 From: Jaroslav Bachorik Date: Mon, 16 Nov 2026 11:53:39 +0100 Subject: [PATCH 4/8] Correct branch-added comments in reference-chain production code --- ddprof-lib/src/main/cpp/counters.h | 7 ++----- ddprof-lib/src/main/cpp/flightRecorder.cpp | 14 ++++---------- .../src/main/cpp/referenceChainTraversal.cpp | 6 ++---- ddprof-lib/src/main/cpp/referenceChains.h | 13 ++++--------- .../java/com/datadoghq/profiler/JavaProfiler.java | 10 ++-------- 5 files changed, 14 insertions(+), 36 deletions(-) diff --git a/ddprof-lib/src/main/cpp/counters.h b/ddprof-lib/src/main/cpp/counters.h index 71412402f0..8bfb0e343a 100644 --- a/ddprof-lib/src/main/cpp/counters.h +++ b/ddprof-lib/src/main/cpp/counters.h @@ -277,11 +277,8 @@ * release is retried on a later call rather than proceeding, but this \ * counts how often that retry path is taken. */ \ X(REFERENCE_CHAIN_TAG_RELEASE_FAILED, "reference_chain_tag_release_failed") \ - /* ReferenceChainTracker::runPassManualWalk()'s root/stack-ref enumeration \ - * (IterateOverReachableObjects) failed with a JVMTI error - the attempt \ - * learned nothing about roots and _root_enum_incomplete holds the terminal \ - * ladder; MAX_CONSECUTIVE_ENUM_ERRORS consecutive failures abandon the \ - * search with SearchAbandonReason::ROOT_ENUM_ERROR. */ \ + /* Counts failed root-enumeration attempts, not abandoned searches. \ + * Includes failures injected by debug tests. */ \ X(REFERENCE_CHAIN_ROOT_ENUM_ERRORS, "reference_chain_root_enum_errors") \ /* The profiler-side reference-chain writer could not acquire a \ * sample-record lock within its bounded retry budget and dropped the \ diff --git a/ddprof-lib/src/main/cpp/flightRecorder.cpp b/ddprof-lib/src/main/cpp/flightRecorder.cpp index f7c4bd0017..c985d4ff8e 100644 --- a/ddprof-lib/src/main/cpp/flightRecorder.cpp +++ b/ddprof-lib/src/main/cpp/flightRecorder.cpp @@ -2664,19 +2664,13 @@ void Recording::recordReferenceChainAbandoned( int start = buf->skip(1); buf->putVar64(T_REFERENCE_CHAIN_ABANDONED); buf->putVar64(event->_start_time); - // SearchAbandonReason (the engine's reason enum) - kept as a small fixed table - // here rather than a T_XXX enum type, mirroring NativeSocketEvent's - // _operation -> kOpNames string mapping above. Indexed directly by the - // SearchAbandonReason value; the "unknown" slot at RECORDING_END (4) exists - // only to keep ROOT_ENUM_ERROR (5) at its enum index - RECORDING_END is never - // enqueued as an abandonment event (see its own comment), so that slot's - // string is never actually written. Without its entry, ROOT_ENUM_ERROR - a - // genuinely distinct, engine-reported abandonment - would serialize as - // "unknown" and misattribute the cause in the JFR event. + // Indexed by SearchAbandonReason, including its internal RECORDING_END value. + // Keep that slot so ROOT_ENUM_ERROR stays at its enum index; recording stop + // does not enqueue an event for RECORDING_END. static const char *const kReasons[] = {"none", "frontier_cap", "ttl", "canary_stuck", "unknown", "root_enum_error"}; - buf->putUtf8(event->_reason < (u8)(sizeof(kReasons) / sizeof(kReasons[0])) + buf->putUtf8(event->_reason < sizeof(kReasons) / sizeof(kReasons[0]) ? kReasons[event->_reason] : "unknown"); buf->putVar32(event->_passes_run); diff --git a/ddprof-lib/src/main/cpp/referenceChainTraversal.cpp b/ddprof-lib/src/main/cpp/referenceChainTraversal.cpp index 252a7764df..3115479e20 100644 --- a/ddprof-lib/src/main/cpp/referenceChainTraversal.cpp +++ b/ddprof-lib/src/main/cpp/referenceChainTraversal.cpp @@ -211,10 +211,8 @@ void ReferenceChainTracker::runPassManualWalk(jvmtiEnv *jvmti, JNIEnv *jni, u64 root_enum_start_ns = OS::nanotime(); jvmtiError root_err; #ifdef DEBUG - // Debug-build-only error injection (setRootEnumErrorInjectionForTest()): forces this attempt - // to fail with JVMTI_ERROR_OUT_OF_MEMORY without touching the real JVMTI call - a failed - // call makes no progress and leaves user_data unmodified, so skipping it is faithful to the - // failure being simulated. Release builds never set the flag. + // Error injection must not admit objects through the heap callbacks. + // Bypass JVMTI so the test reaches the error path without mutating tags. if (_root_enum_error_injection.load(std::memory_order_acquire)) { root_err = JVMTI_ERROR_OUT_OF_MEMORY; } else diff --git a/ddprof-lib/src/main/cpp/referenceChains.h b/ddprof-lib/src/main/cpp/referenceChains.h index ce3d9ea705..428e114bae 100644 --- a/ddprof-lib/src/main/cpp/referenceChains.h +++ b/ddprof-lib/src/main/cpp/referenceChains.h @@ -796,11 +796,8 @@ class ReferenceChainTracker { // ladder abandons the search (ROOT_ENUM_ERROR) - the only bound when ttl=0. u32 _consecutive_enum_errors = 0; - // Debug-build-only test seam flag: when true, runPassManualWalk()'s root/stack-ref enumeration - // attempt fails with JVMTI_ERROR_OUT_OF_MEMORY without touching the real JVMTI call (see - // setRootEnumErrorInjectionForTest()). Written by a JNI test thread, read on the BFS thread, so - // atomic with release/acquire ordering - a torn/relaxed read could let one pass run without the - // injection the test counted on. + // JNI tests toggle this flag while the BFS thread can read it; keep accesses atomic. + // Only DEBUG builds consult it to bypass the root-enumeration JVMTI call. std::atomic _root_enum_error_injection{false}; ReferenceChainTracker() @@ -1313,10 +1310,8 @@ class ReferenceChainTracker { : OS::nanotime() - (u64)ms_since_last_enum * 1000000ULL; _last_root_enum_safepoint_ms = last_enum_cost_ms; } - // Debug-build-only test seam (javaApi.cpp's setRootEnumErrorInjection0()): see - // _root_enum_error_injection's own comment. No engine lock: the flag is atomic; seeding it - // while a driven pass is in flight only shifts which pass sees the injection, which no test - // depends on. + // Takes effect when an enumeration attempt reads the flag; it does not cancel an in-flight walk. + // Tests must disable injection before resetting the shared search. void setRootEnumErrorInjectionForTest(bool enabled) { _root_enum_error_injection.store(enabled, std::memory_order_release); } diff --git a/ddprof-lib/src/main/java/com/datadoghq/profiler/JavaProfiler.java b/ddprof-lib/src/main/java/com/datadoghq/profiler/JavaProfiler.java index 04aab9f192..7671f306e2 100644 --- a/ddprof-lib/src/main/java/com/datadoghq/profiler/JavaProfiler.java +++ b/ddprof-lib/src/main/java/com/datadoghq/profiler/JavaProfiler.java @@ -668,14 +668,8 @@ private static native void setTraceContext0( static native boolean runReferenceChainPass0(); /** - * Test seam (debug native builds only): when {@code enabled}, forces every reference-chain - * root/stack-ref enumeration attempt ({@code IterateOverReachableObjects}) to fail with a JVMTI - * error, without touching the real JVMTI call. With the injection active the tracker counts - * consecutive failed attempts and abandons with the {@code ROOT_ENUM_ERROR} reason after {@code - * MAX_CONSECUTIVE_ENUM_ERRORS} attempts, so a test can drive the {@code - * datadog.ReferenceChainAbandoned} event's {@code root_enum_error} reason deterministically. - * Restore with {@code enabled = false} before the next test in this shared JVM: the flag is - * process-wide singleton state. + * Forces root-enumeration attempts to report a JVMTI error in debug native builds. The flag is + * process-wide; disable it in test cleanup. Release builds ignore this call. */ static native void setRootEnumErrorInjection0(boolean enabled); From 2e409dc2779f5c1241a77a6ff4d8804d6d97cfbe Mon Sep 17 00:00:00 2001 From: Jaroslav Bachorik Date: Mon, 16 Nov 2026 11:53:39 +0100 Subject: [PATCH 5/8] Trim reference-chain test comments to stated constraints --- .../cpp/referenceChainJfrRoundtrip_ut.cpp | 31 +++----- .../src/test/cpp/referenceChainsBfsTests.inc | 10 +-- .../profiler/ReferenceChainTestHooks.java | 1 + .../ReferenceChainRootEnumErrorTest.java | 78 ++++++------------- 4 files changed, 37 insertions(+), 83 deletions(-) diff --git a/ddprof-lib/src/test/cpp/referenceChainJfrRoundtrip_ut.cpp b/ddprof-lib/src/test/cpp/referenceChainJfrRoundtrip_ut.cpp index 91e3cd664e..b35d7e128c 100644 --- a/ddprof-lib/src/test/cpp/referenceChainJfrRoundtrip_ut.cpp +++ b/ddprof-lib/src/test/cpp/referenceChainJfrRoundtrip_ut.cpp @@ -537,24 +537,16 @@ TEST_F(ReferenceChainJfrRoundtripTest, DefaultLivenessEventHasZeroLeakTag) { EXPECT_EQ(0u, event.leak_tag_incarnation); } -// recordReferenceChainAbandoned()'s kReasons[] table must map every -// SearchAbandonReason value to a distinct string, indexed directly by the -// enum value - a stale table silently serializes a genuinely-distinct -// abandonment as "unknown", misattributing the cause in the -// datadog.ReferenceChainAbandoned event. ROOT_ENUM_ERROR (5) pins the -// table's tail - without its entry, the engine's enum-error abandonment -// (referenceChainTraversal.cpp's error branch) serializes as "unknown"; -// an out-of-range value pins the bounds check. +// Exercise the real writer: ROOT_ENUM_ERROR must remain distinguishable from +// the unknown-value fallback even though RECORDING_END occupies the preceding enum slot. TEST_F(ReferenceChainJfrRoundtripTest, AbandonedEventSerializesRootEnumErrorReason) { Arguments args; ASSERT_FALSE(args.parse("referencechains=true:hops=64:budget=1000")); args._jfr_options = JFR_SYNC_OPTS; - // Own file, NOT the companion JMC round-trip path - this test's events use - // reason values only (no class dictionary entries), and leaving them on - // the companion path would make the Java parser test resolve unrelated - // state. + // Java parser tests consume the chain fixture at chainRoundtripJfrPath(). + // Use a separate file so these events cannot replace that fixture. const std::string path = chainRoundtripJfrPath() + ".abandoned"; int fd = open(path.c_str(), O_CREAT | O_RDWR | O_TRUNC, 0644); ASSERT_GE(fd, 0) << "could not open " << path << " for writing"; @@ -563,8 +555,8 @@ TEST_F(ReferenceChainJfrRoundtripTest, Buffer *buf = rec.buffer(/*lock_index=*/0); rec.flushIfNeeded(buf, /*limit=*/0); - // Both events carry _start_time = 0 (single-byte var64) so the reason - // field's offset is computable without decoding the timestamp. + // A zero timestamp occupies one byte, keeping the reason offset fixed. + // Keep the timestamp zero when changing the cases below. struct ReasonCase { u8 reason; const char *expected; @@ -584,20 +576,17 @@ TEST_F(ReferenceChainJfrRoundtripTest, EXPECT_LE(offset_after, RECORDING_BUFFER_LIMIT); EXPECT_GT(offset_after, offset_before); - // Field order (recordReferenceChainAbandoned): 1-byte size prefix - // (writeEventSizePrefix patches one byte - this event is always < - // 128 bytes), var64 type id, var64 startTime, then the reason putUtf8 - // = 1 encoding-tag byte + var32 length + payload. _start_time = 0 - // makes the timestamp var64 exactly one byte. + // This writer reserves one size byte, unlike the chain writer's five-byte prefix. + // Skip the type id and zero timestamp before reading the UTF-8 tag and length. const char *data = buf->data() + offset_before; int off = 1; // size prefix - off += sizeOfVar64((u64)T_REFERENCE_CHAIN_ABANDONED); + off += sizeOfVar64(static_cast(T_REFERENCE_CHAIN_ABANDONED)); off += sizeOfVar64(0); EXPECT_EQ(3, data[off]) << "reason putUtf8's encoding-tag byte must precede its length"; off += 1; u32 len = decodeVar32(data, &off); - u32 expected_len = (u32)strlen(c.expected); + u32 expected_len = static_cast(strlen(c.expected)); ASSERT_EQ(expected_len, len) << "reason " << (int)c.reason << " must serialize as " << c.expected; diff --git a/ddprof-lib/src/test/cpp/referenceChainsBfsTests.inc b/ddprof-lib/src/test/cpp/referenceChainsBfsTests.inc index 1264085763..23f94571ea 100644 --- a/ddprof-lib/src/test/cpp/referenceChainsBfsTests.inc +++ b/ddprof-lib/src/test/cpp/referenceChainsBfsTests.inc @@ -351,9 +351,8 @@ TEST_F(ReferenceChainsBfsTest, ConsecutiveEnumErrorsAbandonSearch) { std::pair saved = ReferenceChainsTestAccessor::setRootEnumRawStateForTest(0, 0); active_fixture->ior_error = JVMTI_ERROR_OUT_OF_MEMORY; - // Pin the errored-attempt accounting: each failed root enumeration must bump the exported - // reference_chain_root_enum_errors counter (runPassManualWalk's error path). Delta-based: - // the counter is process-global and earlier tests in this binary may have incremented it. + // Counters persist across tests in this process. + // Compare against the starting value rather than assuming zero. long long enum_errors_before = Counters::getCounter(REFERENCE_CHAIN_ROOT_ENUM_ERRORS); // Pass 1 (manual): the enumeration attempt errors - incomplete, counter 1, still RUNNING. @@ -382,10 +381,7 @@ TEST_F(ReferenceChainsBfsTest, ConsecutiveEnumErrorsAbandonSearch) { ASSERT_TRUE(tracker->runPass(&mock_jvmti, &mock_jni, &truncated)); EXPECT_EQ(SearchState::ABANDONED, tracker->searchState()); EXPECT_EQ(SearchAbandonReason::ROOT_ENUM_ERROR, ReferenceChainsTestAccessor::searchAbandonReasonForTest()); - // Every one of the MAX_CONSECUTIVE_ENUM_ERRORS errored attempts - including this cap-reaching - // one - must have been counted, so removing or retargeting the increment in the error path - // fails here. - EXPECT_EQ(enum_errors_before + (long long)ReferenceChainTracker::MAX_CONSECUTIVE_ENUM_ERRORS, + EXPECT_EQ(enum_errors_before + static_cast(ReferenceChainTracker::MAX_CONSECUTIVE_ENUM_ERRORS), Counters::getCounter(REFERENCE_CHAIN_ROOT_ENUM_ERRORS)) << "each of the " << ReferenceChainTracker::MAX_CONSECUTIVE_ENUM_ERRORS << " consecutive errored attempts must increment reference_chain_root_enum_errors"; diff --git a/ddprof-test/src/test/java/com/datadoghq/profiler/ReferenceChainTestHooks.java b/ddprof-test/src/test/java/com/datadoghq/profiler/ReferenceChainTestHooks.java index 7a2adee3bf..55b3ef5bd6 100644 --- a/ddprof-test/src/test/java/com/datadoghq/profiler/ReferenceChainTestHooks.java +++ b/ddprof-test/src/test/java/com/datadoghq/profiler/ReferenceChainTestHooks.java @@ -50,6 +50,7 @@ public static boolean runReferenceChainPass0() { return JavaProfiler.runReferenceChainPass0(); } + /** Enables debug-native root-enumeration error injection; release builds ignore it. */ public static void setRootEnumErrorInjection0(boolean enabled) { JavaProfiler.setRootEnumErrorInjection0(enabled); } diff --git a/ddprof-test/src/test/java/com/datadoghq/profiler/referencechains/ReferenceChainRootEnumErrorTest.java b/ddprof-test/src/test/java/com/datadoghq/profiler/referencechains/ReferenceChainRootEnumErrorTest.java index 86a8842422..a5d28dbffb 100644 --- a/ddprof-test/src/test/java/com/datadoghq/profiler/referencechains/ReferenceChainRootEnumErrorTest.java +++ b/ddprof-test/src/test/java/com/datadoghq/profiler/referencechains/ReferenceChainRootEnumErrorTest.java @@ -18,78 +18,52 @@ import org.junit.jupiter.api.Test; /** - * Drives the {@code datadog.ReferenceChainAbandoned} event's {@code root_enum_error} reason end to - * end: with the debug-build error-injection seam active ({@link - * ReferenceChainTestHooks#setRootEnumErrorInjection0(boolean)}), every root/stack-ref enumeration - * attempt fails with a JVMTI error, the tracker counts the consecutive failures, and {@code - * runPass()}'s termination ladder abandons the search with {@code ROOT_ENUM_ERROR} once {@code - * MAX_CONSECUTIVE_ENUM_ERRORS} attempts have errored - queued as an abandonment event that {@code - * Profiler.dump()} writes into a real JFR chunk. - * - *

Accurate serialization is the point: the ladder's other conditions (deferred TTL, held - * no-progress counter) also hold at that mark, so this test pins that the event reports {@code - * reason = "root_enum_error"} rather than the {@code "ttl"} a stale reason table could only - * misattribute this failure as. The byte-level reason-string mapping is asserted separately by the - * native {@code AbandonedEventSerializesRootEnumErrorReason} gtest; the abandon mechanics - * themselves by {@code ConsecutiveEnumErrorsAbandonSearch}. - * - *

Only runs under the debug native build ({@code testdebug}) - the backing native method does - * not exist in a release build (see javaApi.cpp's {@code #ifdef DEBUG} guard), same pattern as - * {@link ReferenceChainTestSeamsTest}. + * Verifies that injected root-enumeration failures reach the JFR as {@code root_enum_error}. The + * native injection seam is inactive in release builds; this test requires DEBUG. */ public class ReferenceChainRootEnumErrorTest extends AbstractProfilerTest { @Override protected String getProfilerCommand() { - // memory=64:l:1.0 is load-bearing (same rationale as - // ReferenceChainTrackingTest.shouldReportAbandonedSearchOnTinyFrontierCap): - // Profiler::start() only starts the ReferenceChainTracker when allocation - // sampling activated. ttl=0 leaves ROOT_ENUM_ERROR as the ladder's only - // termination bound; framecap=2000000 keeps the real heap's ambient root - // count from hitting FRONTIER_CAP first. + // Allocation sampling is required to start the reference-chain tracker. + // Disable the elapsed-time cutoff to target the enumeration-error path. + // Keep a large frontier cap to avoid unrelated capacity failures. return "memory=64:l:1.0,referencechains=true:hops=32:budget=500:ttl=0:framecap=2000000"; } @Override protected boolean isPlatformSupported() { - // Same HotSpot-shaped JVMTI heap-walk assumption as - // ReferenceChainTrackingTest (memleak/LivenessTrackingTest's guard). + // This test uses the same debug seams as ReferenceChainTestSeamsTest. + // Keep their platform exclusions aligned. return !(Platform.isJavaVersion(8) || Platform.isJ9() || Platform.isZing()); } - // Java mirror of referenceChains.h's MAX_CONSECUTIVE_ENUM_ERRORS - no seam - // exposes it. The abandon fires on the attempt that reaches the cap. + // Keep this mirror aligned with ReferenceChainTracker::MAX_CONSECUTIVE_ENUM_ERRORS. + // Native gtests check the exact boundary; this integration test allows extra passes. private static final int MAX_CONSECUTIVE_ENUM_ERRORS = 3; - // msSinceLastEnum seeded before every driven pass: root/stack-ref enumeration re-runs only once - // the adaptive interval floor (>= ROOT_ENUM_MIN_INTERVAL_NS = 2s) has elapsed since the last - // attempt, so each driven pass must see the last attempt comfortably in the past. Same seeding - // shape the native ConsecutiveEnumErrorsAbandonSearch gtest drives. + // Keep this age beyond rootEnumIntervalFloorNs()'s maximum. + // Backdated attempts let the test run without interval sleeps. private static final long ENUM_LONG_AGO_MS = 100_000; - // Driven attempts plus slack: once the search is terminal, - // {@link ReferenceChainTestHooks#runReferenceChainPass0()} keeps returning (no-op), so the - // extra calls are harmless and the exact cap is deliberately not hardcoded here. + // Extra calls can reach terminal-search cleanup without enumerating again. + // The event assertion does not depend on the exact abandonment pass. private static final int MAX_DRIVEN_PASSES = MAX_CONSECUTIVE_ENUM_ERRORS + 4; @Test public void shouldReportRootEnumErrorOnAbandonedSearch() throws Exception { assumeDebugBuild(); - // Shared-JVM hygiene: the tracker is a process-wide singleton whose search may have been - // exhausted by an earlier test - establish this test's own fresh search (also zeroes the - // consecutive-error count a prior search could have left behind). + // The tracker is process-wide and may retain another test's search state. + // Reset it before enabling injection. ReferenceChainTestHooks.resetReferenceChainSearchForTest0(); ReferenceChainTestHooks.setRootEnumErrorInjection0(true); try { - // Driven synchronously, bypassing the background thread's shouldRunPass() gate: each call - // runs exactly one pass whose root enumeration inject-fails. No candidate seeding is - // needed - the injection makes every attempt errored, so the ladder's completion gate - // (no pending work) cannot fire and the error cap is the only bound when ttl=0. + // Drive the tracker directly instead of waiting for background scheduling. + // Failed enumeration marks work incomplete, preventing the empty frontier + // from completing this search before the error limit is reached. for (int i = 0; i < MAX_DRIVEN_PASSES; i++) { - // Enumeration re-runs only past the adaptive interval floor - backdate the last - // attempt so each driven pass runs a real (inject-failing) enumeration attempt. ReferenceChainTestHooks.setReferenceChainRootEnumStateForTest0( ENUM_LONG_AGO_MS, /* lastEnumCostMs= */ 0); if (i == 0) { @@ -101,9 +75,8 @@ public void shouldReportRootEnumErrorOnAbandonedSearch() throws Exception { } } - // The abandonment event reached the pending queue on the cap-reaching pass; a real - // dump() drains and writes it. A concurrent restart by the background thread would not - // lose it - the queue survives until dump() drains it. + // Abandonment queues an event; dump() writes and drains that queue. + // Read the recording rather than asserting only on native tracker state. Path dumpPath = Files.createTempFile("referencechains-rootenum-error-test-", ".jfr"); Files.deleteIfExists(dumpPath); try { @@ -122,18 +95,13 @@ public void shouldReportRootEnumErrorOnAbandonedSearch() throws Exception { + MAX_DRIVEN_PASSES + " inject-failing passes"); assertTrue( - sawRootEnumErrorReason(abandoned), - "Expected the abandonment event's reason to be \"root_enum_error\" " - + "(not \"ttl\" - the ladder's deferred-TTL and held no-progress conditions " - + "also hold at the abandon mark, so serializing them would misattribute a " - + "search whose enumeration keeps failing)"); + sawRootEnumErrorReason(abandoned), "Expected abandonment reason \"root_enum_error\""); } finally { Files.deleteIfExists(dumpPath); } } finally { - // Restore before the next test in this shared JVM: the flag is process-wide - // singleton state, and a leftover injection would fail every later search's - // root enumeration. + // Injection and seeded scheduling state belong to the process-wide tracker. + // Restore both before the next test starts. ReferenceChainTestHooks.setRootEnumErrorInjection0(false); ReferenceChainTestHooks.resetReferenceChainSearchForTest0(); } From 2537400bee7683d1fc549084eacc6d6e51419c55 Mon Sep 17 00:00:00 2001 From: Jaroslav Bachorik Date: Mon, 16 Nov 2026 11:53:39 +0100 Subject: [PATCH 6/8] Name the abandonment event reason field in reference-chain docs --- doc/ReferenceChainsCollectionSummary.md | 4 ++-- doc/architecture/LiveHeapReferenceChainsImplementation.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/ReferenceChainsCollectionSummary.md b/doc/ReferenceChainsCollectionSummary.md index 2cb3e803e3..e61178a8a3 100644 --- a/doc/ReferenceChainsCollectionSummary.md +++ b/doc/ReferenceChainsCollectionSummary.md @@ -153,8 +153,8 @@ The abandonment reasons are: - `CANARY_STUCK`: both frontier and candidate progress met their stall limits. This can occur during urgency or when incomplete enumeration suppresses the earlier no-progress exit. -Abandonment events use a separate queue. The current writer maps `ROOT_ENUM_ERROR` to -`root_enum_error`. Recording stop does not enqueue a `RECORDING_END` abandonment event. +Abandonment events use a separate queue. Their `reason` field is `root_enum_error` for +`ROOT_ENUM_ERROR`. Recording stop does not enqueue a `RECORDING_END` abandonment event. A restart requires released search tags, cleared safepoint-cost debt, the root-enumeration interval, and a current leak candidate. A running search does not restart itself. diff --git a/doc/architecture/LiveHeapReferenceChainsImplementation.md b/doc/architecture/LiveHeapReferenceChainsImplementation.md index de7d67b244..3827a513d1 100644 --- a/doc/architecture/LiveHeapReferenceChainsImplementation.md +++ b/doc/architecture/LiveHeapReferenceChainsImplementation.md @@ -219,8 +219,8 @@ emitted for this reason. The base candidate-stall limit is 30 passes. Consecutive `CANARY_STUCK` restarts can double this limit, up to eight doublings. Other terminal outcomes reset that escalation. Abandonments use a separate queue of at most 16 events. Dump drains it once per occurrence; -queue overflow increments `REFERENCE_CHAIN_EVENTS_DROPPED`. The JFR writer maps -`ROOT_ENUM_ERROR` to the reason string `root_enum_error`. +queue overflow increments `REFERENCE_CHAIN_EVENTS_DROPPED`. The JFR event's `reason` field is +`root_enum_error` for `ROOT_ENUM_ERROR`. ## Cost control From 162c763f464777601cc1795121545bc2d2e1e2ba Mon Sep 17 00:00:00 2001 From: Jaroslav Bachorik Date: Mon, 16 Nov 2026 15:46:32 +0100 Subject: [PATCH 7/8] Address PR 990 review findings --- ddprof-lib/src/main/cpp/flightRecorder.cpp | 5 +++ ddprof-lib/src/main/cpp/referenceChains.h | 6 +++- .../cpp/referenceChainJfrRoundtrip_ut.cpp | 7 ++-- .../ReferenceChainRootEnumErrorTest.java | 32 ++++++++----------- 4 files changed, 29 insertions(+), 21 deletions(-) diff --git a/ddprof-lib/src/main/cpp/flightRecorder.cpp b/ddprof-lib/src/main/cpp/flightRecorder.cpp index c985d4ff8e..8cfece0a14 100644 --- a/ddprof-lib/src/main/cpp/flightRecorder.cpp +++ b/ddprof-lib/src/main/cpp/flightRecorder.cpp @@ -23,6 +23,7 @@ #include "mallocInfo.h" #include "os.h" #include "profiler.h" +#include "referenceChainFrontier.h" #include "signalSafety.h" #include "rustDemangler.h" #include "safeAccess.h" @@ -2670,6 +2671,10 @@ void Recording::recordReferenceChainAbandoned( static const char *const kReasons[] = {"none", "frontier_cap", "ttl", "canary_stuck", "unknown", "root_enum_error"}; + static_assert(SearchAbandonReason::RECORDING_END == 4 && + SearchAbandonReason::ROOT_ENUM_ERROR == + sizeof(kReasons) / sizeof(kReasons[0]) - 1, + "kReasons is positionally indexed by SearchAbandonReason"); buf->putUtf8(event->_reason < sizeof(kReasons) / sizeof(kReasons[0]) ? kReasons[event->_reason] : "unknown"); diff --git a/ddprof-lib/src/main/cpp/referenceChains.h b/ddprof-lib/src/main/cpp/referenceChains.h index 428e114bae..c6a4dd3cd2 100644 --- a/ddprof-lib/src/main/cpp/referenceChains.h +++ b/ddprof-lib/src/main/cpp/referenceChains.h @@ -797,8 +797,10 @@ class ReferenceChainTracker { u32 _consecutive_enum_errors = 0; // JNI tests toggle this flag while the BFS thread can read it; keep accesses atomic. - // Only DEBUG builds consult it to bypass the root-enumeration JVMTI call. + // DEBUG-only: no release code reads it, so it is compiled out entirely. +#ifdef DEBUG std::atomic _root_enum_error_injection{false}; +#endif ReferenceChainTracker() : _enabled(false), @@ -1312,9 +1314,11 @@ class ReferenceChainTracker { } // Takes effect when an enumeration attempt reads the flag; it does not cancel an in-flight walk. // Tests must disable injection before resetting the shared search. +#ifdef DEBUG void setRootEnumErrorInjectionForTest(bool enabled) { _root_enum_error_injection.store(enabled, std::memory_order_release); } +#endif bool shouldRunRootEnumForTest(u64 now_ns, bool manual_first_pass) const { MutexLocker engine_guard(_engine_lock); return shouldRunRootEnum(now_ns, manual_first_pass); diff --git a/ddprof-lib/src/test/cpp/referenceChainJfrRoundtrip_ut.cpp b/ddprof-lib/src/test/cpp/referenceChainJfrRoundtrip_ut.cpp index b35d7e128c..5bbaac9619 100644 --- a/ddprof-lib/src/test/cpp/referenceChainJfrRoundtrip_ut.cpp +++ b/ddprof-lib/src/test/cpp/referenceChainJfrRoundtrip_ut.cpp @@ -548,6 +548,11 @@ TEST_F(ReferenceChainJfrRoundtripTest, // Java parser tests consume the chain fixture at chainRoundtripJfrPath(). // Use a separate file so these events cannot replace that fixture. const std::string path = chainRoundtripJfrPath() + ".abandoned"; + // ASSERT_* below returns early on failure; this guard keeps the file from leaking. + struct UnlinkOnExit { + const std::string &path; + ~UnlinkOnExit() { unlink(path.c_str()); } + } unlink_guard{path}; int fd = open(path.c_str(), O_CREAT | O_RDWR | O_TRUNC, 0644); ASSERT_GE(fd, 0) << "could not open " << path << " for writing"; @@ -594,6 +599,4 @@ TEST_F(ReferenceChainJfrRoundtripTest, << "reason " << (int)c.reason << " must serialize as " << c.expected; } - - unlink(path.c_str()); } diff --git a/ddprof-test/src/test/java/com/datadoghq/profiler/referencechains/ReferenceChainRootEnumErrorTest.java b/ddprof-test/src/test/java/com/datadoghq/profiler/referencechains/ReferenceChainRootEnumErrorTest.java index a5d28dbffb..680d3740d5 100644 --- a/ddprof-test/src/test/java/com/datadoghq/profiler/referencechains/ReferenceChainRootEnumErrorTest.java +++ b/ddprof-test/src/test/java/com/datadoghq/profiler/referencechains/ReferenceChainRootEnumErrorTest.java @@ -54,12 +54,12 @@ protected boolean isPlatformSupported() { public void shouldReportRootEnumErrorOnAbandonedSearch() throws Exception { assumeDebugBuild(); - // The tracker is process-wide and may retain another test's search state. - // Reset it before enabling injection. - ReferenceChainTestHooks.resetReferenceChainSearchForTest0(); - - ReferenceChainTestHooks.setRootEnumErrorInjection0(true); + // Enable injection BEFORE the reset: resetSearchStateForTest() ends with startThread(), so + // the background thread can run one real pass in the window after the reset - a completed + // search would make every later driven pass a no-op. The reset does not touch the flag. try { + ReferenceChainTestHooks.setRootEnumErrorInjection0(true); + ReferenceChainTestHooks.resetReferenceChainSearchForTest0(); // Drive the tracker directly instead of waiting for background scheduling. // Failed enumeration marks work incomplete, preventing the empty frontier // from completing this search before the error limit is reached. @@ -75,25 +75,21 @@ public void shouldReportRootEnumErrorOnAbandonedSearch() throws Exception { } } - // Abandonment queues an event; dump() writes and drains that queue. - // Read the recording rather than asserting only on native tracker state. + // The final driven pass enqueues the abandonment event synchronously inside + // runPass(); one dump drains the pending-event queue and writes the chunk. Path dumpPath = Files.createTempFile("referencechains-rootenum-error-test-", ".jfr"); Files.deleteIfExists(dumpPath); try { - JfrEvents abandoned = null; - for (int attempt = 0; attempt < 8; attempt++) { - dump(dumpPath); - abandoned = verifyEvents(dumpPath, "datadog.ReferenceChainAbandoned", false); - if (abandoned.hasItems() && sawRootEnumErrorReason(abandoned)) { - break; - } - Thread.sleep(1000); - } + dump(dumpPath); + JfrEvents abandoned = verifyEvents(dumpPath, "datadog.ReferenceChainAbandoned", false); assertTrue( - abandoned != null && abandoned.hasItems(), + abandoned.hasItems(), "Expected at least one datadog.ReferenceChainAbandoned event after " + MAX_DRIVEN_PASSES - + " inject-failing passes"); + + " inject-failing passes; if the native MAX_CONSECUTIVE_ENUM_ERRORS grew " + + "beyond " + + MAX_CONSECUTIVE_ENUM_ERRORS + + ", update this test's mirror"); assertTrue( sawRootEnumErrorReason(abandoned), "Expected abandonment reason \"root_enum_error\""); } finally { From 3caaf6e22912b1f6bfc0bd0e3a64178a8b46978f Mon Sep 17 00:00:00 2001 From: Jaroslav Bachorik Date: Mon, 16 Nov 2026 15:53:02 +0100 Subject: [PATCH 8/8] Guard reference-chain counter assertions with ifdef COUNTERS --- ddprof-lib/src/test/cpp/referenceChainsBfsTests.inc | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/ddprof-lib/src/test/cpp/referenceChainsBfsTests.inc b/ddprof-lib/src/test/cpp/referenceChainsBfsTests.inc index 23f94571ea..576bd4bc9d 100644 --- a/ddprof-lib/src/test/cpp/referenceChainsBfsTests.inc +++ b/ddprof-lib/src/test/cpp/referenceChainsBfsTests.inc @@ -353,17 +353,21 @@ TEST_F(ReferenceChainsBfsTest, ConsecutiveEnumErrorsAbandonSearch) { // Counters persist across tests in this process. // Compare against the starting value rather than assuming zero. +#ifdef COUNTERS long long enum_errors_before = Counters::getCounter(REFERENCE_CHAIN_ROOT_ENUM_ERRORS); +#endif // Pass 1 (manual): the enumeration attempt errors - incomplete, counter 1, still RUNNING. bool truncated = true; ASSERT_TRUE(tracker->runPass(&mock_jvmti, &mock_jni, &truncated)); EXPECT_TRUE(truncated); EXPECT_EQ(SearchState::RUNNING, tracker->searchState()); +#ifdef COUNTERS EXPECT_EQ(enum_errors_before + 1, Counters::getCounter(REFERENCE_CHAIN_ROOT_ENUM_ERRORS)) << "the first errored enumeration attempt must increment " "reference_chain_root_enum_errors"; +#endif // Passes 2..MAX: backdate the floor so each pass runs a real enumeration attempt that errors // again; the ladder must abandon when the counter reaches MAX_CONSECUTIVE_ENUM_ERRORS. @@ -381,10 +385,12 @@ TEST_F(ReferenceChainsBfsTest, ConsecutiveEnumErrorsAbandonSearch) { ASSERT_TRUE(tracker->runPass(&mock_jvmti, &mock_jni, &truncated)); EXPECT_EQ(SearchState::ABANDONED, tracker->searchState()); EXPECT_EQ(SearchAbandonReason::ROOT_ENUM_ERROR, ReferenceChainsTestAccessor::searchAbandonReasonForTest()); +#ifdef COUNTERS EXPECT_EQ(enum_errors_before + static_cast(ReferenceChainTracker::MAX_CONSECUTIVE_ENUM_ERRORS), Counters::getCounter(REFERENCE_CHAIN_ROOT_ENUM_ERRORS)) << "each of the " << ReferenceChainTracker::MAX_CONSECUTIVE_ENUM_ERRORS << " consecutive errored attempts must increment reference_chain_root_enum_errors"; +#endif ReferenceChainsTestAccessor::setRootEnumRawStateForTest(saved.first, saved.second); tracker->stop();