google-cloud-logging 0.21.2 → 0.23.0

data/lib/google/cloud/logging/v2/doc/google/logging/v2/logging_config.rb

@@ -15,33 +15,38 @@
 module Google
   module Logging
     module V2
-      # Describes a sink used to export log entries outside Stackdriver Logging.
+      # Describes a sink used to export log entries outside of Stackdriver Logging.
+      # A logs filter controls which log entries are exported.  Sinks can have a
+      # start time and an end time; these can be used to place log entries from an
+      # exact time range into a particular destination.  If both +start_time+ and
+      # +end_time+ are present, then +start_time+ must be less than +end_time+.
       # @!attribute [rw] name
       #   @return [String]
       #     Required. The client-assigned sink identifier, unique within the
       #     project. Example: +"my-syslog-errors-to-pubsub"+.  Sink identifiers are
-      #     limited to 1000 characters and can include only the following characters:
-      #     +A-Z+, +a-z+, +0-9+, and the special characters +_-.+.  The maximum length
-      #     of the name is 100 characters.
+      #     limited to 100 characters and can include only the following characters:
+      #     upper and lower-case alphanumeric characters, underscores, hyphens, and
+      #     periods.
       # @!attribute [rw] destination
       #   @return [String]
-      #     Required. The export destination. See
-      #     {Exporting Logs With Sinks}[https://cloud.google.com/logging/docs/api/tasks/exporting-logs].
-      #     Examples:
+      #     Required. The export destination:
+      #
+      #         "storage.googleapis.com/[GCS_BUCKET]"
+      #         "bigquery.googleapis.com/projects/[PROJECT_ID]/datasets/[DATASET]"
+      #         "pubsub.googleapis.com/projects/[PROJECT_ID]/topics/[TOPIC_ID]"
       #
-      #         "storage.googleapis.com/my-gcs-bucket"
-      #         "bigquery.googleapis.com/projects/my-project-id/datasets/my-dataset"
-      #         "pubsub.googleapis.com/projects/my-project/topics/my-topic"
+      #     For more information,  see
+      #     {Exporting Logs With Sinks}[https://cloud.google.com/logging/docs/api/tasks/exporting-logs].
       # @!attribute [rw] filter
       #   @return [String]
       #     Optional. An {advanced logs filter}[https://cloud.google.com/logging/docs/view/advanced_filters].
       #     Only log entries matching the filter are exported. The filter
       #     must be consistent with the log entry format specified by the
       #     +outputVersionFormat+ parameter, regardless of the format of the
-      #     log entry that was originally written to Stackdriver Logging.
-      #     Example filter (V2 format):
+      #     log entry that was originally ingested by Stackdriver Logging.
+      #     The following example uses field names in the v2 log entry format:
       #
-      #         logName=projects/my-projectid/logs/syslog AND severity>=ERROR
+      #         logName="projects/[PROJECT_ID]/logs/[LOG_ID]" AND severity>=ERROR
       # @!attribute [rw] output_version_format
       #   @return [Google::Logging::V2::LogSink::VersionFormat]
       #     Optional. The log entry version to use for this sink's exported log
@@ -50,18 +55,23 @@ module Google
       #     v2 format is used.
       # @!attribute [rw] writer_identity
       #   @return [String]
-      #     Output only. The iam identity to which the destination needs to grant write
-      #     access.  This may be a service account or a group.
-      #     Examples (Do not assume these specific values):
-      #        "serviceAccount:cloud-logs@system.gserviceaccount.com"
-      #        "group:cloud-logs@google.com"
-      #
-      #       For GCS destinations, the role "roles/owner" is required on the bucket
-      #       For Cloud Pubsub destinations, the role "roles/pubsub.publisher" is
-      #         required on the topic
-      #       For BigQuery, the role "roles/editor" is required on the dataset
+      #     Output only. An IAM identity—a service account or group—that
+      #     will write exported log entries to the destination on behalf of Stackdriver
+      #     Logging. You must grant this identity write-access to the destination.
+      #     Consult the destination service's documentation to determine the exact role
+      #     that must be granted.
+      # @!attribute [rw] start_time
+      #   @return [Google::Protobuf::Timestamp]
+      #     Optional. The time at which this sink will begin exporting log entries.  If
+      #     this value is present, then log entries are exported only if +start_time+
+      #     <=+entry.timestamp+.
+      # @!attribute [rw] end_time
+      #   @return [Google::Protobuf::Timestamp]
+      #     Optional. Time at which this sink will stop exporting log entries.  If this
+      #     value is present, then log entries are exported only if +entry.timestamp+ <
+      #     +end_time+.
       class LogSink
