@zendesk/retrace/esm/v3/matchSpan.d.ts

define and capture Product Operation Traces along with computed metrics with an optional friendly React beacon API

import type { SpanAnnotation } from './spanAnnotationTypes';
import type { Attributes, Span, SpanStatus, SpanType } from './spanTypes';
import type { RecordedSpan } from './traceRecordingTypes';
import type { DraftTraceContext, MapSchemaToTypes, RelationSchemasBase, TraceContext } from './types';
import type { UnionToIntersection } from './typeUtils';
export declare const INACTIVE_CONTEXT: DraftTraceContext<any, any, any>;
export interface PublicSpanMatcherTags {
    /**
     * Only applicable for 'requiredSpans' list: it will opt-out of the default behavior,
     * which interrupts the trace if the requiredSpan has an error status.
     */
    continueWithErrorStatus?: boolean;
    /**
     * If multiple matches are found, this specifies which match to use.
     * It can be set to a negative number to match from the end of the operation (backwards, with syntax like Array.prototype.slice()).
     * This only has an effect on matchers that run when the recording is complete,
     * e.g. in startSpan and endSpan for defining computed spans.
     */
    nthMatch?: number;
    /**
     * Do not consider entries before this index.
     * This only has an effect on matchers that run when the recording is complete.
     */
    lowestIndexToConsider?: number;
    /**
     * Index of last entry to consider. Will stop considering entries beyond this index.
     * This only has an effect on matchers that run when the recording is complete.
     */
    highestIndexToConsider?: number;
}
export interface SpanMatcherTags extends PublicSpanMatcherTags {
    /**
     * @internal
     * Enables the idle-regression check.
     * Only has an effect in for component-lifecycle entries in 'requiredSpans' matchers list.
     */
    idleCheck?: boolean;
    /**
     * @internal
     */
    requiredSpan?: boolean;
}
export interface SpanAndAnnotationForMatching<RelationSchemasT extends RelationSchemasBase<RelationSchemasT>> {
    span: Span<RelationSchemasT> | RecordedSpan<RelationSchemasT>;
    annotation?: SpanAnnotation;
}
/**
 * Function type for matching performance entries.
 */
export interface SpanMatcherFn<SelectedRelationNameT extends keyof RelationSchemasT, RelationSchemasT extends RelationSchemasBase<RelationSchemasT>, VariantsT extends string> extends SpanMatcherTags {
    (spanAndAnnotation: SpanAndAnnotationForMatching<RelationSchemasT>, context: DraftTraceContext<SelectedRelationNameT, RelationSchemasT, VariantsT> | undefined): boolean;
    /** source definition object for debugging (if converted from object) */
    fromDefinition?: SpanMatchDefinition<SelectedRelationNameT, RelationSchemasT, VariantsT>;
}
export type NameMatcher<RelationSchemaT> = string | RegExp | ((name: string, inputRelation: MapSchemaToTypes<RelationSchemaT> | undefined) => boolean);
export interface SpanMatchDefinition<SelectedRelationNameT extends keyof RelationSchemasT, RelationSchemasT extends RelationSchemasBase<RelationSchemasT>, VariantsT extends string> extends PublicSpanMatcherTags {
    name?: NameMatcher<RelationSchemasT[SelectedRelationNameT]>;
    performanceEntryName?: NameMatcher<RelationSchemasT[SelectedRelationNameT]>;
    type?: SpanType;
    status?: SpanStatus;
    attributes?: Attributes;
    id?: string;
    matchingRelations?: (keyof UnionToIntersection<RelationSchemasT[SelectedRelationNameT]>)[] | boolean;
    /** The index of the reoccurrence within the span, calculated based on the span's type+name combination */
    occurrence?: number | ((occurrence: number) => boolean);
    isIdle?: boolean;
    label?: string;
    renderCount?: number;
    fn?: SpanMatcherFn<SelectedRelationNameT, RelationSchemasT, VariantsT>;
    oneOf?: SpanMatchDefinition<SelectedRelationNameT, RelationSchemasT, VariantsT>[];
    not?: SpanMatchDefinition<SelectedRelationNameT, RelationSchemasT, VariantsT>;
}
export type SpanMatch<SelectedRelationNameT extends keyof RelationSchemasT, RelationSchemasT extends RelationSchemasBase<RelationSchemasT>, VariantsT extends string> = SpanMatcherFn<SelectedRelationNameT, RelationSchemasT, VariantsT> | SpanMatchDefinition<SelectedRelationNameT, RelationSchemasT, VariantsT>;
export interface ParentSpanMatcher<SelectedRelationNameT extends keyof RelationSchemasT, RelationSchemasT extends RelationSchemasBase<RelationSchemasT>, VariantsT extends string> {
    /**
     * Define the scope of the search for the parent span.
     * 'span-created-tick' will only search for spans created in the current tick,
     * while 'entire-recording' will search through all recorded spans
     * in the trace that was running when the span was created.
     *
     * Note that search === 'entire-recording' only works
     * when running the matcher when traceContext is available
     * (i.e. before Trace is disposed - while it's active, and when first creating the recording)
     */
    search: 'span-created-tick' | 'span-ended-tick' | 'entire-recording';
    searchDirection: 'after-self' | 'before-self';
    match: SpanMatch<SelectedRelationNameT, RelationSchemasT, VariantsT>;
}
/**
 * The common name of the span to match. Can be a string, RegExp, or function.
 */
