pub struct ContextResolverBuilder { /* private fields */ }
Expand description
Builder for creating a ContextResolver
.
§Missing
- Support for configuring the size limit of cached contexts.
Implementations§
Source§impl ContextResolverBuilder
impl ContextResolverBuilder
Sourcepub fn from_name<S: Into<String>>(name: S) -> Result<Self, GenericError>
pub fn from_name<S: Into<String>>(name: S) -> Result<Self, GenericError>
Creates a new ContextResolverBuilder
with the given resolver name.
The resolver name should be unique, but it is not required to be. Metrics for the resolver will be emitted using the given name, so in cases where the name is not unique, those metrics will be aggregated together and it will not be possible to distinguish between the different resolvers.
§Errors
If the given resolver name is empty, an error is returned.
Sourcepub fn without_caching(self) -> Self
pub fn without_caching(self) -> Self
Sets whether or not to enable caching of resolved contexts.
ContextResolver
provides two main benefits: consistent behavior for resolving contexts (interning, origin
tags, etc), and the caching of those resolved contexts to speed up future resolutions. However, caching contexts
means that we pay a memory cost for the cache itself, even if the contexts are not ever reused or are seen
infrequently. While expiration can help free up cache capacity, it cannot help recover the memory used by the
underlying cache data structure once they have expanded to hold the contexts.
Disabling caching allows normal resolving to take place without the overhead of caching the contexts. This can lead to lower average memory usage, as contexts will only live as long as they are needed, but it will reduce memory determinism as memory will be allocated for every resolved context (minus interned strings), which means that resolving the same context ten times in a row will result in ten separate allocations, and so on.
Defaults to caching enabled.
Sourcepub fn with_cached_contexts_limit(self, limit: usize) -> Self
pub fn with_cached_contexts_limit(self, limit: usize) -> Self
Sets the limit on the number of cached contexts.
This is the maximum number of resolved contexts that can be cached at any given time. This limit does not affect the total number of contexts that can be alive at any given time, which is dependent on the interner capacity and whether or not heap allocations are allowed.
Caching contexts is beneficial when the same context is resolved frequently, and it is generally worth allowing for higher limits on cached contexts when heap allocations are allowed, as this can better amortize the cost of those heap allocations.
If value is zero, caching will be disabled, and no contexts will be cached. This is equivalent to calling
without_caching
.
Defaults to 500,000.
Sourcepub fn with_idle_context_expiration(self, time_to_idle: Duration) -> Self
pub fn with_idle_context_expiration(self, time_to_idle: Duration) -> Self
Sets the time before contexts are considered “idle” and eligible for expiration.
This controls how long a context will be kept in the cache after its last access or creation time. This value is a lower bound, as contexts eligible for expiration may not be expired immediately. Contexts may still be removed prior to their natural expiration time if the cache is full and evictions are required to make room for a new context.
Defaults to no expiration.
Sourcepub fn with_interner_capacity_bytes(self, capacity: NonZeroUsize) -> Self
pub fn with_interner_capacity_bytes(self, capacity: NonZeroUsize) -> Self
Sets the capacity of the string interner, in bytes.
This is the maximum number of bytes that the interner will use for interning strings that are present in contexts being resolved. This capacity may or may not be allocated entirely when the resolver is built, but the interner will not exceed the configured capacity when allocating any backing storage.
This value directly impacts the number of contexts that can be resolved when heap allocations are disabled, as all resolved contexts must either have values (name or tags) that can be inlined or interned. Once the interner is full, contexts may fail to be resolved if heap allocations are disabled.
The optimal value will almost always be workload-dependent, but a good starting point can be to estimate around 150 - 200 bytes per context based on empirical measurements around common metric name and tag lengths. This translate to around 5000 unique contexts per 1MB of interner size.
Defaults to 2MB.
Sourcepub fn with_heap_allocations(self, allow: bool) -> Self
pub fn with_heap_allocations(self, allow: bool) -> Self
Sets whether or not to allow heap allocations when interning strings.
In cases where the interner is full, this setting determines whether or not we refuse to resolve a context, or if we allow it be resolved by allocating strings on the heap. When heap allocations are enabled, the amount of memory that can be used by the interner is effectively unlimited, as contexts that cannot be interned will be simply spill to the heap instead of being limited in any way.
Defaults to true
.
Sets the tags resolver.
Defaults to unset.
Sourcepub fn without_telemetry(self) -> Self
pub fn without_telemetry(self) -> Self
Sets whether or not to enable telemetry for this resolver.
Reporting the telemetry of the resolver requires running an asynchronous task to override adding additional overhead in the hot path of resolving contexts. In some cases, it may be cumbersome to always create the resolver in an asynchronous context so that the telemetry task can be spawned. This method allows disabling telemetry reporting in those cases.
Defaults to telemetry enabled.
Sourcepub fn with_interner(self, interner: GenericMapInterner) -> Self
pub fn with_interner(self, interner: GenericMapInterner) -> Self
Sets the interner to use for this resolver.
If an interner is not provided, an interner will be created in ContextResolverBuilder::build
Sourcepub fn for_tests() -> Self
pub fn for_tests() -> Self
Configures a ContextResolverBuilder
that is suitable for tests.
This configures the builder with the following defaults:
- resolver name of “noop”
- unlimited cache capacity
- no-op interner (all strings are heap-allocated)
- heap allocations allowed
- telemetry disabled
This is generally only useful for testing purposes, and is exposed publicly in order to be used in cross-crate testing scenarios.
Sourcepub fn build(self) -> ContextResolver
pub fn build(self) -> ContextResolver
Builds a ContextResolver
from the current configuration.
Auto Trait Implementations§
impl Freeze for ContextResolverBuilder
impl !RefUnwindSafe for ContextResolverBuilder
impl Send for ContextResolverBuilder
impl Sync for ContextResolverBuilder
impl Unpin for ContextResolverBuilder
impl !UnwindSafe for ContextResolverBuilder
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Source§impl<T> Instrument for T
impl<T> Instrument for T
Source§fn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
Source§fn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
§impl<T> Track for T
impl<T> Track for T
§fn track_allocations(self, token: AllocationGroupToken) -> Tracked<Self>
fn track_allocations(self, token: AllocationGroupToken) -> Tracked<Self>
Tracked
wrapper. Read more§fn in_current_allocation_group(self) -> Tracked<Self>
fn in_current_allocation_group(self) -> Tracked<Self>
Tracked
wrapper. Read more