-        # Available log entry formats. Log entries can be written to Cloud
+        # Available log entry formats. Log entries can be written to Stackdriver
         # Logging in either format and can be exported in either format.
         # Version 2 is the preferred format.
         module VersionFormat
@@ -79,8 +89,10 @@ module Google
       # The parameters to +ListSinks+.
       # @!attribute [rw] parent
       #   @return [String]
-      #     Required. The cloud resource containing the sinks.
-      #     Example: +"projects/my-logging-project"+.
+      #     Required. The resource name where this sink was created:
+      #
+      #         "projects/[PROJECT_ID]"
+      #         "organizations/[ORGANIZATION_ID]"
       # @!attribute [rw] page_token
       #   @return [String]
       #     Optional. If present, then retrieve the next batch of results from the
@@ -108,42 +120,66 @@ module Google
       # The parameters to +GetSink+.
       # @!attribute [rw] sink_name
       #   @return [String]
-      #     Required. The resource name of the sink to return.
-      #     Example: +"projects/my-project-id/sinks/my-sink-id"+.
+      #     Required. The resource name of the sink to return:
+      #
+      #         "projects/[PROJECT_ID]/sinks/[SINK_ID]"
+      #         "organizations/[ORGANIZATION_ID]/sinks/[SINK_ID]"
       class GetSinkRequest; end
 
       # The parameters to +CreateSink+.
       # @!attribute [rw] parent
       #   @return [String]
-      #     Required. The resource in which to create the sink.
-      #     Example: +"projects/my-project-id"+.
-      #     The new sink must be provided in the request.
+      #     Required. The resource in which to create the sink:
+      #
+      #         "projects/[PROJECT_ID]"
+      #         "organizations/[ORGANIZATION_ID]"
       # @!attribute [rw] sink
       #   @return [Google::Logging::V2::LogSink]
       #     Required. The new sink, whose +name+ parameter is a sink identifier that
       #     is not already in use.
+      # @!attribute [rw] unique_writer_identity
+      #   @return [true, false]
+      #     Optional. Whether the sink will have a dedicated service account returned
+      #     in the sink's writer_identity. Set this field to be true to export
+      #     logs from one project to a different project. This field is ignored for
+      #     non-project sinks (e.g. organization sinks) because those sinks are
+      #     required to have dedicated service accounts.
       class CreateSinkRequest; end
 
       # The parameters to +UpdateSink+.
       # @!attribute [rw] sink_name
       #   @return [String]
       #     Required. The resource name of the sink to update, including the parent
-      #     resource and the sink identifier.  If the sink does not exist, this method
-      #     creates the sink.  Example: +"projects/my-project-id/sinks/my-sink-id"+.
+      #     resource and the sink identifier:
+      #
+      #         "projects/[PROJECT_ID]/sinks/[SINK_ID]"
+      #         "organizations/[ORGANIZATION_ID]/sinks/[SINK_ID]"
+      #
+      #     Example: +"projects/my-project-id/sinks/my-sink-id"+.
       # @!attribute [rw] sink
       #   @return [Google::Logging::V2::LogSink]
       #     Required. The updated sink, whose name is the same identifier that appears
       #     as part of +sinkName+.  If +sinkName+ does not exist, then
       #     this method creates a new sink.
+      # @!attribute [rw] unique_writer_identity
+      #   @return [true, false]
+      #     Optional. Whether the sink will have a dedicated service account returned
+      #     in the sink's writer_identity. Set this field to be true to export
+      #     logs from one project to a different project. This field is ignored for
+      #     non-project sinks (e.g. organization sinks) because those sinks are
+      #     required to have dedicated service accounts.
       class UpdateSinkRequest; end
 
       # The parameters to +DeleteSink+.
       # @!attribute [rw] sink_name
       #   @return [String]
       #     Required. The resource name of the sink to delete, including the parent
