@squidcloud/client/dist/internal-common/src/public-types/metric.public-types.d.ts

A typescript implementation of the Squid client

import { MetadataFilter } from './metadata-filter.public-types';
/**
 * Tag filter for metric queries. Accepts either a simple key-value record (backward compatible)
 * or the full {@link MetadataFilter} tree with `$eq`, `$ne`, `$in`, `$nin`, `$exists`,
 * `$gt`, `$gte`, `$lt`, `$lte`, `$and`, `$or`.
 * @category Metrics
 */
export type MetricTagFilter = Record<string, string> | MetadataFilter;
/**
 * Name of metrics publicly provided by the system.
 * - Metrics suffixed by '_time' are 'gauge' metrics.
 * - Metrics suffixed by '_count' are 'count' metrics.
 * All Squid metrics starts with `squid_` prefix.
 */
export declare const SQUID_METRIC_NAMES: readonly ["squid_functionExecution_count", "squid_functionExecution_time"];
/** Name of a built-in Squid metric ('squid_functionExecution_count' or 'squid_functionExecution_time'). */
export type SquidMetricName = (typeof SQUID_METRIC_NAMES)[number];
/** Aggregation function used in metric queries (e.g., 'sum', 'max', 'median'). */
export declare const METRIC_FUNCTIONS: readonly ["sum", "max", "min", "average", "median", "p95", "p99", "count"];
/** Aggregation function used in metric queries (e.g., 'sum', 'max', 'median'). */
export type MetricFunction = (typeof METRIC_FUNCTIONS)[number];
/** Defines source of the metric: reported by user or automatically collected by the system (Squid). */
export declare const METRIC_DOMAIN: readonly ["user", "squid"];
/** Domain of the metric: 'user' for custom metrics, 'squid' for built-in system metrics. */
export type MetricDomain = (typeof METRIC_DOMAIN)[number];
/** Defines how to align data points in a metric query interval. */
export declare const METRIC_INTERVAL_ALIGNMENT: readonly ["align-by-start-time", "align-by-end-time"];
/** Indicates how to align per-point periods in metric queries. */
export type MetricIntervalAlignment = (typeof METRIC_INTERVAL_ALIGNMENT)[number];
/** Behavior when no data is available for a metric query. */
export declare const METRIC_NO_DATA_BEHAVIOR: readonly ["return-no-result-groups", "return-result-group-with-default-values"];
/** Indicates behavior when no data is available. */
export type MetricNoDataBehavior = (typeof METRIC_NO_DATA_BEHAVIOR)[number];
/** Common parameters shared by all metric query requests. */
export interface QueryMetricsRequestCommon {
    /** Kind of the metrics (domain) to query. */
    domain: MetricDomain;
    /** Start of the queried interval. Must be an integer value. */
    periodStartSeconds: number;
    /** End of the queried interval. Must be an integer value. */
    periodEndSeconds: number;
    /**
     * Time interval per point. Must be less than  periodEndSeconds - periodStartSeconds.
     * Set to 0 or keep undefined to have only 1 value in the result.
     */
    pointIntervalSeconds?: number;
    /**
     * Specifies the alignment of the per-point interval.
     * Default: 'align-by-start-time'
     */
    pointIntervalAlignment?: MetricIntervalAlignment;
    /** Aggregation functions that maps multiple points per point region to a single point value. */
    fn: MetricFunction | Array<MetricFunction>;
    /**
     * If there is no data in the specified region this value will be used to fill the gap.
     * Default: null.
     */
    fillValue?: number | null;
    /**
     * Tag filters. Supports two formats:
     * - Simple: `Record<string, string>` — each key-value pair is an exact equality match.
     * - Advanced: `AiContextMetadataFilter` — the same filter syntax used by AI knowledge base
     *   metadata, supporting `$eq`, `$ne`, `$in`, `$nin`, `$exists`, `$and`, `$or`, and
     *   comparison operators (`$gt`, `$gte`, `$lt`, `$lte` — numeric comparisons on string tags).
     *
     * @example Simple format
     * ```ts
     * tagFilter: { aiModel: 'claude-sonnet-4-5-20250514', isError: '0' }
     * ```
     * @example Advanced format
     * ```ts
     * tagFilter: { $or: [{ aiModel: { $in: ['claude-sonnet-4-5-20250514', 'gpt-4o'] } }, { isError: { $ne: '0' } }] }
     * ```
     */
    tagFilter?: MetricTagFilter;
    /**
     * A mapping of known tag values that must be present in the response groups.
     *
     * This ensures that the result will include groups for all specified tag values,
     * even if there is no data for some values in the database.
     *
     * Example: Consider a tag 'isError' with two possible values: '0' and '1'.
     * When 'tagDomains' contains `{'isError': ['0', '1']}`, the result will include
     * groups for both 'isError: 0' and 'isError: 1'. If the database lacks data for
     * 'isError: 1', the points in this group will be set to 'fillValue' (default is 'null').
     *
     * The tags in the new groups will be copied from the existing resultGroups,
     * along with one of the tag domain values.
     *
     * @property {Record<string, string[]>} tagDomains - A record where each key is a tag name and
     * each value is an array of possible values for that tag. Should only contain tags listed in 'groupByTags' field.
     */
    tagDomains?: Record<string, string[]>;
    /** List of ordered tag names for a 'GROUP BY'. */
    groupByTags?: string[];
    /** The results will be ordered by the specified tags (ORDER BY). */
    orderByTags?: string[];
    /**
     * Specifies what result will be returned if there were no records found in the database.
     * In this case the 'resultGroups' array will be empty (default), or can be filled with a default
     * values if 'return-result-group-with-default-values' is specified.
     * The generated result group will have 'tagValues' set to empty strings.
     *
     * May be useful to get a ready-to-render array with no additional post-processing required.
     *
     * Note: 'tagDomains' can provide similar functionality when set of tag values is defined: multiple result groups
     * will be filled with default values. There is no need to use this option if 'tagDomains' is used.
     *
     * Default: 'return-no-result-groups'
     */
    noDataBehavior?: MetricNoDataBehavior;
}
/**
 * Request structure for querying user-defined metrics.
 * @category Metrics
 */
