google-cloud-logging 0.20.1 → 0.21.0

data/lib/google/cloud/logging/sink.rb

@@ -41,18 +41,18 @@ module Google
       #   Permissions for writing exported logs
       #
       # @example
-      #   require "google/cloud"
-      #
-      #   gcloud = Google::Cloud.new
-      #   logging = gcloud.logging
-      #   storage = gcloud.storage
+      #   require "google/cloud/storage"
       #
+      #   storage = Google::Cloud::Storage.new
       #   bucket = storage.create_bucket "my-logs-bucket"
       #
       #   # Grant owner permission to Stackdriver Logging service
       #   email = "cloud-logs@google.com"
       #   bucket.acl.add_owner "group-#{email}"
       #
+      #   require "google/cloud/logging"
+      #
+      #   logging = Google::Cloud::Logging.new
       #   sink = logging.create_sink "my-sink",
       #                              "storage.googleapis.com/#{bucket.id}"
       #
@@ -156,10 +156,9 @@ module Google
         # Updates the logs-based sink.
         #
         # @example
-        #   require "google/cloud"
+        #   require "google/cloud/logging"
         #
-        #   gcloud = Google::Cloud.new
-        #   logging = gcloud.logging
+        #   logging = Google::Cloud::Logging.new
         #   sink = logging.sink "severe_errors"
         #   sink.filter = "logName:syslog AND severity>=ERROR"
         #   sink.save
@@ -184,10 +183,9 @@ module Google
         # @return [Boolean] Returns `true` if the sink was deleted.
         #
         # @example
-        #   require "google/cloud"
+        #   require "google/cloud/logging"
         #
-        #   gcloud = Google::Cloud.new
-        #   logging = gcloud.logging
+        #   logging = Google::Cloud::Logging.new
         #   sink = logging.sink "severe_errors"
         #   sink.delete
         #

data/lib/google/cloud/logging/sink/list.rb

@@ -39,10 +39,9 @@ module Google
           # @return [Boolean]
           #
           # @example
-          #   require "google/cloud"
+          #   require "google/cloud/logging"
           #
-          #   gcloud = Google::Cloud.new
-          #   logging = gcloud.logging
+          #   logging = Google::Cloud::Logging.new
           #
           #   sinks = logging.sinks
           #   if sinks.next?
@@ -59,10 +58,9 @@ module Google
           # @return [Sink::List]
           #
           # @example
-          #   require "google/cloud"
+          #   require "google/cloud/logging"
           #
-          #   gcloud = Google::Cloud.new
-          #   logging = gcloud.logging
+          #   logging = Google::Cloud::Logging.new
           #
           #   sinks = dataset.sinks
           #   if sinks.next?
@@ -95,10 +93,9 @@ module Google
           # @return [Enumerator]
           #
           # @example Iterating each sink by passing a block:
-          #   require "google/cloud"
+          #   require "google/cloud/logging"
           #
-          #   gcloud = Google::Cloud.new
-          #   logging = gcloud.logging
+          #   logging = Google::Cloud::Logging.new
           #   sinks = logging.sinks
           #
           #   sinks.all do |sink|
@@ -106,10 +103,9 @@ module Google
           #   end
           #
           # @example Using the enumerator by not passing a block:
-          #   require "google/cloud"
+          #   require "google/cloud/logging"
           #
-          #   gcloud = Google::Cloud.new
-          #   logging = gcloud.logging
+          #   logging = Google::Cloud::Logging.new
           #   sinks = logging.sinks
           #
           #   all_names = sinks.all.map do |sink|
@@ -117,10 +113,9 @@ module Google
           #   end
           #
           # @example Limit the number of API calls made:
-          #   require "google/cloud"
+          #   require "google/cloud/logging"
           #
-          #   gcloud = Google::Cloud.new
-          #   logging = gcloud.logging
+          #   logging = Google::Cloud::Logging.new
           #   sinks = logging.sinks
           #
           #   sinks.all(request_limit: 10) do |sink|

data/lib/google/cloud/logging/v2/config_service_v2_api.rb

@@ -26,7 +26,7 @@ require "json"
 require "pathname"
 
 require "google/gax"
-require "google/logging/v2/logging_config_services_pb"
+require "google/logging/v2/logging_config_pb"
 
 module Google
   module Cloud
@@ -35,10 +35,10 @@ module Google
         # Service for configuring sinks used to export log entries outside Stackdriver
         # Logging.
         #
-        # @!attribute [r] stub
+        # @!attribute [r] config_service_v2_stub
         #   @return [Google::Logging::V2::ConfigServiceV2::Stub]
         class ConfigServiceV2Api
