sailfork / t3code-github / .repos/ alchemy-effect/ packages/ gcp/ src/ Logging/ Metric.ts

import * as logging from "@distilled.cloud/gcp/logging_v2";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { tagRecord } from "alchemy/Tags";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";
import { GcpEnvironment } from "../Environment.ts";
import { alchemyLabelKeys, createInternalLabels, hasAlchemyLabels } from "../Labels.ts";
import type { Providers } from "../Providers.ts";

const MAX_NAME_LENGTH = 100;
const DEFAULT_METRIC_KIND = "DELTA";
const DEFAULT_VALUE_TYPE = "INT64";

export interface MetricLabel {
  /**
   * Label key. Must match a key in `labelExtractors` when extractors are
   * set.
   */
  key: string;
  /**
   * Human-readable description of the label.
   */
  description?: string;
  /**
   * Label value type.
   * @default "STRING"
   */
  valueType?: "STRING" | "BOOL" | "INT64";
}

export interface MetricDescriptorProps {
  /**
   * Whether the metric records instantaneous values or changes.
   * Immutable after create — changing it replaces the metric.
   * @default "DELTA"
   */
  metricKind?: "GAUGE" | "DELTA" | "CUMULATIVE";
  /**
   * Measurement type. Immutable after create — changing it replaces the
   * metric. `DISTRIBUTION` requires `valueExtractor` and `bucketOptions`.
   * @default "INT64"
   */
  valueType?: "BOOL" | "INT64" | "DOUBLE" | "STRING" | "DISTRIBUTION" | "MONEY";
  /**
   * Unit of the metric value (e.g. `"1"`, `"s"`, `"By"`).
   * @default "1"
   */
  unit?: string;
  /**
   * Concise display name shown in Monitoring.
   */
  displayName?: string;
  /**
   * Time-series labels. New labels may be added; existing keys cannot be
   * renamed or have their value type changed.
   */
  labels?: MetricLabel[];
}

export interface LinearBuckets {
  /** Number of finite buckets. Must be greater than 0. */
  numFiniteBuckets?: number;
  /** Width of each finite bucket. Must be greater than 0. */
  width?: number;
  /** Lower bound of the first finite bucket. */
  offset?: number;
}

export interface ExponentialBuckets {
  /** Number of finite buckets. Must be greater than 0. */
  numFiniteBuckets?: number;
  /** Growth factor between buckets. Must be greater than 1. */
  growthFactor?: number;
  /** Scale of the first bucket. Must be greater than 0. */
  scale?: number;
}

export interface ExplicitBuckets {
  /** Monotonically increasing bucket bounds. */
  bounds?: number[];
}

export interface MetricBucketOptions {
  /** Linear histogram buckets. */
  linearBuckets?: LinearBuckets;
  /** Exponential histogram buckets. */
  exponentialBuckets?: ExponentialBuckets;
  /** Explicit histogram bucket bounds. */
  explicitBuckets?: ExplicitBuckets;
}

export type MetricProps = {
  /**
   * Client-assigned metric id (`METRIC_ID` in
   * `projects/{project}/metrics/{METRIC_ID}`). If omitted, a unique name
   * is generated from the stack, stage, and logical id. Max 100 characters;
   * letters, digits, and `_-. ,+!*'()%/`. Cannot start with `/`. Changing
   * it replaces the metric.
   */
  metricId?: string;
  /**
   * Advanced logs filter used to match log entries. Required. Max 20,000
   * characters.
   */
  filter: string;
  /**
   * Human-readable description. Cloud Logging metrics have no labels, so
   * Alchemy ownership (`alchemy-stack` / `alchemy-stage` / `alchemy-id`)
   * is stored in a `[alchemy …]` prefix for `list` / nuke.
   */
  description?: string;
  /**
   * When true, the metric exists but does not generate time series.
   * @default false
   */
  disabled?: boolean;
  /**
   * Extractor used by distribution metrics (`EXTRACT(field)` or
   * `REGEXP_EXTRACT(field, regex)`).
   */
  valueExtractor?: string;
  /**
   * Map from metric-descriptor label key to an extractor expression.
   */
  labelExtractors?: Record<string, string>;
  /**
   * Log bucket that owns this metric
   * (`projects/{project}/locations/{location}/buckets/{bucket}`). Empty
   * means a non-bucket logs-based metric.
   */
  bucketName?: string;
  /**
   * Metric descriptor. Defaults to a `DELTA`/`INT64` counter. `metricKind`
   * and `valueType` are immutable after create.
   */
  metricDescriptor?: MetricDescriptorProps;
  /**
   * Histogram bucket boundaries. Required when `valueType` is
   * `DISTRIBUTION`.
   */
  bucketOptions?: MetricBucketOptions;
};

