@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 576 lines 18.6 KB
Raw
1 import * as logging from "@distilled.cloud/gcp/logging_v2";
2 import { Unowned } from "alchemy/AdoptPolicy";
3 import { isResolved } from "alchemy/Diff";
4 import { createPhysicalName } from "alchemy/PhysicalName";
5 import * as Provider from "alchemy/Provider";
6 import { Resource } from "alchemy/Resource";
7 import { tagRecord } from "alchemy/Tags";
8 import * as Data from "effect/Data";
9 import * as Effect from "effect/Effect";
10 import * as Stream from "effect/Stream";
11 import { GcpEnvironment } from "../Environment.ts";
12 import { alchemyLabelKeys, createInternalLabels, hasAlchemyLabels } from "../Labels.ts";
13 import type { Providers } from "../Providers.ts";
14
15 const MAX_NAME_LENGTH = 100;
16 const DEFAULT_METRIC_KIND = "DELTA";
17 const DEFAULT_VALUE_TYPE = "INT64";
18
19 export interface MetricLabel {
20 /**
21 * Label key. Must match a key in `labelExtractors` when extractors are
22 * set.
23 */
24 key: string;
25 /**
26 * Human-readable description of the label.
27 */
28 description?: string;
29 /**
30 * Label value type.
31 * @default "STRING"
32 */
33 valueType?: "STRING" | "BOOL" | "INT64";
34 }
35
36 export interface MetricDescriptorProps {
37 /**
38 * Whether the metric records instantaneous values or changes.
39 * Immutable after create — changing it replaces the metric.
40 * @default "DELTA"
41 */
42 metricKind?: "GAUGE" | "DELTA" | "CUMULATIVE";
43 /**
44 * Measurement type. Immutable after create — changing it replaces the
45 * metric. `DISTRIBUTION` requires `valueExtractor` and `bucketOptions`.
46 * @default "INT64"
47 */
48 valueType?: "BOOL" | "INT64" | "DOUBLE" | "STRING" | "DISTRIBUTION" | "MONEY";
49 /**
50 * Unit of the metric value (e.g. `"1"`, `"s"`, `"By"`).
51 * @default "1"
52 */
53 unit?: string;
54 /**
55 * Concise display name shown in Monitoring.
56 */
57 displayName?: string;
58 /**
59 * Time-series labels. New labels may be added; existing keys cannot be
60 * renamed or have their value type changed.
61 */
62 labels?: MetricLabel[];
63 }
64
65 export interface LinearBuckets {
66 /** Number of finite buckets. Must be greater than 0. */
67 numFiniteBuckets?: number;
68 /** Width of each finite bucket. Must be greater than 0. */
69 width?: number;
70 /** Lower bound of the first finite bucket. */
71 offset?: number;
72 }
73
74 export interface ExponentialBuckets {
75 /** Number of finite buckets. Must be greater than 0. */
76 numFiniteBuckets?: number;
77 /** Growth factor between buckets. Must be greater than 1. */
78 growthFactor?: number;
79 /** Scale of the first bucket. Must be greater than 0. */
80 scale?: number;
81 }
82
83 export interface ExplicitBuckets {
84 /** Monotonically increasing bucket bounds. */
85 bounds?: number[];
86 }
87
88 export interface MetricBucketOptions {
89 /** Linear histogram buckets. */
90 linearBuckets?: LinearBuckets;
91 /** Exponential histogram buckets. */
92 exponentialBuckets?: ExponentialBuckets;
93 /** Explicit histogram bucket bounds. */
94 explicitBuckets?: ExplicitBuckets;
95 }
96
97 export type MetricProps = {
98 /**
99 * Client-assigned metric id (`METRIC_ID` in
100 * `projects/{project}/metrics/{METRIC_ID}`). If omitted, a unique name
101 * is generated from the stack, stage, and logical id. Max 100 characters;
102 * letters, digits, and `_-. ,+!*'()%/`. Cannot start with `/`. Changing
103 * it replaces the metric.
104 */
105 metricId?: string;
106 /**
107 * Advanced logs filter used to match log entries. Required. Max 20,000
108 * characters.
109 */
110 filter: string;
111 /**
112 * Human-readable description. Cloud Logging metrics have no labels, so
113 * Alchemy ownership (`alchemy-stack` / `alchemy-stage` / `alchemy-id`)
114 * is stored in a `[alchemy …]` prefix for `list` / nuke.
115 */
116 description?: string;
117 /**
118 * When true, the metric exists but does not generate time series.
119 * @default false
120 */
121 disabled?: boolean;
122 /**
123 * Extractor used by distribution metrics (`EXTRACT(field)` or
124 * `REGEXP_EXTRACT(field, regex)`).
125 */
126 valueExtractor?: string;
127 /**
128 * Map from metric-descriptor label key to an extractor expression.
129 */
130 labelExtractors?: Record<string, string>;
131 /**
132 * Log bucket that owns this metric
133 * (`projects/{project}/locations/{location}/buckets/{bucket}`). Empty
134 * means a non-bucket logs-based metric.
135 */
136 bucketName?: string;
137 /**
138 * Metric descriptor. Defaults to a `DELTA`/`INT64` counter. `metricKind`
139 * and `valueType` are immutable after create.
140 */
141 metricDescriptor?: MetricDescriptorProps;
142 /**
143 * Histogram bucket boundaries. Required when `valueType` is
144 * `DISTRIBUTION`.
145 */
146 bucketOptions?: MetricBucketOptions;
147 };
148
149 export type Metric = Resource<
150 "GCP.Logging.Metric",
151 MetricProps,
152 {
153 /** Full resource name `projects/{project}/metrics/{metricId}`. */
154 name: string;
155 /** Client-assigned metric id. */
156 metricId: string;
157 /** Project id. */
158 project: string;
159 /** Logs filter. */
160 filter: string;
161 /** User description with the Alchemy ownership prefix stripped. */
162 description: string | undefined;
163 /** Whether the metric is disabled. */
164 disabled: boolean;
165 /** Distribution value extractor, if set. */
166 valueExtractor: string | undefined;
167 /** Label extractor map. */
168 labelExtractors: Record<string, string>;
169 /** Owning log bucket, if this is a bucket metric. */
170 bucketName: string | undefined;
171 /** Observed metric descriptor. */
172 metricDescriptor: MetricDescriptorProps | undefined;
173 /** Histogram bucket options, if set. */
174 bucketOptions: MetricBucketOptions | undefined;
175 /** RFC3339 creation timestamp. */
176 createTime: string | undefined;
177 /** RFC3339 last-update timestamp. */
178 updateTime: string | undefined;
179 },
180 never,
181 Providers
182 >;
183
184 /**
185 * A Cloud Logging logs-based metric.
186 *
187 * Cloud Logging metrics have no resource labels. Alchemy stamps ownership
188 * into the description (`[alchemy alchemy-stack=… alchemy-stage=…
189 * alchemy-id=…]`) so `list` / `pnpm nuke:gcp` can find them.
190 *
191 * `metricId`, `metricDescriptor.metricKind`, and
192 * `metricDescriptor.valueType` are immutable — changing them replaces the
193 * metric.
194 *
195 * ### Creating a Metric
196 * **Example:** Generated name, error counter
197 * ```typescript
198 * const errors = yield* GCP.Logging.Metric("Errors", {
199 * filter: "severity>=ERROR",
200 * description: "count error log entries",
201 * });
202 * ```
203 *
204 * **Example:** Explicit id, disabled counter
205 * ```typescript
206 * const warnings = yield* GCP.Logging.Metric("Warnings", {
207 * metricId: "app-warnings",
208 * filter: "severity>=WARNING",
209 * description: "count warning log entries",
210 * disabled: true,
211 * });
212 * ```
213 *
214 * ### Distribution Metrics
215 * **Example:** Histogram of a numeric payload field
216 * ```typescript
217 * const latency = yield* GCP.Logging.Metric("Latency", {
218 * filter: "jsonPayload.latency > 0",
219 * valueExtractor: "EXTRACT(jsonPayload.latency)",
220 * metricDescriptor: {
221 * metricKind: "DELTA",
222 * valueType: "DISTRIBUTION",
223 * },
224 * bucketOptions: {
225 * exponentialBuckets: {
226 * numFiniteBuckets: 8,
227 * growthFactor: 2,
228 * scale: 1,
229 * },
230 * },
231 * });
232 * ```
233 *
234 * @resource
235 * @category Logging
236 */
237 export const Metric = Resource<Metric>("GCP.Logging.Metric");
238
239 export class MetricNotResolved extends Data.TaggedError("GCP.Logging.MetricNotResolved")<{
240 resourceName: string;
241 }> {}
242
243 const lastSegment = (value: string) => {
244 const trimmed = value.replace(/\/+$/, "");
245 const parts = trimmed.split("/");
246 return parts[parts.length - 1] || trimmed;
247 };
248
249 const resourceName = (project: string, metricId: string) =>
250 `projects/${project}/metrics/${metricId}`;
251
252 const metricIdOf = (metric: logging.LogMetric) => {
253 const raw = metric.name ?? metric.resourceName ?? "";
254 return raw.startsWith("projects/") ? lastSegment(raw) : raw;
255 };
256
257 const toId = (id: string, metricId: string | undefined, existing?: string) =>
258 Effect.gen(function* () {
259 return (
260 metricId ??
261 existing ??
262 (yield* createPhysicalName({
263 id,
264 maxLength: MAX_NAME_LENGTH,
265 lowercase: true,
266 }))
267 );
268 });
269
270 const encodeDescription = (
271 labels: Record<string, string>,
272 description: string | undefined,
273 ): string => {
274 const marker = `[alchemy ${alchemyLabelKeys.stack}=${labels[alchemyLabelKeys.stack]} ${alchemyLabelKeys.stage}=${labels[alchemyLabelKeys.stage]} ${alchemyLabelKeys.id}=${labels[alchemyLabelKeys.id]}]`;
275 return description ? `${marker}\n${description}` : marker;
276 };
277
278 const parseDescription = (
279 description: string | undefined,
280 ): {
281 labels: Record<string, string>;
282 description: string | undefined;
283 } => {
284 if (!description?.startsWith("[alchemy ")) {
285 return { labels: {}, description };
286 }
287 const end = description.indexOf("]");
288 if (end < 0) return { labels: {}, description };
289 const labels: Record<string, string> = {};
290 for (const part of description.slice("[alchemy ".length, end).split(/\s+/)) {
291 const eq = part.indexOf("=");
292 if (eq > 0) {
293 labels[part.slice(0, eq)] = part.slice(eq + 1);
294 }
295 }
296 const rest = description.slice(end + 1).replace(/^\n/, "");
297 return { labels, description: rest.length > 0 ? rest : undefined };
298 };
299
300 const hasOwnershipMarker = (description: string | undefined) =>
301 Object.keys(parseDescription(description).labels).some((key) => key.startsWith("alchemy-"));
302
303 const toLabels = (labels: logging.LabelDescriptorList | undefined): MetricLabel[] =>
304 (labels ?? []).flatMap((label) =>
305 label.key
306 ? [
307 {
308 key: label.key,
309 description: label.description,
310 valueType: label.valueType as MetricLabel["valueType"],
311 },
312 ]
313 : [],
314 );
315
316 const toDescriptor = (
317 descriptor: logging.MetricDescriptor | undefined,
318 ): MetricDescriptorProps | undefined => {
319 if (descriptor === undefined) return undefined;
320 const labels = toLabels(descriptor.labels);
321 return {
322 metricKind: descriptor.metricKind as MetricDescriptorProps["metricKind"],
323 valueType: descriptor.valueType as MetricDescriptorProps["valueType"],
324 unit: descriptor.unit,
325 displayName: descriptor.displayName,
326 labels: labels.length > 0 ? labels : undefined,
327 };
328 };
329
330 const toBucketOptions = (
331 options: logging.BucketOptions | undefined,
332 ): MetricBucketOptions | undefined => {
333 if (options === undefined) return undefined;
334 if (
335 options.linearBuckets === undefined &&
336 options.exponentialBuckets === undefined &&
337 options.explicitBuckets === undefined
338 ) {
339 return undefined;
340 }
341 return {
342 linearBuckets: options.linearBuckets,
343 exponentialBuckets: options.exponentialBuckets,
344 explicitBuckets: options.explicitBuckets,
345 };
346 };
347
348 const toAttrs = (metric: logging.LogMetric, project: string) => {
349 const metricId = metricIdOf(metric);
350 const parsed = parseDescription(metric.description);
351 return {
352 name: metric.resourceName ?? resourceName(project, metricId),
353 metricId,
354 project,
355 filter: metric.filter ?? "",
356 description: parsed.description,
357 disabled: metric.disabled === true,
358 valueExtractor: metric.valueExtractor,
359 labelExtractors: tagRecord(metric.labelExtractors),
360 bucketName: metric.bucketName,
361 metricDescriptor: toDescriptor(metric.metricDescriptor),
362 bucketOptions: toBucketOptions(metric.bucketOptions),
363 createTime: metric.createTime,
364 updateTime: metric.updateTime,
365 };
366 };
367
368 const recordsEqual = (left: Record<string, string>, right: Record<string, string>) => {
369 const leftKeys = Object.keys(left).sort();
370 const rightKeys = Object.keys(right).sort();
371 return (
372 leftKeys.length === rightKeys.length &&
373 leftKeys.every((key, index) => key === rightKeys[index] && left[key] === right[key])
374 );
375 };
376
377 const jsonEqual = (left: unknown, right: unknown) =>
378 JSON.stringify(left ?? null) === JSON.stringify(right ?? null);
379
380 const canonLabels = (labels: MetricLabel[] | undefined) =>
381 [...(labels ?? [])]
382 .map((label) => ({
383 key: label.key,
384 description: label.description ?? "",
385 valueType: (label.valueType ?? "STRING").toUpperCase(),
386 }))
387 .sort((a, b) => a.key.localeCompare(b.key));
388
389 const descriptorChanged = (
390 observed: logging.MetricDescriptor | undefined,
391 desired: MetricDescriptorProps | undefined,
392 ) => {
393 if (desired === undefined) return false;
394 if (
395 desired.metricKind !== undefined &&
396 (observed?.metricKind ?? DEFAULT_METRIC_KIND).toUpperCase() !== desired.metricKind.toUpperCase()
397 ) {
398 return true;
399 }
400 if (
401 desired.valueType !== undefined &&
402 (observed?.valueType ?? DEFAULT_VALUE_TYPE).toUpperCase() !== desired.valueType.toUpperCase()
403 ) {
404 return true;
405 }
406 if (desired.unit !== undefined && (observed?.unit ?? "1") !== desired.unit) {
407 return true;
408 }
409 if (desired.displayName !== undefined && (observed?.displayName ?? "") !== desired.displayName) {
410 return true;
411 }
412 if (desired.labels !== undefined) {
413 return !jsonEqual(canonLabels(toLabels(observed?.labels)), canonLabels(desired.labels));
414 }
415 return false;
416 };
417
418 const toWritableDescriptor = (
419 descriptor: MetricDescriptorProps | logging.MetricDescriptor | undefined,
420 ): logging.MetricDescriptor | undefined => {
421 if (descriptor === undefined) return undefined;
422 const labels = descriptor.labels as logging.LabelDescriptorList | undefined;
423 const body: logging.MetricDescriptor = {
424 metricKind: descriptor.metricKind,
425 valueType: descriptor.valueType,
426 unit: descriptor.unit,
427 displayName: descriptor.displayName,
428 labels: labels && labels.length > 0 ? labels : undefined,
429 };
430 if (
431 body.metricKind === undefined &&
432 body.valueType === undefined &&
433 body.unit === undefined &&
434 body.displayName === undefined &&
435 body.labels === undefined
436 ) {
437 return undefined;
438 }
439 return body;
440 };
441
442 const toBody = (
443 metricId: string,
444 news: MetricProps,
445 ownership: Record<string, string>,
446 current?: logging.LogMetric,
447 ): logging.LogMetric => ({
448 name: metricId,
449 filter: news.filter,
450 description: encodeDescription(ownership, news.description),
451 disabled: news.disabled === true,
452 valueExtractor: news.valueExtractor,
453 labelExtractors: news.labelExtractors,
454 bucketName: news.bucketName,
455 bucketOptions: news.bucketOptions,
456 metricDescriptor: toWritableDescriptor(news.metricDescriptor ?? current?.metricDescriptor),
457 });
458
459 const getByName = (metricName: string) =>
460 logging
461 .getProjectsMetrics({ metricName })
462 .pipe(Effect.catchTag("NotFound", () => Effect.undefined));
463
464 export const MetricProvider = () =>
465 Provider.succeed(Metric, {
466 stables: ["name", "metricId", "project", "createTime"],
467
468 diff: Effect.fn(function* ({ news, olds, output }) {
469 if (!isResolved(news)) return undefined;
470 const previousId = olds?.metricId ?? output?.metricId;
471 const nextId = news.metricId ?? previousId;
472 const idChanged =
473 previousId !== undefined && news.metricId !== undefined && previousId !== news.metricId;
474
475 const previousKind = (
476 olds?.metricDescriptor?.metricKind ?? output?.metricDescriptor?.metricKind
477 )?.toUpperCase();
478 const nextKind = news.metricDescriptor?.metricKind?.toUpperCase();
479 const kindChanged =
480 nextKind !== undefined && previousKind !== undefined && nextKind !== previousKind;
481
482 const previousType = (
483 olds?.metricDescriptor?.valueType ?? output?.metricDescriptor?.valueType
484 )?.toUpperCase();
485 const nextType = news.metricDescriptor?.valueType?.toUpperCase();
486 const typeChanged =
487 nextType !== undefined && previousType !== undefined && nextType !== previousType;
488
489 if (!idChanged && !kindChanged && !typeChanged) return undefined;
490 return {
491 action: "replace" as const,
492 deleteFirst: !idChanged && previousId !== undefined && nextId === previousId,
493 };
494 }),
495
496 read: Effect.fn(function* ({ id, olds, output }) {
497 const env = yield* GcpEnvironment.current;
498 const metricId = yield* toId(id, olds?.metricId, output?.metricId);
499 const name = output?.name ?? resourceName(env.project, metricId);
500 const existing = yield* getByName(name);
501 if (existing === undefined) return undefined;
502 const attrs = toAttrs(existing, env.project);
503 return (yield* hasAlchemyLabels(id, parseDescription(existing.description).labels))
504 ? attrs
505 : Unowned(attrs);
506 }),
507
508 list: () =>
509 Effect.gen(function* () {
510 const env = yield* GcpEnvironment.current;
511 return yield* logging.listProjectsMetrics
512 .pages({
513 parent: `projects/${env.project}`,
514 pageSize: 1000,
515 })
516 .pipe(
517 Stream.flatMap((page) => Stream.fromIterable(page.metrics ?? [])),
518 Stream.filter((metric) => hasOwnershipMarker(metric.description)),
519 Stream.map((metric) => toAttrs(metric, env.project)),
520 Stream.runCollect,
521 Effect.map((chunk) => Array.from(chunk)),
522 );
523 }),
524
525 reconcile: Effect.fn(function* ({ id, news, output }) {
526 const env = yield* GcpEnvironment.current;
527 const metricId = yield* toId(id, news.metricId, output?.metricId);
528 const metricName = resourceName(env.project, metricId);
529 const ownership = yield* createInternalLabels(id);
530 const desiredDescription = encodeDescription(ownership, news.description);
531 const desiredDisabled = news.disabled === true;
532 const desiredExtractors = tagRecord(news.labelExtractors);
533
534 let current = yield* getByName(output?.name ?? metricName);
535
536 if (current === undefined) {
537 const created = yield* logging
538 .createProjectsMetrics({
539 parent: `projects/${env.project}`,
540 body: toBody(metricId, news, ownership),
541 })
542 .pipe(Effect.catchTag("Conflict", () => getByName(metricName)));
543 current = created ?? undefined;
544 }
545
546 if (current === undefined) {
547 return yield* new MetricNotResolved({ resourceName: metricName });
548 }
549
550 const needsUpdate =
551 (current.description ?? "") !== desiredDescription ||
552 (current.filter ?? "") !== news.filter ||
553 (current.disabled === true) !== desiredDisabled ||
554 (current.valueExtractor ?? "") !== (news.valueExtractor ?? "") ||
555 !recordsEqual(tagRecord(current.labelExtractors), desiredExtractors) ||
556 (current.bucketName ?? "") !== (news.bucketName ?? "") ||
557 !jsonEqual(toBucketOptions(current.bucketOptions) ?? null, news.bucketOptions ?? null) ||
558 descriptorChanged(current.metricDescriptor, news.metricDescriptor);
559
560 if (needsUpdate) {
561 current = yield* logging.updateProjectsMetrics({
562 metricName,
563 body: toBody(metricId, news, ownership, current),
564 });
565 }
566
567 const latest = (yield* getByName(current.resourceName ?? metricName)) ?? current;
568 return toAttrs(latest, env.project);
569 }),
570
571 delete: Effect.fn(function* ({ output }) {
572 yield* logging
573 .deleteProjectsMetrics({ metricName: output.name })
574 .pipe(Effect.catchTag("NotFound", () => Effect.void));
575 }),
576 });