-          attr_reader :stub
+          attr_reader :config_service_v2_stub
 
           # The default address of the service.
           SERVICE_ADDRESS = "logging.googleapis.com".freeze
@@ -151,8 +151,15 @@ module Google
               timeout: DEFAULT_TIMEOUT,
               app_name: "gax",
               app_version: Google::Gax::VERSION
+            # These require statements are intentionally placed here to initialize
+            # the gRPC module only when it's required.
+            # See https://github.com/googleapis/toolkit/issues/446
+            require "google/gax/grpc"
+            require "google/logging/v2/logging_config_services_pb"
+
             google_api_client = "#{app_name}/#{app_version} " \
-              "#{CODE_GEN_NAME_VERSION} ruby/#{RUBY_VERSION}".freeze
+              "#{CODE_GEN_NAME_VERSION} gax/#{Google::Gax::VERSION} " \
+              "ruby/#{RUBY_VERSION}".freeze
             headers = { :"x-goog-api-client" => google_api_client }
             client_config_file = Pathname.new(__dir__).join(
               "config_service_v2_client_config.json"
@@ -169,7 +176,7 @@ module Google
                 kwargs: headers
               )
             end
-            @stub = Google::Gax::Grpc.create_stub(
+            @config_service_v2_stub = Google::Gax::Grpc.create_stub(
               service_path,
               port,
               chan_creds: chan_creds,
@@ -179,23 +186,23 @@ module Google
             )
 
             @list_sinks = Google::Gax.create_api_call(
-              @stub.method(:list_sinks),
+              @config_service_v2_stub.method(:list_sinks),
               defaults["list_sinks"]
             )
             @get_sink = Google::Gax.create_api_call(
-              @stub.method(:get_sink),
+              @config_service_v2_stub.method(:get_sink),
               defaults["get_sink"]
             )
             @create_sink = Google::Gax.create_api_call(
-              @stub.method(:create_sink),
+              @config_service_v2_stub.method(:create_sink),
               defaults["create_sink"]
             )
             @update_sink = Google::Gax.create_api_call(
-              @stub.method(:update_sink),
+              @config_service_v2_stub.method(:update_sink),
               defaults["update_sink"]
             )
             @delete_sink = Google::Gax.create_api_call(
-              @stub.method(:delete_sink),
+              @config_service_v2_stub.method(:delete_sink),
               defaults["delete_sink"]
             )
           end
@@ -205,7 +212,7 @@ module Google
           # Lists sinks.
           #
           # @param parent [String]
-          #   Required. The resource name containing the sinks.
+          #   Required. The cloud resource containing the sinks.
           #   Example: +"projects/my-logging-project"+.
           # @param page_size [Integer]
           #   The maximum number of resources contained in the underlying API
@@ -222,6 +229,27 @@ module Google
           #   operations such as per-page iteration or access to the response
           #   object.
           # @raise [Google::Gax::GaxError] if the RPC is aborted.
+          # @example
+          #   require "google/cloud/logging/v2/config_service_v2_api"
+          #
+          #   ConfigServiceV2Api = Google::Cloud::Logging::V2::ConfigServiceV2Api
+          #
+          #   config_service_v2_api = ConfigServiceV2Api.new
+          #   formatted_parent = ConfigServiceV2Api.parent_path("[PROJECT]")
+          #
+          #   # Iterate over all results.
+          #   config_service_v2_api.list_sinks(formatted_parent).each do |element|
+          #     # Process element.
+          #   end
+          #
+          #   # Or iterate over results one page at a time.
+          #   config_service_v2_api.list_sinks(formatted_parent).each_page do |page|
+          #     # Process each page at a time.
+          #     page.each do |element|
+          #       # Process element.
+          #     end
+          #   end
+
           def list_sinks \
               parent,
               page_size: nil,
@@ -236,13 +264,22 @@ module Google
           # Gets a sink.
           #
           # @param sink_name [String]
-          #   The resource name of the sink to return.
+          #   Required. The resource name of the sink to return.
           #   Example: +"projects/my-project-id/sinks/my-sink-id"+.
           # @param options [Google::Gax::CallOptions]
           #   Overrides the default settings for this call, e.g, timeout,
           #   retries, etc.
           # @return [Google::Logging::V2::LogSink]
           # @raise [Google::Gax::GaxError] if the RPC is aborted.
+          # @example
+          #   require "google/cloud/logging/v2/config_service_v2_api"
+          #
+          #   ConfigServiceV2Api = Google::Cloud::Logging::V2::ConfigServiceV2Api
+          #
+          #   config_service_v2_api = ConfigServiceV2Api.new
+          #   formatted_sink_name = ConfigServiceV2Api.sink_path("[PROJECT]", "[SINK]")
+          #   response = config_service_v2_api.get_sink(formatted_sink_name)
+
           def get_sink \
               sink_name,
               options: nil
@@ -255,18 +292,28 @@ module Google
           # Creates a sink.
           #
           # @param parent [String]
-          #   The resource in which to create the sink.
+          #   Required. The resource in which to create the sink.
           #   Example: +"projects/my-project-id"+.
-          #
           #   The new sink must be provided in the request.
           # @param sink [Google::Logging::V2::LogSink]
-          #   The new sink, which must not have an identifier that already
-          #   exists.
+          #   Required. The new sink, whose +name+ parameter is a sink identifier that
+          #   is not already in use.
           # @param options [Google::Gax::CallOptions]
           #   Overrides the default settings for this call, e.g, timeout,
           #   retries, etc.
           # @return [Google::Logging::V2::LogSink]
           # @raise [Google::Gax::GaxError] if the RPC is aborted.
+          # @example
+          #   require "google/cloud/logging/v2/config_service_v2_api"
+          #
+          #   ConfigServiceV2Api = Google::Cloud::Logging::V2::ConfigServiceV2Api
+          #   LogSink = Google::Logging::V2::LogSink
+          #
+          #   config_service_v2_api = ConfigServiceV2Api.new
+          #   formatted_parent = ConfigServiceV2Api.parent_path("[PROJECT]")
+          #   sink = LogSink.new
+          #   response = config_service_v2_api.create_sink(formatted_parent, sink)
+
           def create_sink \
               parent,
               sink,
@@ -278,24 +325,32 @@ module Google
             @create_sink.call(req, options)
           end
 
-          # Creates or updates a sink.
+          # Updates or creates a sink.
           #
           # @param sink_name [String]
-          #   The resource name of the sink to update.
-          #   Example: +"projects/my-project-id/sinks/my-sink-id"+.
-          #
-          #   The updated sink must be provided in the request and have the
-          #   same name that is specified in +sinkName+.  If the sink does not
-          #   exist, it is created.
+          #   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"+.
           # @param sink [Google::Logging::V2::LogSink]
-          #   The updated sink, whose name must be the same as the sink
-          #   identifier in +sinkName+.  If +sinkName+ does not exist, then
+          #   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.
           # @param options [Google::Gax::CallOptions]
           #   Overrides the default settings for this call, e.g, timeout,
           #   retries, etc.
           # @return [Google::Logging::V2::LogSink]
           # @raise [Google::Gax::GaxError] if the RPC is aborted.
+          # @example
+          #   require "google/cloud/logging/v2/config_service_v2_api"
+          #
+          #   ConfigServiceV2Api = Google::Cloud::Logging::V2::ConfigServiceV2Api
+          #   LogSink = Google::Logging::V2::LogSink
+          #
+          #   config_service_v2_api = ConfigServiceV2Api.new
+          #   formatted_sink_name = ConfigServiceV2Api.sink_path("[PROJECT]", "[SINK]")
+          #   sink = LogSink.new
+          #   response = config_service_v2_api.update_sink(formatted_sink_name, sink)
+
           def update_sink \
               sink_name,
               sink,
@@ -310,12 +365,23 @@ module Google
           # Deletes a sink.
           #
           # @param sink_name [String]
-          #   The resource name of the sink to delete.
-          #   Example: +"projects/my-project-id/sinks/my-sink-id"+.
+          #   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.
           # @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/config_service_v2_api"
+          #
+          #   ConfigServiceV2Api = Google::Cloud::Logging::V2::ConfigServiceV2Api
+          #
+          #   config_service_v2_api = ConfigServiceV2Api.new
+          #   formatted_sink_name = ConfigServiceV2Api.sink_path("[PROJECT]", "[SINK]")
+          #   config_service_v2_api.delete_sink(formatted_sink_name)
+
           def delete_sink \
               sink_name,
               options: nil

data/lib/google/cloud/logging/v2/logging_service_v2_api.rb

@@ -26,7 +26,7 @@ require "json"
 require "pathname"
 
 require "google/gax"
-require "google/logging/v2/logging_services_pb"
+require "google/logging/v2/logging_pb"
 
 module Google
   module Cloud
@@ -34,10 +34,10 @@ module Google
       module V2
         # Service for ingesting and querying logs.
         #
-        # @!attribute [r] stub
+        # @!attribute [r] logging_service_v2_stub
         #   @return [Google::Logging::V2::LoggingServiceV2::Stub]
         class LoggingServiceV2Api
-          attr_reader :stub
+          attr_reader :logging_service_v2_stub
 
           # The default address of the service.
           SERVICE_ADDRESS = "logging.googleapis.com".freeze
@@ -154,8 +154,15 @@ module Google
               timeout: DEFAULT_TIMEOUT,
               app_name: "gax",
               app_version: Google::Gax::VERSION
+            # These require statements are intentionally placed here to initialize
+            # the gRPC module only when it's required.
+            # See https://github.com/googleapis/toolkit/issues/446
+            require "google/gax/grpc"
+            require "google/logging/v2/logging_services_pb"
+
             google_api_client = "#{app_name}/#{app_version} " \
-              "#{CODE_GEN_NAME_VERSION} ruby/#{RUBY_VERSION}".freeze
+              "#{CODE_GEN_NAME_VERSION} gax/#{Google::Gax::VERSION} " \
+              "ruby/#{RUBY_VERSION}".freeze
             headers = { :"x-goog-api-client" => google_api_client }
             client_config_file = Pathname.new(__dir__).join(
               "logging_service_v2_client_config.json"
@@ -172,7 +179,7 @@ module Google
                 kwargs: headers
               )
             end
-            @stub = Google::Gax::Grpc.create_stub(
+            @logging_service_v2_stub = Google::Gax::Grpc.create_stub(
               service_path,
               port,
               chan_creds: chan_creds,
@@ -182,19 +189,19 @@ module Google
             )
 
             @delete_log = Google::Gax.create_api_call(
-              @stub.method(:delete_log),
+              @logging_service_v2_stub.method(:delete_log),
               defaults["delete_log"]
             )
             @write_log_entries = Google::Gax.create_api_call(
-              @stub.method(:write_log_entries),
+              @logging_service_v2_stub.method(:write_log_entries),
               defaults["write_log_entries"]
             )
             @list_log_entries = Google::Gax.create_api_call(
-              @stub.method(:list_log_entries),
+              @logging_service_v2_stub.method(:list_log_entries),
               defaults["list_log_entries"]
             )
             @list_monitored_resource_descriptors = Google::Gax.create_api_call(
-              @stub.method(:list_monitored_resource_descriptors),
+              @logging_service_v2_stub.method(:list_monitored_resource_descriptors),
               defaults["list_monitored_resource_descriptors"]
             )
           end
@@ -211,6 +218,15 @@ module Google
           #   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"
+          #
+          #   LoggingServiceV2Api = Google::Cloud::Logging::V2::LoggingServiceV2Api
+          #
+          #   logging_service_v2_api = LoggingServiceV2Api.new
+          #   formatted_log_name = LoggingServiceV2Api.log_path("[PROJECT]", "[LOG]")
+          #   logging_service_v2_api.delete_log(formatted_log_name)
+
           def delete_log \
               log_name,
               options: nil
@@ -224,25 +240,34 @@ module Google
           # written by this method.
           #
           # @param log_name [String]
-          #   Optional. A default log resource name for those log entries in +entries+
-          #   that do not specify their own +logName+.  Example:
+          #   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
           #   LogEntry.
           # @param resource [Google::Api::MonitoredResource]
-          #   Optional. A default monitored resource for those log entries in +entries+
-          #   that do not specify their own +resource+.
+          #   Optional. A default monitored resource object that is assigned to all log
+          #   entries in +entries+ that do not specify a value for +resource+. Example:
+          #
+          #       { "type": "gce_instance",
+          #         "labels": {
+          #           "zone": "us-central1-a", "instance_id": "00000000000000000000" }}
+          #
+          #   See LogEntry.
           # @param labels [Hash{String => String}]
-          #   Optional. User-defined +key:value+ items that are added to
-          #   the +labels+ field of each log entry in +entries+, except when a log
-          #   entry specifies its own +key:value+ item with the same key.
-          #   Example: +{ "size": "large", "color":"red" }+
+          #   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.
           # @param entries [Array<Google::Logging::V2::LogEntry>]
-          #   Required. The log entries to write. The log entries must have values for
-          #   all required fields.
+          #   Required. The log entries to write. Values supplied for the fields
+          #   +log_name+, +resource+, and +labels+ in this +entries.write+ request are
+          #   added to those log entries that do not provide their own values for the
+          #   fields.
           #
-          #   To improve throughput and to avoid exceeding the quota limit for calls
-          #   to +entries.write+, use this field to write multiple log entries at once
-          #   rather than  // calling this method for each log entry.
+          #   To improve throughput and to avoid exceeding the
+          #   {quota limit}[https://cloud.google.com/logging/quota-policy] for calls to +entries.write+,
+          #   you should write multiple log entries at once rather than
+          #   calling this method for each individual log entry.
           # @param partial_success [true, false]
           #   Optional. Whether valid entries should be written even if some other
           #   entries fail due to INVALID_ARGUMENT or PERMISSION_DENIED errors. If any
@@ -254,6 +279,15 @@ module Google
           #   retries, etc.
           # @return [Google::Logging::V2::WriteLogEntriesResponse]
           # @raise [Google::Gax::GaxError] if the RPC is aborted.
+          # @example
+          #   require "google/cloud/logging/v2/logging_service_v2_api"
+          #
+          #   LoggingServiceV2Api = Google::Cloud::Logging::V2::LoggingServiceV2Api
+          #
+          #   logging_service_v2_api = LoggingServiceV2Api.new
+          #   entries = []
+          #   response = logging_service_v2_api.write_log_entries(entries)
+
           def write_log_entries \
               entries,
               log_name: nil,
@@ -266,7 +300,13 @@ module Google
             )
             req.log_name = log_name unless log_name.nil?
             req.resource = resource unless resource.nil?
-            req.labels = labels unless labels.nil?
+            # Custom code here to work around setting a Hash where a Map is expected.
+            # If a future PR removes this code then ensure that the bug is fixed.
+            unless labels.nil?
+              labels_map = Google::Protobuf::Map.new(:string, :string)
+              labels.each { |k, v| labels_map[String(k)] = String(v) }
+              req.labels = labels_map
+            end
             req.partial_success = partial_success unless partial_success.nil?
             @write_log_entries.call(req, options)
           end
@@ -276,13 +316,19 @@ module Google
           # {Exporting Logs}[https://cloud.google.com/logging/docs/export].
           #
           # @param project_ids [Array<String>]
-          #   Required. One or more project IDs or project numbers from which to retrieve
-          #   log entries.  Examples of a project ID: +"my-project-1A"+, +"1234567890"+.
+          #   Deprecated. One or more project identifiers or project numbers from which
+          #   to retrieve log entries.  Examples: +"my-project-1A"+, +"1234567890"+. 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.
           # @param filter [String]
-          #   Optional. An {advanced logs filter}[https://cloud.google.com/logging/docs/view/advanced_filters].
-          #   The filter is compared against all log entries in the projects specified by
-          #   +projectIds+.  Only entries that match the filter are retrieved.  An empty
-          #   filter matches all log entries.
+          #   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.
           # @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
@@ -305,8 +351,30 @@ module Google
           #   operations such as per-page iteration or access to the response
           #   object.
           # @raise [Google::Gax::GaxError] if the RPC is aborted.
+          # @example
+          #   require "google/cloud/logging/v2/logging_service_v2_api"
+          #
+          #   LoggingServiceV2Api = Google::Cloud::Logging::V2::LoggingServiceV2Api
+          #
+          #   logging_service_v2_api = LoggingServiceV2Api.new
+          #   project_ids = []
+          #
+          #   # Iterate over all results.
+          #   logging_service_v2_api.list_log_entries(project_ids).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|
+          #     # Process each page at a time.
+          #     page.each do |element|
+          #       # Process element.
+          #     end
+          #   end
+
           def list_log_entries \
               project_ids,
+              resource_names: nil,
               filter: nil,
               order_by: nil,
               page_size: nil,
@@ -314,6 +382,7 @@ module Google
             req = Google::Logging::V2::ListLogEntriesRequest.new(
               project_ids: project_ids
             )
+            req.resource_names = resource_names unless resource_names.nil?
             req.filter = filter unless filter.nil?
             req.order_by = order_by unless order_by.nil?
             req.page_size = page_size unless page_size.nil?
@@ -337,6 +406,26 @@ module Google
           #   operations such as per-page iteration or access to the response
           #   object.
           # @raise [Google::Gax::GaxError] if the RPC is aborted.
+          # @example
+          #   require "google/cloud/logging/v2/logging_service_v2_api"
+          #
+          #   LoggingServiceV2Api = Google::Cloud::Logging::V2::LoggingServiceV2Api
+          #
+          #   logging_service_v2_api = LoggingServiceV2Api.new
+          #
+          #   # Iterate over all results.
+          #   logging_service_v2_api.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|
+          #     # Process each page at a time.
+          #     page.each do |element|
+          #       # Process element.
+          #     end
+          #   end
+
           def list_monitored_resource_descriptors \
               page_size: nil,
               options: nil