Struct TagsResolverBuilder 

pub struct TagsResolverBuilder { /* private fields */ }

A builder for a tag resolver.

Implementations

impl TagsResolverBuilder

pub fn new<S: Into<String>>( name: S, interner: GenericMapInterner, ) -> Result<Self, GenericError>

Creates a new TagsResolverBuilder with the given name and interner.

pub fn with_interner(self, interner: GenericMapInterner) -> Self

Sets the interner to use for this resolver.

This is used when we want to use a separate internet for tagsets, different from the one used for contexts.

Defaults to using the interner passed to the builder.

pub fn without_caching(self) -> Self

Sets whether or not to enable caching of resolved tag sets.

TagsResolver provides two main benefits: consistent behavior for resolving tag sets (interning, origin tags, etc), and the caching of those resolved tag sets to speed up future resolutions. However, caching tag sets means that we pay a memory cost for the cache itself, even if the tag sets 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 tag sets.

Disabling caching allows normal resolving to take place without the overhead of caching the tag sets. This can lead to lower average memory usage, as tag sets will only live as long as they are needed, but it will reduce memory determinism as memory will be allocated for every resolved tag set (minus interned strings), which means that resolving the same tag set ten times in a row will result in ten separate allocations, and so on.

Defaults to caching enabled.

pub fn with_cached_tagsets_limit(self, limit: usize) -> Self

Sets the limit on the number of cached tagsets.

This is the maximum number of resolved tag sets that can be cached at any given time. This limit does not affect the total number of tag sets that can be alive at any given time, which is dependent on the interner capacity and whether or not heap allocations are allowed.

Caching tag sets is beneficial when the same tag set is resolved frequently, and it is generally worth allowing for higher limits on cached tag sets 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 tag sets will be cached. This is equivalent to calling without_caching.

Defaults to 500,000.

pub fn with_idle_tagsets_expiration(self, time_to_idle: Duration) -> Self

Sets the time before tag sets are considered “idle” and eligible for expiration.

This controls how long a tag set will be kept in the cache after its last access or creation time. This value is a lower bound, as tag sets eligible for expiration may not be expired immediately. Tag sets 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.

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.

pub fn with_origin_tags_resolver( self, resolver: Option<Arc<dyn OriginTagsResolver>>, ) -> Self

Sets the origin tags resolver to use when building a context.

In some cases, metrics, events, and service checks may have enriched tags based on their origin – the application/host/container/etc that emitted the metric – which has to be considered when building the context itself. As this can be expensive, it is useful to split the logic of actually grabbing the enriched tags based on the available origin info into a separate phase, and implementation, that can run separately from the initial hash-based approach of checking if a context has already been resolved.

When set, any origin information provided will be considered during hashing when looking up a context, and any enriched tags attached to the detected origin will be accessible from the context.

Defaults to unset.

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.

pub fn build(self) -> TagsResolver

Builds a TagsResolver from the current configuration.

pub fn for_tests() -> Self

Configures a TagsResolverBuilder 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.