ContextResolverBuilder

Struct ContextResolverBuilder 

Source
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

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

pub fn with_tags_resolver(self, resolver: Option<TagsResolver>) -> Self

Sets the tags resolver.

Defaults to unset.

Source

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.

Source

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

Source

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.

Source

pub fn build(self) -> ContextResolver

Builds a ContextResolver from the current configuration.

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
§

impl<T> Track for T

§

fn track_allocations(self, token: AllocationGroupToken) -> Tracked<Self>

Instruments this type by attaching the given allocation group token, returning a Tracked wrapper. Read more
§

fn in_current_allocation_group(self) -> Tracked<Self>

Instruments this type by attaching the current allocation group, returning a Tracked wrapper. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more