-      #     resource and the sink identifier.  Example:
-      #     +"projects/my-project-id/sinks/my-sink-id"+.  It is an error if the sink
-      #     does not exist.
+      #     resource and the sink identifier:
+      #
+      #         "projects/[PROJECT_ID]/sinks/[SINK_ID]"
+      #         "organizations/[ORGANIZATION_ID]/sinks/[SINK_ID]"
+      #
+      #     It is an error if the sink does not exist.
       class DeleteSinkRequest; end
     end
   end

data/lib/google/cloud/logging/v2/doc/google/logging/v2/logging_metrics.rb

@@ -19,21 +19,32 @@ module Google
       # number of log entries that match a logs filter.
       # @!attribute [rw] name
       #   @return [String]
-      #     Required. The client-assigned metric identifier. Example:
-      #     +"severe_errors"+.  Metric identifiers are limited to 100
-      #     characters and can include only the following characters: +A-Z+,
-      #     +a-z+, +0-9+, and the special characters +_-.,+!*',()%/+.  The
-      #     forward-slash character (+/+) denotes a hierarchy of name pieces,
-      #     and it cannot be the first character of the name.  The '%' character
-      #     is used to URL encode unsafe and reserved characters and must be
-      #     followed by two hexadecimal digits according to RFC 1738.
+      #     Required. The client-assigned metric identifier.
+      #     Examples: +"error_count"+, +"nginx/requests"+.
+      #
+      #     Metric identifiers are limited to 100 characters and can include
+      #     only the following characters: +A-Z+, +a-z+, +0-9+, and the
+      #     special characters +_-.,+!*',()%/+.  The forward-slash character
+      #     (+/+) denotes a hierarchy of name pieces, and it cannot be the
+      #     first character of the name.
+      #
+      #     The metric identifier in this field must not be
+      #     {URL-encoded}[https://en.wikipedia.org/wiki/Percent-encoding].
+      #     However, when the metric identifier appears as the +[METRIC_ID]+
+      #     part of a +metric_name+ API parameter, then the metric identifier
+      #     must be URL-encoded. Example:
+      #     +"projects/my-project/metrics/nginx%2Frequests"+.
       # @!attribute [rw] description
       #   @return [String]
       #     Optional. A description of this metric, which is used in documentation.
       # @!attribute [rw] filter
       #   @return [String]
       #     Required. An {advanced logs filter}[https://cloud.google.com/logging/docs/view/advanced_filters].
-      #     Example: +"resource.type=gae_app AND severity>=ERROR"+.
+      #     Example:
+      #
+      #         "resource.type=gae_app AND severity>=ERROR"
+      #
+      #     The maximum length of the filter is 20000 characters.
       # @!attribute [rw] version
       #   @return [Google::Logging::V2::LogMetric::ApiVersion]
       #     Output only. The API version that created or updated this metric.
@@ -53,8 +64,9 @@ module Google
       # The parameters to ListLogMetrics.
       # @!attribute [rw] parent
       #   @return [String]
-      #     Required. The resource name containing the metrics.
-      #     Example: +"projects/my-project-id"+.
+      #     Required. The name of the project containing the metrics:
+      #
+      #         "projects/[PROJECT_ID]"
       # @!attribute [rw] page_token
       #   @return [String]
       #     Optional. If present, then retrieve the next batch of results from the
@@ -82,15 +94,17 @@ module Google
       # The parameters to GetLogMetric.
       # @!attribute [rw] metric_name
       #   @return [String]
-      #     The resource name of the desired metric.
-      #     Example: +"projects/my-project-id/metrics/my-metric-id"+.
+      #     The resource name of the desired metric:
+      #
+      #         "projects/[PROJECT_ID]/metrics/[METRIC_ID]"
       class GetLogMetricRequest; end
 
       # The parameters to CreateLogMetric.
       # @!attribute [rw] parent
       #   @return [String]
-      #     The resource name of the project in which to create the metric.
-      #     Example: +"projects/my-project-id"+.
+      #     The resource name of the project in which to create the metric:
+      #
+      #         "projects/[PROJECT_ID]"
       #
       #     The new metric must be provided in the request.
       # @!attribute [rw] metric
