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

A typescript implementation of the Squid client

import { MetricName } from '../metric-name';
import { AppId } from '../public-types/communication.public-types';
export interface ObservableNameMetrics {
    count: MetricName;
    time: MetricName;
}
export declare const ObservableNames: {
    readonly functionExecution: ObservableNameMetrics;
    readonly codeInitialization: ObservableNameMetrics;
    readonly getAiChatbotProfiles: ObservableNameMetrics;
    readonly aiImageGeneration: ObservableNameMetrics;
    readonly aiRemoveBackground: ObservableNameMetrics;
    readonly aiAudioTranscribe: ObservableNameMetrics;
    readonly aiAudioCreateSpeech: ObservableNameMetrics;
    readonly discoverGraphQLConnectionSchema: ObservableNameMetrics;
    readonly discoverOpenApiSchema: ObservableNameMetrics;
    readonly discoverOpenApiSchemaFromFile: ObservableNameMetrics;
    readonly graphqlQuery: ObservableNameMetrics;
    readonly testGraphQLConnection: ObservableNameMetrics;
    readonly testAgentProtocolConnection: ObservableNameMetrics;
    readonly graphql: ObservableNameMetrics;
    readonly acquireLock: ObservableNameMetrics;
    readonly releaseLock: ObservableNameMetrics;
    /**
     * Timing and count for '/observability/metrics' endpoint calls used to report batch of metrics.
     */
    readonly metricReport: ObservableNameMetrics;
    /**
     * Timing and count for '/observability/metrics/query' endpoint calls used to query metrics.
     */
    readonly metricQuery: ObservableNameMetrics;
    readonly storageUploadFile: ObservableNameMetrics;
    readonly storageGetFileMetadata: ObservableNameMetrics;
    readonly storageGetDownloadUrl: ObservableNameMetrics;
    readonly storageDeleteFiles: ObservableNameMetrics;
    readonly storageListDirectoryContents: ObservableNameMetrics;
    readonly schedulerJob: ObservableNameMetrics;
    readonly eventHandler: ObservableNameMetrics;
    readonly webhook: ObservableNameMetrics;
    readonly openapi: ObservableNameMetrics;
    readonly executeBackendFunction: ObservableNameMetrics;
    readonly apiControllerCall: ObservableNameMetrics;
};
export type ObservableName = keyof typeof ObservableNames;
export interface MetricEvent {
    appId: AppId;
    name: MetricName;
    tags: Record<string, string>;
    timestamp: Date;
    value: number;
    isExposedToUser: boolean;
}
export interface LogEvent {
    message: string;
    level: string;
    tags: Record<string, string>;
    timestamp: Date;
    isExposedToUser: boolean;
    host: string;
    source?: string;
    service?: string;
}
export declare const AUDIT_LOG_EVENT_NAMES: readonly ["ai_agent"];
export type AuditLogEventName = (typeof AUDIT_LOG_EVENT_NAMES)[number];
export interface AuditLogEvent {
    appId: AppId;
    name: AuditLogEventName;
    timestamp: Date;
    context: {
        clientId?: string;
        userId: string;
    };
    tags: Record<string, string>;
}
/** Agent audit log entry - one per agent invocation */
export interface AgentAuditLogEvent {
    appId: AppId;
    /** Agent ID (nullable for query-with-AI operations without an agent) */
    agentId?: string;
    jobId: string;
    prompt: string;
    tags: Record<string, string>;
    createdAt: Date;
    /** Integration ID for query-with-AI operations (nullable, used when not invoked via agent) */
    integrationId?: string;
}
export type AgentAuditLogUpdateType = 'statusUpdate' | 'response';
/** Usage metric for AI model input/output — either token count or character count depending on provider. */
export interface AiUsageMetric {
    unit: 'tokens' | 'characters';
    value: number;
}
/** Agent audit log update entry - status updates and responses for agent invocations */
export interface AgentAuditLogUpdateEvent {
    appId: AppId;
    /** Agent ID (nullable for query-with-AI operations without an agent) */
    agentId?: string;
    jobId: string;
    statusUpdateId: string;
    title: string;
    parentStatusUpdateId?: string;
    tags: Record<string, string>;
    body: string;
    type: AgentAuditLogUpdateType;
    createdAt: Date;
    /** Integration ID for query-with-AI operations (nullable, used when not invoked via agent) */
    integrationId?: string;
    /** Input usage metric (tokens or characters depending on provider). */
    inputUsage?: AiUsageMetric;
    /** Output usage metric (tokens or characters depending on provider). */
    outputUsage?: AiUsageMetric;
    /** Reasoning tokens consumed (where the provider reports them separately from output tokens). */
    reasoningTokens?: number;
    /** Number of input tokens served from the provider's prompt cache (read hits). */
    cacheReadInputTokens?: number;
    /** Number of input tokens written into the provider's prompt cache (cache misses that created new entries). */
    cacheWriteInputTokens?: number;
}
/** Tag for metric events. Value: '0' - not an error, '1' - is an error. */
export declare const O11Y_TAG_IS_ERROR = "isError";
/** Tag for log events. Metrics have an explicit appId field. */
export declare const O11Y_TAG_APP_ID = "appId";
/** Tag for metric and log events. */
export declare const O11Y_TAG_INTEGRATION_ID = "integrationId";
/** Tag for AI events. */
export declare const O11Y_TAG_AI_MODEL = "aiModel";
export declare const O11Y_TAG_AI_PROFILE = "aiProfile";
/** Tag for AI KnowledgeBase events */
export declare const O11Y_TAG_AI_KNOWLEDGE_BASE_MODEL = "aiKnowledgeBaseModel";
export declare const O11Y_TAG_API_KEY_SOURCE = "apiKeySource";
export declare const O11Y_TAG_AI_JOB_ID = "aiJobId";
/** Tag prefix for client-provided metric annotations (see BaseAiChatOptions.metricAnnotations). */
export declare const O11Y_TAG_METRIC_ANNOTATION_PREFIX = "annotation.";
/** Maximum number of AI usage annotation entries kept per call; extra entries are dropped. */
export declare const MAX_METRIC_ANNOTATIONS = 10;
/** Maximum length of an AI usage annotation key; longer keys are dropped. */
export declare const MAX_METRIC_ANNOTATION_KEY_LENGTH = 64;
/** Maximum length of an AI usage annotation value; longer values are truncated. */
export declare const MAX_METRIC_ANNOTATION_VALUE_LENGTH = 256;
/**
 * Sanitizes client-provided metric annotations: caps the number of entries, drops empty or
 * oversized keys, and truncates oversized values. Returns undefined when nothing valid remains.
 */
