- On January 1, 2020 this library will no longer support Python 2 on the latest released version. - Previously released library versions will continue to be available. For more information please + As of January 1, 2020 this library no longer supports Python 2 on the latest released version. + Library versions released prior to that date will continue to be available. For more information please visit Python 2 support on Google Cloud.
{% block body %} {% endblock %} diff --git a/docs/conf.py b/docs/conf.py index 7a03936bb..b507b408e 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -20,12 +20,16 @@ # documentation root, use os.path.abspath to make it absolute, like shown here. sys.path.insert(0, os.path.abspath("..")) +# For plugins that can not read conf.py. +# See also: https://github.com/docascode/sphinx-docfx-yaml/issues/85 +sys.path.insert(0, os.path.abspath(".")) + __version__ = "" # -- General configuration ------------------------------------------------ # If your documentation needs a minimal Sphinx version, state it here. -needs_sphinx = "1.6.3" +needs_sphinx = "1.5.5" # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom @@ -35,24 +39,22 @@ "sphinx.ext.autosummary", "sphinx.ext.intersphinx", "sphinx.ext.coverage", + "sphinx.ext.doctest", "sphinx.ext.napoleon", "sphinx.ext.todo", "sphinx.ext.viewcode", + "recommonmark", ] # autodoc/autosummary flags autoclass_content = "both" -autodoc_default_flags = ["members"] +autodoc_default_options = {"members": True} autosummary_generate = True # Add any paths that contain templates here, relative to this directory. templates_path = ["_templates"] -# Allow markdown includes (so releases.md can include CHANGLEOG.md) -# http://www.sphinx-doc.org/en/master/markdown.html -source_parsers = {".md": "recommonmark.parser.CommonMarkParser"} - # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: # source_suffix = ['.rst', '.md'] @@ -93,7 +95,12 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = ["_build"] +exclude_patterns = [ + "_build", + "samples/AUTHORING_GUIDE.md", + "samples/CONTRIBUTING.md", + "samples/snippets/README.rst", +] # The reST default role (used for this markup: `text`) to use for all # documents. diff --git a/docs/multiprocessing.rst b/docs/multiprocessing.rst new file mode 100644 index 000000000..1cb29d4ca --- /dev/null +++ b/docs/multiprocessing.rst @@ -0,0 +1,7 @@ +.. note:: + + Because this client uses :mod:`grpcio` library, it is safe to + share instances across threads. In multiprocessing scenarios, the best + practice is to create client instances *after* the invocation of + :func:`os.fork` by :class:`multiprocessing.Pool` or + :class:`multiprocessing.Process`. diff --git a/google/cloud/logging_v2/proto/log_entry.proto b/google/cloud/logging_v2/proto/log_entry.proto index 3f9c3d51d..3ad2cfbb5 100644 --- a/google/cloud/logging_v2/proto/log_entry.proto +++ b/google/cloud/logging_v2/proto/log_entry.proto @@ -1,4 +1,4 @@ -// Copyright 2019 Google LLC. +// Copyright 2020 Google LLC // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. @@ -11,12 +11,12 @@ // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. -// syntax = "proto3"; package google.logging.v2; +import "google/api/field_behavior.proto"; import "google/api/monitored_resource.proto"; import "google/api/resource.proto"; import "google/logging/type/http_request.proto"; @@ -34,6 +34,7 @@ option java_multiple_files = true; option java_outer_classname = "LogEntryProto"; option java_package = "com.google.logging.v2"; option php_namespace = "Google\\Cloud\\Logging\\V2"; +option ruby_package = "Google::Cloud::Logging::V2"; // An individual entry in a log. // @@ -55,9 +56,9 @@ message LogEntry { // "billingAccounts/[BILLING_ACCOUNT_ID]/logs/[LOG_ID]" // "folders/[FOLDER_ID]/logs/[LOG_ID]" // - // A project number may optionally be used in place of PROJECT_ID. The project - // number is translated to its corresponding PROJECT_ID internally and the - // `log_name` field will contain PROJECT_ID in queries and exports. + // A project number may be used in place of PROJECT_ID. The project number is + // translated to its corresponding PROJECT_ID internally and the `log_name` + // field will contain PROJECT_ID in queries and exports. // // `[LOG_ID]` must be URL-encoded within `log_name`. Example: // `"organizations/1234567890/logs/cloudresourcemanager.googleapis.com%2Factivity"`. @@ -70,16 +71,16 @@ message LogEntry { // forward-slash is removed. Listing the log entry will not show the leading // slash and filtering for a log name with a leading slash will never return // any results. - string log_name = 12; + string log_name = 12 [(google.api.field_behavior) = REQUIRED]; // Required. The monitored resource that produced this log entry. // // Example: a log entry that reports a database error would be associated with // the monitored resource designating the particular database that reported // the error. - google.api.MonitoredResource resource = 8; + google.api.MonitoredResource resource = 8 [(google.api.field_behavior) = REQUIRED]; - // Optional. The log entry payload, which can be one of multiple types. + // The log entry payload, which can be one of multiple types. oneof payload { // The log entry payload, represented as a protocol buffer. Some Google // Cloud Platform services use this field for their log entry payloads. @@ -99,29 +100,27 @@ message LogEntry { google.protobuf.Struct json_payload = 6; } - // Optional. The time the event described by the log entry occurred. This - // time is used to compute the log entry's age and to enforce the logs - // retention period. If this field is omitted in a new log entry, then Logging - // assigns it the current time. Timestamps have nanosecond accuracy, but - // trailing zeros in the fractional seconds might be omitted when the - // timestamp is displayed. + // Optional. The time the event described by the log entry occurred. This time is used + // to compute the log entry's age and to enforce the logs retention period. + // If this field is omitted in a new log entry, then Logging assigns it the + // 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](/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](/logging/docs/api/tasks/exporting-logs). - google.protobuf.Timestamp timestamp = 9; + // 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. - google.protobuf.Timestamp receive_timestamp = 24; + google.protobuf.Timestamp receive_timestamp = 24 [(google.api.field_behavior) = OUTPUT_ONLY]; - // Optional. The severity of the log entry. The default value is - // `LogSeverity.DEFAULT`. - google.logging.type.LogSeverity severity = 10; + // Optional. The severity of the log entry. The default value is `LogSeverity.DEFAULT`. + google.logging.type.LogSeverity severity = 10 [(google.api.field_behavior) = OPTIONAL]; - // Optional. A unique identifier for the log entry. If you provide a value, - // then Logging considers other log entries in the same project, with the same + // Optional. A unique identifier for the log entry. If you provide a value, then + // Logging considers other log entries in the same project, with the same // `timestamp`, and with the same `insert_id` to be duplicates which are // removed in a single query result. However, there are no guarantees of // de-duplication in the export of logs. @@ -131,43 +130,32 @@ message LogEntry { // // In queries, the `insert_id` is also used to order log entries that have // the same `log_name` and `timestamp` values. - string insert_id = 4; + string insert_id = 4 [(google.api.field_behavior) = OPTIONAL]; - // Optional. Information about the HTTP request associated with this log - // entry, if applicable. - google.logging.type.HttpRequest http_request = 7; + // Optional. Information about the HTTP request associated with this log entry, if + // applicable. + google.logging.type.HttpRequest http_request = 7 [(google.api.field_behavior) = OPTIONAL]; // Optional. A set of user-defined (key, value) data that provides additional // information about the log entry. - map labels = 11; - - // Deprecated. Output only. Additional metadata about the monitored resource. - // - // Only `k8s_container`, `k8s_pod`, and `k8s_node` MonitoredResources have - // this field populated for GKE versions older than 1.12.6. For GKE versions - // 1.12.6 and above, the `metadata` field has been deprecated. The Kubernetes - // pod labels that used to be in `metadata.userLabels` will now be present in - // the `labels` field with a key prefix of `k8s-pod/`. The Stackdriver system - // labels that were present in the `metadata.systemLabels` field will no - // longer be available in the LogEntry. - google.api.MonitoredResourceMetadata metadata = 25 [deprecated = true]; + map labels = 11 [(google.api.field_behavior) = OPTIONAL]; // Optional. Information about an operation associated with the log entry, if // applicable. - LogEntryOperation operation = 15; + LogEntryOperation operation = 15 [(google.api.field_behavior) = OPTIONAL]; - // Optional. Resource name of the trace associated with the log entry, if any. - // If it contains a relative resource name, the name is assumed to be relative - // to `//tracing.googleapis.com`. Example: + // Optional. Resource name of the trace associated with the log entry, if any. If it + // contains a relative resource name, the name is assumed to be relative to + // `//tracing.googleapis.com`. Example: // `projects/my-projectid/traces/06796866738c859f2f19b7cfb3214824` - string trace = 22; + string trace = 22 [(google.api.field_behavior) = OPTIONAL]; // Optional. The span ID within the trace associated with the log entry. // // For Trace spans, this is the same format that the Trace API v2 uses: a // 16-character hexadecimal encoding of an 8-byte array, such as - // "000000000000004a". - string span_id = 27; + // `000000000000004a`. + string span_id = 27 [(google.api.field_behavior) = OPTIONAL]; // Optional. The sampling decision of the trace associated with the log entry. // @@ -176,11 +164,10 @@ message LogEntry { // for storage when this log entry was written, or the sampling decision was // unknown at the time. A non-sampled `trace` value is still useful as a // request correlation identifier. The default is False. - bool trace_sampled = 30; + bool trace_sampled = 30 [(google.api.field_behavior) = OPTIONAL]; - // Optional. Source code location information associated with the log entry, - // if any. - LogEntrySourceLocation source_location = 23; + // Optional. Source code location information associated with the log entry, if any. + LogEntrySourceLocation source_location = 23 [(google.api.field_behavior) = OPTIONAL]; } // Additional information about a potentially long-running operation with which @@ -188,18 +175,18 @@ message LogEntry { message LogEntryOperation { // Optional. An arbitrary operation identifier. Log entries with the same // identifier are assumed to be part of the same operation. - string id = 1; + string id = 1 [(google.api.field_behavior) = OPTIONAL]; // Optional. An arbitrary producer identifier. The combination of `id` and // `producer` must be globally unique. Examples for `producer`: // `"MyDivision.MyBigCompany.com"`, `"github.com/MyProject/MyApplication"`. - string producer = 2; + string producer = 2 [(google.api.field_behavior) = OPTIONAL]; // Optional. Set this to True if this is the first log entry in the operation. - bool first = 3; + bool first = 3 [(google.api.field_behavior) = OPTIONAL]; // Optional. Set this to True if this is the last log entry in the operation. - bool last = 4; + bool last = 4 [(google.api.field_behavior) = OPTIONAL]; } // Additional information about the source code location that produced the log @@ -207,11 +194,11 @@ message LogEntryOperation { message LogEntrySourceLocation { // Optional. Source file name. Depending on the runtime environment, this // might be a simple name or a fully-qualified name. - string file = 1; + string file = 1 [(google.api.field_behavior) = OPTIONAL]; // Optional. Line within the source file. 1-based; 0 indicates no line number // available. - int64 line = 2; + int64 line = 2 [(google.api.field_behavior) = OPTIONAL]; // Optional. Human-readable name of the function or method being invoked, with // optional context such as the class or package name. This information may be @@ -219,5 +206,5 @@ message LogEntrySourceLocation { // less meaningful. The format can vary by language. For example: // `qual.if.ied.Class.method` (Java), `dir/package.func` (Go), `function` // (Python). - string function = 3; + string function = 3 [(google.api.field_behavior) = OPTIONAL]; } diff --git a/google/cloud/logging_v2/proto/logging.proto b/google/cloud/logging_v2/proto/logging.proto index c3a524633..58647b92f 100644 --- a/google/cloud/logging_v2/proto/logging.proto +++ b/google/cloud/logging_v2/proto/logging.proto @@ -1,4 +1,4 @@ -// Copyright 2019 Google LLC. +// Copyright 2020 Google LLC // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. @@ -11,13 +11,11 @@ // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. -// syntax = "proto3"; package google.logging.v2; -import "google/api/annotations.proto"; import "google/api/client.proto"; import "google/api/field_behavior.proto"; import "google/api/monitored_resource.proto"; @@ -26,8 +24,10 @@ 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"; option cc_enable_arenas = true; option csharp_namespace = "Google.Cloud.Logging.V2"; @@ -36,6 +36,7 @@ option java_multiple_files = true; option java_outer_classname = "LoggingProto"; option java_package = "com.google.logging.v2"; option php_namespace = "Google\\Cloud\\Logging\\V2"; +option ruby_package = "Google::Cloud::Logging::V2"; // Service for ingesting and querying logs. service LoggingServiceV2 { @@ -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](/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" @@ -142,7 +144,7 @@ message DeleteLogRequest { string log_name = 1 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { - child_type: "logging.googleapis.com/Log" + type: "logging.googleapis.com/Log" } ]; } @@ -162,13 +164,16 @@ message WriteLogEntriesRequest { // "projects/my-project-id/logs/syslog" // "organizations/1234567890/logs/cloudresourcemanager.googleapis.com%2Factivity" // - // The permission logging.logEntries.create is needed on each - // project, organization, billing account, or folder that is receiving - // new log entries, whether the resource is specified in - // logName or in an individual log entry. - string log_name = 1 [(google.api.resource_reference) = { - type: "logging.googleapis.com/Log" - }]; + // The permission `logging.logEntries.create` is needed on each project, + // organization, billing account, or folder that is receiving new log + // entries, whether the resource is specified in `logName` or in an + // individual log entry. + string log_name = 1 [ + (google.api.field_behavior) = OPTIONAL, + (google.api.resource_reference) = { + type: "logging.googleapis.com/Log" + } + ]; // Optional. A default monitored resource object that is assigned to all log // entries in `entries` that do not specify a value for `resource`. Example: @@ -178,13 +183,13 @@ message WriteLogEntriesRequest { // "zone": "us-central1-a", "instance_id": "00000000000000000000" }} // // See [LogEntry][google.logging.v2.LogEntry]. - google.api.MonitoredResource resource = 2; + google.api.MonitoredResource resource = 2 [(google.api.field_behavior) = OPTIONAL]; // Optional. Default labels that are added to the `labels` field of all log // entries in `entries`. If a log entry already has a label with the same key // as a label in this parameter, then the log entry's label is not changed. // See [LogEntry][google.logging.v2.LogEntry]. - map labels = 3; + map labels = 3 [(google.api.field_behavior) = OPTIONAL]; // Required. The log entries to send to Logging. The order of log // entries in this list does not matter. Values supplied in this method's @@ -200,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](/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](/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](/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 @@ -216,19 +222,16 @@ message WriteLogEntriesRequest { // entry is not written, then the response status is the error associated // with one of the failed entries and the response includes error details // keyed by the entries' zero-based index in the `entries.write` method. - bool partial_success = 5; + bool partial_success = 5 [(google.api.field_behavior) = OPTIONAL]; // Optional. If true, the request should expect normal response, but the // entries won't be persisted nor exported. Useful for checking whether the // logging API endpoints are working properly before sending valuable data. - bool dry_run = 6; + bool dry_run = 6 [(google.api.field_behavior) = OPTIONAL]; } // Result returned from WriteLogEntries. -// empty -message WriteLogEntriesResponse { - -} +message WriteLogEntriesResponse {} // Error details for WriteLogEntries with partial success. message WriteLogEntriesPartialErrors { @@ -243,11 +246,6 @@ message WriteLogEntriesPartialErrors { // The parameters to `ListLogEntries`. message ListLogEntriesRequest { - // Deprecated. Use `resource_names` instead. One or more project identifiers - // or project numbers from which to retrieve log entries. Example: - // `"my-project-1A"`. - repeated string project_ids = 1 [deprecated = true]; - // Required. Names of one or more parent resources from which to // retrieve log entries: // @@ -266,13 +264,13 @@ message ListLogEntriesRequest { ]; // Optional. A filter that chooses which log entries to return. See [Advanced - // Logs Queries](/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; + // 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 // values are `"timestamp asc"` (default) and `"timestamp desc"`. The first @@ -280,18 +278,19 @@ message ListLogEntriesRequest { // `LogEntry.timestamp` (oldest first), and the second option returns entries // in order of decreasing timestamps (newest first). Entries with equal // timestamps are returned in order of their `insert_id` values. - string order_by = 3; + 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; + int32 page_size = 4 [(google.api.field_behavior) = OPTIONAL]; // Optional. If present, then retrieve the next batch of results from the // preceding call to this method. `page_token` must be the value of // `next_page_token` from the previous response. The values of other method // parameters should be identical to those in the previous call. - string page_token = 5; + string page_token = 5 [(google.api.field_behavior) = OPTIONAL]; } // Result returned from `ListLogEntries`. @@ -319,13 +318,13 @@ message ListMonitoredResourceDescriptorsRequest { // Optional. The maximum number of results to return from this request. // Non-positive values are ignored. The presence of `nextPageToken` in the // response indicates that more results might be available. - int32 page_size = 1; + int32 page_size = 1 [(google.api.field_behavior) = OPTIONAL]; // Optional. If present, then retrieve the next batch of results from the // preceding call to this method. `pageToken` must be the value of // `nextPageToken` from the previous response. The values of other method // parameters should be identical to those in the previous call. - string page_token = 2; + string page_token = 2 [(google.api.field_behavior) = OPTIONAL]; } // Result returned from ListMonitoredResourceDescriptors. @@ -347,20 +346,23 @@ message ListLogsRequest { // "organizations/[ORGANIZATION_ID]" // "billingAccounts/[BILLING_ACCOUNT_ID]" // "folders/[FOLDER_ID]" - string parent = 1 [(google.api.resource_reference) = { - child_type: "logging.googleapis.com/Log" - }]; + string parent = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + child_type: "logging.googleapis.com/Log" + } + ]; // Optional. The maximum number of results to return from this request. // Non-positive values are ignored. The presence of `nextPageToken` in the // response indicates that more results might be available. - int32 page_size = 2; + int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL]; // Optional. If present, then retrieve the next batch of results from the // preceding call to this method. `pageToken` must be the value of // `nextPageToken` from the previous response. The values of other method // parameters should be identical to those in the previous call. - string page_token = 3; + string page_token = 3 [(google.api.field_behavior) = OPTIONAL]; } // Result returned from ListLogs. diff --git a/google/cloud/logging_v2/proto/logging_config.proto b/google/cloud/logging_v2/proto/logging_config.proto index 7fb830ded..9486f4a9a 100644 --- a/google/cloud/logging_v2/proto/logging_config.proto +++ b/google/cloud/logging_v2/proto/logging_config.proto @@ -1,4 +1,4 @@ -// Copyright 2019 Google LLC. +// Copyright 2020 Google LLC // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. @@ -11,7 +11,6 @@ // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. -// syntax = "proto3"; @@ -33,6 +32,19 @@ option java_multiple_files = true; option java_outer_classname = "LoggingConfigProto"; option java_package = "com.google.logging.v2"; option php_namespace = "Google\\Cloud\\Logging\\V2"; +option ruby_package = "Google::Cloud::Logging::V2"; +option (google.api.resource_definition) = { + type: "logging.googleapis.com/OrganizationLocation" + pattern: "organizations/{organization}/locations/{location}" +}; +option (google.api.resource_definition) = { + type: "logging.googleapis.com/FolderLocation" + pattern: "folders/{folder}/locations/{location}" +}; +option (google.api.resource_definition) = { + type: "logging.googleapis.com/BillingAccountLocation" + pattern: "billingAccounts/{billing_account}/locations/{location}" +}; // Service for configuring sinks used to route log entries. service ConfigServiceV2 { @@ -43,6 +55,79 @@ service ConfigServiceV2 { "https://www.googleapis.com/auth/logging.admin," "https://www.googleapis.com/auth/logging.read"; + // Lists buckets (Beta). + rpc ListBuckets(ListBucketsRequest) returns (ListBucketsResponse) { + option (google.api.http) = { + get: "/v2/{parent=*/*/locations/*}/buckets" + additional_bindings { + get: "/v2/{parent=projects/*/locations/*}/buckets" + } + additional_bindings { + get: "/v2/{parent=organizations/*/locations/*}/buckets" + } + additional_bindings { + get: "/v2/{parent=folders/*/locations/*}/buckets" + } + additional_bindings { + get: "/v2/{parent=billingAccounts/*/locations/*}/buckets" + } + }; + option (google.api.method_signature) = "parent"; + } + + // Gets a bucket (Beta). + rpc GetBucket(GetBucketRequest) returns (LogBucket) { + option (google.api.http) = { + get: "/v2/{name=*/*/locations/*/buckets/*}" + additional_bindings { + get: "/v2/{name=projects/*/locations/*/buckets/*}" + } + additional_bindings { + get: "/v2/{name=organizations/*/locations/*/buckets/*}" + } + additional_bindings { + get: "/v2/{name=folders/*/locations/*/buckets/*}" + } + additional_bindings { + get: "/v2/{name=billingAccounts/*/buckets/*}" + } + }; + } + + // Updates a bucket. This method replaces the following fields in the + // existing bucket with values from the new bucket: `retention_period` + // + // If the retention period is decreased and the bucket is locked, + // FAILED_PRECONDITION will be returned. + // + // If the bucket has a LifecycleState of DELETE_REQUESTED, FAILED_PRECONDITION + // will be returned. + // + // A buckets region may not be modified after it is created. + // This method is in Beta. + rpc UpdateBucket(UpdateBucketRequest) returns (LogBucket) { + option (google.api.http) = { + patch: "/v2/{name=*/*/locations/*/buckets/*}" + body: "bucket" + additional_bindings { + patch: "/v2/{name=projects/*/locations/*/buckets/*}" + body: "bucket" + } + additional_bindings { + patch: "/v2/{name=organizations/*/locations/*/buckets/*}" + body: "bucket" + } + additional_bindings { + patch: "/v2/{name=folders/*/locations/*/buckets/*}" + body: "bucket" + } + additional_bindings { + patch: "/v2/{name=billingAccounts/*/locations/*/buckets/*}" + body: "bucket" + } + }; + } + // Lists sinks. rpc ListSinks(ListSinksRequest) returns (ListSinksResponse) { option (google.api.http) = { @@ -297,7 +382,8 @@ service ConfigServiceV2 { // the GCP organization. // // See [Enabling CMEK for Logs - // Router](/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" @@ -320,7 +406,8 @@ service ConfigServiceV2 { // 3) access to the key is disabled. // // See [Enabling CMEK for Logs - // Router](/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" @@ -333,6 +420,48 @@ service ConfigServiceV2 { } } +// Describes a repository of logs (Beta). +message LogBucket { + option (google.api.resource) = { + type: "logging.googleapis.com/LogBucket" + pattern: "projects/{project}/locations/{location}/buckets/{bucket}" + pattern: "organizations/{organization}/locations/{location}/buckets/{bucket}" + pattern: "folders/{folder}/locations/{location}/buckets/{bucket}" + pattern: "billingAccounts/{billing_account}/locations/{location}/buckets/{bucket}" + }; + + // The resource name of the bucket. + // For example: + // "projects/my-project-id/locations/my-location/buckets/my-bucket-id The + // supported locations are: + // "global" + // "us-central1" + // + // For the location of `global` it is unspecified where logs are actually + // stored. + // Once a bucket has been created, the location can not be changed. + string name = 1; + + // Describes this bucket. + string description = 3; + + // Output only. The creation timestamp of the bucket. This is not set for any of the + // default buckets. + google.protobuf.Timestamp create_time = 4 [(google.api.field_behavior) = OUTPUT_ONLY]; + + // Output only. The last update timestamp of the bucket. + google.protobuf.Timestamp update_time = 5 [(google.api.field_behavior) = OUTPUT_ONLY]; + + // Logs will be retained by default for this amount of time, after which they + // will automatically be deleted. The minimum retention period is 1 day. + // If this value is set to zero at bucket creation time, the default time of + // 30 days will be used. + int32 retention_days = 11; + + // Output only. The bucket lifecycle state. + LifecycleState lifecycle_state = 12 [(google.api.field_behavior) = OUTPUT_ONLY]; +} + // Describes a sink used to export log entries to one of the following // destinations in any project: a Cloud Storage bucket, a BigQuery dataset, or a // Cloud Pub/Sub topic. A logs filter controls which log entries are exported. @@ -340,16 +469,14 @@ service ConfigServiceV2 { // folder. message LogSink { option (google.api.resource) = { - type: "logging.googleapis.com/Sink" + type: "logging.googleapis.com/LogSink" pattern: "projects/{project}/sinks/{sink}" pattern: "organizations/{organization}/sinks/{sink}" pattern: "folders/{folder}/sinks/{sink}" 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; @@ -361,12 +488,12 @@ message LogSink { V1 = 2; } - // Required. The client-assigned sink identifier, unique within the - // project. Example: `"my-syslog-errors-to-pubsub"`. Sink identifiers are - // limited to 100 characters and can include only the following characters: - // upper and lower-case alphanumeric characters, underscores, hyphens, and - // periods. First character has to be alphanumeric. - string name = 1; + // Required. The client-assigned sink identifier, unique within the project. Example: + // `"my-syslog-errors-to-pubsub"`. Sink identifiers are limited to 100 + // characters and can include only the following characters: upper and + // lower-case alphanumeric characters, underscores, hyphens, and periods. + // First character has to be alphanumeric. + string name = 1 [(google.api.field_behavior) = REQUIRED]; // Required. The export destination: // @@ -377,42 +504,44 @@ 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](/logging/docs/api/tasks/exporting-logs). - string destination = 3 [(google.api.resource_reference) = { - type: "*" - }]; + // [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) = { + type: "*" + } + ]; - // Optional. An [advanced logs filter](/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; + string filter = 5 [(google.api.field_behavior) = OPTIONAL]; // Optional. A description of this sink. // The maximum length of the description is 8000 characters. - string description = 18; + string description = 18 [(google.api.field_behavior) = OPTIONAL]; // Optional. If set to True, then this sink is disabled and it does not // export any log entries. - bool disabled = 19; + 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 writes the exported log entries to the sink's destination. - // This field is set by - // [sinks.create][google.logging.v2.ConfigServiceV2.CreateSink] - // and - // [sinks.update][google.logging.v2.ConfigServiceV2.UpdateSink] - // based on the value of `unique_writer_identity` in those methods. + // Output only. An IAM identity–a service account or group—under which Logging + // writes the exported log entries to the sink's destination. This field is + // set by [sinks.create][google.logging.v2.ConfigServiceV2.CreateSink] and + // [sinks.update][google.logging.v2.ConfigServiceV2.UpdateSink] based on the + // value of `unique_writer_identity` in those methods. // // Until you grant this identity write-access to the destination, log entry // exports from this sink will fail. For more information, // see [Granting Access for a - // Resource](/iam/docs/granting-roles-to-service-accounts#granting_access_to_a_service_account_for_a_resource). + // Resource](https://cloud.google.com/iam/docs/granting-roles-to-service-accounts#granting_access_to_a_service_account_for_a_resource). // Consult the destination service's documentation to determine the // appropriate IAM roles to assign to the identity. string writer_identity = 8 [(google.api.field_behavior) = OUTPUT_ONLY]; @@ -430,12 +559,12 @@ message LogSink { // // logName:("projects/test-project1/" OR "projects/test-project2/") AND // resource.type=gce_instance - bool include_children = 9; + bool include_children = 9 [(google.api.field_behavior) = OPTIONAL]; - // Optional. Destination dependent options. + // Destination dependent options. oneof options { // Optional. Options that affect sinks exporting data to BigQuery. - BigQueryOptions bigquery_options = 12; + BigQueryOptions bigquery_options = 12 [(google.api.field_behavior) = OPTIONAL]; } // Output only. The creation timestamp of the sink. @@ -447,24 +576,19 @@ message LogSink { // // This field may not be present for older sinks. google.protobuf.Timestamp update_time = 14 [(google.api.field_behavior) = OUTPUT_ONLY]; - - // Do not use. This field is ignored. - google.protobuf.Timestamp start_time = 10 [deprecated = true]; - - // Do not use. This field is ignored. - google.protobuf.Timestamp end_time = 11 [deprecated = true]; } // Options that change functionality of a sink exporting data to BigQuery. message BigQueryOptions { // Optional. Whether to use [BigQuery's partition - // tables](/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](/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; + // 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, // false if legacy ingestion-time partitioning is in use. @@ -475,6 +599,114 @@ message BigQueryOptions { bool uses_timestamp_column_partitioning = 3 [(google.api.field_behavior) = OUTPUT_ONLY]; } +// LogBucket lifecycle states (Beta). +enum LifecycleState { + // Unspecified state. This is only used/useful for distinguishing + // unset values. + LIFECYCLE_STATE_UNSPECIFIED = 0; + + // The normal and active state. + ACTIVE = 1; + + // The bucket has been marked for deletion by the user. + DELETE_REQUESTED = 2; +} + +// The parameters to `ListBuckets` (Beta). +message ListBucketsRequest { + // Required. The parent resource whose buckets are to be listed: + // + // "projects/[PROJECT_ID]/locations/[LOCATION_ID]" + // "organizations/[ORGANIZATION_ID]/locations/[LOCATION_ID]" + // "billingAccounts/[BILLING_ACCOUNT_ID]/locations/[LOCATION_ID]" + // "folders/[FOLDER_ID]/locations/[LOCATION_ID]" + // + // Note: The locations portion of the resource must be specified, but + // supplying the character `-` in place of [LOCATION_ID] will return all + // buckets. + string parent = 1 [ + (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 + // `nextPageToken` from the previous response. The values of other method + // parameters should be identical to those in the previous call. + string page_token = 2 [(google.api.field_behavior) = OPTIONAL]; + + // Optional. The maximum number of results to return from this request. + // Non-positive values are ignored. The presence of `nextPageToken` in the + // response indicates that more results might be available. + int32 page_size = 3 [(google.api.field_behavior) = OPTIONAL]; +} + +// The response from ListBuckets (Beta). +message ListBucketsResponse { + // A list of buckets. + repeated LogBucket buckets = 1; + + // If there might be more results than appear in this response, then + // `nextPageToken` is included. To get the next set of results, call the same + // method again using the value of `nextPageToken` as `pageToken`. + string next_page_token = 2; +} + +// The parameters to `UpdateBucket` (Beta). +message UpdateBucketRequest { + // Required. The full resource name of the bucket to update. + // + // "projects/[PROJECT_ID]/locations/[LOCATION_ID]/buckets/[BUCKET_ID]" + // "organizations/[ORGANIZATION_ID]/locations/[LOCATION_ID]/buckets/[BUCKET_ID]" + // "billingAccounts/[BILLING_ACCOUNT_ID]/locations/[LOCATION_ID]/buckets/[BUCKET_ID]" + // "folders/[FOLDER_ID]/locations/[LOCATION_ID]/buckets/[BUCKET_ID]" + // + // Example: + // `"projects/my-project-id/locations/my-location/buckets/my-bucket-id"`. Also + // requires permission "resourcemanager.projects.updateLiens" to set the + // locked property + string name = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "logging.googleapis.com/LogBucket" + } + ]; + + // Required. The updated bucket. + LogBucket bucket = 2 [(google.api.field_behavior) = REQUIRED]; + + // Required. Field mask that specifies the fields in `bucket` that need an update. A + // bucket field will be overwritten if, and only if, it is in the update + // mask. `name` and output only fields cannot be updated. + // + // For a detailed `FieldMask` definition, see + // https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#google.protobuf.FieldMask + // + // Example: `updateMask=retention_days`. + google.protobuf.FieldMask update_mask = 4 [(google.api.field_behavior) = REQUIRED]; +} + +// The parameters to `GetBucket` (Beta). +message GetBucketRequest { + // Required. The resource name of the bucket: + // + // "projects/[PROJECT_ID]/locations/[LOCATION_ID]/buckets/[BUCKET_ID]" + // "organizations/[ORGANIZATION_ID]/locations/[LOCATION_ID]/buckets/[BUCKET_ID]" + // "billingAccounts/[BILLING_ACCOUNT_ID]/locations/[LOCATION_ID]/buckets/[BUCKET_ID]" + // "folders/[FOLDER_ID]/locations/[LOCATION_ID]/buckets/[BUCKET_ID]" + // + // Example: + // `"projects/my-project-id/locations/my-location/buckets/my-bucket-id"`. + string name = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "logging.googleapis.com/LogBucket" + } + ]; +} + // The parameters to `ListSinks`. message ListSinksRequest { // Required. The parent resource whose sinks are to be listed: @@ -486,7 +718,7 @@ message ListSinksRequest { string parent = 1 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { - child_type: "logging.googleapis.com/Sink" + child_type: "logging.googleapis.com/LogSink" } ]; @@ -494,12 +726,12 @@ message ListSinksRequest { // preceding call to this method. `pageToken` must be the value of // `nextPageToken` from the previous response. The values of other method // parameters should be identical to those in the previous call. - string page_token = 2; + string page_token = 2 [(google.api.field_behavior) = OPTIONAL]; // Optional. The maximum number of results to return from this request. // Non-positive values are ignored. The presence of `nextPageToken` in the // response indicates that more results might be available. - int32 page_size = 3; + int32 page_size = 3 [(google.api.field_behavior) = OPTIONAL]; } // Result returned from `ListSinks`. @@ -526,7 +758,7 @@ message GetSinkRequest { string sink_name = 1 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { - type: "logging.googleapis.com/Sink" + type: "logging.googleapis.com/LogSink" } ]; } @@ -544,7 +776,7 @@ message CreateSinkRequest { string parent = 1 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { - child_type: "logging.googleapis.com/Sink" + child_type: "logging.googleapis.com/LogSink" } ]; @@ -563,13 +795,13 @@ message CreateSinkRequest { // resource such as an organization, then the value of `writer_identity` will // be a unique service account used only for exports from the new sink. For // more information, see `writer_identity` in [LogSink][google.logging.v2.LogSink]. - bool unique_writer_identity = 3; + bool unique_writer_identity = 3 [(google.api.field_behavior) = OPTIONAL]; } // The parameters to `UpdateSink`. message UpdateSinkRequest { - // Required. The full resource name of the sink to update, including the - // parent resource and the sink identifier: + // Required. The full resource name of the sink to update, including the parent + // resource and the sink identifier: // // "projects/[PROJECT_ID]/sinks/[SINK_ID]" // "organizations/[ORGANIZATION_ID]/sinks/[SINK_ID]" @@ -580,12 +812,12 @@ message UpdateSinkRequest { string sink_name = 1 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { - type: "logging.googleapis.com/Sink" + type: "logging.googleapis.com/LogSink" } ]; - // Required. The updated sink, whose name is the same identifier that appears - // as part of `sink_name`. + // Required. The updated sink, whose name is the same identifier that appears as part + // of `sink_name`. LogSink sink = 2 [(google.api.field_behavior) = REQUIRED]; // Optional. See [sinks.create][google.logging.v2.ConfigServiceV2.CreateSink] @@ -599,7 +831,7 @@ message UpdateSinkRequest { // `writer_identity` is changed to a unique service account. // + It is an error if the old value is true and the new value is // set to false or defaulted to false. - bool unique_writer_identity = 3; + bool unique_writer_identity = 3 [(google.api.field_behavior) = OPTIONAL]; // Optional. Field mask that specifies the fields in `sink` that need // an update. A sink field will be overwritten if, and only if, it is @@ -615,13 +847,13 @@ message UpdateSinkRequest { // https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#google.protobuf.FieldMask // // Example: `updateMask=filter`. - google.protobuf.FieldMask update_mask = 4; + google.protobuf.FieldMask update_mask = 4 [(google.api.field_behavior) = OPTIONAL]; } // The parameters to `DeleteSink`. message DeleteSinkRequest { - // Required. The full resource name of the sink to delete, including the - // parent resource and the sink identifier: + // Required. The full resource name of the sink to delete, including the parent + // resource and the sink identifier: // // "projects/[PROJECT_ID]/sinks/[SINK_ID]" // "organizations/[ORGANIZATION_ID]/sinks/[SINK_ID]" @@ -632,7 +864,7 @@ message DeleteSinkRequest { string sink_name = 1 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { - type: "logging.googleapis.com/Sink" + type: "logging.googleapis.com/LogSink" } ]; } @@ -645,47 +877,48 @@ message DeleteSinkRequest { // apply to child resources, and that you can't exclude audit log entries. message LogExclusion { option (google.api.resource) = { - type: "logging.googleapis.com/Exclusion" + type: "logging.googleapis.com/LogExclusion" pattern: "projects/{project}/exclusions/{exclusion}" pattern: "organizations/{organization}/exclusions/{exclusion}" pattern: "folders/{folder}/exclusions/{exclusion}" pattern: "billingAccounts/{billing_account}/exclusions/{exclusion}" }; - // Required. A client-assigned identifier, such as - // `"load-balancer-exclusion"`. Identifiers are limited to 100 characters and - // can include only letters, digits, underscores, hyphens, and periods. - // First character has to be alphanumeric. - string name = 1; + // Required. A client-assigned identifier, such as `"load-balancer-exclusion"`. + // Identifiers are limited to 100 characters and can include only letters, + // digits, underscores, hyphens, and periods. First character has to be + // alphanumeric. + string name = 1 [(google.api.field_behavior) = REQUIRED]; // Optional. A description of this exclusion. - string description = 2; + string description = 2 [(google.api.field_behavior) = OPTIONAL]; - // Required. An [advanced logs filter](/logging/docs/view/advanced-queries) - // that matches the log entries to be excluded. By using the - // [sample function](/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: // // `"resource.type=gcs_bucket severity=ERROR" // // The maximum length of the filter is 20000 characters. - string filter = 3; + string filter = 3 [(google.api.field_behavior) = REQUIRED]; // Optional. The metric descriptor associated with the logs-based metric. // If unspecified, it uses a default metric descriptor with a DELTA metric @@ -160,7 +160,7 @@ message LogMetric { // be updated once initially configured. New labels can be added in the // `metric_descriptor`, but existing labels cannot be modified except for // their description. - google.api.MetricDescriptor metric_descriptor = 5; + google.api.MetricDescriptor metric_descriptor = 5 [(google.api.field_behavior) = OPTIONAL]; // Optional. A `value_extractor` is required when using a distribution // logs-based metric to extract the values to record from a log entry. @@ -181,7 +181,7 @@ message LogMetric { // distribution. // // Example: `REGEXP_EXTRACT(jsonPayload.request, ".*quantity=(\d+).*")` - string value_extractor = 6; + string value_extractor = 6 [(google.api.field_behavior) = OPTIONAL]; // Optional. A map from a label key string to an extractor expression which is // used to extract data from a log entry field and assign as the label value. @@ -197,22 +197,22 @@ message LogMetric { // // Note that there are upper bounds on the maximum number of labels and the // number of active time series that are allowed in a project. - map label_extractors = 7; + map label_extractors = 7 [(google.api.field_behavior) = OPTIONAL]; // Optional. The `bucket_options` are required when the logs-based metric is // using a DISTRIBUTION value type and it describes the bucket boundaries // used to create a histogram of the extracted values. - google.api.Distribution.BucketOptions bucket_options = 8; + google.api.Distribution.BucketOptions bucket_options = 8 [(google.api.field_behavior) = OPTIONAL]; // Output only. The creation timestamp of the metric. // // This field may not be present for older metrics. - google.protobuf.Timestamp create_time = 9; + google.protobuf.Timestamp create_time = 9 [(google.api.field_behavior) = OUTPUT_ONLY]; // Output only. The last update timestamp of the metric. // // This field may not be present for older metrics. - google.protobuf.Timestamp update_time = 10; + google.protobuf.Timestamp update_time = 10 [(google.api.field_behavior) = OUTPUT_ONLY]; // Deprecated. The API version that created or updated this metric. // The v2 format is used by default and cannot be changed. @@ -235,12 +235,12 @@ message ListLogMetricsRequest { // preceding call to this method. `pageToken` must be the value of // `nextPageToken` from the previous response. The values of other method // parameters should be identical to those in the previous call. - string page_token = 2; + string page_token = 2 [(google.api.field_behavior) = OPTIONAL]; // Optional. The maximum number of results to return from this request. // Non-positive values are ignored. The presence of `nextPageToken` in the // response indicates that more results might be available. - int32 page_size = 3; + int32 page_size = 3 [(google.api.field_behavior) = OPTIONAL]; } // Result returned from ListLogMetrics. @@ -262,7 +262,7 @@ message GetLogMetricRequest { string metric_name = 1 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { - type: "logging.googleapis.com/Metric" + type: "logging.googleapis.com/LogMetric" } ]; } @@ -277,7 +277,7 @@ message CreateLogMetricRequest { string parent = 1 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { - type: "logging.googleapis.com/Metric" + child_type: "logging.googleapis.com/LogMetric" } ]; @@ -298,7 +298,7 @@ message UpdateLogMetricRequest { string metric_name = 1 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { - type: "logging.googleapis.com/Metric" + type: "logging.googleapis.com/LogMetric" } ]; @@ -314,7 +314,7 @@ message DeleteLogMetricRequest { string metric_name = 1 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { - type: "logging.googleapis.com/Metric" + type: "logging.googleapis.com/LogMetric" } ]; } diff --git a/scripts/decrypt-secrets.sh b/scripts/decrypt-secrets.sh index ff599eb2a..21f6d2a26 100755 --- a/scripts/decrypt-secrets.sh +++ b/scripts/decrypt-secrets.sh @@ -20,14 +20,27 @@ ROOT=$( dirname "$DIR" ) # Work from the project root. cd $ROOT +# Prevent it from overriding files. +# We recommend that sample authors use their own service account files and cloud project. +# In that case, they are supposed to prepare these files by themselves. +if [[ -f "testing/test-env.sh" ]] || \ + [[ -f "testing/service-account.json" ]] || \ + [[ -f "testing/client-secrets.json" ]]; then + echo "One or more target files exist, aborting." + exit 1 +fi + # Use SECRET_MANAGER_PROJECT if set, fallback to cloud-devrel-kokoro-resources. PROJECT_ID="${SECRET_MANAGER_PROJECT:-cloud-devrel-kokoro-resources}" gcloud secrets versions access latest --secret="python-docs-samples-test-env" \ + --project="${PROJECT_ID}" \ > testing/test-env.sh gcloud secrets versions access latest \ --secret="python-docs-samples-service-account" \ + --project="${PROJECT_ID}" \ > testing/service-account.json gcloud secrets versions access latest \ --secret="python-docs-samples-client-secrets" \ - > testing/client-secrets.json \ No newline at end of file + --project="${PROJECT_ID}" \ + > testing/client-secrets.json diff --git a/scripts/readme-gen/readme_gen.py b/scripts/readme-gen/readme_gen.py new file mode 100644 index 000000000..d309d6e97 --- /dev/null +++ b/scripts/readme-gen/readme_gen.py @@ -0,0 +1,66 @@ +#!/usr/bin/env python + +# Copyright 2016 Google Inc +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +"""Generates READMEs using configuration defined in yaml.""" + +import argparse +import io +import os +import subprocess + +import jinja2 +import yaml + + +jinja_env = jinja2.Environment( + trim_blocks=True, + loader=jinja2.FileSystemLoader( + os.path.abspath(os.path.join(os.path.dirname(__file__), 'templates')))) + +README_TMPL = jinja_env.get_template('README.tmpl.rst') + + +def get_help(file): + return subprocess.check_output(['python', file, '--help']).decode() + + +def main(): + parser = argparse.ArgumentParser() + parser.add_argument('source') + parser.add_argument('--destination', default='README.rst') + + args = parser.parse_args() + + source = os.path.abspath(args.source) + root = os.path.dirname(source) + destination = os.path.join(root, args.destination) + + jinja_env.globals['get_help'] = get_help + + with io.open(source, 'r') as f: + config = yaml.load(f) + + # This allows get_help to execute in the right directory. + os.chdir(root) + + output = README_TMPL.render(config) + + with io.open(destination, 'w') as f: + f.write(output) + + +if __name__ == '__main__': + main() diff --git a/scripts/readme-gen/templates/README.tmpl.rst b/scripts/readme-gen/templates/README.tmpl.rst new file mode 100644 index 000000000..4fd239765 --- /dev/null +++ b/scripts/readme-gen/templates/README.tmpl.rst @@ -0,0 +1,87 @@ +{# The following line is a lie. BUT! Once jinja2 is done with it, it will + become truth! #} +.. This file is automatically generated. Do not edit this file directly. + +{{product.name}} Python Samples +=============================================================================== + +.. image:: https://gstatic.com/cloudssh/images/open-btn.png + :target: https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/GoogleCloudPlatform/python-docs-samples&page=editor&open_in_editor={{folder}}/README.rst + + +This directory contains samples for {{product.name}}. {{product.description}} + +{{description}} + +.. _{{product.name}}: {{product.url}} + +{% if required_api_url %} +To run the sample, you need to enable the API at: {{required_api_url}} +{% endif %} + +{% if required_role %} +To run the sample, you need to have `{{required_role}}` role. +{% endif %} + +{{other_required_steps}} + +{% if setup %} +Setup +------------------------------------------------------------------------------- + +{% for section in setup %} + +{% include section + '.tmpl.rst' %} + +{% endfor %} +{% endif %} + +{% if samples %} +Samples +------------------------------------------------------------------------------- + +{% for sample in samples %} +{{sample.name}} ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +{% if not sample.hide_cloudshell_button %} +.. image:: https://gstatic.com/cloudssh/images/open-btn.png + :target: https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/GoogleCloudPlatform/python-docs-samples&page=editor&open_in_editor={{folder}}/{{sample.file}},{{folder}}/README.rst +{% endif %} + + +{{sample.description}} + +To run this sample: + +.. code-block:: bash + + $ python {{sample.file}} +{% if sample.show_help %} + + {{get_help(sample.file)|indent}} +{% endif %} + + +{% endfor %} +{% endif %} + +{% if cloud_client_library %} + +The client library +------------------------------------------------------------------------------- + +This sample uses the `Google Cloud Client Library for Python`_. +You can read the documentation for more details on API usage and use GitHub +to `browse the source`_ and `report issues`_. + +.. _Google Cloud Client Library for Python: + https://googlecloudplatform.github.io/google-cloud-python/ +.. _browse the source: + https://github.com/GoogleCloudPlatform/google-cloud-python +.. _report issues: + https://github.com/GoogleCloudPlatform/google-cloud-python/issues + +{% endif %} + +.. _Google Cloud SDK: https://cloud.google.com/sdk/ \ No newline at end of file diff --git a/scripts/readme-gen/templates/auth.tmpl.rst b/scripts/readme-gen/templates/auth.tmpl.rst new file mode 100644 index 000000000..1446b94a5 --- /dev/null +++ b/scripts/readme-gen/templates/auth.tmpl.rst @@ -0,0 +1,9 @@ +Authentication +++++++++++++++ + +This sample requires you to have authentication setup. Refer to the +`Authentication Getting Started Guide`_ for instructions on setting up +credentials for applications. + +.. _Authentication Getting Started Guide: + https://cloud.google.com/docs/authentication/getting-started diff --git a/scripts/readme-gen/templates/auth_api_key.tmpl.rst b/scripts/readme-gen/templates/auth_api_key.tmpl.rst new file mode 100644 index 000000000..11957ce27 --- /dev/null +++ b/scripts/readme-gen/templates/auth_api_key.tmpl.rst @@ -0,0 +1,14 @@ +Authentication +++++++++++++++ + +Authentication for this service is done via an `API Key`_. To obtain an API +Key: + +1. Open the `Cloud Platform Console`_ +2. Make sure that billing is enabled for your project. +3. From the **Credentials** page, create a new **API Key** or use an existing + one for your project. + +.. _API Key: + https://developers.google.com/api-client-library/python/guide/aaa_apikeys +.. _Cloud Console: https://console.cloud.google.com/project?_ diff --git a/scripts/readme-gen/templates/install_deps.tmpl.rst b/scripts/readme-gen/templates/install_deps.tmpl.rst new file mode 100644 index 000000000..a0406dba8 --- /dev/null +++ b/scripts/readme-gen/templates/install_deps.tmpl.rst @@ -0,0 +1,29 @@ +Install Dependencies +++++++++++++++++++++ + +#. Clone python-docs-samples and change directory to the sample directory you want to use. + + .. code-block:: bash + + $ git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git + +#. Install `pip`_ and `virtualenv`_ if you do not already have them. You may want to refer to the `Python Development Environment Setup Guide`_ for Google Cloud Platform for instructions. + + .. _Python Development Environment Setup Guide: + https://cloud.google.com/python/setup + +#. Create a virtualenv. Samples are compatible with Python 2.7 and 3.4+. + + .. code-block:: bash + + $ virtualenv env + $ source env/bin/activate + +#. Install the dependencies needed to run the samples. + + .. code-block:: bash + + $ pip install -r requirements.txt + +.. _pip: https://pip.pypa.io/ +.. _virtualenv: https://virtualenv.pypa.io/ diff --git a/scripts/readme-gen/templates/install_portaudio.tmpl.rst b/scripts/readme-gen/templates/install_portaudio.tmpl.rst new file mode 100644 index 000000000..5ea33d18c --- /dev/null +++ b/scripts/readme-gen/templates/install_portaudio.tmpl.rst @@ -0,0 +1,35 @@ +Install PortAudio ++++++++++++++++++ + +Install `PortAudio`_. This is required by the `PyAudio`_ library to stream +audio from your computer's microphone. PyAudio depends on PortAudio for cross-platform compatibility, and is installed differently depending on the +platform. + +* For Mac OS X, you can use `Homebrew`_:: + + brew install portaudio + + **Note**: if you encounter an error when running `pip install` that indicates + it can't find `portaudio.h`, try running `pip install` with the following + flags:: + + pip install --global-option='build_ext' \ + --global-option='-I/usr/local/include' \ + --global-option='-L/usr/local/lib' \ + pyaudio + +* For Debian / Ubuntu Linux:: + + apt-get install portaudio19-dev python-all-dev + +* Windows may work without having to install PortAudio explicitly (it will get + installed with PyAudio). + +For more details, see the `PyAudio installation`_ page. + + +.. _PyAudio: https://people.csail.mit.edu/hubert/pyaudio/ +.. _PortAudio: http://www.portaudio.com/ +.. _PyAudio installation: + https://people.csail.mit.edu/hubert/pyaudio/#downloads +.. _Homebrew: http://brew.sh diff --git a/synth.metadata b/synth.metadata index a5616d3e5..ff0272d65 100644 --- a/synth.metadata +++ b/synth.metadata @@ -1,32 +1,25 @@ { "sources": [ - { - "generator": { - "name": "artman", - "version": "2.0.0", - "dockerImage": "googleapis/artman@sha256:b3b47805231a305d0f40c4bf069df20f6a2635574e6d4259fac651d3f9f6e098" - } - }, { "git": { "name": ".", - "remote": "git@github.com:googleapis/python-logging", - "sha": "a22a3bfdd4c8a4d6e9cc0c7d7504322ff31ad7ea" + "remote": "https://github.com/googleapis/python-logging.git", + "sha": "0a1dd94811232634fdb849cb2c85bd44e870642f" } }, { "git": { "name": "googleapis", "remote": "https://github.com/googleapis/googleapis.git", - "sha": "aaff764c185e18a6c73227357c3df5fa60fec85a", - "internalRef": "309426927" + "sha": "e5211c547d63632963f9125e2b333185d57ff8f6", + "internalRef": "337519886" } }, { "git": { "name": "synthtool", "remote": "https://github.com/googleapis/synthtool.git", - "sha": "cdddf139b36000b3a7c65fd2a7781e253262359a" + "sha": "da5c6050d13b4950c82666a81d8acd25157664ae" } } ], @@ -37,9 +30,77 @@ "apiName": "logging", "apiVersion": "v2", "language": "python", - "generator": "gapic", - "config": "google/logging/artman_logging.yaml" + "generator": "bazel" } } + ], + "generatedFiles": [ + ".coveragerc", + ".flake8", + ".github/CONTRIBUTING.md", + ".github/ISSUE_TEMPLATE/bug_report.md", + ".github/ISSUE_TEMPLATE/feature_request.md", + ".github/ISSUE_TEMPLATE/support_request.md", + ".github/PULL_REQUEST_TEMPLATE.md", + ".github/release-please.yml", + ".github/snippet-bot.yml", + ".gitignore", + ".kokoro/build.sh", + ".kokoro/continuous/common.cfg", + ".kokoro/continuous/continuous.cfg", + ".kokoro/docker/docs/Dockerfile", + ".kokoro/docker/docs/fetch_gpg_keys.sh", + ".kokoro/docs/common.cfg", + ".kokoro/docs/docs-presubmit.cfg", + ".kokoro/docs/docs.cfg", + ".kokoro/populate-secrets.sh", + ".kokoro/presubmit/common.cfg", + ".kokoro/presubmit/presubmit.cfg", + ".kokoro/publish-docs.sh", + ".kokoro/release.sh", + ".kokoro/release/common.cfg", + ".kokoro/release/release.cfg", + ".kokoro/samples/lint/common.cfg", + ".kokoro/samples/lint/continuous.cfg", + ".kokoro/samples/lint/periodic.cfg", + ".kokoro/samples/lint/presubmit.cfg", + ".kokoro/samples/python3.6/common.cfg", + ".kokoro/samples/python3.6/continuous.cfg", + ".kokoro/samples/python3.6/periodic.cfg", + ".kokoro/samples/python3.6/presubmit.cfg", + ".kokoro/samples/python3.7/common.cfg", + ".kokoro/samples/python3.7/continuous.cfg", + ".kokoro/samples/python3.7/periodic.cfg", + ".kokoro/samples/python3.7/presubmit.cfg", + ".kokoro/samples/python3.8/common.cfg", + ".kokoro/samples/python3.8/continuous.cfg", + ".kokoro/samples/python3.8/periodic.cfg", + ".kokoro/samples/python3.8/presubmit.cfg", + ".kokoro/test-samples.sh", + ".kokoro/trampoline.sh", + ".kokoro/trampoline_v2.sh", + ".trampolinerc", + "CODE_OF_CONDUCT.md", + "CONTRIBUTING.rst", + "LICENSE", + "MANIFEST.in", + "docs/_static/custom.css", + "docs/_templates/layout.html", + "docs/conf.py", + "docs/multiprocessing.rst", + "google/cloud/logging_v2/proto/log_entry.proto", + "google/cloud/logging_v2/proto/logging.proto", + "google/cloud/logging_v2/proto/logging_config.proto", + "google/cloud/logging_v2/proto/logging_metrics.proto", + "renovate.json", + "scripts/decrypt-secrets.sh", + "scripts/readme-gen/readme_gen.py", + "scripts/readme-gen/templates/README.tmpl.rst", + "scripts/readme-gen/templates/auth.tmpl.rst", + "scripts/readme-gen/templates/auth_api_key.tmpl.rst", + "scripts/readme-gen/templates/install_deps.tmpl.rst", + "scripts/readme-gen/templates/install_portaudio.tmpl.rst", + "setup.cfg", + "testing/.gitignore" ] } \ No newline at end of file