google-cloud-logging 0.21.2 → 0.23.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0758635d13fae9220da1dd1b95478cb80307ce3f
-  data.tar.gz: d5dd229ab4f849b1145c9b98da3684b763c3af86
+  metadata.gz: 2658b3d8de071df00d572f934df7ba5ae0be360d
+  data.tar.gz: 18b9dd38df8bc706d2aa821b0f6030fdda4abef3
 SHA512:
-  metadata.gz: 1ad8e872864d97efef6ed58e463ab945082a697f9f70d5f91ce26c1ecf319d5954c1401349fcb73b10372756966447e81c75d64ff7d96a49c4cfaba13503a001
-  data.tar.gz: da1d3f340ac647a47adcdd276ed8df241bcf900cae54a5546ff17336d8ff56addb9a0fd814b4b03dbce4d68640f3fa0801a9d3504536206e2adc3434be10f4e7
+  metadata.gz: 889cb152ecd3759eb2b586a18dd6043ea47f85d565e80c55b65f70a23fabbcefd140409f6c27a298ccb6992cf196e6178368c6bbea100a33112bd522ae38d58d
+  data.tar.gz: 7ef4b2783d70281cdc5b0a4216098cf9e0a49c359a8af8f52d17e9b947d70ae4628d72ef06b56d77eaaefc1eb2d71b96e3bb329e1b50dfdff0bd9745c6d6d326

data/.yardopts

@@ -1,8 +1,5 @@
 --no-private
 --title=Stackdriver Logging
---exclude lib/google/logging
---exclude lib/google/cloud/logging/v2
---exclude lib/google/cloud/logging/v2.rb
 --markup markdown
 
 ./lib/**/*.rb

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

@@ -62,7 +62,7 @@ module Google
           #
           #   logging = Google::Cloud::Logging.new
           #
-          #   entries = dataset.entries
+          #   entries = logging.entries
           #   if entries.next?
           #     next_entries = entries.next
           #   end
@@ -70,9 +70,9 @@ module Google
           def next
             return nil unless next?
             ensure_service!
-            grpc = @service.list_entries token: token, projects: @projects,
+            grpc = @service.list_entries token: token, resources: @resources,
                                          filter: @filter, order: @order,
-                                         max: @max
+                                         max: @max, projects: @projects
             self.class.from_grpc grpc, @service
           end
 
@@ -100,7 +100,7 @@ module Google
           #   logging = Google::Cloud::Logging.new
           #   entries = logging.entries order: "timestamp desc"
           #
-          #   entries.all do |entry|
+          #   entries.all do |e|
           #     puts "[#{e.timestamp}] #{e.log_name} #{e.payload.inspect}"
           #   end
           #
@@ -120,7 +120,7 @@ module Google
           #   logging = Google::Cloud::Logging.new
           #   entries = logging.entries order: "timestamp desc"
           #
-          #   entries.all(request_limit: 10) do |entry|
+          #   entries.all(request_limit: 10) do |e|
           #     puts "[#{e.timestamp}] #{e.log_name} #{e.payload.inspect}"
           #   end
           #
@@ -144,8 +144,8 @@ module Google
           ##
           # @private New Entry::List from a
           # Google::Logging::V2::ListLogEntryResponse object.
-          def self.from_grpc grpc_list, service, projects: nil, filter: nil,
-                             order: nil, max: nil
+          def self.from_grpc grpc_list, service, resources: nil, filter: nil,
+                             order: nil, max: nil, projects: nil
             entries = new(Array(grpc_list.entries).map do |grpc_entry|
               Entry.from_grpc grpc_entry
             end)
@@ -154,6 +154,7 @@ module Google
             entries.instance_variable_set "@token", token
             entries.instance_variable_set "@service", service
             entries.instance_variable_set "@projects", projects
+            entries.instance_variable_set "@resources", resources
             entries.instance_variable_set "@filter", filter
             entries.instance_variable_set "@order", order
             entries.instance_variable_set "@max", max

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

@@ -86,7 +86,7 @@ module Google
         #
         #   resource = logging.resource "gae_app", labels: {
         #                                 "module_id" => "1",
-        #                                 "version_id" => "20150925t173233" }
+        #                                 "version_id" => "20150925t173233"
         #                               }
         #
         #   logger = Google::Cloud::Logging::Logger.new writer,
@@ -324,7 +324,7 @@ module Google
         ##
         # Untrack the trace_id that's associated with current Thread
         #
-        # @return The trace_id that's being deleted
+        # @return [String] The trace_id that's being deleted
         def delete_trace_id
           trace_ids.delete current_thread_id
         end

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

