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

package/dist/graph/environment/fetchers/cloud-run.js

@@ -0,0 +1,88 @@
+import { ServiceDeploymentStatus, } from '@causa/workspace-core';
+import { googleResources } from '../resources.js';
+/**
+ * The deployment status for each state of the `Ready` terminal condition of a Cloud Run service.
+ * States are listed both by name and by number, as clients may return either.
+ */
+const DEPLOYMENT_STATUSES = {
+    CONDITION_PENDING: ServiceDeploymentStatus.Deploying,
+    1: ServiceDeploymentStatus.Deploying,
+    CONDITION_RECONCILING: ServiceDeploymentStatus.Deploying,
+    2: ServiceDeploymentStatus.Deploying,
+    CONDITION_FAILED: ServiceDeploymentStatus.Failed,
+    3: ServiceDeploymentStatus.Failed,
+    CONDITION_SUCCEEDED: ServiceDeploymentStatus.Deployed,
+    4: ServiceDeploymentStatus.Deployed,
+};
+/**
+ * Returns what is deployed for a Cloud Run service.
+ *
+ * @param service The Cloud Run service.
+ * @returns The deployment.
+ */
+function toDeployment(service) {
+    const image = service.template?.containers?.[0]?.image ?? undefined;
+    const updateSeconds = service.updateTime?.seconds;
+    const updatedAt = updateSeconds
+        ? new Date(Number(updateSeconds.toString()) * 1000)
+        : undefined;
+    const { state, message } = service.terminalCondition ?? {};
+    const status = state ? DEPLOYMENT_STATUSES[state] : undefined;
+    return {
+        ...(image ? { image } : {}),
+        ...(updatedAt ? { updatedAt } : {}),
+        ...(status ? { status } : {}),
+        ...(status && message ? { message } : {}),
+    };
+}
+/**
+ * Reads the deployments of Cloud Run services.
+ */
+export const googleCloudRun = {
+    name: 'googleCloudRun',
+    description: 'The `deployment` of services deployed on Cloud Run: the container image, the last update time, and the status of the latest deployment from the `Ready` condition. The deployment is the current one, with a warning when the service was updated after the end of the evaluation window.',
+    fetch: async (environment) => {
+        const services = googleResources(environment, 'run.googleapis.com/Service', 'service');
+        if (services.length === 0) {
+            return {};
+        }
+        const { CloudRunService } = await import('../../../services/cloud-run.js');
+        const { servicesClient } = environment.context.service(CloudRunService);
+        // Calls on a gax client crash the process when credentials cannot be loaded, while `initialize` rejects.
+        await servicesClient.initialize();
+        const byLocation = Map.groupBy(services, ({ segments }) => `projects/${segments.projects}/locations/${segments.locations}`);
+        const nodes = {};
+        const warnings = [];
+        await Promise.all([...byLocation].map(async ([parent, serviceNodes]) => {
+            let deployed;
+            try {
+                [deployed] = await servicesClient.listServices({ parent });
+            }
+            catch (error) {
+                warnings.push({
+                    message: `Failed to list the Cloud Run services in '${parent}': ${error.message ?? error}`,
+                });
+                return;
+            }
+            const byName = new Map(deployed.map((s) => [s.name, s]));
+            for (const { node, name } of serviceNodes) {
+                const service = byName.get(name);
+                if (!service) {
+                    warnings.push({
+                        message: `The Cloud Run service '${name}' of '${node.id}' does not exist.`,
+                    });
+                    continue;
+                }
+                const deployment = toDeployment(service);
+                const { updatedAt } = deployment;
+                if (updatedAt && updatedAt > environment.at) {
+                    warnings.push({
+                        message: `The Cloud Run service '${name}' of '${node.id}' was updated at ${updatedAt.toISOString()}, after the end of the evaluation window. Its deployment is the current one.`,
+                    });
+                }
+                nodes[node.id] = { data: { deployment } };
+            }
+        }));
+        return { nodes, warnings };
+    },
+};

package/dist/graph/environment/fetchers/cloud-scheduler.d.ts

@@ -0,0 +1,5 @@
+import { type GraphEnvironmentFetcher } from '@causa/workspace-core';
+/**
+ * Reads the last attempt and next run of Cloud Scheduler jobs.
+ */
+export declare const googleCloudScheduler: GraphEnvironmentFetcher;

package/dist/graph/environment/fetchers/cloud-scheduler.js