export interface QueryUserMetricsRequest<NameType extends string = string> extends QueryMetricsRequestCommon {
    /** Specifies the user domain for custom metrics. */
    domain: 'user';
    /** Name of the user-defined metric to query. */
    name: NameType;
}
/**
 * Request structure for querying built-in Squid metrics.
 * @category Metrics
 */
export interface QuerySquidMetricsRequest<NameType extends SquidMetricName = SquidMetricName> extends QueryMetricsRequestCommon {
    /** Specifies the squid domain for built-in system metrics. */
    domain: 'squid';
    /** Name of the built-in Squid metric to query. */
    name: NameType;
}
/** A request to query metrics, either Squid or user-defined, depending on the domain and metric name. */
export type QueryMetricsRequest<NameType extends string = string> = QuerySquidMetricsRequest<NameType extends SquidMetricName ? NameType : SquidMetricName> | QueryUserMetricsRequest<NameType>;
/**
 * Every result point is a list of [timestamp, values...],
 * where list of values are defined by the list of functions in the request.
 * If there is no data for the point 'null' is used as a 'value'.
 * The timestamp is always equal to the point period start date and is measured in Unix epoch seconds.
 */
export type QueryMetricsResultPoint = [number, ...(number | null)[]];
/** A group of metric results that share the same tag values. */
export interface QueryMetricsResultGroup {
    /** Values of the tags in the group. The tags are ordered the same way as in request.groupByTags collection. */
    tagValues: string[];
    /** List of result points for the group. */
    points: Array<QueryMetricsResultPoint>;
}
/** Common structure for metric query responses. */
export interface QueryMetricsResponseCommon {
    /**
     * Result of the metrics query.
     * Contains only 1 element if `groupByTags` are empty, otherwise contains multiple results grouped by tags.
     */
    resultGroups: Array<QueryMetricsResultGroup>;
}
/**
 * Response for a user-defined metric query.
 * @category Metrics
 */
export interface QueryUserMetricsResponse<NameType extends string = string> extends QueryMetricsResponseCommon {
    /** Specifies the user domain for custom metrics. */
    domain: 'user';
    /** Name of the queried user-defined metric. */
    metricName: NameType;
}
/**
 * A single metric response for 'SquidMetricsRequest'.
 * @category Metrics
 */
export interface QuerySquidMetricsResponse<NameType extends SquidMetricName> extends QueryMetricsResponseCommon {
    /** Specifies the squid domain for built-in system metrics. */
    domain: 'squid';
    /** Name of the queried built-in Squid metric. */
    metricName: NameType;
}
/** Final normalized response for a metrics query, required fields guaranteed. */
export type QueryMetricsResponse<NameType extends string = string> = Required<QuerySquidMetricsResponse<NameType extends SquidMetricName ? NameType : SquidMetricName> | QueryUserMetricsResponse<NameType>>;
/**
 * A single metric event (wire format).
 * @category Metrics
 */
export interface Metric<MetricNameType = string> {
    /** Name of the metric. */
    name: MetricNameType;
    /** Value of the metric. */
    value: number;
    /** Time associated with the metric. Milliseconds since UNIX epoch. */
    timestamp: number;
    /** Set of tags for the metric. */
    tags: Record<string, string>;
}