export type Metric = Resource<
  "GCP.Logging.Metric",
  MetricProps,
  {
    /** Full resource name `projects/{project}/metrics/{metricId}`. */
    name: string;
    /** Client-assigned metric id. */
    metricId: string;
    /** Project id. */
    project: string;
    /** Logs filter. */
    filter: string;
    /** User description with the Alchemy ownership prefix stripped. */
    description: string | undefined;
    /** Whether the metric is disabled. */
    disabled: boolean;
    /** Distribution value extractor, if set. */
    valueExtractor: string | undefined;
    /** Label extractor map. */
    labelExtractors: Record<string, string>;
    /** Owning log bucket, if this is a bucket metric. */
    bucketName: string | undefined;
    /** Observed metric descriptor. */
    metricDescriptor: MetricDescriptorProps | undefined;
    /** Histogram bucket options, if set. */
    bucketOptions: MetricBucketOptions | undefined;
    /** RFC3339 creation timestamp. */
    createTime: string | undefined;
    /** RFC3339 last-update timestamp. */
    updateTime: string | undefined;
  },
  never,
  Providers
>;

/**
 * A Cloud Logging logs-based metric.
 *
 * Cloud Logging metrics have no resource labels. Alchemy stamps ownership
 * into the description (`[alchemy alchemy-stack=… alchemy-stage=…
 * alchemy-id=…]`) so `list` / `pnpm nuke:gcp` can find them.
 *
 * `metricId`, `metricDescriptor.metricKind`, and
 * `metricDescriptor.valueType` are immutable — changing them replaces the
 * metric.
 *
 * ### Creating a Metric
 * **Example:** Generated name, error counter
 * ```typescript
 * const errors = yield* GCP.Logging.Metric("Errors", {
 *   filter: "severity>=ERROR",
 *   description: "count error log entries",
 * });
 * ```
 *
 * **Example:** Explicit id, disabled counter
 * ```typescript
 * const warnings = yield* GCP.Logging.Metric("Warnings", {
 *   metricId: "app-warnings",
 *   filter: "severity>=WARNING",
 *   description: "count warning log entries",
 *   disabled: true,
 * });
 * ```
 *
 * ### Distribution Metrics
 * **Example:** Histogram of a numeric payload field
 * ```typescript
 * const latency = yield* GCP.Logging.Metric("Latency", {
 *   filter: "jsonPayload.latency > 0",
 *   valueExtractor: "EXTRACT(jsonPayload.latency)",
 *   metricDescriptor: {
 *     metricKind: "DELTA",
 *     valueType: "DISTRIBUTION",
 *   },
 *   bucketOptions: {
 *     exponentialBuckets: {
 *       numFiniteBuckets: 8,
 *       growthFactor: 2,
 *       scale: 1,
 *     },
 *   },
 * });
 * ```
 *
 * @resource
 * @category Logging
 */
export const Metric = Resource<Metric>("GCP.Logging.Metric");

export class MetricNotResolved extends Data.TaggedError("GCP.Logging.MetricNotResolved")<{
  resourceName: string;
}> {}

const lastSegment = (value: string) => {
  const trimmed = value.replace(/\/+$/, "");
  const parts = trimmed.split("/");
  return parts[parts.length - 1] || trimmed;
};

