google-cloud-logging 0.24.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d45a1ba9632dc323314bfe54cd33c915b0ee49b3
-  data.tar.gz: 9679812393a50bf2add34272191477b4becc6313
+  metadata.gz: 3ed947d4ac0a7d053284364df99d1d27eb2dd013
+  data.tar.gz: 66c8792bbad62413185d1abfedb3e3e9692def55
 SHA512:
-  metadata.gz: fde2ed6e950481674e70b3193f7e007f2ee2c97b7e4d2cab34e97ec157f2788a06897dfbb6515feaf5607d46e6f2836663f00e826193dc6e70debd29a3aed9ab
-  data.tar.gz: 85ae2b82f29cd721a021408c8ee1083d5e548be252220d1b2207473355d5369b9dfefdf4a32ee279aaa8d8985d161a58de9f361250a3a310af2b518ed055be1d
+  metadata.gz: e49e794f719c33b0c7d5473610152544e0b17519da2bc04bf7543a6c973c931d56c336a5b9fee74bec6781f123ba5b72ee6be23ac2f78abbdea5e5fdefe1dfd7
+  data.tar.gz: a63f6b59880746e4898a9e5dd32b72dbbd866be2dcf0801fff66e9a151d7fe3b3c7d4edbc37b01ea634939bd34b07c6cadd7abb2648a11cf2f4eaf4a255829b1

data/README.md

