scope.hpp File Reference

Scope — a per-library metrics instance with a shared name prefix, default constant labels, and default display metadata. More...

#include <prom/metric_base.hpp>
#include <prom/registry.hpp>
#include <cstdint>
#include <memory>
#include <mutex>
#include <string>
#include <string_view>
#include <unordered_map>
#include <utility>
#include <vector>

Include dependency graph for scope.hpp:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	prom::ScopeConfig
	The configuration a Scope applies to every metric created through it. More...
class	prom::Scope
	A named, reconfigurable metrics instance for one library. More...

Namespaces
namespace	prom
namespace	prom::detail
	Portable atomic shared_ptr<const T> exposing just load()/store().

Functions
std::shared_ptr< Scope >	prom::scope (const std::string_view name, ScopeConfig config)
	Get-or-create the process-wide scope named name, using config only if it does not yet exist (a later call returns the existing scope and ignores config — reconfigure through the returned scope's setters instead).
std::shared_ptr< Scope >	prom::scope (const std::string_view name)
	Get-or-create the scope named name with a default config whose prefix is name + "_".
std::shared_ptr< Scope >	prom::find_scope (const std::string_view name)
	Return the scope named name, or nullptr if none has been created.
std::vector< std::shared_ptr< Scope > >	prom::scopes ()
	Every process-wide scope created so far (unordered).
std::vector< std::string >	prom::scope_names ()
	The names of every process-wide scope created so far (unordered).

Detailed Description

Scope — a per-library metrics instance with a shared name prefix, default constant labels, and default display metadata.

A Scope is to prom what a named logger is to a logging library: a library configures one instance for itself (prom::scope("foo", {.prefix = "foo_", ...})), stores it, and creates all its metrics through it. Scopes are registered process-wide by name, so a user of the library can fetch the same scope (prom::scope("foo")) and adjust it.

The scope config is live, not cached. A scoped metric does not copy the prefix / labels / display at creation. It re-resolves them whenever the scope's configuration changes, so mutating a scope at runtime reconfigures every metric created from it — subsequent samples flow to the newly-derived series. (Already-emitted series under the old name/labels are left as-is; backends cannot rename a registered series.)

Scopes are deliberately adapter-agnostic: they only decorate specs and hand them to Registry::global(). All adapter resolution stays in the registry layer.

A scope's decoration chains onto the process-wide global decoration (the one Registry::global()->set_prefix(...) mutates), applied outermost: a global prefix reg_ under a scope prefix foo_ yields reg_foo_meter, and label precedence is own → scope → global.