@@ -0,0 +1,95 @@
+import { ScheduledJobAttemptStatus, } from '@causa/workspace-core';
+import { googleResources } from '../resources.js';
+/**
+ * Returns the data of a scheduled job.
+ * The attempt succeeded if its status code is `OK`. The status message is kept, or the name of the code if the attempt
+ * failed without a message.
+ *
+ * @param job The Cloud Scheduler job.
+ * @param statusCodes The gRPC status codes, which are passed as `google-gax` is imported dynamically.
+ * @returns The data of the node.
+ */
+function toData(job, statusCodes) {
+    const code = job.status?.code ?? statusCodes.OK;
+    const succeeded = code === statusCodes.OK;
+    const message = job.status?.message ||
+        (succeeded ? undefined : (statusCodes[code] ?? `${code}`));
+    return {
+        ...(job.lastAttemptTime
+            ? {
+                lastAttempt: {
+                    time: new Date(job.lastAttemptTime),
+                    status: succeeded
+                        ? ScheduledJobAttemptStatus.Succeeded
+                        : ScheduledJobAttemptStatus.Failed,
+                    ...(message ? { message } : {}),
+                },
+            }
+            : {}),
+        ...(job.scheduleTime && job.state === 'ENABLED'
+            ? { nextRun: new Date(job.scheduleTime) }
+            : {}),
+    };
+}
+/**
+ * Reads the last attempt and next run of Cloud Scheduler jobs.
+ */
+export const googleCloudScheduler = {
+    name: 'googleCloudScheduler',
+    description: 'The `lastAttempt` and `nextRun` of Cloud Scheduler jobs. Paused jobs have no next run. They are the current ones, with a warning when the job was attempted after the end of the evaluation window.',
+    fetch: async (environment) => {
+        const jobs = googleResources(environment, 'cloudscheduler.googleapis.com/Job', 'scheduledJob');
+        const byLocation = Map.groupBy(jobs, ({ segments }) => `projects/${segments.projects}/locations/${segments.locations}`);
+        if (byLocation.size === 0) {
+            return {};
+        }
+        const [{ GoogleApisService }, { Status }] = await Promise.all([
+            import('../../../services/google-apis.js'),
+            import('google-gax'),
+        ]);
+        const client = await environment.context
+            .service(GoogleApisService)
+            .getClient('cloudscheduler', 'v1', {});
+        const nodes = {};
+        const warnings = [];
+        await Promise.all([...byLocation].map(async ([parent, jobNodes]) => {
+            const deployed = new Map();
+            try {
+                let pageToken;
+                do {
+                    const { data } = await client.projects.locations.jobs.list({
+                        parent,
+                        pageSize: 500,
+                        pageToken,
+                    });
+                    (data.jobs ?? []).forEach((j) => j.name && deployed.set(j.name, j));
+                    pageToken = data.nextPageToken ?? undefined;
+                } while (pageToken);
+            }
+            catch (error) {
+                warnings.push({
+                    message: `Failed to list the Cloud Scheduler jobs in '${parent}': ${error.message ?? error}`,
+                });
+                return;
+            }
+            for (const { node, name } of jobNodes) {
+                const job = deployed.get(name);
+                if (!job) {
+                    warnings.push({
+                        message: `The Cloud Scheduler job '${name}' of '${node.id}' does not exist.`,
+                    });
+                    continue;
+                }
+                const data = toData(job, Status);
+                const time = data.lastAttempt?.time;
+                if (time && time > environment.at) {
+                    warnings.push({
+                        message: `The Cloud Scheduler job '${name}' of '${node.id}' was last attempted at ${time.toISOString()}, after the end of the evaluation window. Its last attempt and next run are the current ones.`,
+                    });
+                }
+                nodes[node.id] = { data };
+            }
+        }));
+        return { nodes, warnings };
+    },
+};

package/dist/graph/environment/fetchers/console-links.d.ts

@@ -0,0 +1,14 @@
+import type { GraphEnvironmentFetcher } from '@causa/workspace-core';
+/**
+ * Builds the URL of a page of the Google Cloud console.
+ *
+ * @param segments The segments of the path of the page, which are encoded.
+ * @param project The GCP project.
+ * @param query Additional query parameters.
+ * @returns The URL.
+ */
+export declare function consoleUrl(segments: string[], project: string, query?: Record<string, string>): string;
+/**
+ * Builds links to the Google Cloud console for the nodes' resources.
+ */
+export declare const googleConsoleLinks: GraphEnvironmentFetcher;

package/dist/graph/environment/fetchers/console-links.js

