@causa/workspace-google 1.4.0-beta.1 → 1.4.0-beta.2

package/dist/graph/environment/load-balancer-backends.js

@@ -0,0 +1,126 @@
+import { GraphEnvironmentFact, } from '@causa/workspace-core/graph';
+import { templateMapping, } from './monitoring-mappings.js';
+import { googleResources } from './resources.js';
+/**
+ * Maps load balancer labels to the URL maps of the graph, i.e. API routers.
+ */
+export const URL_MAP_MAPPING = templateMapping({
+    nodeType: 'apiRouter',
+    resourceType: 'compute.googleapis.com/UrlMap',
+    monitoredResource: 'https_lb_rule',
+    name: 'projects/{project}/global/urlMaps/{resource.label.url_map_name}',
+});
+/**
+ * Serverless network endpoint groups, routing requests to Cloud Run services.
+ * They are listed in the regions of the services, in the projects of the URL maps.
+ */
+export const SERVERLESS_NEG_BACKENDS = {
+    nodeType: 'service',
+    resourceType: 'run.googleapis.com/Service',
+    keyLabels: ['resource.label.backend_scope', 'resource.label.backend_name'],
+    list: async (context, projects, resources) => {
+        const locations = new Map();
+        for (const { segments } of resources) {
+            const { projects: project, locations: region } = segments;
+            if (project && region && projects.includes(project)) {
+                locations.set(`projects/${project}/regions/${region}`, {
+                    project,
+                    region,
+                });
+            }
+        }
+        if (locations.size === 0) {
+            return [];
+        }
+        const { GoogleApisService } = await import('../../services/google-apis.js');
+        const client = await context
+            .service(GoogleApisService)
+            .getClient('compute', 'v1', {});
+        const backends = await Promise.all([...locations.values()].map(async ({ project, region }) => {
+            const groups = [];
+            try {
+                let pageToken;
+                do {
+                    const { data } = await client.regionNetworkEndpointGroups.list({
+                        project,
+                        region,
+                        pageToken,
+                    });
+                    groups.push(...(data.items ?? []));
+                    pageToken = data.nextPageToken ?? undefined;
+                } while (pageToken);
+            }
+            catch (error) {
+                throw new Error(`Failed to list the network endpoint groups in project '${project}' and region '${region}': ${error.message ?? error}`, { cause: error });
+            }
+            return groups.flatMap((group) => {
+                const service = group.cloudRun?.service;
+                if (group.networkEndpointType !== 'SERVERLESS' ||
+                    !group.name ||
+                    !service) {
+                    return [];
+                }
+                return [
+                    {
+                        kind: SERVERLESS_NEG_BACKENDS,
+                        project,
+                        labels: {
+                            'resource.label.backend_scope': region,
+                            'resource.label.backend_name': group.name,
+                        },
+                        resource: `projects/${project}/locations/${region}/services/${service}`,
+                    },
+                ];
+            });
+        }));
+        return backends.flat();
+    },
+};
+/**
+ * The kinds of backends through which requests can be routed to nodes.
+ */
+export const LOAD_BALANCER_BACKEND_KINDS = [
+    SERVERLESS_NEG_BACKENDS,
+];
+/**
+ * Lists the backends of all kinds, in the projects of the URL maps of the graph. No API is called if the graph has no
+ * URL map. The fact fails if some backends cannot be listed.
+ */
+export class LoadBalancerBackendsFact extends GraphEnvironmentFact {
+    async compute(environment) {
+        const projects = [
+            ...new Set(googleResources(environment, URL_MAP_MAPPING.resourceType, URL_MAP_MAPPING.nodeType).map(({ segments }) => segments.projects)),
+        ];
+        if (projects.length === 0) {
+            return { value: [] };
+        }
+        const backends = await Promise.all(LOAD_BALANCER_BACKEND_KINDS.map((kind) => kind.list(environment.context, projects, googleResources(environment, kind.resourceType, kind.nodeType))));
+        return { value: backends.flat() };
+    }
+}
+/**
+ * Builds the mapping of the backends of a kind, from load balancer labels to the resources they route requests to.
+ *
+ * @param kind The kind of backends.
+ * @returns The mapping.
+ */
+export function loadBalancerBackendMapping(kind) {
+    return {
+        nodeType: kind.nodeType,
+        resourceType: kind.resourceType,
+        monitoredResource: URL_MAP_MAPPING.monitoredResource,
+        keyLabels: kind.keyLabels,
+        resolver: async (environment) => {
+            const backends = await environment.get(LoadBalancerBackendsFact);
+            const key = (project, labels) => JSON.stringify([project, ...kind.keyLabels.map((l) => labels[l])]);
+            const resources = new Map(backends
+                .filter((b) => b.kind === kind)
+                .map((b) => [key(b.project, b.labels), b.resource]));
+            return ({ project, labels }) => resources.get(key(project, labels));
+        },
+    };
+}
+/**
+ * The mappings of load balancer labels to the resources backends route requests to, one per kind of backend.
+ */
+export const LOAD_BALANCER_BACKEND_MAPPINGS = LOAD_BALANCER_BACKEND_KINDS.map(loadBalancerBackendMapping);