const resourceName = (project: string, metricId: string) =>
  `projects/${project}/metrics/${metricId}`;

const metricIdOf = (metric: logging.LogMetric) => {
  const raw = metric.name ?? metric.resourceName ?? "";
  return raw.startsWith("projects/") ? lastSegment(raw) : raw;
};

const toId = (id: string, metricId: string | undefined, existing?: string) =>
  Effect.gen(function* () {
    return (
      metricId ??
      existing ??
      (yield* createPhysicalName({
        id,
        maxLength: MAX_NAME_LENGTH,
        lowercase: true,
      }))
    );
  });

const encodeDescription = (
  labels: Record<string, string>,
  description: string | undefined,
): string => {
  const marker = `[alchemy ${alchemyLabelKeys.stack}=${labels[alchemyLabelKeys.stack]} ${alchemyLabelKeys.stage}=${labels[alchemyLabelKeys.stage]} ${alchemyLabelKeys.id}=${labels[alchemyLabelKeys.id]}]`;
  return description ? `${marker}\n${description}` : marker;
};

const parseDescription = (
  description: string | undefined,
): {
  labels: Record<string, string>;
  description: string | undefined;
} => {
  if (!description?.startsWith("[alchemy ")) {
    return { labels: {}, description };
  }
  const end = description.indexOf("]");
  if (end < 0) return { labels: {}, description };
  const labels: Record<string, string> = {};
  for (const part of description.slice("[alchemy ".length, end).split(/\s+/)) {
    const eq = part.indexOf("=");
    if (eq > 0) {
      labels[part.slice(0, eq)] = part.slice(eq + 1);
    }
  }
  const rest = description.slice(end + 1).replace(/^\n/, "");
  return { labels, description: rest.length > 0 ? rest : undefined };
};

const hasOwnershipMarker = (description: string | undefined) =>
  Object.keys(parseDescription(description).labels).some((key) => key.startsWith("alchemy-"));

const toLabels = (labels: logging.LabelDescriptorList | undefined): MetricLabel[] =>
  (labels ?? []).flatMap((label) =>
    label.key
      ? [
          {
            key: label.key,
            description: label.description,
            valueType: label.valueType as MetricLabel["valueType"],
          },
        ]
      : [],
  );

const toDescriptor = (
  descriptor: logging.MetricDescriptor | undefined,
): MetricDescriptorProps | undefined => {
  if (descriptor === undefined) return undefined;
  const labels = toLabels(descriptor.labels);
  return {
    metricKind: descriptor.metricKind as MetricDescriptorProps["metricKind"],
    valueType: descriptor.valueType as MetricDescriptorProps["valueType"],
    unit: descriptor.unit,
    displayName: descriptor.displayName,
    labels: labels.length > 0 ? labels : undefined,
  };
};

const toBucketOptions = (
  options: logging.BucketOptions | undefined,
): MetricBucketOptions | undefined => {
  if (options === undefined) return undefined;
  if (
    options.linearBuckets === undefined &&
    options.exponentialBuckets === undefined &&
    options.explicitBuckets === undefined
  ) {
    return undefined;
  }
  return {
    linearBuckets: options.linearBuckets,
    exponentialBuckets: options.exponentialBuckets,
    explicitBuckets: options.explicitBuckets,
  };
};

const toAttrs = (metric: logging.LogMetric, project: string) => {
  const metricId = metricIdOf(metric);
  const parsed = parseDescription(metric.description);
  return {
    name: metric.resourceName ?? resourceName(project, metricId),
    metricId,
    project,
    filter: metric.filter ?? "",
    description: parsed.description,
    disabled: metric.disabled === true,
    valueExtractor: metric.valueExtractor,
    labelExtractors: tagRecord(metric.labelExtractors),
    bucketName: metric.bucketName,
    metricDescriptor: toDescriptor(metric.metricDescriptor),
    bucketOptions: toBucketOptions(metric.bucketOptions),
    createTime: metric.createTime,
    updateTime: metric.updateTime,
  };
};