@@ -102,24 +116,24 @@ module Google
       # The parameters to UpdateLogMetric.
       # @!attribute [rw] metric_name
       #   @return [String]
-      #     The resource name of the metric to update.
-      #     Example: +"projects/my-project-id/metrics/my-metric-id"+.
+      #     The resource name of the metric to update:
       #
-      #     The updated metric must be provided in the request and have the
-      #     same identifier that is specified in +metricName+.
-      #     If the metric does not exist, it is created.
+      #         "projects/[PROJECT_ID]/metrics/[METRIC_ID]"
+      #
+      #     The updated metric must be provided in the request and it's
+      #     +name+ field must be the same as +[METRIC_ID]+ If the metric
+      #     does not exist in +[PROJECT_ID]+, then a new metric is created.
       # @!attribute [rw] metric
       #   @return [Google::Logging::V2::LogMetric]
-      #     The updated metric, whose name must be the same as the
-      #     metric identifier in +metricName+. If +metricName+ does not
-      #     exist, then a new metric is created.
+      #     The updated metric.
       class UpdateLogMetricRequest; end
 
       # The parameters to DeleteLogMetric.
       # @!attribute [rw] metric_name
       #   @return [String]
-      #     The resource name of the metric to delete.
-      #     Example: +"projects/my-project-id/metrics/my-metric-id"+.
+      #     The resource name of the metric to delete:
+      #
+      #         "projects/[PROJECT_ID]/metrics/[METRIC_ID]"
       class DeleteLogMetricRequest; end
     end
   end

data/lib/google/cloud/logging/v2/{logging_service_v2_api.rb → logging_service_v2_client.rb}

@@ -36,7 +36,7 @@ module Google
         #
         # @!attribute [r] logging_service_v2_stub
         #   @return [Google::Logging::V2::LoggingServiceV2::Stub]
-        class LoggingServiceV2Api
+        class LoggingServiceV2Client
           attr_reader :logging_service_v2_stub
 
           # The default address of the service.
@@ -72,11 +72,11 @@ module Google
             "https://www.googleapis.com/auth/logging.write"
           ].freeze
 
-          PARENT_PATH_TEMPLATE = Google::Gax::PathTemplate.new(
+          PROJECT_PATH_TEMPLATE = Google::Gax::PathTemplate.new(
             "projects/{project}"
           )
 
-          private_constant :PARENT_PATH_TEMPLATE
+          private_constant :PROJECT_PATH_TEMPLATE
 
           LOG_PATH_TEMPLATE = Google::Gax::PathTemplate.new(
             "projects/{project}/logs/{log}"
@@ -84,11 +84,11 @@ module Google
 
           private_constant :LOG_PATH_TEMPLATE
 
-          # Returns a fully-qualified parent resource name string.
+          # Returns a fully-qualified project resource name string.
           # @param project [String]
           # @return [String]
-          def self.parent_path project
-            PARENT_PATH_TEMPLATE.render(
+          def self.project_path project
+            PROJECT_PATH_TEMPLATE.render(
               :"project" => project
             )
           end
@@ -104,11 +104,11 @@ module Google
             )
           end
 
-          # Parses the project from a parent resource.
-          # @param parent_name [String]
+          # Parses the project from a project resource.
+          # @param project_name [String]
           # @return [String]
-          def self.match_project_from_parent_name parent_name
-            PARENT_PATH_TEMPLATE.match(parent_name)["project"]
+          def self.match_project_from_project_name project_name
+            PROJECT_PATH_TEMPLATE.match(project_name)["project"]
           end
 
           # Parses the project from a log resource.
@@ -160,6 +160,7 @@ module Google
             require "google/gax/grpc"
             require "google/logging/v2/logging_services_pb"
 
+
             google_api_client = "#{app_name}/#{app_version} " \
               "#{CODE_GEN_NAME_VERSION} gax/#{Google::Gax::VERSION} " \
               "ruby/#{RUBY_VERSION}".freeze
@@ -208,24 +209,32 @@ module Google
 
           # Service calls
 
-          # Deletes a log and all its log entries.
-          # The log will reappear if it receives new entries.
+          # Deletes all the log entries in a log.
+          # The log reappears if it receives new entries.
           #
           # @param log_name [String]
-          #   Required. The resource name of the log to delete.  Example:
-          #   +"projects/my-project/logs/syslog"+.
+          #   Required. The resource name of the log to delete:
+          #
+          #       "projects/[PROJECT_ID]/logs/[LOG_ID]"
+          #       "organizations/[ORGANIZATION_ID]/logs/[LOG_ID]"
+          #
+          #   +[LOG_ID]+ must be URL-encoded. For example,
+          #   +"projects/my-project-id/logs/syslog"+,
+          #   +"organizations/1234567890/logs/cloudresourcemanager.googleapis.com%2Factivity"+.
+          #   For more information about log names, see
+          #   LogEntry.
           # @param options [Google::Gax::CallOptions]
           #   Overrides the default settings for this call, e.g, timeout,
           #   retries, etc.
           # @raise [Google::Gax::GaxError] if the RPC is aborted.
           # @example
-          #   require "google/cloud/logging/v2/logging_service_v2_api"
+          #   require "google/cloud/logging/v2/logging_service_v2_client"
           #
-          #   LoggingServiceV2Api = Google::Cloud::Logging::V2::LoggingServiceV2Api
+          #   LoggingServiceV2Client = Google::Cloud::Logging::V2::LoggingServiceV2Client
           #
-          #   logging_service_v2_api = LoggingServiceV2Api.new
-          #   formatted_log_name = LoggingServiceV2Api.log_path("[PROJECT]", "[LOG]")
-          #   logging_service_v2_api.delete_log(formatted_log_name)
+          #   logging_service_v2_client = LoggingServiceV2Client.new
+          #   formatted_log_name = LoggingServiceV2Client.log_path("[PROJECT]", "[LOG]")
+          #   logging_service_v2_client.delete_log(formatted_log_name)
 
           def delete_log \
               log_name,
@@ -234,6 +243,7 @@ module Google
               log_name: log_name
             }.delete_if { |_, v| v.nil? })
             @delete_log.call(req, options)
