From a74f10708208dd1c3f9e83b016cac371f1522dd6 Mon Sep 17 00:00:00 2001 From: "gcf-owl-bot[bot]" <78513119+gcf-owl-bot[bot]@users.noreply.github.com> Date: Mon, 9 Dec 2024 14:17:24 -0800 Subject: [PATCH] docs: [batch] clarify options for logs (#5864) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs: clarify options for logs docs: Clarify the custom instance template needs to be in the same project PiperOrigin-RevId: 702966613 Source-Link: https://github.com/googleapis/googleapis/commit/2cb4e7a6f328b0a017e040e2c6150c17ef6bea61 Source-Link: https://github.com/googleapis/googleapis-gen/commit/14a9205201b8000a2fedda894e105256ceed9075 Copy-Tag: eyJwIjoicGFja2FnZXMvZ29vZ2xlLWNsb3VkLWJhdGNoLy5Pd2xCb3QueWFtbCIsImgiOiIxNGE5MjA1MjAxYjgwMDBhMmZlZGRhODk0ZTEwNTI1NmNlZWQ5MDc1In0= * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md * docs: clarify options for logs docs: clarify the custom instance template needs to be in the same project PiperOrigin-RevId: 703266926 Source-Link: https://github.com/googleapis/googleapis/commit/3735100771044022d9e57f25fdbf0e67f45a857e Source-Link: https://github.com/googleapis/googleapis-gen/commit/4190d79c5b8e8f62f66db0e1c182308b8037b94a Copy-Tag: eyJwIjoicGFja2FnZXMvZ29vZ2xlLWNsb3VkLWJhdGNoLy5Pd2xCb3QueWFtbCIsImgiOiI0MTkwZDc5YzViOGU4ZjYyZjY2ZGIwZTFjMTgyMzA4YjgwMzdiOTRhIn0= * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md --------- Co-authored-by: Owl Bot Co-authored-by: d-goog <188102366+d-goog@users.noreply.github.com> --- .../protos/google/cloud/batch/v1/job.proto | 35 ++++++++++++------- .../google/cloud/batch/v1alpha/job.proto | 35 ++++++++++++------- 2 files changed, 44 insertions(+), 26 deletions(-) diff --git a/packages/google-cloud-batch/protos/google/cloud/batch/v1/job.proto b/packages/google-cloud-batch/protos/google/cloud/batch/v1/job.proto index a537b67e50f..a215c35b837 100644 --- a/packages/google-cloud-batch/protos/google/cloud/batch/v1/job.proto +++ b/packages/google-cloud-batch/protos/google/cloud/batch/v1/job.proto @@ -90,13 +90,15 @@ message Job { repeated JobNotification notifications = 14; } -// LogsPolicy describes how outputs from a Job's Tasks (stdout/stderr) will be -// preserved. +// LogsPolicy describes if and how a job's logs are preserved. Logs include +// information that is automatically written by the Batch service agent and any +// information that you configured the job's runnables to write to the `stdout` +// or `stderr` streams. message LogsPolicy { // `CloudLoggingOption` contains additional settings for Cloud Logging logs // generated by Batch job. message CloudLoggingOption { - // Optional. Set this flag to true to change the [monitored resource + // Optional. Set this field to `true` to change the [monitored resource // type](https://cloud.google.com/monitoring/api/resources) for // Cloud Logging logs generated by this Batch job from // the @@ -110,26 +112,32 @@ message LogsPolicy { // The destination (if any) for logs. enum Destination { - // Logs are not preserved. + // (Default) Logs are not preserved. DESTINATION_UNSPECIFIED = 0; - // Logs are streamed to Cloud Logging. + // Logs are streamed to Cloud Logging. Optionally, you can configure + // additional settings in the `cloudLoggingOption` field. CLOUD_LOGGING = 1; - // Logs are saved to a file path. + // Logs are saved to the file path specified in the `logsPath` field. PATH = 2; } - // Where logs should be saved. + // If and where logs should be saved. Destination destination = 1; - // The path to which logs are saved when the destination = PATH. This can be a - // local file path on the VM, or under the mount point of a Persistent Disk or - // Filestore, or a Cloud Storage path. + // When `destination` is set to `PATH`, you must set this field to the path + // where you want logs to be saved. This path can point to a local directory + // on the VM or (if congifured) a directory under the mount path of any + // Cloud Storage bucket, network file system (NFS), or writable persistent + // disk that is mounted to the job. For example, if the job has a bucket with + // `mountPath` set to `/mnt/disks/my-bucket`, you can write logs to the + // root directory of the `remotePath` of that bucket by setting this field to + // `/mnt/disks/my-bucket/`. string logs_path = 2; - // Optional. Additional settings for Cloud Logging. It will only take effect - // when the destination of `LogsPolicy` is set to `CLOUD_LOGGING`. + // Optional. When `destination` is set to `CLOUD_LOGGING`, you can optionally + // set this field to configure additional settings for Cloud Logging. CloudLoggingOption cloud_logging_option = 3 [(google.api.field_behavior) = OPTIONAL]; } @@ -429,7 +437,8 @@ message AllocationPolicy { // Named the field as 'instance_template' instead of 'template' to avoid // C++ keyword conflict. // - // Batch only supports global instance templates. + // Batch only supports global instance templates from the same project as + // the job. // You can specify the global instance template as a full or partial URL. string instance_template = 2; } diff --git a/packages/google-cloud-batch/protos/google/cloud/batch/v1alpha/job.proto b/packages/google-cloud-batch/protos/google/cloud/batch/v1alpha/job.proto index 8a0ee90d878..8ab62c01f9a 100644 --- a/packages/google-cloud-batch/protos/google/cloud/batch/v1alpha/job.proto +++ b/packages/google-cloud-batch/protos/google/cloud/batch/v1alpha/job.proto @@ -113,13 +113,15 @@ message Job { repeated JobNotification notifications = 14; } -// LogsPolicy describes how outputs from a Job's Tasks (stdout/stderr) will be -// preserved. +// LogsPolicy describes if and how a job's logs are preserved. Logs include +// information that is automatically written by the Batch service agent and any +// information that you configured the job's runnables to write to the `stdout` +// or `stderr` streams. message LogsPolicy { // `CloudLoggingOption` contains additional settings for Cloud Logging logs // generated by Batch job. message CloudLoggingOption { - // Optional. Set this flag to true to change the [monitored resource + // Optional. Set this field to `true` to change the [monitored resource // type](https://cloud.google.com/monitoring/api/resources) for // Cloud Logging logs generated by this Batch job from // the @@ -133,26 +135,32 @@ message LogsPolicy { // The destination (if any) for logs. enum Destination { - // Logs are not preserved. + // (Default) Logs are not preserved. DESTINATION_UNSPECIFIED = 0; - // Logs are streamed to Cloud Logging. + // Logs are streamed to Cloud Logging. Optionally, you can configure + // additional settings in the `cloudLoggingOption` field. CLOUD_LOGGING = 1; - // Logs are saved to a file path. + // Logs are saved to the file path specified in the `logsPath` field. PATH = 2; } - // Where logs should be saved. + // If and where logs should be saved. Destination destination = 1; - // The path to which logs are saved when the destination = PATH. This can be a - // local file path on the VM, or under the mount point of a Persistent Disk or - // Filestore, or a Cloud Storage path. + // When `destination` is set to `PATH`, you must set this field to the path + // where you want logs to be saved. This path can point to a local directory + // on the VM or (if congifured) a directory under the mount path of any + // Cloud Storage bucket, network file system (NFS), or writable persistent + // disk that is mounted to the job. For example, if the job has a bucket with + // `mountPath` set to `/mnt/disks/my-bucket`, you can write logs to the + // root directory of the `remotePath` of that bucket by setting this field to + // `/mnt/disks/my-bucket/`. string logs_path = 2; - // Optional. Additional settings for Cloud Logging. It will only take effect - // when the destination of `LogsPolicy` is set to `CLOUD_LOGGING`. + // Optional. When `destination` is set to `CLOUD_LOGGING`, you can optionally + // set this field to configure additional settings for Cloud Logging. CloudLoggingOption cloud_logging_option = 3 [(google.api.field_behavior) = OPTIONAL]; } @@ -504,7 +512,8 @@ message AllocationPolicy { // Named the field as 'instance_template' instead of 'template' to avoid // C++ keyword conflict. // - // Batch only supports global instance templates. + // Batch only supports global instance templates from the same project as + // the job. // You can specify the global instance template as a full or partial URL. string instance_template = 2; }