@@ -2,7 +2,7 @@
 
 [Stackdriver Logging](https://cloud.google.com/logging/) ([docs](https://cloud.google.com/logging/docs/)) allows you to store, search, analyze, monitor, and alert on log data and events from Google Cloud Platform and Amazon Web Services (AWS). It supports ingestion of any custom log data from any source. Stackdriver Logging is a fully-managed service that performs at scale and can ingest application and system log data from thousands of VMs. Even better, you can analyze all that log data in real-time.
 
-- [google-cloud-logging API documentation](http://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-logging/master/google/cloud/logging)
+- [google-cloud-logging API documentation](http://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-logging/latest)
 - [google-cloud-logging on RubyGems](https://rubygems.org/gems/google-cloud-logging)
 - [Stackdriver Logging documentation](https://cloud.google.com/logging/docs/)
 
@@ -46,7 +46,7 @@ logging.write_entries entry
 
 ## Rails Integration
 
-This library also provides a built in Railtie for Ruby on Rails integration. When enabled, it sets an instance of Google::Cloud::Logging::Logger as the default Rails logger. Then all consequent log entries will be submitted to the Stackdriver Logging service. 
+This library also provides a built in Railtie for Ruby on Rails integration. When enabled, it sets an instance of Google::Cloud::Logging::Logger as the default Rails logger. Then all consequent log entries will be submitted to the Stackdriver Logging service.
 
 To do this, simply add this line to config/application.rb:
 ```ruby
@@ -60,13 +60,13 @@ config.google_cloud.keyfile = "/path/to/gcp/secret.json"
 # Or more specificly for Logging
 config.google_cloud.logging.project_id = "gcp-project-id"
 config.google_cloud.logging.keyfile = "/path/to/gcp/sercret.json"
- 
+
 # Explicitly enable or disable Logging
 config.google_cloud.use_logging = true
- 
+
 # Set Stackdriver Logging log name
 config.google_cloud.logging.log_name = "my-app-log"
- 
+
 # Override default monitored resource if needed. E.g. used on AWS
 config.google_cloud.logging.monitored_resource.type = "aws_ec2_instance"
 config.google_cloud.logging.monitored_resource.labels.instance_id = "ec2-instance-id"

data/lib/google/cloud/logging.rb

@@ -84,7 +84,7 @@ module Google
     # require "google/cloud/logging"
     #
     # logging = Google::Cloud::Logging.new
-    # entries = logging.entries filter: "log:syslog"
+    # entries = logging.entries filter: "logName:syslog"
     # entries.each do |e|
     #   puts "[#{e.timestamp}] #{e.payload.inspect}"
     # end
@@ -98,7 +98,7 @@ module Google
     # logging = Google::Cloud::Logging.new
     # entries = logging.entries order: "timestamp desc"
     # entries.each do |e|
-    #   puts "[#{e.timestamp}] #{e.log_name} #{e.payload.inspect}"
+    #   puts "[#{e.timestamp}] #{e.log_name}"
     # end
     # ```
     #
@@ -121,10 +121,11 @@ module Google
     #
     # 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
-    # logs](https://cloud.google.com/logging/docs/export/configure_export#setting_product_name_short_permissions_for_writing_exported_logs).
+    # [Exporting Logs
+    # (V2)](https://cloud.google.com/logging/docs/export/configure_export_v2).
     #
     # ```ruby
+    # require "google/cloud/storage"
     # require "google/cloud/logging"
     #
     # storage = Google::Cloud::Storage.new
@@ -135,8 +136,6 @@ module Google
     # 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",

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

@@ -17,6 +17,7 @@ require "google/cloud/logging/convert"
 require "google/cloud/logging/resource"
 require "google/cloud/logging/entry/http_request"
 require "google/cloud/logging/entry/operation"
+require "google/cloud/logging/entry/source_location"
 require "google/cloud/logging/entry/list"
 
 module Google
@@ -67,6 +68,7 @@ module Google
           @http_request = HttpRequest.new
           @operation = Operation.new
           @severity = :DEFAULT
+          @source_location = SourceLocation.new
         end
 
         ##
@@ -349,6 +351,21 @@ module Google
         # @return [Google::Cloud::Logging::Entry::Operation]
         attr_reader :operation
 
+        ##
+        # 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`
+        # Optional.
+        # @return [String]
+        attr_accessor :trace
+
+        ##
+        # Source code location information associated with the log entry, if
+        # any.
+        # @return [Google::Cloud::Logging::Entry::SourceLocation]
+        attr_reader :source_location
+
         ##
         # @private Determines if the Entry has any data.
         def empty?
@@ -359,7 +376,9 @@ module Google
             payload.nil? &&
             resource.empty? &&
             http_request.empty? &&
-            operation.empty?
+            operation.empty? &&
+            trace.nil? &&
+            source_location.empty?
         end
 
         ##
@@ -374,7 +393,9 @@ module Google
             labels: labels_grpc,
             resource: resource.to_grpc,
             http_request: http_request.to_grpc,
-            operation: operation.to_grpc
+            operation: operation.to_grpc,
+            trace: trace.to_s,
+            source_location: source_location.to_grpc
           )
           # Add payload
           append_payload grpc
@@ -398,6 +419,11 @@ module Google
                                     HttpRequest.from_grpc(grpc.http_request)
             e.instance_variable_set "@operation",
                                     Operation.from_grpc(grpc.operation)
+            e.trace = grpc.trace
+            e.instance_variable_set "@source_location",
+                                    SourceLocation.from_grpc(
+                                      grpc.source_location
+                                    )
           end
         end
 

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

@@ -77,15 +77,15 @@ module Google
           end
 
           ##
-          # Retrieves all log entries by repeatedly loading {#next} until
-          # {#next?} returns `false`. Calls the given block once for each log
-          # entry, which is passed as the parameter.
+          # Retrieves remaining results by repeatedly invoking {#next} until
+          # {#next?} returns `false`. Calls the given block once for each
+          # result, which is passed as the argument to the block.
           #
           # An Enumerator is returned if no block is given.
           #
-          # This method may make several API calls until all log entries are
-          # retrieved. Be sure to use as narrow a search criteria as possible.
-          # Please use with caution.
+          # This method will make repeated API calls until all remaining results
+          # are retrieved. (Unlike `#each`, for example, which merely iterates
+          # over the results returned by a single API call.) Use with caution.
           #
           # @param [Integer] request_limit The upper limit of API requests to
           #   make to load all log entries. Default is no limit.

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

@@ -74,7 +74,7 @@ module Google
           end
 
           ##
-          # @private New HttpRequest from a
+          # @private New Google::Cloud::Logging::Entry::Operation from a
           # Google::Logging::V2::LogEntryOperation object.
           def self.from_grpc grpc
             return new if grpc.nil?

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

@@ -0,0 +1,86 @@
+# Copyright 2017 Google Inc. All rights reserved.
+#
+# 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.
+
+
+module Google
+  module Cloud
+    module Logging
+      class Entry
+        ##
+        # # SourceLocation
+        #
+        # Additional information about the source code location that produced
+        # the log entry.
+        #
+        # See also {Google::Cloud::Logging::Entry#source_location}.
+        #
+        class SourceLocation
+          ##
+          # @private Create an empty SourceLocation object.
+          def initialize
+          end
+
+          ##
+          # Source file name. Depending on the runtime environment, this might
+          # be a simple name or a fully-qualified name. Optional.
+          attr_accessor :file
+
+          ##
+          # Line within the source file. 1-based; `0` indicates no line number
+          # available. Optional.
+          attr_accessor :line
+
+          ##
+          # Human-readable name of the function or method being invoked, with
+          # optional context such as the class or package name. This information
+          # may be used in contexts such as the logs viewer, where a file and
+          # line number are less meaningful. Optional.
+          attr_accessor :function
+
+          ##
+          # @private Determines if the SourceLocation has any data.
+          def empty?
+            file.nil? &&
+              line.nil? &&
+              function.nil?
+          end
+
+          ##
+          # @private Exports the SourceLocation to a
+          # Google::Logging::V2::LogEntrySourceLocation object.
+          def to_grpc
+            return nil if empty?
+            Google::Logging::V2::LogEntrySourceLocation.new(
+              file:       file.to_s,
+              line:       line,
+              function:   function.to_s
+            )
+          end
+
+          ##
+          # @private New Google::Cloud::Logging::Entry::SourceLocation from a
+          # Google::Logging::V2::LogEntrySourceLocation object.
+          def self.from_grpc grpc
+            return new if grpc.nil?
+            new.tap do |o|
+              o.file       = grpc.file
+              o.line       = grpc.line
+              o.function   = grpc.function
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,155 @@
+# Copyright 2017 Google Inc. All rights reserved.
+#
+# 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.
+
+
+require "delegate"
+
+module Google
+  module Cloud
+    module Logging
+      class Log
+        ##
+        # Log::List is a special case Array with additional values.
+        class List < DelegateClass(::Array)
+          ##
+          # If not empty, indicates that there are more records that match
+          # the request and this value should be passed to continue.
+          attr_accessor :token
+
+          ##
+          # @private Create a new Log::List with an array of log names.
+          def initialize arr = []
+            super arr
+          end
+
+          ##
+          # Whether there is a next page of logs.
+          #
+          # @return [Boolean]
+          #
+          # @example
+          #   require "google/cloud/logging"
+          #
+          #   logging = Google::Cloud::Logging.new
+          #
+          #   logs = logging.logs
+          #   if logs.next?
+          #     next_logs = logs.next
+          #   end
+          #
+          def next?
+            !token.nil?
+          end
+
+          ##
+          # Retrieve the next page of logs.
+          #
+          # @return [Log::List]
+          #
+          # @example
+          #   require "google/cloud/logging"
+          #
+          #   logging = Google::Cloud::Logging.new
+          #
+          #   logs = logging.logs
+          #   if logs.next?
+          #     next_logs = logs.next
+          #   end
+          #
+          def next
+            return nil unless next?
+            ensure_service!
+            grpc = @service.list_logs token: token, resource: @resource,
+                                      max: @max
+            self.class.from_grpc grpc, @service
+          end
+
+          ##
+          # Retrieves remaining results by repeatedly invoking {#next} until
+          # {#next?} returns `false`. Calls the given block once for each
+          # result, which is passed as the argument to the block.
+          #
+          # An Enumerator is returned if no block is given.
+          #
+          # This method will make repeated API calls until all remaining results
+          # are retrieved. (Unlike `#each`, for example, which merely iterates
+          # over the results returned by a single API call.) Use with caution.
+          #
+          # @param [Integer] request_limit The upper limit of API requests to
+          #   make to load all log names. Default is no limit.
+          # @yield [log] The block for accessing each log name.
+          # @yieldparam [String] log The log name.
+          #
+          # @return [Enumerator]
+          #
+          # @example Iterating each log name by passing a block:
+          #   require "google/cloud/logging"
+          #
+          #   logging = Google::Cloud::Logging.new
+          #   logs = logging.logs
+          #
+          #   logs.all { |l| puts l }
+          #
+          # @example Limit the number of API calls made:
+          #   require "google/cloud/logging"
+          #
+          #   logging = Google::Cloud::Logging.new
+          #   logs = logging.logs
+          #
+          #   logs.all(request_limit: 10) { |l| puts l }
+          #
+          def all request_limit: nil
+            request_limit = request_limit.to_i if request_limit
+            unless block_given?
+              return enum_for(:all, request_limit: request_limit)
+            end
+            results = self
+            loop do
+              results.each { |r| yield r }
+              if request_limit
+                request_limit -= 1
+                break if request_limit < 0
+              end
+              break unless results.next?
+              results = results.next
+            end
+          end
+
+          ##
+          # @private New Log::List from a
+          # Google::Logging::V2::ListLogsResponse object.
+          def self.from_grpc grpc_list, service, resource: nil, max: nil
+            logs = new(Array(grpc_list.log_names))
+            token = grpc_list.next_page_token
+            token = nil if token == ""
+            logs.instance_variable_set "@token", token
+            logs.instance_variable_set "@service", service
+            logs.instance_variable_set "@resource", resource
+            logs.instance_variable_set "@max", max
+            logs
+          end
+
+          protected
+
+          ##
+          # @private Raise an error unless an active connection to the service
+          # is available.
+          def ensure_service!
+            fail "Must have active connection to service" unless @service
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -76,15 +76,15 @@ module Google
           end
 
           ##
-          # Retrieves all metrics by repeatedly loading {#next} until {#next?}
-          # returns `false`. Calls the given block once for each metric, which
-          # is passed as the parameter.
+          # Retrieves remaining results by repeatedly invoking {#next} until
+          # {#next?} returns `false`. Calls the given block once for each
+          # result, which is passed as the argument to the block.
           #
           # An Enumerator is returned if no block is given.
           #
-          # This method may make several API calls until all metrics are
-          # retrieved. Be sure to use as narrow a search criteria as possible.
-          # Please use with caution.
+          # This method will make repeated API calls until all remaining results
+          # are retrieved. (Unlike `#each`, for example, which merely iterates
+          # over the results returned by a single API call.) Use with caution.
           #
           # @param [Integer] request_limit The upper limit of API requests to
           #   make to load all metrics. Default is no limit.