+            nil
           end
 
           # Writes log entries to Stackdriver Logging.  All log entries are
@@ -241,8 +251,15 @@ module Google
           #
           # @param log_name [String]
           #   Optional. A default log resource name that is assigned to all log entries
-          #   in +entries+ that do not specify a value for +log_name+.  Example:
-          #   +"projects/my-project/logs/syslog"+.  See
+          #   in +entries+ that do not specify a value for +log_name+:
+          #
+          #       "projects/[PROJECT_ID]/logs/[LOG_ID]"
+          #       "organizations/[ORGANIZATION_ID]/logs/[LOG_ID]"
+          #
+          #   +[LOG_ID]+ must be URL-encoded. For example,
+          #   +"projects/my-project-id/logs/syslog"+ or
+          #   +"organizations/1234567890/logs/cloudresourcemanager.googleapis.com%2Factivity"+.
+          #   For more information about log names, see
           #   LogEntry.
           # @param resource [Google::Api::MonitoredResource]
           #   Optional. A default monitored resource object that is assigned to all log
@@ -280,13 +297,13 @@ module Google
           # @return [Google::Logging::V2::WriteLogEntriesResponse]
           # @raise [Google::Gax::GaxError] if the RPC is aborted.
           # @example
-          #   require "google/cloud/logging/v2/logging_service_v2_api"
+          #   require "google/cloud/logging/v2/logging_service_v2_client"
           #
-          #   LoggingServiceV2Api = Google::Cloud::Logging::V2::LoggingServiceV2Api
+          #   LoggingServiceV2Client = Google::Cloud::Logging::V2::LoggingServiceV2Client
           #
-          #   logging_service_v2_api = LoggingServiceV2Api.new
+          #   logging_service_v2_client = LoggingServiceV2Client.new
           #   entries = []
-          #   response = logging_service_v2_api.write_log_entries(entries)
+          #   response = logging_service_v2_client.write_log_entries(entries)
 
           def write_log_entries \
               entries,
@@ -311,18 +328,23 @@ module Google
           #
           # @param project_ids [Array<String>]
           #   Deprecated. One or more project identifiers or project numbers from which
