diagnostics: add STEP-099 render source readiness audit

This commit is contained in:
tei
2026-10-06 15:15:12 +09:00
parent e8b451fe70
commit 8a5214d92d
13 changed files with 915 additions and 9 deletions

View File

@@ -65,6 +65,50 @@ RendererObserver& nullObserver() {
return observer;
}
const char* sourceTypeText(style::SourceType type) noexcept {
switch (type) {
case style::SourceType::Vector: return "vector";
case style::SourceType::Raster: return "raster";
case style::SourceType::RasterDEM: return "raster-dem";
case style::SourceType::GeoJSON: return "geojson";
case style::SourceType::Video: return "video";
case style::SourceType::Annotations: return "annotations";
case style::SourceType::Image: return "image";
case style::SourceType::CustomVector: return "customvector";
case style::SourceType::RasterArray: return "raster-array";
}
return "unknown";
}
const char* tileOperationText(TileOperation op) noexcept {
switch (op) {
case TileOperation::RequestedFromCache: return "RequestedFromCache";
case TileOperation::RequestedFromNetwork: return "RequestedFromNetwork";
case TileOperation::LoadFromNetwork: return "LoadFromNetwork";
case TileOperation::LoadFromCache: return "LoadFromCache";
case TileOperation::StartParse: return "StartParse";
case TileOperation::EndParse: return "EndParse";
case TileOperation::Error: return "Error";
case TileOperation::Cancelled: return "Cancelled";
case TileOperation::NullOp: return "NullOp";
}
return "Unknown";
}
const char* readinessEventType(RetainedUnderlayReason reason) noexcept {
switch (reason) {
case RetainedUnderlayReason::SourceMutation: return "SourceMutation";
case RetainedUnderlayReason::TileMutation: return "TileMutation";
case RetainedUnderlayReason::ImageMutation: return "ImageMutation";
case RetainedUnderlayReason::GlyphMutation: return "GlyphMutation";
case RetainedUnderlayReason::StyleMutation: return "StyleMutation";
case RetainedUnderlayReason::LayerMutation:
case RetainedUnderlayReason::LayerGroupMutation: return "LayerMutation";
case RetainedUnderlayReason::ContextReset: return "ContextReset";
default: return "OtherMutation";
}
}
class RenderTreeImpl final : public RenderTree {
public:
RenderTreeImpl(std::unique_ptr<RenderTreeParameters> parameters_,
@@ -153,9 +197,89 @@ RenderOrchestrator::~RenderOrchestrator() {
threadPool.waitForEmpty();
}
void RenderOrchestrator::advanceRetainedUnderlayContentRevision(RetainedUnderlayReason reason) noexcept {
void RenderOrchestrator::recordReadinessMutation(const char* eventType,
RetainedUnderlayReason reason,
const std::optional<std::string>& sourceId,
const std::string& tileAction) noexcept {
try {
std::lock_guard<std::mutex> lock(readinessDiagnosticsMutex);
const auto sequence = ++readinessEventSequence;
lastReadinessMutation.sequence = sequence;
lastReadinessMutation.contentRevision = retainedUnderlayContentRevision.load(std::memory_order_acquire);
lastReadinessMutation.eventType = eventType;
lastReadinessMutation.reason = retainedUnderlayReasonText(reason);
lastReadinessMutation.sourceId = sourceId;
lastReadinessMutation.affectedSegmentIndices.clear();
lastReadinessMutation.dependencyScope = sourceId ? "unresolved-until-snapshot" : "shared/global/unknown";
if (sourceId) {
auto& state = sourceReadinessEvents[*sourceId];
state.lastMutationReason = retainedUnderlayReasonText(reason);
if (reason == RetainedUnderlayReason::SourceMutation) state.lastSourceMutationSequence = sequence;
if (reason == RetainedUnderlayReason::TileMutation) state.lastTileChangedSequence = sequence;
if (!tileAction.empty()) {
state.lastTileActionSequence = sequence;
state.lastTileAction = tileAction;
}
}
} catch (...) {
// Diagnostic recording is best-effort and must not escape into renderer mutation paths.
}
}
void RenderOrchestrator::advanceRetainedUnderlayContentRevision(
RetainedUnderlayReason reason,
const std::optional<std::string>& sourceId) noexcept {
retainedUnderlayContentReason.store(reason, std::memory_order_release);
retainedUnderlayContentRevision.fetch_add(1, std::memory_order_acq_rel);
recordReadinessMutation(readinessEventType(reason), reason, sourceId);
}
RendererReadinessDiagnostics RenderOrchestrator::buildReadinessDiagnostics(bool styleLoaded,
bool spriteLoaded) const {
RendererReadinessDiagnostics result;
result.styleLoaded = styleLoaded;
result.imageManagerLoaded = imageManager->isLoaded();
result.spriteLoaded = spriteLoaded;
result.contentRevision = retainedUnderlayContentRevision.load(std::memory_order_acquire);
std::unordered_map<std::string, SourceReadinessEventState> sourceEvents;
{
std::lock_guard<std::mutex> lock(readinessDiagnosticsMutex);
// Snapshot-only: do not prune or otherwise mutate diagnostic history from a query path.
// Entries for sources no longer present are naturally ignored below because we enumerate
// the current renderSources set and only look up matching ids.
sourceEvents = sourceReadinessEvents;
result.lastMutation = lastReadinessMutation;
}
result.renderOrchestratorLoaded = result.imageManagerLoaded;
result.sources.reserve(renderSources.size());
for (const auto& [sourceId, renderSource] : renderSources) {
const auto stats = renderSource->getReadinessDiagnostics();
RenderSourceReadinessDiagnostics source;
source.sourceId = sourceId;
source.sourceType = sourceTypeText(renderSource->baseImpl->type);
source.enabled = renderSource->isEnabled();
source.isLoaded = renderSource->isLoaded();
source.tileBacked = stats.tileBacked;
source.tileCount = stats.tileCount;
source.incompleteTileCount = stats.incompleteTileCount;
source.loadedTileCount = stats.loadedTileCount;
source.hasFadingTiles = stats.hasFadingTiles;
result.hasFadingTiles = result.hasFadingTiles || stats.hasFadingTiles;
result.renderOrchestratorLoaded = result.renderOrchestratorLoaded && source.isLoaded;
if (const auto it = sourceEvents.find(sourceId); it != sourceEvents.end()) {
source.lastSourceMutationSequence = it->second.lastSourceMutationSequence;
source.lastTileChangedSequence = it->second.lastTileChangedSequence;
source.lastTileActionSequence = it->second.lastTileActionSequence;
source.lastTileAction = it->second.lastTileAction;
source.lastMutationReason = it->second.lastMutationReason;
}
result.sources.push_back(std::move(source));
}
std::ranges::sort(result.sources, {}, &RenderSourceReadinessDiagnostics::sourceId);
return result;
}
void RenderOrchestrator::markContextLost() {
@@ -361,6 +485,15 @@ std::unique_ptr<RenderTree> RenderOrchestrator::createRenderTree(
const SourceDifference sourceDiff = diffSources(sourceImpls, updateParameters->sources);
if (!sourceDiff.added.empty() || !sourceDiff.removed.empty() || !sourceDiff.changed.empty()) {
advanceRetainedUnderlayContentRevision(RetainedUnderlayReason::SourceMutation);
for (const auto& entry : sourceDiff.added) {
recordReadinessMutation("SourceMutation", RetainedUnderlayReason::SourceMutation, entry.first);
}
for (const auto& entry : sourceDiff.removed) {
recordReadinessMutation("SourceMutation", RetainedUnderlayReason::SourceMutation, entry.first);
}
for (const auto& entry : sourceDiff.changed) {
recordReadinessMutation("SourceMutation", RetainedUnderlayReason::SourceMutation, entry.first);
}
}
sourceImpls = updateParameters->sources;
@@ -519,7 +652,17 @@ std::unique_ptr<RenderTree> RenderOrchestrator::createRenderTree(
addChanges(changes);
}
// Readiness is sampled for diagnostics only. Preserve the renderer's formal load gate.
renderTreeParameters->loaded = updateParameters->styleLoaded && isLoaded();
if (updateParameters->retainedUnderlayState) {
try {
auto readinessDiagnostics =
buildReadinessDiagnostics(updateParameters->styleLoaded, updateParameters->spriteLoaded);
updateParameters->retainedUnderlayState->recordRendererReadiness(std::move(readinessDiagnostics));
} catch (...) {
// A failed diagnostic snapshot must not affect the render tree or its formal loaded gate.
}
}
if (!isMapModeContinuous && !renderTreeParameters->loaded) {
return nullptr;
}
@@ -835,7 +978,7 @@ void RenderOrchestrator::setFeatureState(const std::string& sourceID,
if (RenderSource* renderSource = getRenderSource(sourceID)) {
renderSource->setFeatureState(sourceLayerID, featureID, state);
advanceRetainedUnderlayContentRevision(RetainedUnderlayReason::SourceMutation);
advanceRetainedUnderlayContentRevision(RetainedUnderlayReason::SourceMutation, sourceID);
}
}
@@ -858,7 +1001,7 @@ void RenderOrchestrator::removeFeatureState(const std::string& sourceID,
if (RenderSource* renderSource = getRenderSource(sourceID)) {
renderSource->removeFeatureState(sourceLayerID, featureID, stateKey);
advanceRetainedUnderlayContentRevision(RetainedUnderlayReason::SourceMutation);
advanceRetainedUnderlayContentRevision(RetainedUnderlayReason::SourceMutation, sourceID);
}
}
@@ -1080,6 +1223,13 @@ void RenderOrchestrator::clearData() {
imageManager->clear();
glyphManager->evict(fontStacks(*layerImpls));
try {
std::lock_guard<std::mutex> lock(readinessDiagnosticsMutex);
sourceReadinessEvents.clear();
lastReadinessMutation = {};
} catch (...) {
// Keep renderer style cleanup independent from optional diagnostic history cleanup.
}
advanceRetainedUnderlayContentRevision(RetainedUnderlayReason::StyleMutation);
}
@@ -1295,10 +1445,10 @@ void RenderOrchestrator::onTileError(RenderSource& source, const OverscaledTileI
observer->onResourceError(error);
}
void RenderOrchestrator::onTileChanged(RenderSource&, const OverscaledTileID&) {
void RenderOrchestrator::onTileChanged(RenderSource& source, const OverscaledTileID&) {
MLN_TRACE_FUNC();
advanceRetainedUnderlayContentRevision(RetainedUnderlayReason::TileMutation);
advanceRetainedUnderlayContentRevision(RetainedUnderlayReason::TileMutation, source.baseImpl->id);
observer->onInvalidate();
}
@@ -1306,6 +1456,15 @@ void RenderOrchestrator::onTileAction(RenderSource&,
TileOperation op,
const OverscaledTileID& id,
const std::string& sourceID) {
try {
std::lock_guard<std::mutex> lock(readinessDiagnosticsMutex);
const auto sequence = ++readinessEventSequence;
auto& state = sourceReadinessEvents[sourceID];
state.lastTileActionSequence = sequence;
state.lastTileAction = tileOperationText(op);
} catch (...) {
// Tile action observation is best-effort; always forward the original observer callback.
}
observer->onTileAction(op, id, sourceID);
}

View File

@@ -20,6 +20,7 @@
#include <atomic>
#include <map>
#include <memory>
#include <mutex>
#include <optional>
#include <string>
#include <unordered_map>
@@ -332,7 +333,14 @@ private:
/// Move changes into the pending set, clearing the provided collection
void addChanges(UniqueChangeRequestVec&);
void advanceRetainedUnderlayContentRevision(RetainedUnderlayReason) noexcept;
void advanceRetainedUnderlayContentRevision(
RetainedUnderlayReason,
const std::optional<std::string>& sourceId = std::nullopt) noexcept;
void recordReadinessMutation(const char* eventType,
RetainedUnderlayReason reason,
const std::optional<std::string>& sourceId = std::nullopt,
const std::string& tileAction = {}) noexcept;
RendererReadinessDiagnostics buildReadinessDiagnostics(bool styleLoaded, bool spriteLoaded) const;
RendererObserver* observer;
@@ -366,6 +374,18 @@ private:
std::atomic<uint64_t> retainedUnderlayContentRevision{1};
std::atomic<RetainedUnderlayReason> retainedUnderlayContentReason{RetainedUnderlayReason::None};
struct SourceReadinessEventState {
uint64_t lastSourceMutationSequence = 0;
uint64_t lastTileChangedSequence = 0;
uint64_t lastTileActionSequence = 0;
std::string lastTileAction{"none"};
std::string lastMutationReason{"none"};
};
mutable std::mutex readinessDiagnosticsMutex;
uint64_t readinessEventSequence = 0;
std::unordered_map<std::string, SourceReadinessEventState> sourceReadinessEvents;
RenderMutationDiagnostics lastReadinessMutation;
#if MLN_RENDER_BACKEND_OPENGL
bool androidGoldfishMitigationEnabled{false};
#endif

View File

@@ -81,6 +81,20 @@ inline void writeOptionalString(Writer& writer, const char* key, const std::opti
if (value) writer.String(value->c_str()); else writer.Null();
}
template <typename Writer>
inline void writeOptionalUint32(Writer& writer, const char* key, const std::optional<uint32_t>& value) {
writer.Key(key);
if (value) writer.Uint(*value); else writer.Null();
}
template <typename Writer>
inline void writeStringArray(Writer& writer, const char* key, const std::vector<std::string>& values) {
writer.Key(key);
writer.StartArray();
for (const auto& value : values) writer.String(value.c_str());
writer.EndArray();
}
template <typename Writer>
inline void writeStyleLayerDiagnostics(Writer& writer, const StyleLayerDiagnostics& layer) {
writer.StartObject();
@@ -117,6 +131,43 @@ inline std::string renderSegmentDiagnosticsToJSON(const RenderSegmentDiagnostics
writer.Key("fastPathHit"); writer.Uint64(snapshot.fastPathHit);
writer.Key("fastPathMiss"); writer.Uint64(snapshot.fastPathMiss);
writer.Key("fullCpuFrame"); writer.Uint64(snapshot.fullCpuFrame);
writer.Key("styleLoaded"); writer.Bool(snapshot.styleLoaded);
writer.Key("imageManagerLoaded"); writer.Bool(snapshot.imageManagerLoaded);
writer.Key("renderOrchestratorLoaded"); writer.Bool(snapshot.renderOrchestratorLoaded);
writer.Key("spriteLoaded"); writer.Bool(snapshot.spriteLoaded);
writer.Key("hasFadingTiles"); writer.Bool(snapshot.hasFadingTiles);
writer.Key("contentRevision"); writer.Uint64(snapshot.contentRevision);
writer.Key("sources"); writer.StartArray();
for (const auto& source : snapshot.sources) {
writer.StartObject();
writer.Key("sourceId"); writer.String(source.sourceId.c_str());
writer.Key("sourceType"); writer.String(source.sourceType.c_str());
writer.Key("enabled"); writer.Bool(source.enabled);
writer.Key("isLoaded"); writer.Bool(source.isLoaded);
writer.Key("tileBacked"); writer.Bool(source.tileBacked);
writeOptionalUint32(writer, "tileCount", source.tileCount);
writeOptionalUint32(writer, "incompleteTileCount", source.incompleteTileCount);
writeOptionalUint32(writer, "loadedTileCount", source.loadedTileCount);
writer.Key("hasFadingTiles"); writer.Bool(source.hasFadingTiles);
writer.Key("lastSourceMutationSequence"); writer.Uint64(source.lastSourceMutationSequence);
writer.Key("lastTileChangedSequence"); writer.Uint64(source.lastTileChangedSequence);
writer.Key("lastTileActionSequence"); writer.Uint64(source.lastTileActionSequence);
writer.Key("lastTileAction"); writer.String(source.lastTileAction.c_str());
writer.Key("lastMutationReason"); writer.String(source.lastMutationReason.c_str());
writer.EndObject();
}
writer.EndArray();
writer.Key("lastMutation"); writer.StartObject();
writer.Key("sequence"); writer.Uint64(snapshot.lastMutation.sequence);
writer.Key("contentRevision"); writer.Uint64(snapshot.lastMutation.contentRevision);
writer.Key("eventType"); writer.String(snapshot.lastMutation.eventType.c_str());
writer.Key("reason"); writer.String(snapshot.lastMutation.reason.c_str());
writeOptionalString(writer, "sourceId", snapshot.lastMutation.sourceId);
writer.Key("affectedSegmentIndices"); writer.StartArray();
for (const auto index : snapshot.lastMutation.affectedSegmentIndices) writer.Uint(index);
writer.EndArray();
writer.Key("dependencyScope"); writer.String(snapshot.lastMutation.dependencyScope.c_str());
writer.EndObject();
writer.Key("styleLayers"); writer.StartArray();
for (const auto& layer : snapshot.styleLayers) writeStyleLayerDiagnostics(writer, layer);
writer.EndArray();
@@ -134,6 +185,8 @@ inline std::string renderSegmentDiagnosticsToJSON(const RenderSegmentDiagnostics
writer.Key("layers"); writer.StartArray();
for (const auto& layer : segment.layers) writeStyleLayerDiagnostics(writer, layer);
writer.EndArray();
writeStringArray(writer, "dependentSourceIds", segment.dependentSourceIds);
writeStringArray(writer, "unknownDependencies", segment.unknownDependencies);
writer.Key("cache");
if (!segment.cache) {
writer.Null();

View File

@@ -11,8 +11,10 @@
#include <mbgl/style/source_impl.hpp>
#include <mbgl/style/layer_properties.hpp>
#include <cstdint>
#include <map>
#include <memory>
#include <optional>
#include <unordered_map>
#include <vector>
@@ -49,6 +51,14 @@ public:
using RenderTiles = std::shared_ptr<const std::vector<std::reference_wrapper<const RenderTile>>>;
struct RenderSourceReadinessStats {
bool tileBacked = false;
std::optional<uint32_t> tileCount;
std::optional<uint32_t> incompleteTileCount;
std::optional<uint32_t> loadedTileCount;
bool hasFadingTiles = false;
};
class RenderSource : protected TileObserver {
public:
static std::unique_ptr<RenderSource> create(const Immutable<style::Source::Impl>&, const TaggedScheduler&);
@@ -68,6 +78,17 @@ public:
virtual void prepare(const SourcePrepareParameters&) = 0;
virtual void updateFadingTiles() = 0;
virtual bool hasFadingTiles() const = 0;
// Read on the renderer thread while the source and its tile pyramid are owned by RenderOrchestrator.
// This is an observational summary and must not define or modify isLoaded().
virtual RenderSourceReadinessStats getReadinessDiagnostics() const {
return {
.tileBacked = false,
.tileCount = std::nullopt,
.incompleteTileCount = std::nullopt,
.loadedTileCount = std::nullopt,
.hasFadingTiles = hasFadingTiles(),
};
}
// If supported, returns a shared list of RenderTiles, sorted by tile id and
// excluding tiles hold for fade; returns nullptr otherwise.
virtual RenderTiles getRenderTiles() const { return nullptr; }

View File

@@ -5,8 +5,10 @@
#include <mbgl/renderer/render_segment.hpp>
#include <mbgl/renderer/render_segment_plan.hpp>
#include <algorithm>
#include <atomic>
#include <mutex>
#include <set>
#include <tuple>
#include <utility>
@@ -224,6 +226,18 @@ public:
entry.layers.assign(next.styleLayers.begin() + segment.beginIndex,
next.styleLayers.begin() + segment.endExclusive);
}
std::set<std::string> dependentSourceIds;
std::set<std::string> unknownDependencies;
for (const auto& layer : entry.layers) {
if (layer.sourceId) dependentSourceIds.insert(*layer.sourceId);
if (layer.layerType == "symbol") {
unknownDependencies.insert("symbol/glyph/image/placement");
} else if (layer.layerType == "custom" || layer.layerType == "custom-drawable") {
unknownDependencies.insert("custom");
}
}
entry.dependentSourceIds.assign(dependentSourceIds.begin(), dependentSourceIds.end());
entry.unknownDependencies.assign(unknownDependencies.begin(), unknownDependencies.end());
if (segment.strategy == RenderSegmentStrategy::Retained) {
++next.retainedSegmentCount;
entry.cache.emplace();
@@ -240,6 +254,37 @@ public:
renderSegmentDiagnostics = std::move(next);
}
void recordRendererReadiness(RendererReadinessDiagnostics readiness) {
std::lock_guard<std::mutex> lock(rangeMutex);
renderSegmentDiagnostics.styleLoaded = readiness.styleLoaded;
renderSegmentDiagnostics.imageManagerLoaded = readiness.imageManagerLoaded;
renderSegmentDiagnostics.renderOrchestratorLoaded = readiness.renderOrchestratorLoaded;
renderSegmentDiagnostics.spriteLoaded = readiness.spriteLoaded;
renderSegmentDiagnostics.hasFadingTiles = readiness.hasFadingTiles;
renderSegmentDiagnostics.contentRevision = readiness.contentRevision;
renderSegmentDiagnostics.sources = std::move(readiness.sources);
auto mutation = std::move(readiness.lastMutation);
mutation.affectedSegmentIndices.clear();
if (mutation.sequence != 0) {
if (mutation.sourceId) {
for (const auto& segment : renderSegmentDiagnostics.segments) {
if (std::find(segment.dependentSourceIds.begin(),
segment.dependentSourceIds.end(),
*mutation.sourceId) != segment.dependentSourceIds.end()) {
mutation.affectedSegmentIndices.push_back(segment.segmentIndex);
}
}
mutation.dependencyScope = mutation.affectedSegmentIndices.empty()
? "source-not-in-render-segments"
: "source-local-diagnostic";
} else {
mutation.dependencyScope = "shared/global/unknown";
}
}
renderSegmentDiagnostics.lastMutation = std::move(mutation);
}
RenderSegmentDiagnostics renderSegmentSnapshot() const {
std::lock_guard<std::mutex> lock(rangeMutex);
auto result = renderSegmentDiagnostics;

View File

@@ -486,6 +486,23 @@ bool RenderTileSource::hasFadingTiles() const {
return tilePyramid.hasFadingTiles();
}
RenderSourceReadinessStats RenderTileSource::getReadinessDiagnostics() const {
RenderSourceReadinessStats result;
result.tileBacked = true;
result.tileCount = static_cast<uint32_t>(tilePyramid.getTiles().size());
uint32_t incomplete = 0;
uint32_t loaded = 0;
for (const auto& entry : tilePyramid.getTiles()) {
const auto& tile = *entry.second;
if (!tile.isComplete()) ++incomplete;
if (tile.isLoaded()) ++loaded;
}
result.incompleteTileCount = incomplete;
result.loadedTileCount = loaded;
result.hasFadingTiles = tilePyramid.hasFadingTiles();
return result;
}
RenderTiles RenderTileSource::getRenderTiles() const {
if (!filteredRenderTiles) {
auto result = std::make_shared<std::vector<std::reference_wrapper<const RenderTile>>>();

View File

@@ -23,6 +23,7 @@ public:
void prepare(const SourcePrepareParameters&) override;
void updateFadingTiles() override;
bool hasFadingTiles() const override;
RenderSourceReadinessStats getReadinessDiagnostics() const override;
RenderTiles getRenderTiles() const override;
RenderTiles getRenderTilesSortedByYPosition() const override;