@@ -0,0 +1,132 @@
+import { googleResources } from '../resources.js';
+/**
+ * The base URL of the Google Cloud console.
+ */
+const CONSOLE_URL = 'https://console.cloud.google.com';
+/**
+ * Builds the URL of a page of the Google Cloud console.
+ *
+ * @param segments The segments of the path of the page, which are encoded.
+ * @param project The GCP project.
+ * @param query Additional query parameters.
+ * @returns The URL.
+ */
+export function consoleUrl(segments, project, query = {}) {
+    const path = segments.map(encodeURIComponent).join('/');
+    const parameters = new URLSearchParams({ project, ...query });
+    return `${CONSOLE_URL}/${path}?${parameters}`;
+}
+/**
+ * The builders of links, keyed by resource type.
+ */
+const LINK_BUILDERS = {
+    'run.googleapis.com/Service': ({ projects, locations, services }) => [
+        {
+            label: 'Cloud Run service',
+            url: consoleUrl(['run', 'detail', locations, services, 'metrics'], projects),
+        },
+        {
+            label: 'Cloud Run service logs',
+            url: consoleUrl(['run', 'detail', locations, services, 'logs'], projects),
+        },
+    ],
+    'pubsub.googleapis.com/Topic': ({ projects, topics }) => [
+        {
+            label: 'Pub/Sub topic',
+            url: consoleUrl(['cloudpubsub', 'topic', 'detail', topics], projects),
+        },
+    ],
+    'pubsub.googleapis.com/Subscription': ({ projects, subscriptions }) => [
+        {
+            label: 'Pub/Sub subscription',
+            url: consoleUrl(['cloudpubsub', 'subscription', 'detail', subscriptions], projects),
+        },
+    ],
+    'cloudtasks.googleapis.com/Queue': ({ projects, locations, queues }) => [
+        {
+            label: 'Cloud Tasks queue',
+            url: consoleUrl(['cloudtasks', 'queue', locations, queues, 'tasks'], projects),
+        },
+    ],
+    'cloudscheduler.googleapis.com/Job': ({ projects }) => [
+        {
+            label: 'Cloud Scheduler jobs',
+            url: consoleUrl(['cloudscheduler'], projects),
+        },
+    ],
+    'spanner.googleapis.com/Instance': ({ projects, instances }) => [
+        {
+            label: 'Spanner instance',
+            url: consoleUrl(['spanner', 'instances', instances, 'details', 'databases'], projects),
+        },
+    ],
+    'spanner.googleapis.com/Database': ({ projects, instances, databases }) => [
+        {
+            label: 'Spanner database',
+            url: consoleUrl([
+                'spanner',
+                'instances',
+                instances,
+                'databases',
+                databases,
+                'details',
+                'tables',
+            ], projects),
+        },
+    ],
+    'firestore.googleapis.com/Database': ({ projects, databases }) => [
+        {
+            label: 'Firestore database',
+            url: consoleUrl([
+                'firestore',
+                'databases',
+                databases === '(default)' ? '-default-' : databases,
+                'data',
+            ], projects),
+        },
+    ],
+    'bigquery.googleapis.com/Dataset': ({ projects, datasets }) => [
+        {
+            label: 'BigQuery dataset',
+            url: consoleUrl(['bigquery'], projects, {
+                p: projects,
+                d: datasets,
+                page: 'dataset',
+            }),
+        },
+    ],
+    'bigquery.googleapis.com/Table': ({ projects, datasets, tables }) => [
+        {
+            label: 'BigQuery table',
+            url: consoleUrl(['bigquery'], projects, {
+                p: projects,
+                d: datasets,
+                t: tables,
+                page: 'table',
+            }),
+        },
+    ],
+    'compute.googleapis.com/UrlMap': ({ projects }) => [
+        {
+            label: 'Load balancers',
+            url: consoleUrl(['net-services', 'loadbalancing', 'list', 'loadBalancers'], projects),
+        },
+    ],
+};
+/**
+ * Builds links to the Google Cloud console for the nodes' resources.
+ */
+export const googleConsoleLinks = {
+    name: 'googleConsoleLinks',
+    description: 'The `links` of nodes whose resource is a Google Cloud resource, to the Google Cloud console.',
+    fetch: async (environment) => {
+        const nodes = {};
+        for (const { node, type, segments } of googleResources(environment)) {
+            const builder = LINK_BUILDERS[type];
+            if (builder && segments.projects) {
+                nodes[node.id] = { data: { links: builder(segments) } };
+            }
+        }
+        return { nodes };
+    },
+};

package/dist/graph/environment/fetchers/error-reporting.d.ts

@@ -0,0 +1,5 @@
+import { type GraphEnvironmentFetcher } from '@causa/workspace-core';
+/**
+ * Reads the open groups of errors of Cloud Run services from Error Reporting, as alerts.
+ */
+export declare const googleErrorReporting: GraphEnvironmentFetcher;

