@oneuptime/common 11.7.3 → 12.0.0

package/Types/Runbook/RunbookExecutionDeadline.ts

@@ -0,0 +1,129 @@
+/*
+ * When a runbook execution stops being anybody's responsibility.
+ *
+ * An execution runs inside a single queue job on one Worker. If that Worker
+ * dies mid-step and the job is never redelivered — Redis lost it, the stall
+ * budget ran out, the handler threw somewhere unrecoverable — the row stays
+ * Running with nobody advancing it. Nothing else in the system would ever
+ * change it, so the reconciler needs a defensible answer to "has this been
+ * abandoned?".
+ *
+ * The answer is derived from the step that is currently Running: it cannot
+ * legitimately outlive the claim + execution window its author configured, so
+ * anything past that window plus a grace margin is abandoned. Deriving it per
+ * execution (rather than picking one global timeout) matters now that a step
+ * may be configured for anything from one second to one hour — a single
+ * threshold would either kill live hour-long restores or leave a one-second
+ * step hanging for an hour.
+ */
+
+import {
+  BashStepConfig,
+  HttpRequestStepConfig,
+  JavaScriptStepConfig,
+  RunbookStep,
+} from "./RunbookStep";
+import { RunbookStepExecutionState } from "./RunbookStepExecution";
+import RunbookStepExecutionStatus from "./RunbookStepExecutionStatus";
+import RunbookStepType from "./RunbookStepType";
+import {
+  MAX_STEP_EXECUTION_TIMEOUT_IN_MS,
+  resolveAgentClaimTimeoutInMs,
+  resolveStepExecutionTimeoutInMs,
+} from "./RunbookStepTimeout";
+
+/*
+ * Margin on top of a step's own window before the execution is declared
+ * abandoned. The Worker running the step gives up at claim + execution + 5s
+ * and then writes the failure itself, so this only has to outlast that write —
+ * five minutes leaves room for a slow database or a Worker that is briefly
+ * paused, and keeps the reconciler from racing a run that is still healthy.
+ */
+export const STUCK_EXECUTION_GRACE_IN_MS: number = 5 * 60 * 1000;
+
+/*
+ * Allowance for a step type whose runtime the author cannot bound — today
+ * that is the AI step, which runs as long as the model provider takes. The
+ * longest configurable step window is the least surprising ceiling to borrow.
+ */
+export const UNBOUNDED_STEP_ALLOWANCE_IN_MS: number =
+  MAX_STEP_EXECUTION_TIMEOUT_IN_MS;
+
+/*
+ * The longest a single step can legitimately occupy its Worker. Agent steps
+ * spend the claim window waiting for an agent to pick the job up and the
+ * execution window actually running, so they get both.
+ */
+export function getStepMaxRuntimeInMs(step: RunbookStep): number {
+  switch (step.type) {
+    case RunbookStepType.Bash:
+    case RunbookStepType.JavaScript: {
+      const config: BashStepConfig | JavaScriptStepConfig = step.config as
+        | BashStepConfig
+        | JavaScriptStepConfig;
+      return (
+        resolveAgentClaimTimeoutInMs(config.claimTimeoutInMs) +
+        resolveStepExecutionTimeoutInMs(config.timeoutInMs)
+      );
+    }
+
+    case RunbookStepType.HttpRequest: {
+      const config: HttpRequestStepConfig =
+        step.config as HttpRequestStepConfig;
+      return resolveStepExecutionTimeoutInMs(config.timeoutInMs);
+    }
+
+    /*
+     * Manual steps park the execution as WaitingForManualStep rather than
+     * Running, so one found Running is a torn write, not a wait. It gets no
+     * allowance — the grace margin alone decides.
+     */
+    case RunbookStepType.Manual:
+      return 0;
+
+    default:
+      return UNBOUNDED_STEP_ALLOWANCE_IN_MS;
+  }
+}
+
+/*
+ * Deadline for an execution currently in the Running state.
+ *
+ * Anchored on the running step's own startedAt where possible. Two fallbacks
+ * use the execution's updatedAt instead:
+ *
+ *  - A step is Running but carries no usable startedAt. The state machine
+ *    stamps startedAt and persists in the same write, so updatedAt is the same
+ *    instant; the step still gets its full allowance.
+ *  - No step is Running at all. The Worker died between steps, so nothing is
+ *    executing and no allowance is owed — only the grace margin.
+ */
+export function getRunningExecutionDeadline(data: {
+  stepExecutions: Array<RunbookStepExecutionState>;
+  executionUpdatedAt: Date;
+}): Date {
+  const runningStep: RunbookStepExecutionState | undefined =
+    data.stepExecutions.find((stepExecution: RunbookStepExecutionState) => {
+      return stepExecution.status === RunbookStepExecutionStatus.Running;
+    });
+
+  if (!runningStep) {
+    return new Date(
+      data.executionUpdatedAt.getTime() + STUCK_EXECUTION_GRACE_IN_MS,
+    );
+  }
+
+  const startedAtMs: number = runningStep.startedAt
+    ? new Date(runningStep.startedAt).getTime()
+    : NaN;
+
+  const anchorMs: number = isFinite(startedAtMs)
+    ? startedAtMs
+    : data.executionUpdatedAt.getTime();
+
+  return new Date(
+    anchorMs +
+      getStepMaxRuntimeInMs(runningStep.step) +
+      STUCK_EXECUTION_GRACE_IN_MS,
+  );
+}

