blob: a372fbafc758dc725cc2fb5d63a6a3361b9adc68 [file] [log] [blame]
// Copyright 2019 The Chromium Authors. All rights reserved.
// 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 "base/optional.h"
#include "base/profiler/metadata_recorder.h"
#include "base/strings/string_piece.h"
// -----------------------------------------------------------------------------
// Usage documentation
// -----------------------------------------------------------------------------
//
// Overview:
// These functions provide a means to control the metadata attached to samples
// collected by the stack sampling profiler. Metadata state is shared between
// all threads within a 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() {
// base::SetSampleMetadata("Renderer.IsLoading", 1);
// }
//
// void DidFinishLoad() {
// base::RemoveSampleMetadata("Renderer.IsLoading");
// }
//
// 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 BASE_EXPORT ScopedSampleMetadata {
public:
// Set the metadata value associated with |name|.
ScopedSampleMetadata(StringPiece name, int64_t value);
// Set the metadata value associated with the pair (|name|, |key|). This
// constructor allows the metadata to be associated with an additional
// user-defined key. One might supply a key based on the frame id, for
// example, to distinguish execution in service of scrolling between different
// frames. Prefer the previous constructor if no user-defined metadata is
// required. Note: values specified for a name and key are stored separately
// from values specified with only a name.
ScopedSampleMetadata(StringPiece name, int64_t key, int64_t value);
ScopedSampleMetadata(const ScopedSampleMetadata&) = delete;
~ScopedSampleMetadata();
ScopedSampleMetadata& operator=(const ScopedSampleMetadata&) = delete;
private:
const uint64_t name_hash_;
Optional<int64_t> key_;
};
// Set the metadata value associated with |name| in the process-global stack
// sampling profiler metadata, overwriting any previous value set for that
// |name|.
BASE_EXPORT void SetSampleMetadata(StringPiece name, int64_t value);
// Set the metadata value associated with the pair (|name|, |key|) in the
// process-global stack sampling profiler metadata, overwriting any previous
// value set for that (|name|, |key|) pair. This constructor allows the metadata
// to be associated with an additional user-defined key. One might supply a key
// based on the frame id, for example, to distinguish execution in service of
// scrolling between different frames. Prefer the previous function if no
// user-defined metadata is required. Note: values specified for a name and key
// are stored separately from values specified with only a name.
BASE_EXPORT void SetSampleMetadata(StringPiece name,
int64_t key,
int64_t value);
// Removes the metadata item with the specified name from the process-global
// stack sampling profiler metadata.
//
// If such an item doesn't exist, this has no effect.
BASE_EXPORT void RemoveSampleMetadata(StringPiece name);
// Removes the metadata item with the specified (|name|, |key|) pair from the
// process-global stack sampling profiler metadata. This function does not alter
// values set with the name |name| but no key.
//
// If such an item doesn't exist, this has no effect.
BASE_EXPORT void RemoveSampleMetadata(StringPiece name, int64_t key);
// 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,
StringPiece name,
int64_t value);
BASE_EXPORT void ApplyMetadataToPastSamples(TimeTicks period_start,
TimeTicks period_end,
StringPiece name,
int64_t key,
int64_t value);
// 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_