package/dist/graph/environment/fetchers/error-reporting.js

@@ -0,0 +1,98 @@
+import { GraphAlertSeverity, } from '@causa/workspace-core';
+import { googleResources } from '../resources.js';
+import { consoleUrl } from './console-links.js';
+/**
+ * The longest period over which Error Reporting can list groups. Periods always end now.
+ */
+const PERIOD = 'PERIOD_30_DAYS';
+/**
+ * The length of {@link PERIOD}, in milliseconds.
+ */
+const PERIOD_LENGTH = 30 * 24 * 3600 * 1000;
+/**
+ * Converts the statistics of an open error group to an alert, titled with the first line of the message of the group's
+ * representative error.
+ *
+ * @param stats The statistics of the group.
+ * @param project The GCP project of the group.
+ * @returns The alert, or `undefined` if the group has never been seen.
+ */
+function toGraphAlert(stats, project) {
+    if (!stats.firstSeenTime) {
+        return undefined;
+    }
+    const groupId = stats.group?.groupId ?? undefined;
+    const message = stats.representative?.message?.split('\n', 1)[0].trim();
+    return {
+        title: message || `Error group ${groupId}`,
+        severity: GraphAlertSeverity.Error,
+        openedAt: new Date(stats.firstSeenTime),
+        ...(groupId
+            ? { url: consoleUrl(['errors', 'detail', groupId], project) }
+            : {}),
+    };
+}
+/**
+ * Reads the open groups of errors of Cloud Run services from Error Reporting, as alerts.
+ */
+export const googleErrorReporting = {
+    name: 'googleErrorReporting',
+    description: 'The `alerts` of Cloud Run services for their open Error Reporting groups, i.e. groups with occurrences during the last 30 days, first seen before the end of the evaluation window. Acknowledged, resolved, and muted groups are excluded.',
+    fetch: async (environment) => {
+        const services = googleResources(environment, 'run.googleapis.com/Service', 'service');
+        if (services.length === 0) {
+            return {};
+        }
+        const { at } = environment;
+        if (Date.now() - at.getTime() > PERIOD_LENGTH) {
+            return {
+                warnings: [
+                    {
+                        message: 'Error groups cannot be listed for an evaluation window ending more than 30 days ago.',
+                    },
+                ],
+            };
+        }
+        const { GoogleApisService } = await import('../../../services/google-apis.js');
+        const client = await environment.context
+            .service(GoogleApisService)
+            .getClient('clouderrorreporting', 'v1beta1', {});
+        const nodes = {};
+        const warnings = [];
+        await Promise.all(services.map(async ({ node, segments }) => {
+            const stats = [];
+            try {
+                let pageToken;
+                do {
+                    const { data } = await client.projects.groupStats.list({
+                        projectName: `projects/${segments.projects}`,
+                        'serviceFilter.service': segments.services,
+                        'timeRange.period': PERIOD,
+                        pageSize: 100,
+                        pageToken,
+                    });
+                    stats.push(...(data.errorGroupStats ?? []));
+                    pageToken = data.nextPageToken ?? undefined;
+                } while (pageToken);
+            }
+            catch (error) {
+                warnings.push({
+                    message: `Failed to list the error groups of '${node.id}': ${error.message ?? error}`,
+                });
+                return;
+            }
+            const alerts = stats.flatMap((groupStats) => {
+                // An unspecified resolution status is interpreted as open.
+                const status = groupStats.group?.resolutionStatus ?? 'OPEN';
+                const alert = status === 'OPEN'
+                    ? toGraphAlert(groupStats, segments.projects)
+                    : undefined;
+                return alert && alert.openedAt < at ? [alert] : [];
+            });
+            if (alerts.length > 0) {
+                nodes[node.id] = { alerts };
+            }
+        }));
+        return { nodes, warnings };
+    },
+};

package/dist/graph/environment/fetchers/index.d.ts

@@ -0,0 +1,5 @@
+import type { GraphEnvironmentFetcher } from '@causa/workspace-core';
+/**
+ * The fetchers of environment data and metrics for Google Cloud.
+ */
+export declare const GOOGLE_GRAPH_ENVIRONMENT_FETCHERS: GraphEnvironmentFetcher[];

package/dist/graph/environment/fetchers/index.js