@@ -63,7 +63,7 @@ module Google
           #
           #   logging = Google::Cloud::Logging.new
           #
-          #   metrics = dataset.metrics
+          #   metrics = logging.metrics
           #   if metrics.next?
           #     next_metrics = metrics.next
           #   end

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

@@ -78,32 +78,36 @@ module Google
         # based on the current environment.
         #
         # @example If both type and labels are provided, it returns resource:
-        #   rc = Middleware.build_monitored_resource "aws_ec2_instance",
-        #                                            { instance_id: "ec2-id",
-        #                                              aws_account: "aws-id" }
+        #   rc = Google::Cloud::Logging::Middleware.build_monitored_resource(
+        #          "aws_ec2_instance",
+        #          {
+        #            instance_id: "ec2-id",
+        #            aws_account: "aws-id"
+        #          }
+        #        )
         #   rc.type   #=> "aws_ec2_instance"
         #   rc.labels #=> { instance_id: "ec2-id", aws_account: "aws-id" }
         #
         # @example If running from GAE, returns default resource:
-        #   rc = Middleware.build_monitored_resource
+        #   rc = Google::Cloud::Logging::Middleware.build_monitored_resource
         #   rc.type   #=> "gae_app"
-        #   rc.labels #=> { module_id: [GAE module name],
-        #             #     version_id: [GAE module version] }
+        #   rc.labels # { module_id: [GAE module name],
+        #             #   version_id: [GAE module version] }
         #
         # @example If running from GKE, returns default resource:
-        #   rc = Middleware.build_monitored_resource
+        #   rc = Google::Cloud::Logging::Middleware.build_monitored_resource
         #   rc.type   #=> "container"
-        #   rc.labels #=> { cluster_name: [GKE cluster name],
-        #             #     namespace_id: [GKE namespace_id] }
+        #   rc.labels # { cluster_name: [GKE cluster name],
+        #             #   namespace_id: [GKE namespace_id] }
         #
         # @example If running from GCE, return default resource:
-        #   rc = Middleware.build_monitored_resource
+        #   rc = Google::Cloud::Logging::Middleware.build_monitored_resource
         #   rc.type   #=> "gce_instance"
-        #   rc.labels #=> { instance_id: [GCE VM instance id],
-        #             #     zone: [GCE vm group zone] }
+        #   rc.labels # { instance_id: [GCE VM instance id],
+        #             #   zone: [GCE vm group zone] }
         #
         # @example Otherwise default to generic "global" type:
-        #   rc = Middleware.build_monitored_resource
+        #   rc = Google::Cloud::Logging::Middleware.build_monitored_resource
         #   rc.type   #=> "global"
         #   rc.labels #=> {}
         #
@@ -132,25 +136,25 @@ module Google
         # the correct monitoring resource types and labels.
         #
         # @example If running from GAE, returns default resource:
-        #   rc = Middleware.build_monitored_resource
+        #   rc = Google::Cloud::Logging::Middleware.build_monitored_resource
         #   rc.type   #=> "gae_app"
-        #   rc.labels #=> { module_id: [GAE module name],
-        #             #     version_id: [GAE module version] }
+        #   rc.labels # { module_id: [GAE module name],
+        #             #   version_id: [GAE module version] }
         #
         # @example If running from GKE, returns default resource:
-        #   rc = Middleware.build_monitored_resource
+        #   rc = Google::Cloud::Logging::Middleware.build_monitored_resource
         #   rc.type   #=> "container"
-        #   rc.labels #=> { cluster_name: [GKE cluster name],
-        #             #     namespace_id: [GKE namespace_id] }
+        #   rc.labels # { cluster_name: [GKE cluster name],
+        #             #   namespace_id: [GKE namespace_id] }
         #
         # @example If running from GCE, return default resource:
-        #   rc = Middleware.build_monitored_resource
+        #   rc = Google::Cloud::Logging::Middleware.build_monitored_resource
         #   rc.type   #=> "gce_instance"
-        #   rc.labels #=> { instance_id: [GCE VM instance id],
-        #             #     zone: [GCE vm group zone] }
+        #   rc.labels # { instance_id: [GCE VM instance id],
+        #             #   zone: [GCE vm group zone] }
         #
         # @example Otherwise default to generic "global" type:
-        #   rc = Middleware.build_monitored_resource
+        #   rc = Google::Cloud::Logging::Middleware.build_monitored_resource
         #   rc.type   #=> "global"
         #   rc.labels #=> {}
         #

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

