From aba9760d6abc15f724753c26d6f306e0f76dd11a Mon Sep 17 00:00:00 2001 From: Google APIs Date: Tue, 7 Jul 2020 10:52:01 -0700 Subject: [PATCH] feat: Update Logging API protos. Renames the service name from Stackdriver Logging to Cloud Logging. Specifies client retry behavior and a few other documentation updates. PiperOrigin-RevId: 320016414 --- google/logging/v2/BUILD.bazel | 14 ++++ google/logging/v2/log_entry.proto | 10 +-- google/logging/v2/logging.proto | 34 ++++++---- google/logging/v2/logging.yaml | 13 ++-- google/logging/v2/logging_config.proto | 68 +++++++++++-------- .../v2/logging_grpc_service_config.json | 35 ++++++++-- google/logging/v2/logging_metrics.proto | 6 +- 7 files changed, 115 insertions(+), 65 deletions(-) diff --git a/google/logging/v2/BUILD.bazel b/google/logging/v2/BUILD.bazel index 02426700..8fe7a53e 100644 --- a/google/logging/v2/BUILD.bazel +++ b/google/logging/v2/BUILD.bazel @@ -1,4 +1,13 @@ # This file was automatically generated by BuildFileGenerator +# https://github.com/googleapis/gapic-generator/tree/master/rules_gapic/bazel + +# Most of the manual changes to this file will be overwritten. +# It's **only** allowed to change the following rule attribute values: +# - names of *_gapic_assembly_* rules +# - certain parameters of *_gapic_library rules, including but not limited to: +# * extra_protoc_parameters +# * extra_protoc_file_parameters +# The complete list of preserved parameters can be found in the source code. # This is an API workspace, having public visibility by default makes perfect sense. package(default_visibility = ["//visibility:public"]) @@ -71,6 +80,7 @@ java_gapic_library( name = "logging_java_gapic", src = ":logging_proto_with_info", gapic_yaml = "logging_gapic.yaml", + grpc_service_config = "logging_grpc_service_config.json", package = "google.logging.v2", service_yaml = "logging.yaml", test_deps = [ @@ -209,6 +219,7 @@ py_gapic_library( name = "logging_py_gapic", src = ":logging_proto_with_info", gapic_yaml = "logging_gapic.yaml", + grpc_service_config = "logging_grpc_service_config.json", package = "google.logging.v2", service_yaml = "logging.yaml", deps = [ @@ -253,6 +264,7 @@ php_gapic_library( name = "logging_php_gapic", src = ":logging_proto_with_info", gapic_yaml = "logging_gapic.yaml", + grpc_service_config = "logging_grpc_service_config.json", package = "google.logging.v2", service_yaml = "logging.yaml", deps = [ @@ -326,6 +338,7 @@ ruby_gapic_library( name = "logging_ruby_gapic", src = ":logging_proto_with_info", gapic_yaml = "logging_gapic.yaml", + grpc_service_config = "logging_grpc_service_config.json", package = "google.logging.v2", service_yaml = "logging.yaml", deps = [ @@ -370,6 +383,7 @@ csharp_gapic_library( name = "logging_csharp_gapic", src = ":logging_proto_with_info", gapic_yaml = "logging_gapic.yaml", + grpc_service_config = "logging_grpc_service_config.json", package = "google.logging.v2", service_yaml = "logging.yaml", deps = [ diff --git a/google/logging/v2/log_entry.proto b/google/logging/v2/log_entry.proto index d2a172ec..3ad2cfbb 100644 --- a/google/logging/v2/log_entry.proto +++ b/google/logging/v2/log_entry.proto @@ -106,11 +106,11 @@ message LogEntry { // current time. Timestamps have nanosecond accuracy, but trailing zeros in // the fractional seconds might be omitted when the timestamp is displayed. // - // Incoming log entries should have timestamps that are no more than the [logs - // retention period](https://cloud.google.com/logging/quotas) in the past, and no more than 24 hours - // in the future. Log entries outside those time boundaries will not be - // available when calling `entries.list`, but those log entries can still be - // [exported with LogSinks](https://cloud.google.com/logging/docs/api/tasks/exporting-logs). + // Incoming log entries must have timestamps that don't exceed the + // [logs retention + // period](https://cloud.google.com/logging/quotas#logs_retention_periods) in + // the past, and that don't exceed 24 hours in the future. Log entries outside + // those time boundaries aren't ingested by Logging. google.protobuf.Timestamp timestamp = 9 [(google.api.field_behavior) = OPTIONAL]; // Output only. The time the log entry was received by Logging. diff --git a/google/logging/v2/logging.proto b/google/logging/v2/logging.proto index 8a2a8a58..58647b92 100644 --- a/google/logging/v2/logging.proto +++ b/google/logging/v2/logging.proto @@ -24,6 +24,7 @@ import "google/logging/v2/log_entry.proto"; import "google/logging/v2/logging_config.proto"; import "google/protobuf/duration.proto"; import "google/protobuf/empty.proto"; +import "google/protobuf/field_mask.proto"; import "google/protobuf/timestamp.proto"; import "google/rpc/status.proto"; import "google/api/annotations.proto"; @@ -87,7 +88,8 @@ service LoggingServiceV2 { // Lists log entries. Use this method to retrieve log entries that originated // from a project/folder/organization/billing account. For ways to export log - // entries, see [Exporting Logs](https://cloud.google.com/logging/docs/export). + // entries, see [Exporting + // Logs](https://cloud.google.com/logging/docs/export). rpc ListLogEntries(ListLogEntriesRequest) returns (ListLogEntriesResponse) { option (google.api.http) = { post: "/v2/entries:list" @@ -203,15 +205,16 @@ message WriteLogEntriesRequest { // the entries later in the list. See the `entries.list` method. // // Log entries with timestamps that are more than the - // [logs retention period](https://cloud.google.com/logging/quota-policy) in the past or more than - // 24 hours in the future will not be available when calling `entries.list`. - // However, those log entries can still be - // [exported with LogSinks](https://cloud.google.com/logging/docs/api/tasks/exporting-logs). + // [logs retention period](https://cloud.google.com/logging/quota-policy) in + // the past or more than 24 hours in the future will not be available when + // calling `entries.list`. However, those log entries can still be [exported + // with + // LogSinks](https://cloud.google.com/logging/docs/api/tasks/exporting-logs). // // To improve throughput and to avoid exceeding the - // [quota limit](https://cloud.google.com/logging/quota-policy) for calls to `entries.write`, - // you should try to include several log entries in this list, - // rather than calling this method for each individual log entry. + // [quota limit](https://cloud.google.com/logging/quota-policy) for calls to + // `entries.write`, you should try to include several log entries in this + // list, rather than calling this method for each individual log entry. repeated LogEntry entries = 4 [(google.api.field_behavior) = REQUIRED]; // Optional. Whether valid entries should be written even if some other @@ -261,12 +264,12 @@ message ListLogEntriesRequest { ]; // Optional. A filter that chooses which log entries to return. See [Advanced - // Logs Queries](https://cloud.google.com/logging/docs/view/advanced-queries). Only log entries that - // match the filter are returned. An empty filter matches all log entries in - // the resources listed in `resource_names`. Referencing a parent resource - // that is not listed in `resource_names` will cause the filter to return no - // results. - // The maximum length of the filter is 20000 characters. + // Logs Queries](https://cloud.google.com/logging/docs/view/advanced-queries). + // Only log entries that match the filter are returned. An empty filter + // matches all log entries in the resources listed in `resource_names`. + // Referencing a parent resource that is not listed in `resource_names` will + // cause the filter to return no results. The maximum length of the filter is + // 20000 characters. string filter = 2 [(google.api.field_behavior) = OPTIONAL]; // Optional. How the results should be sorted. Presently, the only permitted @@ -278,7 +281,8 @@ message ListLogEntriesRequest { string order_by = 3 [(google.api.field_behavior) = OPTIONAL]; // Optional. The maximum number of results to return from this request. - // Non-positive values are ignored. The presence of `next_page_token` in the + // Default is 50. If the value is negative or exceeds 1000, + // the request is rejected. The presence of `next_page_token` in the // response indicates that more results might be available. int32 page_size = 4 [(google.api.field_behavior) = OPTIONAL]; diff --git a/google/logging/v2/logging.yaml b/google/logging/v2/logging.yaml index 5d04a82e..9e0c9e7d 100644 --- a/google/logging/v2/logging.yaml +++ b/google/logging/v2/logging.yaml @@ -1,7 +1,7 @@ type: google.api.Service config_version: 3 name: logging.googleapis.com -title: Stackdriver Logging API +title: Cloud Logging API apis: - name: google.logging.v2.ConfigServiceV2 @@ -10,14 +10,13 @@ apis: documentation: summary: |- - Writes log entries and manages your Stackdriver Logging configuration. The - table entries below are presented in alphabetical order, not in order of - common use. For explanations of the concepts found in the table entries, - read the Stackdriver Logging - documentation. + Writes log entries and manages your Cloud Logging configuration. The table + entries below are presented in alphabetical order, not in order of common + use. For explanations of the concepts found in the table entries, read the + documentation at https://cloud.google.com/logging/docs. overview: '# Introduction -The Stackdriver Logging service.' +The Cloud Logging service.' backend: rules: diff --git a/google/logging/v2/logging_config.proto b/google/logging/v2/logging_config.proto index 5fd8d496..9486f4a9 100644 --- a/google/logging/v2/logging_config.proto +++ b/google/logging/v2/logging_config.proto @@ -382,7 +382,8 @@ service ConfigServiceV2 { // the GCP organization. // // See [Enabling CMEK for Logs - // Router](https://cloud.google.com/logging/docs/routing/managed-encryption) for more information. + // Router](https://cloud.google.com/logging/docs/routing/managed-encryption) + // for more information. rpc GetCmekSettings(GetCmekSettingsRequest) returns (CmekSettings) { option (google.api.http) = { get: "/v2/{name=*/*}/cmekSettings" @@ -405,7 +406,8 @@ service ConfigServiceV2 { // 3) access to the key is disabled. // // See [Enabling CMEK for Logs - // Router](https://cloud.google.com/logging/docs/routing/managed-encryption) for more information. + // Router](https://cloud.google.com/logging/docs/routing/managed-encryption) + // for more information. rpc UpdateCmekSettings(UpdateCmekSettingsRequest) returns (CmekSettings) { option (google.api.http) = { patch: "/v2/{name=*/*}/cmekSettings" @@ -474,9 +476,7 @@ message LogSink { pattern: "billingAccounts/{billing_account}/sinks/{sink}" }; - // Available log entry formats. Log entries can be written to - // Logging in either format and can be exported in either format. - // Version 2 is the preferred format. + // Deprecated. This is unused. enum VersionFormat { // An unspecified format version that will default to V2. VERSION_FORMAT_UNSPECIFIED = 0; @@ -504,7 +504,8 @@ message LogSink { // The sink's `writer_identity`, set when the sink is created, must // have permission to write to the destination or else the log // entries are not exported. For more information, see - // [Exporting Logs with Sinks](https://cloud.google.com/logging/docs/api/tasks/exporting-logs). + // [Exporting Logs with + // Sinks](https://cloud.google.com/logging/docs/api/tasks/exporting-logs). string destination = 3 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { @@ -512,9 +513,10 @@ message LogSink { } ]; - // Optional. An [advanced logs filter](https://cloud.google.com/logging/docs/view/advanced-queries). The only - // exported log entries are those that are in the resource owning the sink and - // that match the filter. For example: + // Optional. An [advanced logs + // filter](https://cloud.google.com/logging/docs/view/advanced-queries). The + // only exported log entries are those that are in the resource owning the + // sink and that match the filter. For example: // // logName="projects/[PROJECT_ID]/logs/[LOG_ID]" AND severity>=ERROR string filter = 5 [(google.api.field_behavior) = OPTIONAL]; @@ -527,8 +529,7 @@ message LogSink { // export any log entries. bool disabled = 19 [(google.api.field_behavior) = OPTIONAL]; - // Deprecated. The log entry format to use for this sink's exported log - // entries. The v2 format is used by default and cannot be changed. + // Deprecated. This field is unused. VersionFormat output_version_format = 6 [deprecated = true]; // Output only. An IAM identity–a service account or group—under which Logging @@ -580,12 +581,13 @@ message LogSink { // Options that change functionality of a sink exporting data to BigQuery. message BigQueryOptions { // Optional. Whether to use [BigQuery's partition - // tables](https://cloud.google.com/bigquery/docs/partitioned-tables). By default, Logging - // creates dated tables based on the log entries' timestamps, e.g. - // syslog_20170523. With partitioned tables the date suffix is no longer + // tables](https://cloud.google.com/bigquery/docs/partitioned-tables). By + // default, Logging creates dated tables based on the log entries' timestamps, + // e.g. syslog_20170523. With partitioned tables the date suffix is no longer // present and [special query - // syntax](https://cloud.google.com/bigquery/docs/querying-partitioned-tables) has to be used instead. - // In both cases, tables are sharded based on UTC timezone. + // syntax](https://cloud.google.com/bigquery/docs/querying-partitioned-tables) + // has to be used instead. In both cases, tables are sharded based on UTC + // timezone. bool use_partitioned_tables = 1 [(google.api.field_behavior) = OPTIONAL]; // Output only. True if new timestamp column based partitioning is in use, @@ -626,7 +628,8 @@ message ListBucketsRequest { (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { child_type: "logging.googleapis.com/LogBucket" - }]; + } + ]; // Optional. If present, then retrieve the next batch of results from the // preceding call to this method. `pageToken` must be the value of @@ -890,9 +893,10 @@ message LogExclusion { // Optional. A description of this exclusion. string description = 2 [(google.api.field_behavior) = OPTIONAL]; - // Required. An [advanced logs filter](https://cloud.google.com/logging/docs/view/advanced-queries) - // that matches the log entries to be excluded. By using the - // [sample function](https://cloud.google.com/logging/docs/view/advanced-queries#sample), + // Required. An [advanced logs + // filter](https://cloud.google.com/logging/docs/view/advanced-queries) that + // matches the log entries to be excluded. By using the [sample + // function](https://cloud.google.com/logging/docs/view/advanced-queries#sample), // you can exclude less than 100% of the matching log entries. // For example, the following query matches 99% of low-severity log // entries from Google Cloud Storage buckets: @@ -1047,8 +1051,9 @@ message DeleteExclusionRequest { // The parameters to // [GetCmekSettings][google.logging.v2.ConfigServiceV2.GetCmekSettings]. // -// See [Enabling CMEK for Logs Router](https://cloud.google.com/logging/docs/routing/managed-encryption) -// for more information. +// See [Enabling CMEK for Logs +// Router](https://cloud.google.com/logging/docs/routing/managed-encryption) for +// more information. message GetCmekSettingsRequest { // Required. The resource for which to retrieve CMEK settings. // @@ -1073,8 +1078,9 @@ message GetCmekSettingsRequest { // The parameters to // [UpdateCmekSettings][google.logging.v2.ConfigServiceV2.UpdateCmekSettings]. // -// See [Enabling CMEK for Logs Router](https://cloud.google.com/logging/docs/routing/managed-encryption) -// for more information. +// See [Enabling CMEK for Logs +// Router](https://cloud.google.com/logging/docs/routing/managed-encryption) for +// more information. message UpdateCmekSettingsRequest { // Required. The resource name for the CMEK settings to update. // @@ -1093,7 +1099,8 @@ message UpdateCmekSettingsRequest { // Required. The CMEK settings to update. // // See [Enabling CMEK for Logs - // Router](https://cloud.google.com/logging/docs/routing/managed-encryption) for more information. + // Router](https://cloud.google.com/logging/docs/routing/managed-encryption) + // for more information. CmekSettings cmek_settings = 2 [(google.api.field_behavior) = REQUIRED]; // Optional. Field mask identifying which fields from `cmek_settings` should @@ -1113,8 +1120,9 @@ message UpdateCmekSettingsRequest { // organizations. Once configured, it applies to all projects and folders in the // GCP organization. // -// See [Enabling CMEK for Logs Router](https://cloud.google.com/logging/docs/routing/managed-encryption) -// for more information. +// See [Enabling CMEK for Logs +// Router](https://cloud.google.com/logging/docs/routing/managed-encryption) for +// more information. message CmekSettings { option (google.api.resource) = { type: "logging.googleapis.com/CmekSettings" @@ -1150,7 +1158,8 @@ message CmekSettings { // To disable CMEK for the Logs Router, set this field to an empty string. // // See [Enabling CMEK for Logs - // Router](https://cloud.google.com/logging/docs/routing/managed-encryption) for more information. + // Router](https://cloud.google.com/logging/docs/routing/managed-encryption) + // for more information. string kms_key_name = 2; // Output only. The service account that will be used by the Logs Router to access your @@ -1163,6 +1172,7 @@ message CmekSettings { // obtain the service account ID. // // See [Enabling CMEK for Logs - // Router](https://cloud.google.com/logging/docs/routing/managed-encryption) for more information. + // Router](https://cloud.google.com/logging/docs/routing/managed-encryption) + // for more information. string service_account_id = 3 [(google.api.field_behavior) = OUTPUT_ONLY]; } diff --git a/google/logging/v2/logging_grpc_service_config.json b/google/logging/v2/logging_grpc_service_config.json index 6f0c97e8..fc9c085b 100755 --- a/google/logging/v2/logging_grpc_service_config.json +++ b/google/logging/v2/logging_grpc_service_config.json @@ -39,8 +39,29 @@ "maxBackoff": "60s", "backoffMultiplier": 1.3, "retryableStatusCodes": [ - "UNAVAILABLE", - "DEADLINE_EXCEEDED" + "DEADLINE_EXCEEDED", + "INTERNAL", + "UNAVAILABLE" + ] + } + }, + { + "name": [ + { + "service": "google.logging.v2.LoggingServiceV2", + "method": "TailLogEntries" + } + ], + "timeout": "3600s", + "retryPolicy": { + "maxAttempts": 5, + "initialBackoff": "0.100s", + "maxBackoff": "60s", + "backoffMultiplier": 1.3, + "retryableStatusCodes": [ + "DEADLINE_EXCEEDED", + "INTERNAL", + "UNAVAILABLE" ] } }, @@ -82,8 +103,9 @@ "maxBackoff": "60s", "backoffMultiplier": 1.3, "retryableStatusCodes": [ - "UNAVAILABLE", - "DEADLINE_EXCEEDED" + "DEADLINE_EXCEEDED", + "INTERNAL", + "UNAVAILABLE" ] } }, @@ -130,8 +152,9 @@ "maxBackoff": "60s", "backoffMultiplier": 1.3, "retryableStatusCodes": [ - "UNAVAILABLE", - "DEADLINE_EXCEEDED" + "DEADLINE_EXCEEDED", + "INTERNAL", + "UNAVAILABLE" ] } } diff --git a/google/logging/v2/logging_metrics.proto b/google/logging/v2/logging_metrics.proto index e147578a..eb9f73ff 100644 --- a/google/logging/v2/logging_metrics.proto +++ b/google/logging/v2/logging_metrics.proto @@ -130,9 +130,9 @@ message LogMetric { // The maximum length of the description is 8000 characters. string description = 2 [(google.api.field_behavior) = OPTIONAL]; - // Required. An [advanced logs filter](https://cloud.google.com/logging/docs/view/advanced_filters) which is - // used to match log entries. - // Example: + // Required. An [advanced logs + // filter](https://cloud.google.com/logging/docs/view/advanced_filters) which + // is used to match log entries. Example: // // "resource.type=gae_app AND severity>=ERROR" //