package/Types/Runbook/RunbookStep.ts

@@ -74,12 +74,77 @@ export interface AIStepConfig {
   maxTokens?: number;
 }
 
+/*
+ * Run a command on a host the Runner can reach over SSH.
+ *
+ * The point of a first-class step type — rather than "write `ssh host cmd` in
+ * a Bash step" — is that the credential is a managed, encrypted object with
+ * its own permissions instead of a private key sitting on the Runner's disk,
+ * and the command is a value we can validate rather than an opaque script.
+ */
+export interface SSHStepConfig {
+  /*
+   * ID of the RunbookCredential (type SSH) holding the host, user and key.
+   * The Runner resolves it at claim time; it is never stored on the step.
+   */
+  credentialId: string;
+  // The command to run on the remote host, verbatim.
+  command: string;
+  timeoutInMs?: number;
+  // ID of the Runner that opens the connection. Only it may claim the job.
+  agentId: string;
+  claimTimeoutInMs?: number;
+}
+
+/*
+ * The workload actions that cover almost every "turn it off and on again"
+ * remediation. Deliberately a closed set of verbs rather than free-form
+ * manifests: a runbook that can PATCH arbitrary Kubernetes objects is a
+ * cluster-admin shell, and the whole reason this exists is to make the common
+ * remediations safe rather than to add another way to run anything.
+ */
+export enum KubernetesAction {
+  // Rolling restart: stamps the pod template so the controller recreates pods.
+  RestartWorkload = "RestartWorkload",
+  // Set replica count — scale out under load, or to zero and back.
+  ScaleWorkload = "ScaleWorkload",
+}
+
+export enum KubernetesWorkloadKind {
+  Deployment = "Deployment",
+  StatefulSet = "StatefulSet",
+  DaemonSet = "DaemonSet",
+}
+
+export interface KubernetesStepConfig {
+  /*
+   * ID of the RunbookCredential (type Kubernetes) holding the API server URL,
+   * the service-account token and the CA certificate.
+   */
+  credentialId: string;
+  action: KubernetesAction;
+  workloadKind: KubernetesWorkloadKind;
+  namespace: string;
+  workloadName: string;
+  /*
+   * Target replica count. Required for ScaleWorkload and ignored otherwise.
+   * Zero is legitimate — draining a workload is a remediation.
+   */
+  replicas?: number;
+  timeoutInMs?: number;
+  // ID of the Runner that talks to the API server. Only it may claim the job.
+  agentId: string;
+  claimTimeoutInMs?: number;
+}
+
 export type RunbookStepConfig =
   | ManualStepConfig
   | JavaScriptStepConfig
   | HttpRequestStepConfig
   | BashStepConfig