-          #   to retrieve log entries.  Examples: +"my-project-1A"+, +"1234567890"+. If
+          #   to retrieve log entries.  Example: +"my-project-1A"+. If
           #   present, these project identifiers are converted to resource format and
           #   added to the list of resources in +resourceNames+. Callers should use
           #   +resourceNames+ rather than this parameter.
           # @param resource_names [Array<String>]
-          #   Optional. One or more cloud resources from which to retrieve log entries.
-          #   Example: +"projects/my-project-1A"+, +"projects/1234567890"+.  Projects
-          #   listed in +projectIds+ are added to this list.
+          #   Required. One or more cloud resources from which to retrieve log
+          #   entries:
+          #
+          #       "projects/[PROJECT_ID]"
+          #       "organizations/[ORGANIZATION_ID]"
+          #
+          #   Projects listed in the +project_ids+ field are added to this list.
           # @param filter [String]
           #   Optional. A filter that chooses which log entries to return.  See {Advanced
           #   Logs Filters}[https://cloud.google.com/logging/docs/view/advanced_filters].  Only log entries that
           #   match the filter are returned.  An empty filter matches all log entries.
+          #   The maximum length of the filter is 20000 characters.
           # @param order_by [String]
           #   Optional. How the results should be sorted.  Presently, the only permitted
           #   values are +"timestamp asc"+ (default) and +"timestamp desc"+. The first
@@ -346,20 +368,20 @@ module Google
           #   object.
           # @raise [Google::Gax::GaxError] if the RPC is aborted.
           # @example
-          #   require "google/cloud/logging/v2/logging_service_v2_api"
+          #   require "google/cloud/logging/v2/logging_service_v2_client"
           #
-          #   LoggingServiceV2Api = Google::Cloud::Logging::V2::LoggingServiceV2Api
+          #   LoggingServiceV2Client = Google::Cloud::Logging::V2::LoggingServiceV2Client
           #
-          #   logging_service_v2_api = LoggingServiceV2Api.new
-          #   project_ids = []
+          #   logging_service_v2_client = LoggingServiceV2Client.new
+          #   resource_names = []
           #
           #   # Iterate over all results.
-          #   logging_service_v2_api.list_log_entries(project_ids).each do |element|
+          #   logging_service_v2_client.list_log_entries(resource_names).each do |element|
           #     # Process element.
           #   end
           #
           #   # Or iterate over results one page at a time.
-          #   logging_service_v2_api.list_log_entries(project_ids).each_page do |page|
+          #   logging_service_v2_client.list_log_entries(resource_names).each_page do |page|
           #     # Process each page at a time.
           #     page.each do |element|
           #       # Process element.
@@ -367,15 +389,15 @@ module Google
           #   end
 
           def list_log_entries \
-              project_ids,
-              resource_names: nil,
+              resource_names,
+              project_ids: nil,
               filter: nil,
               order_by: nil,
               page_size: nil,
               options: nil
             req = Google::Logging::V2::ListLogEntriesRequest.new({
-              project_ids: project_ids,
               resource_names: resource_names,
+              project_ids: project_ids,
               filter: filter,
               order_by: order_by,
               page_size: page_size
@@ -401,19 +423,19 @@ module Google
           #   object.
           # @raise [Google::Gax::GaxError] if the RPC is aborted.
           # @example
-          #   require "google/cloud/logging/v2/logging_service_v2_api"
+          #   require "google/cloud/logging/v2/logging_service_v2_client"
           #
-          #   LoggingServiceV2Api = Google::Cloud::Logging::V2::LoggingServiceV2Api
+          #   LoggingServiceV2Client = Google::Cloud::Logging::V2::LoggingServiceV2Client
           #
-          #   logging_service_v2_api = LoggingServiceV2Api.new
+          #   logging_service_v2_client = LoggingServiceV2Client.new
           #
           #   # Iterate over all results.
-          #   logging_service_v2_api.list_monitored_resource_descriptors.each do |element|
+          #   logging_service_v2_client.list_monitored_resource_descriptors.each do |element|
           #     # Process element.
           #   end
           #
           #   # Or iterate over results one page at a time.
-          #   logging_service_v2_api.list_monitored_resource_descriptors.each_page do |page|
+          #   logging_service_v2_client.list_monitored_resource_descriptors.each_page do |page|
           #     # Process each page at a time.
           #     page.each do |element|
           #       # Process element.