@@ -0,0 +1,17 @@
+import { googleCloudMonitoringAlerts } from './cloud-monitoring-alerts.js';
+import { googleCloudMonitoring } from './cloud-monitoring.js';
+import { googleCloudRun } from './cloud-run.js';
+import { googleCloudScheduler } from './cloud-scheduler.js';
+import { googleConsoleLinks } from './console-links.js';
+import { googleErrorReporting } from './error-reporting.js';
+/**
+ * The fetchers of environment data and metrics for Google Cloud.
+ */
+export const GOOGLE_GRAPH_ENVIRONMENT_FETCHERS = [
+    googleCloudMonitoring,
+    googleCloudMonitoringAlerts,
+    googleCloudRun,
+    googleCloudScheduler,
+    googleConsoleLinks,
+    googleErrorReporting,
+];

package/dist/graph/environment/index.d.ts

@@ -0,0 +1,9 @@
+export * from './fetchers/index.js';
+export * from './load-balancer-backends.js';
+export * from './monitoring-alerts.js';
+export * from './monitoring-catalog.js';
+export * from './monitoring-mappings.js';
+export * from './monitoring-query.js';
+export * from './monitoring-values.js';
+export * from './resource-resolvers.js';
+export * from './resources.js';

package/dist/graph/environment/index.js

@@ -0,0 +1,9 @@
+export * from './fetchers/index.js';
+export * from './load-balancer-backends.js';
+export * from './monitoring-alerts.js';
+export * from './monitoring-catalog.js';
+export * from './monitoring-mappings.js';
+export * from './monitoring-query.js';
+export * from './monitoring-values.js';
+export * from './resource-resolvers.js';
+export * from './resources.js';

package/dist/graph/environment/load-balancer-backends.d.ts

@@ -0,0 +1,82 @@
+import type { WorkspaceContext } from '@causa/workspace';
+import { GraphEnvironmentFact, type GraphEnvironmentContext, type GraphFactOutput } from '@causa/workspace-core/graph';
+import { type MonitoringLabel, type MonitoringResourceMapping } from './monitoring-mappings.js';
+import { type GoogleResource } from './resources.js';
+/**
+ * Maps load balancer labels to the URL maps of the graph, i.e. API routers.
+ */
+export declare const URL_MAP_MAPPING: MonitoringResourceMapping;
+/**
+ * A backend of load balancers, which routes requests to a resource.
+ */
+export type LoadBalancerBackend = {
+    /**
+     * The kind of the backend.
+     */
+    readonly kind: LoadBalancerBackendKind;
+    /**
+     * The GCP project of the backend.
+     */
+    readonly project: string;
+    /**
+     * The values of the key labels of the kind identifying the backend.
+     */
+    readonly labels: Readonly<Record<MonitoringLabel, string>>;
+    /**
+     * The full resource name of the resource the backend routes requests to, e.g. a Cloud Run service.
+     */
+    readonly resource: string;
+};
+/**
+ * A kind of load balancer backend, routing requests to the resources of nodes of a type.
+ */
+export type LoadBalancerBackendKind = {
+    /**
+     * The type of the nodes requests are routed to.
+     */
+    readonly nodeType: string;
+    /**
+     * The type of the nodes' resource, in their `data.resource.type`.
+     */
+    readonly resourceType: string;
+    /**
+     * The labels of load balancer time series and alerts identifying a backend of this kind within a project.
+     */
+    readonly keyLabels: readonly MonitoringLabel[];
+    /**
+     * Lists the backends of this kind. It throws if some backends cannot be listed.
+     *
+     * @param context The context, from which the `GoogleApisService` is obtained.
+     * @param projects The projects of the graph's URL maps, in which backends are listed.
+     * @param resources The resources of the kind's types, e.g. to only list regional backends in their regions.
+     * @returns The backends.
+     */
+    list(context: WorkspaceContext, projects: readonly string[], resources: readonly GoogleResource[]): Promise<LoadBalancerBackend[]>;
+};
+/**
+ * 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 declare const SERVERLESS_NEG_BACKENDS: LoadBalancerBackendKind;
+/**
+ * The kinds of backends through which requests can be routed to nodes.
+ */
+export declare const LOAD_BALANCER_BACKEND_KINDS: readonly LoadBalancerBackendKind[];
+/**
+ * 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 declare class LoadBalancerBackendsFact extends GraphEnvironmentFact<readonly LoadBalancerBackend[]> {
+    compute(environment: GraphEnvironmentContext): Promise<GraphFactOutput<readonly LoadBalancerBackend[]>>;
+}
+/**
+ * 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 declare function loadBalancerBackendMapping(kind: LoadBalancerBackendKind): MonitoringResourceMapping;
+/**
+ * The mappings of load balancer labels to the resources backends route requests to, one per kind of backend.
+ */
+export declare const LOAD_BALANCER_BACKEND_MAPPINGS: readonly MonitoringResourceMapping[];