-  | AIStepConfig;
+  | AIStepConfig
+  | SSHStepConfig
+  | KubernetesStepConfig;
 
 export interface RunbookStep {
   id: string;

package/Types/Runbook/RunbookStepTimeout.ts

@@ -0,0 +1,202 @@
+/*
+ * Timeouts are configured per step and stored on the step config in
+ * milliseconds. Both the dashboard (which edits them) and the Worker (which
+ * enforces them) resolve values through this module so a step never runs with
+ * a bound the author could not see, and never with one that would pin a
+ * Worker slot open indefinitely.
+ */
+
+// How long the step itself may run before it is killed.
+export const DEFAULT_STEP_EXECUTION_TIMEOUT_IN_MS: number = 30 * 1000;
+export const MIN_STEP_EXECUTION_TIMEOUT_IN_MS: number = 1000;
+export const MAX_STEP_EXECUTION_TIMEOUT_IN_MS: number = 60 * 60 * 1000;
+
+/*
+ * How long the Worker waits for the selected agent to claim the job. Only
+ * meaningful for Bash and JavaScript steps, which never run on the Worker.
+ */
+export const DEFAULT_AGENT_CLAIM_TIMEOUT_IN_MS: number = 2 * 60 * 1000;
+export const MIN_AGENT_CLAIM_TIMEOUT_IN_MS: number = 1000;
+export const MAX_AGENT_CLAIM_TIMEOUT_IN_MS: number = 60 * 60 * 1000;
+
+export interface TimeoutBounds {
+  defaultInMs: number;
+  minInMs: number;
+  maxInMs: number;
+}
+
+export const STEP_EXECUTION_TIMEOUT_BOUNDS: TimeoutBounds = {
+  defaultInMs: DEFAULT_STEP_EXECUTION_TIMEOUT_IN_MS,
+  minInMs: MIN_STEP_EXECUTION_TIMEOUT_IN_MS,
+  maxInMs: MAX_STEP_EXECUTION_TIMEOUT_IN_MS,
+};
+
+export const AGENT_CLAIM_TIMEOUT_BOUNDS: TimeoutBounds = {
+  defaultInMs: DEFAULT_AGENT_CLAIM_TIMEOUT_IN_MS,
+  minInMs: MIN_AGENT_CLAIM_TIMEOUT_IN_MS,
+  maxInMs: MAX_AGENT_CLAIM_TIMEOUT_IN_MS,
+};
+
+/*
+ * Resolve a configured timeout to the value execution should actually use.
+ *
+ * Anything unusable — unset, blank, non-numeric, zero or negative — falls back
+ * to the default rather than failing the step, because a runbook that runs
+ * with the documented default is more useful during an incident than one that
+ * refuses to run at all. Usable values are rounded to whole milliseconds and
+ * clamped into range.
+ */
+export function resolveTimeoutInMs(
+  value: number | string | null | undefined,
+  bounds: TimeoutBounds,
+): number {
+  if (value === null || value === undefined || value === "") {
+    return bounds.defaultInMs;
+  }
+
+  const parsed: number = typeof value === "number" ? value : Number(value);
+
+  if (!isFinite(parsed) || parsed <= 0) {
+    return bounds.defaultInMs;
+  }
+
+  return Math.min(Math.max(Math.round(parsed), bounds.minInMs), bounds.maxInMs);
+}
+
+export function resolveStepExecutionTimeoutInMs(
+  value: number | string | null | undefined,
+): number {
+  return resolveTimeoutInMs(value, STEP_EXECUTION_TIMEOUT_BOUNDS);
+}
+
+export function resolveAgentClaimTimeoutInMs(
+  value: number | string | null | undefined,
+): number {
+  return resolveTimeoutInMs(value, AGENT_CLAIM_TIMEOUT_BOUNDS);
+}
+
+/*
+ * Milliseconds are the storage unit; seconds are what people think in. The
+ * two helpers below bridge the step editor's seconds input and the stored
+ * value. An empty input means "unset" — the step then uses the default — so
+ * it round-trips to undefined rather than to zero.
+ */
+export function timeoutInMsToSecondsInputValue(
+  value: number | null | undefined,
+): string {
+  if (value === null || value === undefined || !isFinite(Number(value))) {
+    return "";
+  }
+
+  const seconds: number = Number(value) / 1000;
+
+  if (seconds <= 0) {
+    return "";
+  }
+
+  // Sub-second values would render as "0" and read as "no timeout"; keep the decimal.
+  return String(Math.round(seconds * 1000) / 1000);
+}
+
+export function secondsInputValueToTimeoutInMs(
+  value: string,
+): number | undefined {
+  const trimmed: string = (value || "").trim();
+
+  if (!trimmed) {
+    return undefined;
+  }
+
+  const seconds: number = Number(trimmed);
+
+  if (!isFinite(seconds) || seconds <= 0) {
+    return undefined;
+  }
+
+  const inMs: number = Math.round(seconds * 1000);
+
+  /*
+   * Sub-half-millisecond input rounds to zero. Zero is not a timeout, so it
+   * reports as unset like any other unusable value — storing a literal 0 would
+   * put a number in the step config that means nothing.
+   */
+  if (inMs <= 0) {
+    return undefined;
+  }
+
+  return inMs;
+}
+
+/*
+ * Shown when the field holds something that is not a number at all. Lives here
+ * rather than in the editor so the message the browser's own parse failure
+ * produces is the same one this validator produces.
+ */
+export const NON_NUMERIC_TIMEOUT_MESSAGE: string = "Enter a number of seconds.";
+
+/*
+ * Validation message for the step editor. Returns null when the input is
+ * acceptable — including when it is blank, which simply means "use the
+ * default". Out-of-range values are still saved and then clamped at run time;
+ * the message is what tells the author that will happen.
+ */
+export function getTimeoutValidationError(
+  value: string,
+  bounds: TimeoutBounds,
+): string | null {
+  const trimmed: string = (value || "").trim();
+
+  if (!trimmed) {
+    return null;
+  }
+
+  const seconds: number = Number(trimmed);
+
+  if (!isFinite(seconds)) {
+    return NON_NUMERIC_TIMEOUT_MESSAGE;
+  }
+
+  const inMs: number = Math.round(seconds * 1000);
+
+  /*
+   * Zero, negatives, and anything that rounds down to zero milliseconds are
+   * not timeouts. They fall back to the default rather than being clamped up,
+   * so they get the same message.
+   */
+  if (seconds <= 0 || inMs <= 0) {
+    return "Timeout must be greater than 0 seconds.";
+  }
+
+  if (inMs < bounds.minInMs) {
+    return `Minimum is ${bounds.minInMs / 1000} second${
+      bounds.minInMs === 1000 ? "" : "s"
+    }.`;
+  }
+
+  if (inMs > bounds.maxInMs) {
+    return `Maximum is ${bounds.maxInMs / 1000} seconds (${
+      bounds.maxInMs / 60000
+    } minutes).`;
+  }
+
+  return null;
+}
+
+/*
+ * True when the input is a usable number that sits outside the bounds — the
+ * only case where run time will clamp it. Unusable input (blank, zero, junk)
+ * falls back to the default instead, which is the opposite end of the range,
+ * so the editor must not promise clamping there.
+ */
+export function willTimeoutBeClamped(
+  value: string,
+  bounds: TimeoutBounds,
+): boolean {
+  const inMs: number | undefined = secondsInputValueToTimeoutInMs(value);
+
+  if (inMs === undefined) {
+    return false;
+  }
+
+  return inMs < bounds.minInMs || inMs > bounds.maxInMs;
+}

package/Types/Runbook/RunbookStepType.ts

@@ -4,6 +4,32 @@ enum RunbookStepType {
   HttpRequest = "HttpRequest",
   Bash = "Bash",
   AI = "AI",
+  SSH = "SSH",
+  Kubernetes = "Kubernetes",
 }
 
 export default RunbookStepType;
+
+/*
+ * Step types that execute on a Runner rather than on the OneUptime Worker,
+ * because they act on the customer's own infrastructure. Everything listed
+ * here carries an agentId on its config and goes through the RunnerJob
+ * claim path.
+ *
+ * This list is the ENFORCEMENT point — RunnerJobService refuses to
+ * enqueue a job for any type not in it, so a Runner can never be handed work
+ * it has no executor for. The Worker's own dispatch is a per-type switch
+ * rather than a list check (each type needs different arguments), so adding a
+ * type here without adding it there means the step fails with "unknown step
+ * type" rather than being silently mis-run.
+ */
+export const RUNNER_EXECUTED_STEP_TYPES: Array<RunbookStepType> = [
+  RunbookStepType.JavaScript,
+  RunbookStepType.Bash,
+  RunbookStepType.SSH,
+  RunbookStepType.Kubernetes,
+];
+
+export function isRunnerExecutedStepType(type: RunbookStepType): boolean {
+  return RUNNER_EXECUTED_STEP_TYPES.includes(type);
+}

package/Types/Runbook/RunnerJobOrigin.ts

@@ -0,0 +1,20 @@
+/*
+ * Where a RunnerJob came from — the discriminator that decides which Runner
+ * capability gates its claim.
+ *
+ * Runbook:       a step of a runbook execution (the original job source).
+ *                Claimable only by Runners with canRunRunbooks.
+ * AiRemediation: an ad-hoc command composed by an AI remediation run (either
+ *                auto-executed under an operator allowlist or human-approved
+ *                as part of a command plan). Claimable only by Runners with
+ *                canRunAiCommands.
+ *
+ * Rows created before this enum existed were backfilled to Runbook by the
+ * AddAiCommandRemediation migration, so the column is NOT NULL.
+ */
+enum RunnerJobOrigin {
+  Runbook = "Runbook",
+  AiRemediation = "AiRemediation",
+}
+
+export default RunnerJobOrigin;

package/Types/Runbook/{RunbookAgentJobStatus.ts → RunnerJobStatus.ts}

@@ -1,4 +1,4 @@
-enum RunbookAgentJobStatus {
+enum RunnerJobStatus {
   // Inserted by the Worker. No agent has claimed it yet.
   Pending = "Pending",
   // An agent has atomically claimed the job and is preparing to execute it.
@@ -18,4 +18,4 @@ enum RunbookAgentJobStatus {
   Cancelled = "Cancelled",
 }
 
-export default RunbookAgentJobStatus;
+export default RunnerJobStatus;

package/Types/StatusPage/StatusPageReport.ts

@@ -0,0 +1,99 @@
+/*
+ * The shape of the scheduled "Uptime Report" email for a status page.
+ *
+ * A status page organises its resources into a tree of groups (Corporate Unit ->
+ * Region -> Market -> Unit), and every level of that tree shows a rolled up
+ * availability on the live page. Recipients of this email frequently have no
+ * login, so the report has to carry the same hierarchy - a flat list of monitor
+ * names says nothing about which region or unit a monitor belongs to.
+ *
+ * Three views of the same numbers are exposed, because the built-in email
+ * template and customer authored templates need different things:
+ *
+ *   - `resources`  - every resource, flat. The original shape, kept so templates
+ *                    written before groups existed keep rendering. Each row now
+ *                    also carries the group it belongs to.
+ *   - `groups`     - the nested tree, for templates that can recurse.
+ *   - `rows`       - the tree flattened into render order with a `depth` on each
+ *                    row. Email HTML cannot recurse comfortably, so the built-in
+ *                    template walks this.
+ */
+
+export interface StatusPageReportItem {
+  resourceName: string;
+  totalIncidentCount: number;
+  uptimePercent: number;
+  uptimePercentAsString: string;
+  downtimeInHoursAndMinutes: string;
+  /*
+   * The group this resource is attached to directly. Empty string when the
+   * resource is not in any group (it renders above the groups on the live page).
+   */
+  groupName: string;
+  /*
+   * Every group from the top of the tree down to this resource's own group,
+   * joined with " / " - e.g. "Region 001 / Market 001 / Unit 0660". Empty string
+   * when the resource is not in any group.
+   */
+  groupPath: string;
+}
+
+/*
+ * Numbers rolled up over a group and everything nested under it - the same set
+ * of resources the live status page rolls a group's uptime over.
+ */
+export interface StatusPageReportGroupMetrics {
+  uptimePercent: number;
+  uptimePercentAsString: string;
+  downtimeInHoursAndMinutes: string;
+  totalIncidentCount: number;
+}
+
+export interface StatusPageReportGroup extends StatusPageReportGroupMetrics {
+  groupName: string;
+  // Ancestors and this group joined with " / ".
+  groupPath: string;
+  // 0 for a top level group, 1 for its children, and so on.
+  depth: number;
+  // Resources in this group AND in every group nested under it.
+  totalResources: number;
+  // Resources attached to this group directly, in status page order.
+  resources: Array<StatusPageReportItem>;
+  subGroups: Array<StatusPageReportGroup>;
+}
+
+/*
+ * One line of the report, in the order the live status page renders it:
+ * ungrouped resources first, then each group followed by its own resources and
+ * then its sub groups.
+ */
+export interface StatusPageReportRow {
+  isGroup: boolean;
+  name: string;
+  depth: number;
+  // Precomputed so an email template does not have to do arithmetic in Handlebars.
+  indentInPixels: number;
+  uptimePercentAsString: string;
+  downtimeInHoursAndMinutes: string;
+  totalIncidentCount: number;
+  /*
+   * Only meaningful on a group row: how many resources the group rolls up.
+   * Always 0 on a resource row.
+   */
+  totalResources: number;
+}
+
+export interface StatusPageReport {
+  reportDates: string; // start date and end date in string. e.g. "01 July 2021 - 14 July 2021"
+  totalResources: number;
+  totalIncidents: number;
+  averageUptimePercent: string;
+  totalDowntimeInHoursAndMinutes: string;
+  resources: Array<StatusPageReportItem>;
+  groups: Array<StatusPageReportGroup>;
+  // Resources that are not in any group, in status page order.
+  ungroupedResources: Array<StatusPageReportItem>;
+  rows: Array<StatusPageReportRow>;
+  // Whether this status page organises its resources into groups at all.
+  hasGroups: boolean;
+}

package/Types/Telemetry/DropFilterSampling.ts

@@ -0,0 +1,92 @@
+/*
+ * Sampling decision shared by the log and trace drop-filter engines.
+ *
+ * This used to be `filter.samplePercentage || 50` duplicated in two
+ * services, which had three separate problems:
+ *
+ *   1. `samplePercentage` is nullable with no default and the form field
+ *      was optional, so an UNSET percentage silently became "throw away
+ *      half of every matching record" — while the view page rendered the
+ *      same unset value as "0% kept".
+ *   2. A stored `0` was indistinguishable from unset, so it also kept 50%.
+ *   3. The two copies could drift.
+ *
+ * The fix is to fail SAFE: a percentage we cannot honour makes the filter a
+ * no-op rather than a data shredder. Callers that want "discard everything
+ * matching" have an explicit `drop` action for that.
+ *
+ * Note on the `0` case specifically. A literal reading of `0` is "keep 0%",
+ * i.e. drop every matching record — but `0` NEVER meant that in any shipped
+ * version (it kept half), so honouring it now would start deleting data
+ * that used to survive. Treating it as misconfigured is strictly less
+ * destructive than both the old behaviour and the literal reading, and
+ * save-time validation (Common/Server/Utils/DropFilterValidation.ts) stops
+ * new rows from getting there at all.
+ */
+
+// Keep everything: the fail-safe value for a percentage we can't honour.
+export const KEEP_ALL_PERCENTAGE: number = 100;
+
+/*
+ * The range a human is allowed to save. Enforced at the API boundary by
+ * Common/Server/Utils/DropFilterValidation.ts and mirrored in the dashboard
+ * form; kept here so the validator, the form and the engine cannot drift
+ * apart on what counts as a usable percentage.
+ */
+export const MIN_SAMPLE_PERCENTAGE: number = 1;
+export const MAX_SAMPLE_PERCENTAGE: number = 99;
+
+/*
+ * Whether a stored value is one the engine will actually sample on. The
+ * dashboard uses this to render "not configured" instead of the "0% kept"
+ * it used to show for an unset percentage — a display that directly
+ * contradicted the engine's old behaviour of keeping half.
+ */
+export function isSamplePercentageConfigured(
+  samplePercentage: number | undefined | null,
+): boolean {
+  return resolveSamplePercentage(samplePercentage) < KEEP_ALL_PERCENTAGE;
+}
+
+/*
+ * Normalize a stored `samplePercentage` into a percentage-to-KEEP.
+ *
+ * Anything that is not a finite number in the exclusive range (0, 100) is
+ * misconfigured and resolves to "keep everything".
+ */
+export function resolveSamplePercentage(
+  samplePercentage: number | undefined | null,
+): number {
+  if (
+    typeof samplePercentage !== "number" ||
+    !Number.isFinite(samplePercentage)
+  ) {
+    return KEEP_ALL_PERCENTAGE;
+  }
+
+  if (samplePercentage <= 0 || samplePercentage >= KEEP_ALL_PERCENTAGE) {
+    return KEEP_ALL_PERCENTAGE;
+  }
+
+  return samplePercentage;
+}
+
+/*
+ * True when a sample-action filter should discard this record.
+ *
+ * `random` is injectable so the decision is testable without stubbing
+ * global Math.random. It is only consulted when the percentage actually
+ * calls for sampling, so a keep-everything filter costs no entropy.
+ */
+export function shouldDropBySampling(
+  samplePercentage: number | undefined | null,
+  random: () => number = Math.random,
+): boolean {
+  const keepPercentage: number = resolveSamplePercentage(samplePercentage);
+
+  if (keepPercentage >= KEEP_ALL_PERCENTAGE) {
+    return false;
+  }
+
+  return random() * 100 >= keepPercentage;
+}

package/Types/Telemetry/TelemetryRetentionConfig.ts

@@ -29,9 +29,26 @@ export default interface TelemetryRetentionConfig {
   profiles?: {
     default?: number | null;
   };
+  /*
+   * Session replay does NOT go through resolveTelemetryRetentionInDays
+   * below. That function puts service.retainTelemetryDataForDays above the
+   * project pillar default, so an application configured for 90-day trace
+   * retention would silently inherit 90-day replay retention, and an
+   * unconfigured one would get 15 days rather than replay's 7. Replay is
+   * resolved by Common/Server/Utils/SessionReplay/SessionReplayRetention.ts,
+   * which reads only this pillar and then clamps to the allowed set.
+   */
+  sessionReplay?: {
+    default?: number | null;
+  };
 }
 
-export type TelemetryPillar = "logs" | "traces" | "metrics" | "profiles";
+export type TelemetryPillar =
+  | "logs"
+  | "traces"
+  | "metrics"
+  | "profiles"
+  | "sessionReplay";
 
 export const HARDCODED_DEFAULT_TELEMETRY_RETENTION_IN_DAYS: number = 15;