import * as amp from "@distilled.cloud/aws/amp";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, hasAlchemyTags } from "alchemy/Tags";
import { toWireSeconds } from "alchemy/Util/Duration";
import type * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as Option from "effect/Option";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";
import { syncAmpTags, toTagRecord } from "./internal.ts";
/**
* Tolerance band around the expected value inside which deviations are not
* flagged — either an absolute `amount` or a `ratio` of the expected value.
*/
export type AnomalyDetectorIgnoreNearExpected = { amount: number } | { ratio: number };
/** What the detector does with evaluation windows that have no data. */
export type AnomalyDetectorMissingDataAction = { markAsAnomaly: boolean } | { skip: boolean };
export interface AnomalyDetectorProps {
/**
* Id of the AMP workspace the detector runs in. Changing the workspace
* replaces the detector.
*/
workspaceId: string;
/**
* Human-readable alias for the detector, unique within the workspace.
* Changing the alias replaces the detector.
*/
alias: string;
/**
* The PromQL query producing the time series the Random Cut Forest
* algorithm scores for anomalies. Updating it retrains the detector.
*/
query: string;
/**
* Number of consecutive data points combined into one sample (shingle)
* for scoring. If omitted, the service default is used.
*/
shingleSize?: number;
/**
* Number of points sampled per Random Cut Forest tree. If omitted, the
* service default is used.
*/
sampleSize?: number;
/**
* Suppress anomalies above the expected value that fall within this
* tolerance band.
*/
ignoreNearExpectedFromAbove?: AnomalyDetectorIgnoreNearExpected;
/**
* Suppress anomalies below the expected value that fall within this
* tolerance band.
*/
ignoreNearExpectedFromBelow?: AnomalyDetectorIgnoreNearExpected;
/**
* How often the detector evaluates the query. Accepts any
* `Duration.Input` (e.g. `"1 minute"`, `Duration.minutes(1)`; a bare
* number is milliseconds); the wire unit is whole seconds
* (`evaluationIntervalInSeconds`). If omitted, the service default is
* used.
*/
evaluationInterval?: Duration.Input;
/**
* What to do when an evaluation window has no data: mark it as an
* anomaly (`{ markAsAnomaly: true }`) or skip it (`{ skip: true }`).
*/
missingDataAction?: AnomalyDetectorMissingDataAction;
/**
* Extra labels attached to the anomaly metrics the detector emits.
*/
labels?: Record<string, string>;
/**
* User-defined tags for the detector.
*/
tags?: Record<string, string>;
}
export interface AnomalyDetector extends Resource<
"AWS.AMP.AnomalyDetector",
AnomalyDetectorProps,
{
workspaceId: string;
anomalyDetectorId: string;
anomalyDetectorArn: string;
alias: string;
status: string;
},
never,
Providers
> {}
/**
* A Random Cut Forest anomaly detector inside an Amazon Managed Service for
* Prometheus workspace — continuously evaluates a PromQL query and emits
* anomaly scores as new metrics in the same workspace.
*
* ### Creating an Anomaly Detector
* **Example:** Detect Anomalies on a Request-Rate Query
* ```typescript
* const workspace = yield* AMP.Workspace("Metrics", {});
* const detector = yield* AMP.AnomalyDetector("RequestSpikes", {
* workspaceId: workspace.workspaceId,
* alias: "request-spikes",
* query: 'rate(http_requests_total{job="api"}[5m])',
* evaluationInterval: "1 minute",
* missingDataAction: { skip: true },
* });
* ```
*
* @resource
*/
export const AnomalyDetector = Resource<AnomalyDetector>("AWS.AMP.AnomalyDetector");
export const AnomalyDetectorProvider = () =>
Provider.effect(
AnomalyDetector,
Effect.gen(function* () {
const toAttrs = (workspaceId: string, detector: amp.AnomalyDetectorDescription) => ({
workspaceId,
anomalyDetectorId: detector.anomalyDetectorId,
anomalyDetectorArn: detector.arn,
alias: detector.alias,
status: detector.status.statusCode,
});
/** Describe a detector by id; typed not-found → undefined. */
const describe = Effect.fn(function* (workspaceId: string, anomalyDetectorId: string) {
const response = yield* amp
.describeAnomalyDetector({ workspaceId, anomalyDetectorId })
.pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
return response?.anomalyDetector;
});
/**
* Find a detector by its alias (the deterministic identity within a
* workspace) — used when no id is cached in `output`.
*/
const findByAlias = Effect.fn(function* (workspaceId: string, alias: string) {
const summary = yield* amp.listAnomalyDetectors.items({ workspaceId, alias }).pipe(
Stream.filter((s) => s.alias === alias),
Stream.runHead,
Effect.map(Option.getOrUndefined),
Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
);
return summary === undefined
? undefined
: yield* describe(workspaceId, summary.anomalyDetectorId);
});
/**
* Bounded best-effort wait toward ACTIVE. Training/backfill can
* outlast the window; the last observed description is returned and
* a still-training detector converges on a later reconcile.
*/
const waitSettled = Effect.fn(function* (workspaceId: string, anomalyDetectorId: string) {
return yield* amp.describeAnomalyDetector({ workspaceId, anomalyDetectorId }).pipe(
Effect.map((r) => r.anomalyDetector),
Effect.repeat({
schedule: Schedule.max([Schedule.fixed("3 seconds"), Schedule.recurs(20)]),
until: (d): boolean =>
d.status.statusCode !== "CREATING" && d.status.statusCode !== "UPDATING",
}),
);
});
const canonical = (value: unknown) =>
JSON.stringify(value, (_, v: unknown) =>
v !== null && typeof v === "object" && !Array.isArray(v)
? Object.fromEntries(
Object.entries(v as Record<string, unknown>).sort(([a], [b]) => a.localeCompare(b)),
)
: v,
);
/**
* Detect drift between desired props and the observed detector.
* Only user-specified fields participate — omitted optional fields
* defer to service defaults and never force a (full-retrain) put.
*/
const configDrifts = (
news: AnomalyDetectorProps,
observed: amp.AnomalyDetectorDescription,
): boolean => {
const rcf = observed.configuration?.randomCutForest;
const drift =
news.query !== rcf?.query ||
(news.shingleSize !== undefined && news.shingleSize !== rcf?.shingleSize) ||
(news.sampleSize !== undefined && news.sampleSize !== rcf?.sampleSize) ||
(news.ignoreNearExpectedFromAbove !== undefined &&
canonical(news.ignoreNearExpectedFromAbove) !==
canonical(rcf?.ignoreNearExpectedFromAbove)) ||
(news.ignoreNearExpectedFromBelow !== undefined &&
canonical(news.ignoreNearExpectedFromBelow) !==
canonical(rcf?.ignoreNearExpectedFromBelow)) ||
(news.evaluationInterval !== undefined &&
toWireSeconds(news.evaluationInterval) !== observed.evaluationIntervalInSeconds) ||
(news.missingDataAction !== undefined &&
canonical(news.missingDataAction) !== canonical(observed.missingDataAction)) ||
(news.labels !== undefined &&
canonical(news.labels) !== canonical(toTagRecord(observed.labels)));
return drift;
};
const toConfiguration = (news: AnomalyDetectorProps) => ({
randomCutForest: {
query: news.query,
shingleSize: news.shingleSize,
sampleSize: news.sampleSize,
ignoreNearExpectedFromAbove: news.ignoreNearExpectedFromAbove,
ignoreNearExpectedFromBelow: news.ignoreNearExpectedFromBelow,
},
});
return {
stables: ["workspaceId", "anomalyDetectorId", "anomalyDetectorArn", "alias"],
diff: Effect.fn(function* ({ olds, news }) {
if (!isResolved(news)) return undefined;
if (olds?.workspaceId !== news.workspaceId || olds?.alias !== news.alias) {
return { action: "replace" } as const;
}
}),
read: Effect.fn(function* ({ id, olds, output }) {
const workspaceId = output?.workspaceId ?? olds?.workspaceId;
if (!workspaceId) return undefined;
const detector =
output?.anomalyDetectorId !== undefined
? yield* describe(workspaceId, output.anomalyDetectorId)
: olds?.alias !== undefined
? yield* findByAlias(workspaceId, olds.alias)
: undefined;
if (detector === undefined) return undefined;
const attrs = toAttrs(workspaceId, detector);
const tags = toTagRecord(detector.tags);
return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
}),
reconcile: Effect.fn(function* ({ id, news, output, session }) {
const workspaceId = news!.workspaceId;
const internalTags = yield* createInternalTags(id);
const desiredTags = { ...internalTags, ...news!.tags };
// 1. Observe — by cached id, falling back to the alias.
let detector =
output?.anomalyDetectorId !== undefined
? yield* describe(workspaceId, output.anomalyDetectorId)
: yield* findByAlias(workspaceId, news!.alias);
// 2. Ensure — create if missing.
if (detector === undefined) {
const created = yield* amp.createAnomalyDetector({
workspaceId,
alias: news!.alias,
configuration: toConfiguration(news!),
evaluationIntervalInSeconds: toWireSeconds(news!.evaluationInterval),
missingDataAction: news!.missingDataAction,
labels: news!.labels,
tags: desiredTags,
});
detector = yield* waitSettled(workspaceId, created.anomalyDetectorId);
} else if (configDrifts(news!, detector)) {
// 3. Sync — `putAnomalyDetector` triggers a full retrain, so it
// is only called when an observed aspect actually drifts.
yield* amp.putAnomalyDetector({
workspaceId,
anomalyDetectorId: detector.anomalyDetectorId,
configuration: toConfiguration(news!),
evaluationIntervalInSeconds: toWireSeconds(news!.evaluationInterval),
missingDataAction: news!.missingDataAction,
labels: news!.labels,
});
detector = yield* waitSettled(workspaceId, detector.anomalyDetectorId);
}
// 3b. Sync tags — diff against OBSERVED cloud tags.
yield* syncAmpTags(detector.arn, desiredTags);
yield* session.note(`${workspaceId}/${detector.anomalyDetectorId}`);
return toAttrs(workspaceId, detector);
}),
delete: Effect.fn(function* ({ output }) {
yield* amp
.deleteAnomalyDetector({
workspaceId: output.workspaceId,
anomalyDetectorId: output.anomalyDetectorId,
})
.pipe(
Effect.catchTag("ResourceNotFoundException", () => Effect.void),
// A detector mid-training rejects deletion; retry briefly.
Effect.retry({
while: (e) => e._tag === "ConflictException",
schedule: Schedule.max([Schedule.fixed("4 seconds"), Schedule.recurs(25)]),
}),
);
}),
// Sub-resource keyed by its parent workspace — not independently
// enumerable across the account.
list: () => Effect.succeed([]),
};
}),
);