@@ -88,9 +88,11 @@ module Google
         # Lists log entries. Use this method to retrieve log entries from Cloud
         # Logging.
         #
-        # @param [String, Array] projects One or more project IDs or project
-        #   numbers from which to retrieve log entries. If `nil`, the ID of the
-        #   receiving project instance will be used.
+        # @param [String, Array<String>] resources One or more cloud resources
+        #   from which to retrieve log entries. If both `resources` and
+        #   `projects` are `nil`, the ID of the receiving project instance will
+        #   be used. Examples: `"projects/my-project-1A"`,
+        #   `"projects/1234567890"`.
         # @param [String] filter An [advanced logs
         #   filter](https://cloud.google.com/logging/docs/view/advanced_filters).
         #   The filter is compared against all log entries in the projects
@@ -102,6 +104,12 @@ module Google
         # @param [String] token A previously-returned page token representing
         #   part of the larger set of results to view.
         # @param [Integer] max Maximum number of entries to return.
+        # @param [String, Array<String>] projects One or more project IDs or
+        #   project numbers from which to retrieve log entries. Each value will
+        #   be formatted as a project resource name and added to any values
+        #   passed to `resources`. If both `resources` and `projects` are `nil`,
+        #   the ID of the receiving project instance will be used. This is
+        #   deprecated in favor of `resources`.
         #
         # @return [Array<Google::Cloud::Logging::Entry>] (See
         #   {Google::Cloud::Logging::Entry::List})
@@ -143,13 +151,16 @@ module Google
         #     puts "[#{e.timestamp}] #{e.log_name} #{e.payload.inspect}"
         #   end
         #
-        def entries projects: nil, filter: nil, order: nil, token: nil, max: nil
+        def entries resources: nil, filter: nil, order: nil, token: nil,
+                    max: nil, projects: nil
           ensure_service!
-          list_grpc = service.list_entries projects: projects, filter: filter,
-                                           order: order, token: token, max: max
+          list_grpc = service.list_entries resources: resources, filter: filter,
+                                           order: order, token: token, max: max,
+                                           projects: projects
           Entry::List.from_grpc list_grpc, service,
-                                projects: projects, max: max,
-                                filter: filter, order: order
+                                resources: resources, max: max,
+                                filter: filter, order: order,
+                                projects: projects
         end
         alias_method :find_entries, :entries
 
@@ -533,6 +544,13 @@ module Google
         #  consistent with the log entry format designed by the `version`
         #  parameter, regardless of the format of the log entry that was
         #  originally written to Stackdriver Logging.
+        # @param [Time, nil] start_at The time at which this sink will begin
+        #   exporting log entries. If this value is present, then log entries
+        #   are exported only if `start_at` is less than the log entry's
+        #   timestamp. Optional.
+        # @param [Time, nil] end_at Time at which this sink will stop exporting
+        #   log entries. If this value is present, then log entries are exported
+        #   only if the log entry's timestamp is less than `end_at`. Optional.
         # @param [Symbol] version The log entry version used when exporting log
         #   entries from this sink. This version does not have to correspond to
         #   the version of the log entry when it was written to Stackdriver
@@ -540,6 +558,12 @@ module Google
         #   Version 2 is currently the preferred format. An unspecified version
         #   format currently defaults to V2 in the service. The default value is
         #   `:unspecified`.
+        # @param [Boolean] unique_writer_identity 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. Optional.
         #
         # @return [Google::Cloud::Logging::Sink] a project sink
         #
@@ -561,10 +585,15 @@ module Google
         #   sink = logging.create_sink "my-sink",
         #                              "storage.googleapis.com/#{bucket.id}"
         #
-        def create_sink name, destination, filter: nil, version: :unspecified
+        def create_sink name, destination, filter: nil, start_at: nil,
+                        end_at: nil, version: :unspecified,
+                        unique_writer_identity: nil
           version = Sink.resolve_version version
           ensure_service!
-          grpc = service.create_sink name, destination, filter, version
+          grpc = service.create_sink \
+            name, destination, filter, version,
+            start_time: start_at, end_time: end_at,
+            unique_writer_identity: unique_writer_identity
           Sink.from_grpc grpc, service
         end
         alias_method :new_sink, :create_sink
@@ -587,7 +616,7 @@ module Google
         #   require "google/cloud/logging"
         #
         #   logging = Google::Cloud::Logging.new
-        #   sink = logging.sink "non-existing-sink" #=> nil
+        #   sink = logging.sink "non-existing-sink" # nil
         #
         def sink sink_name
           ensure_service!
