@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 06:00 UTC

main
ts 310 lines 12.1 KB
Raw
1 import * as amp from "@distilled.cloud/aws/amp";
2 import { Unowned } from "alchemy/AdoptPolicy";
3 import { isResolved } from "alchemy/Diff";
4 import * as Provider from "alchemy/Provider";
5 import { Resource } from "alchemy/Resource";
6 import { createInternalTags, hasAlchemyTags } from "alchemy/Tags";
7 import { toWireSeconds } from "alchemy/Util/Duration";
8 import type * as Duration from "effect/Duration";
9 import * as Effect from "effect/Effect";
10 import * as Option from "effect/Option";
11 import * as Schedule from "effect/Schedule";
12 import * as Stream from "effect/Stream";
13 import type { Providers } from "../Providers.ts";
14 import { syncAmpTags, toTagRecord } from "./internal.ts";
15
16 /**
17 * Tolerance band around the expected value inside which deviations are not
18 * flagged — either an absolute `amount` or a `ratio` of the expected value.
19 */
20 export type AnomalyDetectorIgnoreNearExpected = { amount: number } | { ratio: number };
21
22 /** What the detector does with evaluation windows that have no data. */
23 export type AnomalyDetectorMissingDataAction = { markAsAnomaly: boolean } | { skip: boolean };
24
25 export interface AnomalyDetectorProps {
26 /**
27 * Id of the AMP workspace the detector runs in. Changing the workspace
28 * replaces the detector.
29 */
30 workspaceId: string;
31 /**
32 * Human-readable alias for the detector, unique within the workspace.
33 * Changing the alias replaces the detector.
34 */
35 alias: string;
36 /**
37 * The PromQL query producing the time series the Random Cut Forest
38 * algorithm scores for anomalies. Updating it retrains the detector.
39 */
40 query: string;
41 /**
42 * Number of consecutive data points combined into one sample (shingle)
43 * for scoring. If omitted, the service default is used.
44 */
45 shingleSize?: number;
46 /**
47 * Number of points sampled per Random Cut Forest tree. If omitted, the
48 * service default is used.
49 */
50 sampleSize?: number;
51 /**
52 * Suppress anomalies above the expected value that fall within this
53 * tolerance band.
54 */
55 ignoreNearExpectedFromAbove?: AnomalyDetectorIgnoreNearExpected;
56 /**
57 * Suppress anomalies below the expected value that fall within this
58 * tolerance band.
59 */
60 ignoreNearExpectedFromBelow?: AnomalyDetectorIgnoreNearExpected;
61 /**
62 * How often the detector evaluates the query. Accepts any
63 * `Duration.Input` (e.g. `"1 minute"`, `Duration.minutes(1)`; a bare
64 * number is milliseconds); the wire unit is whole seconds
65 * (`evaluationIntervalInSeconds`). If omitted, the service default is
66 * used.
67 */
68 evaluationInterval?: Duration.Input;
69 /**
70 * What to do when an evaluation window has no data: mark it as an
71 * anomaly (`{ markAsAnomaly: true }`) or skip it (`{ skip: true }`).
72 */
73 missingDataAction?: AnomalyDetectorMissingDataAction;
74 /**
75 * Extra labels attached to the anomaly metrics the detector emits.
76 */
77 labels?: Record<string, string>;
78 /**
79 * User-defined tags for the detector.
80 */
81 tags?: Record<string, string>;
82 }
83
84 export interface AnomalyDetector extends Resource<
85 "AWS.AMP.AnomalyDetector",
86 AnomalyDetectorProps,
87 {
88 workspaceId: string;
89 anomalyDetectorId: string;
90 anomalyDetectorArn: string;
91 alias: string;
92 status: string;
93 },
94 never,
95 Providers
96 > {}
97
98 /**
99 * A Random Cut Forest anomaly detector inside an Amazon Managed Service for
100 * Prometheus workspace — continuously evaluates a PromQL query and emits
101 * anomaly scores as new metrics in the same workspace.
102 *
103 * ### Creating an Anomaly Detector
104 * **Example:** Detect Anomalies on a Request-Rate Query
105 * ```typescript
106 * const workspace = yield* AMP.Workspace("Metrics", {});
107 * const detector = yield* AMP.AnomalyDetector("RequestSpikes", {
108 * workspaceId: workspace.workspaceId,
109 * alias: "request-spikes",
110 * query: 'rate(http_requests_total{job="api"}[5m])',
111 * evaluationInterval: "1 minute",
112 * missingDataAction: { skip: true },
113 * });
114 * ```
115 *
116 * @resource
117 */
118 export const AnomalyDetector = Resource<AnomalyDetector>("AWS.AMP.AnomalyDetector");
119
120 export const AnomalyDetectorProvider = () =>
121 Provider.effect(
122 AnomalyDetector,
123 Effect.gen(function* () {
124 const toAttrs = (workspaceId: string, detector: amp.AnomalyDetectorDescription) => ({
125 workspaceId,
126 anomalyDetectorId: detector.anomalyDetectorId,
127 anomalyDetectorArn: detector.arn,
128 alias: detector.alias,
129 status: detector.status.statusCode,
130 });
131
132 /** Describe a detector by id; typed not-found → undefined. */
133 const describe = Effect.fn(function* (workspaceId: string, anomalyDetectorId: string) {
134 const response = yield* amp
135 .describeAnomalyDetector({ workspaceId, anomalyDetectorId })
136 .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
137 return response?.anomalyDetector;
138 });
139
140 /**
141 * Find a detector by its alias (the deterministic identity within a
142 * workspace) — used when no id is cached in `output`.
143 */
144 const findByAlias = Effect.fn(function* (workspaceId: string, alias: string) {
145 const summary = yield* amp.listAnomalyDetectors.items({ workspaceId, alias }).pipe(
146 Stream.filter((s) => s.alias === alias),
147 Stream.runHead,
148 Effect.map(Option.getOrUndefined),
149 Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
150 );
151 return summary === undefined
152 ? undefined
153 : yield* describe(workspaceId, summary.anomalyDetectorId);
154 });
155
156 /**
157 * Bounded best-effort wait toward ACTIVE. Training/backfill can
158 * outlast the window; the last observed description is returned and
159 * a still-training detector converges on a later reconcile.
160 */
161 const waitSettled = Effect.fn(function* (workspaceId: string, anomalyDetectorId: string) {
162 return yield* amp.describeAnomalyDetector({ workspaceId, anomalyDetectorId }).pipe(
163 Effect.map((r) => r.anomalyDetector),
164 Effect.repeat({
165 schedule: Schedule.max([Schedule.fixed("3 seconds"), Schedule.recurs(20)]),
166 until: (d): boolean =>
167 d.status.statusCode !== "CREATING" && d.status.statusCode !== "UPDATING",
168 }),
169 );
170 });
171
172 const canonical = (value: unknown) =>
173 JSON.stringify(value, (_, v: unknown) =>
174 v !== null && typeof v === "object" && !Array.isArray(v)
175 ? Object.fromEntries(
176 Object.entries(v as Record<string, unknown>).sort(([a], [b]) => a.localeCompare(b)),
177 )
178 : v,
179 );
180
181 /**
182 * Detect drift between desired props and the observed detector.
183 * Only user-specified fields participate — omitted optional fields
184 * defer to service defaults and never force a (full-retrain) put.
185 */
186 const configDrifts = (
187 news: AnomalyDetectorProps,
188 observed: amp.AnomalyDetectorDescription,
189 ): boolean => {
190 const rcf = observed.configuration?.randomCutForest;
191 const drift =
192 news.query !== rcf?.query ||
193 (news.shingleSize !== undefined && news.shingleSize !== rcf?.shingleSize) ||
194 (news.sampleSize !== undefined && news.sampleSize !== rcf?.sampleSize) ||
195 (news.ignoreNearExpectedFromAbove !== undefined &&
196 canonical(news.ignoreNearExpectedFromAbove) !==
197 canonical(rcf?.ignoreNearExpectedFromAbove)) ||
198 (news.ignoreNearExpectedFromBelow !== undefined &&
199 canonical(news.ignoreNearExpectedFromBelow) !==
200 canonical(rcf?.ignoreNearExpectedFromBelow)) ||
201 (news.evaluationInterval !== undefined &&
202 toWireSeconds(news.evaluationInterval) !== observed.evaluationIntervalInSeconds) ||
203 (news.missingDataAction !== undefined &&
204 canonical(news.missingDataAction) !== canonical(observed.missingDataAction)) ||
205 (news.labels !== undefined &&
206 canonical(news.labels) !== canonical(toTagRecord(observed.labels)));
207 return drift;
208 };
209
210 const toConfiguration = (news: AnomalyDetectorProps) => ({
211 randomCutForest: {
212 query: news.query,
213 shingleSize: news.shingleSize,
214 sampleSize: news.sampleSize,
215 ignoreNearExpectedFromAbove: news.ignoreNearExpectedFromAbove,
216 ignoreNearExpectedFromBelow: news.ignoreNearExpectedFromBelow,
217 },
218 });
219
220 return {
221 stables: ["workspaceId", "anomalyDetectorId", "anomalyDetectorArn", "alias"],
222
223 diff: Effect.fn(function* ({ olds, news }) {
224 if (!isResolved(news)) return undefined;
225 if (olds?.workspaceId !== news.workspaceId || olds?.alias !== news.alias) {
226 return { action: "replace" } as const;
227 }
228 }),
229
230 read: Effect.fn(function* ({ id, olds, output }) {
231 const workspaceId = output?.workspaceId ?? olds?.workspaceId;
232 if (!workspaceId) return undefined;
233 const detector =
234 output?.anomalyDetectorId !== undefined
235 ? yield* describe(workspaceId, output.anomalyDetectorId)
236 : olds?.alias !== undefined
237 ? yield* findByAlias(workspaceId, olds.alias)
238 : undefined;
239 if (detector === undefined) return undefined;
240 const attrs = toAttrs(workspaceId, detector);
241 const tags = toTagRecord(detector.tags);
242 return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
243 }),
244
245 reconcile: Effect.fn(function* ({ id, news, output, session }) {
246 const workspaceId = news!.workspaceId;
247 const internalTags = yield* createInternalTags(id);
248 const desiredTags = { ...internalTags, ...news!.tags };
249
250 // 1. Observe — by cached id, falling back to the alias.
251 let detector =
252 output?.anomalyDetectorId !== undefined
253 ? yield* describe(workspaceId, output.anomalyDetectorId)
254 : yield* findByAlias(workspaceId, news!.alias);
255
256 // 2. Ensure — create if missing.
257 if (detector === undefined) {
258 const created = yield* amp.createAnomalyDetector({
259 workspaceId,
260 alias: news!.alias,
261 configuration: toConfiguration(news!),
262 evaluationIntervalInSeconds: toWireSeconds(news!.evaluationInterval),
263 missingDataAction: news!.missingDataAction,
264 labels: news!.labels,
265 tags: desiredTags,
266 });
267 detector = yield* waitSettled(workspaceId, created.anomalyDetectorId);
268 } else if (configDrifts(news!, detector)) {
269 // 3. Sync — `putAnomalyDetector` triggers a full retrain, so it
270 // is only called when an observed aspect actually drifts.
271 yield* amp.putAnomalyDetector({
272 workspaceId,
273 anomalyDetectorId: detector.anomalyDetectorId,
274 configuration: toConfiguration(news!),
275 evaluationIntervalInSeconds: toWireSeconds(news!.evaluationInterval),
276 missingDataAction: news!.missingDataAction,
277 labels: news!.labels,
278 });
279 detector = yield* waitSettled(workspaceId, detector.anomalyDetectorId);
280 }
281
282 // 3b. Sync tags — diff against OBSERVED cloud tags.
283 yield* syncAmpTags(detector.arn, desiredTags);
284
285 yield* session.note(`${workspaceId}/${detector.anomalyDetectorId}`);
286 return toAttrs(workspaceId, detector);
287 }),
288
289 delete: Effect.fn(function* ({ output }) {
290 yield* amp
291 .deleteAnomalyDetector({
292 workspaceId: output.workspaceId,
293 anomalyDetectorId: output.anomalyDetectorId,
294 })
295 .pipe(
296 Effect.catchTag("ResourceNotFoundException", () => Effect.void),
297 // A detector mid-training rejects deletion; retry briefly.
298 Effect.retry({
299 while: (e) => e._tag === "ConflictException",
300 schedule: Schedule.max([Schedule.fixed("4 seconds"), Schedule.recurs(25)]),
301 }),
302 );
303 }),
304
305 // Sub-resource keyed by its parent workspace — not independently
306 // enumerable across the account.
307 list: () => Effect.succeed([]),
308 };
309 }),
310 );