const recordsEqual = (left: Record<string, string>, right: Record<string, string>) => {
  const leftKeys = Object.keys(left).sort();
  const rightKeys = Object.keys(right).sort();
  return (
    leftKeys.length === rightKeys.length &&
    leftKeys.every((key, index) => key === rightKeys[index] && left[key] === right[key])
  );
};

const jsonEqual = (left: unknown, right: unknown) =>
  JSON.stringify(left ?? null) === JSON.stringify(right ?? null);

const canonLabels = (labels: MetricLabel[] | undefined) =>
  [...(labels ?? [])]
    .map((label) => ({
      key: label.key,
      description: label.description ?? "",
      valueType: (label.valueType ?? "STRING").toUpperCase(),
    }))
    .sort((a, b) => a.key.localeCompare(b.key));

const descriptorChanged = (
  observed: logging.MetricDescriptor | undefined,
  desired: MetricDescriptorProps | undefined,
) => {
  if (desired === undefined) return false;
  if (
    desired.metricKind !== undefined &&
    (observed?.metricKind ?? DEFAULT_METRIC_KIND).toUpperCase() !== desired.metricKind.toUpperCase()
  ) {
    return true;
  }
  if (
    desired.valueType !== undefined &&
    (observed?.valueType ?? DEFAULT_VALUE_TYPE).toUpperCase() !== desired.valueType.toUpperCase()
  ) {
    return true;
  }
  if (desired.unit !== undefined && (observed?.unit ?? "1") !== desired.unit) {
    return true;
  }
  if (desired.displayName !== undefined && (observed?.displayName ?? "") !== desired.displayName) {
    return true;
  }
  if (desired.labels !== undefined) {
    return !jsonEqual(canonLabels(toLabels(observed?.labels)), canonLabels(desired.labels));
  }
  return false;
};

const toWritableDescriptor = (
  descriptor: MetricDescriptorProps | logging.MetricDescriptor | undefined,
): logging.MetricDescriptor | undefined => {
  if (descriptor === undefined) return undefined;
  const labels = descriptor.labels as logging.LabelDescriptorList | undefined;
  const body: logging.MetricDescriptor = {
    metricKind: descriptor.metricKind,
    valueType: descriptor.valueType,
    unit: descriptor.unit,
    displayName: descriptor.displayName,
    labels: labels && labels.length > 0 ? labels : undefined,
  };
  if (
    body.metricKind === undefined &&
    body.valueType === undefined &&
    body.unit === undefined &&
    body.displayName === undefined &&
    body.labels === undefined
  ) {
    return undefined;
  }
  return body;
};

const toBody = (
  metricId: string,
  news: MetricProps,
  ownership: Record<string, string>,
  current?: logging.LogMetric,
): logging.LogMetric => ({
  name: metricId,
  filter: news.filter,
  description: encodeDescription(ownership, news.description),
  disabled: news.disabled === true,
  valueExtractor: news.valueExtractor,
  labelExtractors: news.labelExtractors,
  bucketName: news.bucketName,
  bucketOptions: news.bucketOptions,
  metricDescriptor: toWritableDescriptor(news.metricDescriptor ?? current?.metricDescriptor),
});

const getByName = (metricName: string) =>
  logging
    .getProjectsMetrics({ metricName })
    .pipe(Effect.catchTag("NotFound", () => Effect.undefined));