@@ -686,7 +715,7 @@ module Google
         #   require "google/cloud/logging"
         #
         #   logging = Google::Cloud::Logging.new
-        #   metric = logging.metric "non_existing_metric" #=> nil
+        #   metric = logging.metric "non_existing_metric" # nil
         #
         def metric name
           ensure_service!

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

@@ -37,7 +37,7 @@ module Google
       #   resource_descriptor = logging.resource_descriptors.first
       #   resource_descriptor.type #=> "cloudsql_database"
       #   resource_descriptor.name #=> "Cloud SQL Database"
-      #   resource_descriptor.labels.map &:key #=> ["database_id", "region"]
+      #   resource_descriptor.labels.map &:key #=> ["database_id", "zone"]
       #
       class ResourceDescriptor
         ##

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

@@ -33,7 +33,7 @@ module Google
                        client_config: nil
           @project = project
           @credentials = credentials
-          @host = host || V2::LoggingServiceV2Api::SERVICE_ADDRESS
+          @host = host || V2::LoggingServiceV2Client::SERVICE_ADDRESS
           @timeout = timeout
           @client_config = client_config || {}
         end
@@ -53,7 +53,7 @@ module Google
         def logging
           return mocked_logging if mocked_logging
           @logging ||= \
-            V2::LoggingServiceV2Api.new(
+            V2::LoggingServiceV2Client.new(
               service_path: host,
               channel: channel,
               timeout: timeout,
@@ -66,7 +66,7 @@ module Google
         def sinks
           return mocked_sinks if mocked_sinks
           @sinks ||= \
-            V2::ConfigServiceV2Api.new(
+            V2::ConfigServiceV2Client.new(
               service_path: host,
               channel: channel,
               timeout: timeout,
@@ -79,7 +79,7 @@ module Google
         def metrics
           return mocked_metrics if mocked_metrics
           @metrics ||= \
-            V2::MetricsServiceV2Api.new(
+            V2::MetricsServiceV2Client.new(
               service_path: host,
               channel: channel,
               timeout: timeout,
@@ -93,10 +93,12 @@ module Google
           credentials == :this_channel_is_insecure
         end
 
-        def list_entries projects: nil, filter: nil, order: nil, token: nil,
-                         max: nil
+        def list_entries resources: nil, filter: nil, order: nil, token: nil,
+                         max: nil, projects: nil
 
-          project_ids = Array(projects || @project)
+          project_ids = Array(projects).map { |p| "projects/#{p}" }
+          resource_names = Array(resources) + project_ids
+          resource_names = ["projects/#{@project}"] if resource_names.empty?
           call_opts = default_options
           if token
             call_opts = Google::Gax::CallOptions.new(kwargs: default_headers,
@@ -104,11 +106,9 @@ module Google
           end
 
           execute do
-            paged_enum = logging.list_log_entries project_ids,
-                                                  filter: filter,
-                                                  order_by: order,
-                                                  page_size: max,
-                                                  options: call_opts
+            paged_enum = logging.list_log_entries \
+              resource_names, filter: filter, order_by: order, page_size: max,
+                              options: call_opts
             paged_enum.page.response
           end
         end
@@ -162,13 +162,19 @@ module Google
           end
         end
 
-        def create_sink name, destination, filter, version
+        def create_sink name, destination, filter, version, start_time: nil,
+                        end_time: nil, unique_writer_identity: nil
           sink = Google::Logging::V2::LogSink.new({
             name: name, destination: destination, filter: filter,
-            output_version_format: version }.delete_if { |_, v| v.nil? })
+            output_version_format: version,
+            start_time: time_to_timestamp(start_time),
+            end_time: time_to_timestamp(end_time)
+          }.delete_if { |_, v| v.nil? })
 
           execute do
-            sinks.create_sink project_path, sink, options: default_options
+            sinks.create_sink project_path, sink,
+                              unique_writer_identity: unique_writer_identity,
+                              options: default_options
           end
         end
 
@@ -176,13 +182,18 @@ module Google
           execute { sinks.get_sink sink_path(name), options: default_options }
         end
 
-        def update_sink name, destination, filter, version
+        def update_sink name, destination, filter, version, start_time: nil,
+                        end_time: nil, unique_writer_identity: nil
           sink = Google::Logging::V2::LogSink.new({
             name: name, destination: destination, filter: filter,
-            output_version_format: version }.delete_if { |_, v| v.nil? })
+            output_version_format: version,
+            start_time: time_to_timestamp(start_time),
+            end_time: time_to_timestamp(end_time) }.delete_if { |_, v| v.nil? })
 
           execute do
-            sinks.update_sink sink_path(name), sink, options: default_options
+            sinks.update_sink sink_path(name), sink,
+                              unique_writer_identity: unique_writer_identity,
+                              options: default_options
           end
         end
 
@@ -276,6 +287,24 @@ module Google
           Google::Gax::CallOptions.new kwargs: default_headers
         end
 
+        ##
+        # @private Get a Google::Protobuf::Timestamp object from a Time object.
+        def time_to_timestamp time
+          return nil if time.nil?
+          # Make sure we have a Time object
+          return nil unless time.respond_to? :to_time
+          time = time.to_time
+          Google::Protobuf::Timestamp.new seconds: time.to_i, nanos: time.nsec
+        end
+
+        ##
+        # @private Get a Time object from a Google::Protobuf::Timestamp object.
+        def timestamp_to_time timestamp
+          return nil if timestamp.nil?
+          # Time.at takes microseconds, so convert nano seconds to microseconds
+          Time.at timestamp.seconds, Rational(timestamp.nanos, 1000)
+        end
+
         def execute
           yield
         rescue Google::Gax::GaxError => e

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

@@ -25,6 +25,11 @@ module Google
       # a sink, new log entries are exported. Stackdriver Logging does not send
       # previously-ingested log entries to the sink's destination.
       #
+      # 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_at`
+      # and `end_at` are present, then `start_at` must be less than `end_at`.
+      #
       # Before creating the sink, ensure that you have granted
       # `cloud-logs@google.com` permission to write logs to the destination. See
       # [Permissions for writing exported
@@ -152,9 +157,62 @@ module Google
           version == :V1
         end
 
+        ##
+        # The time at which this sink will begin exporting log entries. If this
+        # value is present, then log entries are exported only if `start_at`
+        # is less than the log entry's timestamp. Optional.
+        def start_at
+          timestamp_to_time @grpc.start_time
+        end
+        alias_method :start_time, :start_at
+
+        ##
+        # Sets the time at which this sink will begin exporting log entries. If
+        # this value is present, then log entries are exported only if
+        # `start_at` is less than the log entry's timestamp. Optional.
+        def start_at= new_start_at
+          @grpc.start_time = time_to_timestamp new_start_at
+        end
+        alias_method :start_time=, :start_at=
+
+        ##
+        # Time at which this sink will stop exporting log entries. If this
+        # value is present, then log entries are exported only if the log
+        # entry's timestamp is less than `end_at`. Optional.
+        def end_at
+          timestamp_to_time @grpc.end_time
+        end
+        alias_method :end_time, :end_at
+
+        ##
+        # Sets the time at which this sink will stop exporting log entries. If
+        # this value is present, then log entries are exported only if the log
+        # entry's timestamp is less than `end_at`. Optional.
+        def end_at= new_end_at
+          @grpc.end_time = time_to_timestamp new_end_at
+        end
+        alias_method :end_time=, :end_at=
+
+        ##
+        # 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.
+        def writer_identity
+          @grpc.writer_identity
+        end
+
         ##
         # Updates the logs-based sink.
         #
+        # @param [Boolean] unique_writer_identity 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. Optional.
+        #
         # @example
         #   require "google/cloud/logging"
         #
@@ -163,9 +221,12 @@ module Google
         #   sink.filter = "logName:syslog AND severity>=ERROR"
         #   sink.save
         #
-        def save
+        def save unique_writer_identity: nil
           ensure_service!
-          @grpc = service.update_sink name, destination, filter, version
+          @grpc = service.update_sink \
+            name, destination, filter, version,
+            start_time: start_at, end_time: end_at,
+            unique_writer_identity: unique_writer_identity
         end
 
         ##
@@ -222,6 +283,24 @@ module Google
         def ensure_service!
           fail "Must have active connection to service" unless service
         end
+
+        ##
+        # @private Get a Google::Protobuf::Timestamp object from a Time object.
+        def time_to_timestamp time
+          return nil if time.nil?
+          # Make sure we have a Time object
+          return nil unless time.respond_to? :to_time
+          time = time.to_time
+          Google::Protobuf::Timestamp.new seconds: time.to_i, nanos: time.nsec
+        end
+
+        ##
+        # @private Get a Time object from a Google::Protobuf::Timestamp object.
+        def timestamp_to_time timestamp
+          return nil if timestamp.nil?
+          # Time.at takes microseconds, so convert nano seconds to microseconds
+          Time.at timestamp.seconds, Rational(timestamp.nanos, 1000)
+        end
       end
     end
   end