chromium/base/profiler/sample_metadata.h

// Copyright 2019 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef BASE_PROFILER_SAMPLE_METADATA_H_
#define BASE_PROFILER_SAMPLE_METADATA_H_

#include <optional>
#include <string_view>

#include "base/base_export.h"
#include "base/profiler/metadata_recorder.h"
#include "base/threading/platform_thread.h"

// -----------------------------------------------------------------------------
// Usage documentation
// -----------------------------------------------------------------------------
//
// Overview:
// These functions provide a means to control the metadata attached to samples
// collected by the stack sampling profiler. SampleMetadataScope controls the
// scope covered by the metadata (thread, process).
//
// Any samples collected by the sampling profiler will include the active
// metadata. This enables us to later analyze targeted subsets of samples
// (e.g. those collected during paint or layout).
//
// For example:
//
//   void DidStartLoad() {
//     is_loading_metadata_.Set(1);
//   }
//
//   void DidFinishLoad() {
//     is_loading_metadata_.Remove();
//   }
//
//   base::SampleMetadata is_loading_metadata_;
//
// Alternatively, ScopedSampleMetadata can be used to ensure that the metadata
// is removed correctly.
//
// For example:
//
//   void DoExpensiveWork() {
//     base::ScopedSampleMetadata metadata("xyz", 1);
//     if (...) {
//       ...
//       if (...) {
//         ...
//         return;
//       }
//     }
//     ...
//   }

namespace base {

class TimeTicks;

enum class SampleMetadataScope { … };

class BASE_EXPORT SampleMetadata { … };

class BASE_EXPORT ScopedSampleMetadata { … };

// Applies the specified metadata to samples already recorded between
// |period_start| and |period_end| in all thread's active profiles, subject to
// the condition that the profile fully encompasses the period and the profile
// has not already completed. The condition ensures that the metadata is applied
// only if all execution during its scope was seen in the profile. This avoids
// biasng the samples towards the 'middle' of the execution seen during the
// metadata scope (i.e. because the start or end of execution was missed), at
// the cost of missing execution that are longer than the profiling period, or
// extend before or after it. |period_end| must be <= TimeTicks::Now().
BASE_EXPORT void ApplyMetadataToPastSamples(TimeTicks period_start,
                                            TimeTicks period_end,
                                            std::string_view name,
                                            int64_t value,
                                            SampleMetadataScope scope);
BASE_EXPORT void ApplyMetadataToPastSamples(TimeTicks period_start,
                                            TimeTicks period_end,
                                            std::string_view name,
                                            int64_t key,
                                            int64_t value,
                                            SampleMetadataScope scope);

// Adds metadata as metadata global to the sampling profile. Has the effect of
// applying the metadata to all samples in the profile, even ones collected
// earlier in time. This is probably not what you want for most use cases;
// prefer using SampleMetadata / ScopedSampleMetadata /
// ApplyMetadataToPastSamples instead.
BASE_EXPORT void AddProfileMetadata(std::string_view name,
                                    int64_t key,
                                    int64_t value,
                                    SampleMetadataScope scope);

// Returns the process-global metadata recorder instance used for tracking
// sampling profiler metadata.
//
// This function should not be called by non-profiler related code.
BASE_EXPORT MetadataRecorder* GetSampleMetadataRecorder();

}  // namespace base

#endif  // BASE_PROFILER_SAMPLE_METADATA_H_