export declare function sanitizeMetricAnnotations(annotations: Record<string, string> | undefined): Record<string, string> | undefined;
/** Tag for metric and log events. Value: '0' - not a tenant originated, '1' - is a tenant originated. */
export declare const O11Y_TAG_IS_TENANT_ORIGINATED = "isTenantOriginated";
/** Contains a full (with a service name) function name for backend functions. */
export declare const O11Y_TAG_FUNCTION_NAME = "functionName";
/** Contains a type of the function name for backend functions (See ExecuteFunctionAnnotationType.). */
export declare const O11Y_TAG_FUNCTION_TYPE = "functionType";
/** Tag for the trace ID. Used in logs. */
export declare const O11Y_TAG_TRACE_ID = "trace_id";
/** Tag for the span ID. Used in logs. */
export declare const O11Y_TAG_SPAN_ID = "span_id";
/**
 * Tag carrying Squid's own correlation id (the `n_`/`c_`/`k_` short id minted by
 * `generateTraceId`). Distinct from `trace_id`/`span_id`, which hold the W3C ids from OTel.
 * Rides W3C baggage under the same key on internal hops; attached to spans and logs.
 */
export declare const O11Y_TAG_SQUID_TRACE_ID = "squid_tid";
export declare function getBooleanMetricTagValue(value: boolean): string;
export declare const COUNT_METRIC_SUFFIXES: string[];
export declare const GAUGE_METRIC_SUFFIXES: string[];