package/dist/graph/environment/monitoring-alerts.d.ts

@@ -0,0 +1,60 @@
+import type { WorkspaceContext } from '@causa/workspace';
+import type { monitoring_v3 } from 'googleapis';
+import { type MonitoringLabel } from './monitoring-mappings.js';
+/**
+ * An alert, as returned by the Cloud Monitoring Alerts API.
+ */
+export type MonitoringAlert = monitoring_v3.Schema$Alert;
+/**
+ * The monitored resource of an alert.
+ */
+export type MonitoringAlertResource = {
+    /**
+     * The monitored resource type, e.g. `cloud_run_revision`.
+     */
+    readonly type: string;
+    /**
+     * The GCP project of the resource: the `project_id` label, or the project from which the alert was listed.
+     */
+    readonly project: string;
+    /**
+     * The labels of the alert, keyed by name. Resource labels take precedence over metric labels with the same name, as
+     * alerts aggregating away the resource type only keep metric labels.
+     */
+    readonly labels: Readonly<Record<string, string>>;
+};
+/**
+ * An alert open at a given time, along with its monitored resource.
+ */
+export type OpenMonitoringAlert = {
+    /**
+     * The alert, as returned by the Alerts API.
+     */
+    readonly alert: MonitoringAlert;
+    /**
+     * The GCP project from which the alert was listed.
+     */
+    readonly project: string;
+    /**
+     * The monitored resource of the alert. It is `undefined` when its type is unknown.
+     */
+    readonly resource?: MonitoringAlertResource;
+};
+/**
+ * Returns the value of a label of the resource of an alert, read by its name regardless of its source, as alerts
+ * aggregating away the resource type only keep metric labels.
+ *
+ * @param resource The resource of the alert.
+ * @param label The label.
+ * @returns The value of the label.
+ */
+export declare function alertLabelValue(resource: MonitoringAlertResource, label: MonitoringLabel): string | undefined;
+/**
+ * Lists the alerts of a project that were open at a given time, along with their monitored resources.
+ *
+ * @param context The context, from which the `GoogleApisService` is obtained.
+ * @param project The GCP project.
+ * @param at The time at which the alerts were open.
+ * @returns The alerts.
+ */
+export declare function listOpenAlerts(context: WorkspaceContext, project: string, at: Date): Promise<OpenMonitoringAlert[]>;

package/dist/graph/environment/monitoring-alerts.js

@@ -0,0 +1,67 @@
+import { monitoringLabelName, } from './monitoring-mappings.js';
+/**
+ * The resource type of alerts whose condition aggregates away the monitored resource type, e.g. a PromQL query
+ * aggregating a metric written against several resource types.
+ */
+const PROMETHEUS_TARGET = 'prometheus_target';
+/**
+ * Returns the value of a label of the resource of an alert, read by its name regardless of its source, as alerts
+ * aggregating away the resource type only keep metric labels.
+ *
+ * @param resource The resource of the alert.
+ * @param label The label.
+ * @returns The value of the label.
+ */
+export function alertLabelValue(resource, label) {
+    return resource.labels[monitoringLabelName(label)];
+}
+/**
+ * Lists the alerts of a project that were open at a given time, along with their monitored resources.
+ *
+ * @param context The context, from which the `GoogleApisService` is obtained.
+ * @param project The GCP project.
+ * @param at The time at which the alerts were open.
+ * @returns The alerts.
+ */
+export async function listOpenAlerts(context, project, at) {
+    const { GoogleApisService } = await import('../../services/google-apis.js');
+    const client = await context
+        .service(GoogleApisService)
+        .getClient('monitoring', 'v3', {});
+    // The API only supports `>=` and `<=` comparisons, and timestamps without fractional seconds. Alerts that are still
+    // open have no closing time.
+    const time = at.toISOString().replace(/\.\d+Z$/, 'Z');
+    const filter = `open_time <= "${time}" AND (state = "OPEN" OR close_time >= "${time}")`;
+    const alerts = [];
+    let pageToken;
+    do {
+        const { data } = await client.projects.alerts.list({
+            parent: `projects/${project}`,
+            filter,
+            pageSize: 1000,
+            pageToken,
+        });
+        alerts.push(...(data.alerts ?? []));
+        pageToken = data.nextPageToken ?? undefined;
+    } while (pageToken);
+    return alerts.map((alert) => {
+        const labels = {
+            ...alert.metric?.labels,
+            ...alert.resource?.labels,
+        };
+        const resourceType = alert.resource?.type;
+        // PromQL alerts have their resource type set to `prometheus_target`. In that case, the actual resource type is read
+        // from the `monitored_resource` label, which the alert is expected to group by.
+        const type = resourceType && resourceType !== PROMETHEUS_TARGET
+            ? resourceType
+            : labels.monitored_resource;
+        if (!type) {
+            return { alert, project };
+        }
+        return {
+            alert,
+            project,
+            resource: { type, project: labels.project_id ?? project, labels },
+        };
+    });
+}