export declare function withName<const SelectedRelationNameT extends keyof RelationSchemasT, const RelationSchemasT extends RelationSchemasBase<RelationSchemasT>, const VariantsT extends string>(value: NameMatcher<RelationSchemasT[SelectedRelationNameT]>): SpanMatcherFn<SelectedRelationNameT, RelationSchemasT, VariantsT>;
export declare function withLabel<const SelectedRelationNameT extends keyof RelationSchemasT, const RelationSchemasT extends RelationSchemasBase<RelationSchemasT>, const VariantsT extends string>(value: string): SpanMatcherFn<SelectedRelationNameT, RelationSchemasT, VariantsT>;
/**
 * The PerformanceEntry.name of the entry to match. Can be a string, RegExp, or function.
 */
export declare function withPerformanceEntryName<const SelectedRelationNameT extends keyof RelationSchemasT, const RelationSchemasT extends RelationSchemasBase<RelationSchemasT>, const VariantsT extends string>(value: NameMatcher<RelationSchemasT[SelectedRelationNameT]>): SpanMatcherFn<SelectedRelationNameT, RelationSchemasT, VariantsT>;
export declare function withType<const SelectedRelationNameT extends keyof RelationSchemasT, const RelationSchemasT extends RelationSchemasBase<RelationSchemasT>, const VariantsT extends string>(value: SpanType): SpanMatcherFn<SelectedRelationNameT, RelationSchemasT, VariantsT>;
export declare function withStatus<const SelectedRelationNameT extends keyof RelationSchemasT, const RelationSchemasT extends RelationSchemasBase<RelationSchemasT>, const VariantsT extends string>(value: SpanStatus): SpanMatcherFn<SelectedRelationNameT, RelationSchemasT, VariantsT>;
/**
 * The subset of attributes (metadata) to match against the span.
 */
export declare function withAttributes<const SelectedRelationNameT extends keyof RelationSchemasT, const RelationSchemasT extends RelationSchemasBase<RelationSchemasT>, const VariantsT extends string>(attrs: Attributes): SpanMatcherFn<SelectedRelationNameT, RelationSchemasT, VariantsT>;
export declare function withId<const SelectedRelationNameT extends keyof RelationSchemasT, const RelationSchemasT extends RelationSchemasBase<RelationSchemasT>, const VariantsT extends string>(value: string): SpanMatcherFn<SelectedRelationNameT, RelationSchemasT, VariantsT>;
/**
 * A list of keys of trace's relations to match against the span's.
 */
export declare function withMatchingRelations<const SelectedRelationNameT extends keyof RelationSchemasT, const RelationSchemasT extends RelationSchemasBase<RelationSchemasT>, const VariantsT extends string>(keys?: NoInfer<keyof UnionToIntersection<RelationSchemasT[SelectedRelationNameT]>>[] | true): SpanMatcherFn<SelectedRelationNameT, RelationSchemasT, VariantsT>;
/**
 * The occurrence of the span with the same name and type within the operation.
 */