export const MetricProvider = () =>
  Provider.succeed(Metric, {
    stables: ["name", "metricId", "project", "createTime"],

    diff: Effect.fn(function* ({ news, olds, output }) {
      if (!isResolved(news)) return undefined;
      const previousId = olds?.metricId ?? output?.metricId;
      const nextId = news.metricId ?? previousId;
      const idChanged =
        previousId !== undefined && news.metricId !== undefined && previousId !== news.metricId;

      const previousKind = (
        olds?.metricDescriptor?.metricKind ?? output?.metricDescriptor?.metricKind
      )?.toUpperCase();
      const nextKind = news.metricDescriptor?.metricKind?.toUpperCase();
      const kindChanged =
        nextKind !== undefined && previousKind !== undefined && nextKind !== previousKind;

      const previousType = (
        olds?.metricDescriptor?.valueType ?? output?.metricDescriptor?.valueType
      )?.toUpperCase();
      const nextType = news.metricDescriptor?.valueType?.toUpperCase();
      const typeChanged =
        nextType !== undefined && previousType !== undefined && nextType !== previousType;

      if (!idChanged && !kindChanged && !typeChanged) return undefined;
      return {
        action: "replace" as const,
        deleteFirst: !idChanged && previousId !== undefined && nextId === previousId,
      };
    }),

    read: Effect.fn(function* ({ id, olds, output }) {
      const env = yield* GcpEnvironment.current;
      const metricId = yield* toId(id, olds?.metricId, output?.metricId);
      const name = output?.name ?? resourceName(env.project, metricId);
      const existing = yield* getByName(name);
      if (existing === undefined) return undefined;
      const attrs = toAttrs(existing, env.project);
      return (yield* hasAlchemyLabels(id, parseDescription(existing.description).labels))
        ? attrs
        : Unowned(attrs);
    }),

    list: () =>
      Effect.gen(function* () {
        const env = yield* GcpEnvironment.current;
        return yield* logging.listProjectsMetrics
          .pages({
            parent: `projects/${env.project}`,
            pageSize: 1000,
          })
          .pipe(
            Stream.flatMap((page) => Stream.fromIterable(page.metrics ?? [])),
            Stream.filter((metric) => hasOwnershipMarker(metric.description)),
            Stream.map((metric) => toAttrs(metric, env.project)),
            Stream.runCollect,
            Effect.map((chunk) => Array.from(chunk)),
          );
      }),

    reconcile: Effect.fn(function* ({ id, news, output }) {
      const env = yield* GcpEnvironment.current;
      const metricId = yield* toId(id, news.metricId, output?.metricId);
      const metricName = resourceName(env.project, metricId);
      const ownership = yield* createInternalLabels(id);
      const desiredDescription = encodeDescription(ownership, news.description);
      const desiredDisabled = news.disabled === true;
      const desiredExtractors = tagRecord(news.labelExtractors);

      let current = yield* getByName(output?.name ?? metricName);

      if (current === undefined) {
        const created = yield* logging
          .createProjectsMetrics({
            parent: `projects/${env.project}`,
            body: toBody(metricId, news, ownership),
          })
          .pipe(Effect.catchTag("Conflict", () => getByName(metricName)));
        current = created ?? undefined;
      }

      if (current === undefined) {
        return yield* new MetricNotResolved({ resourceName: metricName });
      }

      const needsUpdate =
        (current.description ?? "") !== desiredDescription ||
        (current.filter ?? "") !== news.filter ||
        (current.disabled === true) !== desiredDisabled ||
        (current.valueExtractor ?? "") !== (news.valueExtractor ?? "") ||
        !recordsEqual(tagRecord(current.labelExtractors), desiredExtractors) ||
        (current.bucketName ?? "") !== (news.bucketName ?? "") ||
        !jsonEqual(toBucketOptions(current.bucketOptions) ?? null, news.bucketOptions ?? null) ||
        descriptorChanged(current.metricDescriptor, news.metricDescriptor);

      if (needsUpdate) {
        current = yield* logging.updateProjectsMetrics({
          metricName,
          body: toBody(metricId, news, ownership, current),
        });
      }

      const latest = (yield* getByName(current.resourceName ?? metricName)) ?? current;
      return toAttrs(latest, env.project);
    }),

    delete: Effect.fn(function* ({ output }) {
      yield* logging
        .deleteProjectsMetrics({ metricName: output.name })
        .pipe(Effect.catchTag("NotFound", () => Effect.void));
    }),
  });