package/dist/graph/environment/monitoring-catalog.d.ts

@@ -0,0 +1,95 @@
+import { GraphMetricKind, type Graph, type GraphMetricDefinitionsByType } from '@causa/workspace-core';
+import { type GraphNodeEntry } from '@causa/workspace-core/graph';
+import { type MonitoringLabel, type MonitoringResourceMapping } from './monitoring-mappings.js';
+export declare const CLOUD_RUN_SERVICE_MAPPING: MonitoringResourceMapping;
+export declare const PUBSUB_TOPIC_MAPPING: MonitoringResourceMapping;
+export declare const PUBSUB_SUBSCRIPTION_MAPPING: MonitoringResourceMapping;
+export declare const CLOUD_TASKS_QUEUE_MAPPING: MonitoringResourceMapping;
+export declare const SPANNER_INSTANCE_MAPPING: MonitoringResourceMapping;
+export declare const SPANNER_DATABASE_MAPPING: MonitoringResourceMapping;
+export declare const FIRESTORE_DATABASE_MAPPING: MonitoringResourceMapping;
+export declare const BIGQUERY_DATASET_MAPPING: MonitoringResourceMapping;
+export declare const CLOUD_SCHEDULER_JOB_MAPPING: MonitoringResourceMapping;
+/**
+ * All the mappings of Cloud Monitoring monitored resources to the resources of nodes.
+ */
+export declare const MONITORING_RESOURCE_MAPPINGS: readonly MonitoringResourceMapping[];
+/**
+ * A metric of a node type, read from Cloud Monitoring.
+ */
+export type MonitoringMetric = {
+    /**
+     * The name of the metric in the graph.
+     */
+    readonly metric: string;
+    /**
+     * How the time series of the metric map to the nodes it measures.
+     */
+    readonly mapping: MonitoringResourceMapping;
+    /**
+     * The Cloud Monitoring metric type.
+     */
+    readonly metricType: string;
+    /**
+     * An additional filter on the time series.
+     */
+    readonly filter?: string;
+    /**
+     * How time series of the same node and group are combined. Defaults to `REDUCE_SUM`.
+     */
+    readonly reducer?: 'REDUCE_SUM' | 'REDUCE_MAX';
+    /**
+     * The labels of the time series by which values are grouped, keyed by the name of the group key in the graph.
+     */
+    readonly groupBy?: Record<string, MonitoringLabel>;
+    /**
+     * How the time series of the metric map to other nodes the values relate to, e.g. the services load balancers route
+     * requests to. Values are also grouped by the `node` key, whose values are node IDs. The mappings are tried from the
+     * one with the most key labels, and share the monitored resource of {@link MonitoringMetric.mapping}.
+     */
+    readonly groupByNode?: readonly MonitoringResourceMapping[];
+    /**
+     * The factor applied to values, e.g. to convert microseconds to milliseconds. Defaults to `1`.
+     */
+    readonly scale?: number;
+    /**
+     * Whether the value is the number of values in the distribution, per second.
+     */
+    readonly countRate?: boolean;
+    /**
+     * The minimum alignment period, in seconds, for metrics sampled less often than the evaluation window.
+     */
+    readonly minPeriod?: number;
+    /**
+     * Whether the metric measures the resource of a node, when it doesn't measure all the resources of its mapping.
+     * Nodes for which it returns `false` get no value, and their series are not supported. Defaults to all nodes.
+     *
+     * @param node The node.
+     * @param graph The graph containing the node.
+     * @returns Whether the metric measures the node.
+     */
+    readonly measures?: (node: GraphNodeEntry, graph: Graph) => boolean;
+};
+/**
+ * Returns whether a subscription pushes messages to a service, rather than e.g. writing them to a table.
+ *
+ * @param node The node of the subscription.
+ * @param graph The graph containing the node.
+ * @returns `true` if the subscription targets a service.
+ */
+export declare function isPushSubscription(node: GraphNodeEntry, graph: Graph): boolean;
+/**
+ * The metrics read from Cloud Monitoring.
+ */
+export declare const MONITORING_METRICS: readonly MonitoringMetric[];
+/**
+ * The definitions of the metrics of the node types defined by the Google module.
+ */
+export declare const GOOGLE_GRAPH_METRIC_DEFINITIONS: GraphMetricDefinitionsByType;
+/**
+ * Returns the kind of a metric read from Cloud Monitoring, from its definition for the type of its nodes.
+ *
+ * @param metric The metric.
+ * @returns The kind of the metric.
+ */
+export declare function monitoringMetricKind(metric: MonitoringMetric): GraphMetricKind;