export declare function withOccurrence<const SelectedRelationNameT extends keyof RelationSchemasT, const RelationSchemasT extends RelationSchemasBase<RelationSchemasT>, const VariantsT extends string>(value: number | ((occurrence: number) => boolean)): SpanMatcherFn<SelectedRelationNameT, RelationSchemasT, VariantsT>;
export declare function withComponentRenderCount<const SelectedRelationNameT extends keyof RelationSchemasT, const RelationSchemasT extends RelationSchemasBase<RelationSchemasT>, const VariantsT extends string>(name: NameMatcher<RelationSchemasT[SelectedRelationNameT]>, renderCount: number): SpanMatcherFn<SelectedRelationNameT, RelationSchemasT, VariantsT>;
/**
 * only applicable for component-lifecycle entries
 */
export declare function whenIdle<const SelectedRelationNameT extends keyof RelationSchemasT, const RelationSchemasT extends RelationSchemasBase<RelationSchemasT>, const VariantsT extends string>(value?: boolean): SpanMatcherFn<SelectedRelationNameT, RelationSchemasT, VariantsT>;
/**
 * @internal
 * tag matcher with a special, internal matcher tag, and match on span.status === 'error'
 */
export declare function requiredSpanWithErrorStatus<const SelectedRelationNameT extends keyof RelationSchemasT, const RelationSchemasT extends RelationSchemasBase<RelationSchemasT>, const VariantsT extends string>(): SpanMatcherFn<SelectedRelationNameT, RelationSchemasT, VariantsT>;
/**
 * Only applicable for 'requiredSpans' list: it will opt-out of the default behavior,
 * which interrupts the trace if the requiredSpan has an error status.
 */
export declare function continueWithErrorStatus<const SelectedRelationNameT extends keyof RelationSchemasT, const RelationSchemasT extends RelationSchemasBase<RelationSchemasT>, const VariantsT extends string>(): SpanMatcherFn<SelectedRelationNameT, RelationSchemasT, VariantsT>;
export declare function withAllConditions<const SelectedRelationNameT extends keyof RelationSchemasT, const RelationSchemasT extends RelationSchemasBase<RelationSchemasT>, const VariantsT extends string>(...matchers: SpanMatcherFn<SelectedRelationNameT, RelationSchemasT, VariantsT>[]): SpanMatcherFn<SelectedRelationNameT, RelationSchemasT, VariantsT>;
export declare function withOneOfConditions<const SelectedRelationNameT extends keyof RelationSchemasT, const RelationSchemasT extends RelationSchemasBase<RelationSchemasT>, const VariantsT extends string>(...matchers: SpanMatcherFn<SelectedRelationNameT, RelationSchemasT, VariantsT>[]): SpanMatcherFn<SelectedRelationNameT, RelationSchemasT, VariantsT>;
export declare function not<const SelectedRelationNameT extends keyof RelationSchemasT, const RelationSchemasT extends RelationSchemasBase<RelationSchemasT>, const VariantsT extends string>(matcher: SpanMatcherFn<SelectedRelationNameT, RelationSchemasT, VariantsT>): SpanMatcherFn<SelectedRelationNameT, RelationSchemasT, VariantsT>;
export declare function fromDefinition<const SelectedRelationNameT extends keyof RelationSchemasT, const RelationSchemasT extends RelationSchemasBase<RelationSchemasT>, const VariantsT extends string>(definition: SpanMatchDefinition<SelectedRelationNameT, RelationSchemasT, VariantsT>): SpanMatcherFn<SelectedRelationNameT, RelationSchemasT, VariantsT>;
/**
 * Evaluates a span matcher against an entry array.
 * Respects matching index, lowestIndexToConsider, and highestIndexToConsider.
 */
export declare function findMatchingSpan<const SelectedRelationNameT extends keyof RelationSchemasT, const RelationSchemasT extends RelationSchemasBase<RelationSchemasT>, const VariantsT extends string, const RecordedItem extends SpanAndAnnotationForMatching<RelationSchemasT>>(matcher: SpanMatcherFn<SelectedRelationNameT, RelationSchemasT, VariantsT>, recordedItemsArray: readonly RecordedItem[], context: TraceContext<SelectedRelationNameT, RelationSchemasT, VariantsT> | undefined, 
/** config argument can be used to override tags from matcher: */
{ lowestIndexToConsider, highestIndexToConsider: highestIndexToConsiderInput, nthMatch, }?: PublicSpanMatcherTags): RecordedItem | undefined;