google-cloud-logging 0.20.0

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

@@ -0,0 +1,86 @@
+# Copyright 2016 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
+      ##
+      # # Resource
+      #
+      # A monitored resource is an abstraction used to characterize many kinds
+      # of objects in your cloud infrastructure, including Google Cloud SQL
+      # databases, Google App Engine apps, Google Compute Engine virtual machine
+      # instances, and so forth. Each of those kinds of objects is described by
+      # an instance of {ResourceDescriptor}.
+      #
+      # For use with {Google::Cloud::Logging::Entry#resource},
+      # {Google::Cloud::Logging::Project#resource}, and
+      # {Google::Cloud::Logging::Project#write_entries}.
+      #
+      # @example
+      #   require "google/cloud"
+      #
+      #   gcloud = Google::Cloud.new
+      #   logging = gcloud.logging
+      #   resource = logging.resource "gae_app",
+      #                               "module_id" => "1",
+      #                               "version_id" => "20150925t173233"
+      #
+      class Resource
+        ##
+        # Create an empty Resource object.
+        def initialize
+          @labels = {}
+        end
+
+        ##
+        # The type of resource, as represented by a {ResourceDescriptor}.
+        attr_accessor :type
+
+        ##
+        # A set of labels that can be used to describe instances of this
+        # monitored resource type.
+        attr_accessor :labels
+
+        ##
+        # @private Determines if the Resource has any data.
+        def empty?
+          type.nil? && (labels.nil? || labels.empty?)
+        end
+
+        ##
+        # @private Exports the Resource to a Google::Api::MonitoredResource
+        # object.
+        def to_grpc
+          return nil if empty?
+          Google::Api::MonitoredResource.new(
+            type: type,
+            labels: Hash[labels.map { |k, v| [String(k), String(v)] }]
+          )
+        end
+
+        ##
+        # @private New Resource from a Google::Api::MonitoredResource object.
+        def self.from_grpc grpc
+          return new if grpc.nil?
+          new.tap do |r|
+            r.type = grpc.type
+            r.labels = Core::GRPCUtils.map_to_hash(grpc.labels)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,139 @@
+# Copyright 2016 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 "google/cloud/logging/resource_descriptor/list"
+
+module Google
+  module Cloud
+    module Logging
+      ##
+      # # ResourceDescriptor
+      #
+      # Describes a type of monitored resource supported by Stackdriver Logging.
+      # Each ResourceDescriptor has a type name, such as `cloudsql_database`,
+      # `gae_app`, or `gce_instance`. It also specifies a set of labels that
+      # must all be given values in a {Resource} instance to represent an actual
+      # instance of the type.
+      #
+      # ResourceDescriptor instances are read-only. You cannot create your own
+      # instances, but you can list them with {Project#resource_descriptors}.
+      #
+      # @example
+      #   require "google/cloud"
+      #
+      #   gcloud = Google::Cloud.new
+      #   logging = gcloud.logging
+      #   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"]
+      #
+      class ResourceDescriptor
+        ##
+        # @private New ResourceDescriptor from a Google API Client object.
+        def initialize
+          @labels = []
+        end
+
+        ##
+        # The monitored resource type. For example, `cloudsql_database`.
+        attr_reader :type
+
+        ##
+        # A display name for the monitored resource type. For example,
+        # `Cloud SQL Database`.
+        attr_reader :name
+
+        ##
+        # A detailed description of the monitored resource type, which is used
+        # in documentation.
+        attr_reader :description
+
+        ##
+        # A set of definitions of the labels that can be used to describe
+        # instances of this monitored resource type. For example, Cloud SQL
+        # databases must be labeled with their `database_id` and their `region`.
+        #
+        # @return [Array<LabelDescriptor>]
+        #
+        attr_reader :labels
+
+        ##
+        # @private New ResourceDescriptor from a
+        # Google::Api::MonitoredResourceDescriptor object.
+        def self.from_grpc grpc
+          r = new
+          r.instance_variable_set "@type", grpc.type
+          r.instance_variable_set "@name", grpc.display_name
+          r.instance_variable_set "@description", grpc.description
+          labels = Array(grpc.labels).map do |g|
+            LabelDescriptor.from_grpc g
+          end
+          r.instance_variable_set "@labels", labels
+          r
+        end
+
+        ##
+        # # LabelDescriptor
+        #
+        # A definition of a label that can be used to describe instances of a
+        # {Resource}. For example, Cloud SQL databases must be labeled with
+        # their `database_id`. See {ResourceDescriptor#labels}.
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   logging = gcloud.logging
+        #   resource_descriptor = logging.resource_descriptors.first
+        #   label_descriptor = resource_descriptor.labels.first
+        #   label_descriptor.key #=> "database_id"
+        #   label_descriptor.description #=> "The ID of the database."
+        #
+        class LabelDescriptor
+          ##
+          # The key (name) of the label.
+          attr_reader :key
+
+          ##
+          # The type of data that can be assigned to the label.
+          #
+          # @return [Symbol, nil] Returns `:string`, `:boolean`, `:integer`, or
+          #   `nil` if there is no type.
+          #
+          attr_reader :type
+
+          ##
+          # A human-readable description for the label.
+          attr_reader :description
+
+          ##
+          # @private New LabelDescriptor from a Google::Api::LabelDescriptor
+          # object.
+          def self.from_grpc grpc
+            type_sym = { STRING: :string,
+                         BOOL:   :boolean,
+                         INT64:  :integer }[grpc.value_type]
+            l = new
+            l.instance_variable_set "@key", grpc.key
+            l.instance_variable_set "@type", type_sym
+            l.instance_variable_set "@description", grpc.description
+            l
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,179 @@
+# Copyright 2016 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 ResourceDescriptor
+        ##
+        # ResourceDescriptor::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 ResourceDescriptor::List with an array of
+          # ResourceDescriptor instances.
+          def initialize arr = []
+            super arr
+          end
+
+          ##
+          # Whether there is a next page of resource descriptors.
+          #
+          # @return [Boolean]
+          #
+          # @example
+          #   require "google/cloud"
+          #
+          #   gcloud = Google::Cloud.new
+          #   logging = gcloud.logging
+          #
+          #   resource_descriptors = logging.resource_descriptors
+          #   if resource_descriptors.next?
+          #     next_resource_descriptors = resource_descriptors.next
+          #   end
+          #
+          def next?
+            !token.nil?
+          end
+
+          ##
+          # Retrieve the next page of resource descriptors.
+          #
+          # @return [Sink::List]
+          #
+          # @example
+          #   require "google/cloud"
+          #
+          #   gcloud = Google::Cloud.new
+          #   logging = gcloud.logging
+          #
+          #   resource_descriptors = logging.resource_descriptors
+          #   if resource_descriptors.next?
+          #     next_resource_descriptors = resource_descriptors.next
+          #   end
+          #
+          def next
+            return nil unless next?
+            ensure_service!
+            list_grpc = @service.list_resource_descriptors(
+              token: token, max: @max)
+            self.class.from_grpc list_grpc, @service
+          end
+
+          ##
+          # Retrieves all resource descriptors by repeatedly loading {#next}
+          # until {#next?} returns `false`. Calls the given block once for each
+          # resource descriptor, which is passed as the parameter.
+          #
+          # An Enumerator is returned if no block is given.
+          #
+          # This method may make several API calls until all resource
+          # descriptors are retrieved. Be sure to use as narrow a search
+          # criteria as possible. Please use with caution.
+          #
+          # @param [Integer] request_limit The upper limit of API requests to
+          #   make to load all resource descriptors. Default is no limit.
+          # @yield [resource_descriptor] The block for accessing each resource
+          #   descriptor.
+          # @yieldparam [ResourceDescriptor] resource_descriptor The resource
+          #   descriptor object.
+          #
+          # @return [Enumerator]
+          #
+          # @example Iterating each resource descriptor by passing a block:
+          #   require "google/cloud"
+          #
+          #   gcloud = Google::Cloud.new
+          #   logging = gcloud.logging
+          #   resource_descriptors = logging.resource_descriptors
+          #
+          #   resource_descriptors.all do |rd|
+          #     puts rd.type
+          #   end
+          #
+          # @example Using the enumerator by not passing a block:
+          #   require "google/cloud"
+          #
+          #   gcloud = Google::Cloud.new
+          #   logging = gcloud.logging
+          #   resource_descriptors = logging.resource_descriptors
+          #
+          #   all_types = resource_descriptors.all.map do |rd|
+          #     rd.type
+          #   end
+          #
+          # @example Limit the number of API calls made:
+          #   require "google/cloud"
+          #
+          #   gcloud = Google::Cloud.new
+          #   logging = gcloud.logging
+          #   resource_descriptors = logging.resource_descriptors
+          #
+          #   resource_descriptors.all(request_limit: 10) do |rd|
+          #     puts rd.type
+          #   end
+          #
+          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 ResourceDescriptor::List from a
+          # Google::Logging::V2::ListMonitoredResourceDescriptorsResponse
+          # object.
+          def self.from_grpc grpc_list, service, max = nil
+            rds = new(Array(grpc_list.resource_descriptors).map do |grpc|
+              ResourceDescriptor.from_grpc grpc
+            end)
+            token = grpc_list.next_page_token
+            token = nil if token == ""
+            rds.instance_variable_set "@token", token
+            rds.instance_variable_set "@service", service
+            rds.instance_variable_set "@max", max
+            rds
+          end
+
+          protected
+
+          ##
+          # Raise an error unless an active service is available.
+          def ensure_service!
+            fail "Must have active service" unless @service
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,270 @@
+# Copyright 2016 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 "google/cloud/errors"
+require "google/cloud/core/grpc_backoff"
+require "google/logging/v2/logging_services_pb"
+require "google/logging/v2/logging_config_services_pb"
+require "google/logging/v2/logging_metrics_services_pb"
+
+module Google
+  module Cloud
+    module Logging
+      ##
+      # @private Represents the gRPC Logging service, including all the API
+      # methods.
+      class Service
+        attr_accessor :project, :credentials, :host, :retries, :timeout
+
+        ##
+        # Creates a new Service instance.
+        def initialize project, credentials, host: nil, retries: nil,
+                       timeout: nil
+          @project = project
+          @credentials = credentials
+          @host = host || "logging.googleapis.com"
+          @retries = retries
+          @timeout = timeout
+        end
+
+        def creds
+          GRPC::Core::ChannelCredentials.new.compose \
+            GRPC::Core::CallCredentials.new credentials.client.updater_proc
+        end
+
+        def logging
+          return mocked_logging if mocked_logging
+          @logging ||= Google::Logging::V2::LoggingServiceV2::Stub.new(
+            host, creds, timeout: timeout)
+        end
+        attr_accessor :mocked_logging
+
+        def sinks
+          return mocked_sinks if mocked_sinks
+          @sinks ||= Google::Logging::V2::ConfigServiceV2::Stub.new(
+            host, creds, timeout: timeout)
+        end
+        attr_accessor :mocked_sinks
+
+        def metrics
+          return mocked_metrics if mocked_metrics
+          @metrics ||= Google::Logging::V2::MetricsServiceV2::Stub.new(
+            host, creds, timeout: timeout)
+        end
+        attr_accessor :mocked_metrics
+
+        def list_entries projects: nil, filter: nil, order: nil, token: nil,
+                         max: nil
+          list_params = { project_ids: Array(projects || @project),
+                          filter: filter,
+                          order_by: order,
+                          page_token: token,
+                          page_size: max
+                        }.delete_if { |_, v| v.nil? }
+
+          list_req = Google::Logging::V2::ListLogEntriesRequest.new(list_params)
+
+          execute { logging.list_log_entries list_req }
+        end
+
+        def write_entries entries, log_name: nil, resource: nil, labels: nil
+          # Fix log names so they are the full path
+          entries = Array(entries).each do |entry|
+            entry.log_name = log_path(entry.log_name)
+          end
+          resource = resource.to_grpc if resource
+          labels = Hash[labels.map { |k, v| [String(k), String(v)] }] if labels
+
+          write_params = { entries: entries,
+                           log_name: log_path(log_name),
+                           resource: resource, labels: labels
+                         }.delete_if { |_, v| v.nil? }
+
+          write_req = Google::Logging::V2::WriteLogEntriesRequest.new(
+            write_params)
+
+          execute { logging.write_log_entries write_req }
+        end
+
+        def delete_log name
+          delete_req = Google::Logging::V2::DeleteLogRequest.new(
+            log_name: log_path(name)
+          )
+
+          execute { logging.delete_log delete_req }
+        end
+
+        def list_resource_descriptors token: nil, max: nil
+          list_params = { page_token: token,
+                          page_size: max
+                        }.delete_if { |_, v| v.nil? }
+
+          list_req = \
+            Google::Logging::V2::ListMonitoredResourceDescriptorsRequest.new(
+              list_params)
+
+          execute { logging.list_monitored_resource_descriptors list_req }
+        end
+
+        def list_sinks token: nil, max: nil
+          list_params = { parent: project_path,
+                          page_token: token,
+                          page_size: max
+                        }.delete_if { |_, v| v.nil? }
+
+          list_req = Google::Logging::V2::ListSinksRequest.new(list_params)
+
+          execute { sinks.list_sinks list_req }
+        end
+
+        def create_sink name, destination, filter, version
+          sink_params = {
+            name: name, destination: destination,
+            filter: filter, output_version_format: version
+          }.delete_if { |_, v| v.nil? }
+
+          create_req = Google::Logging::V2::CreateSinkRequest.new(
+            parent: project_path,
+            sink: Google::Logging::V2::LogSink.new(sink_params)
+          )
+
+          execute { sinks.create_sink create_req }
+        end
+
+        def get_sink name
+          get_req = Google::Logging::V2::GetSinkRequest.new(
+            sink_name: sink_path(name)
+          )
+
+          execute { sinks.get_sink get_req }
+        end
+
+        def update_sink name, destination, filter, version
+          sink_params = {
+            name: name, destination: destination,
+            filter: filter, output_version_format: version
+          }.delete_if { |_, v| v.nil? }
+
+          update_req = Google::Logging::V2::UpdateSinkRequest.new(
+            sink_name: sink_path(name),
+            sink: Google::Logging::V2::LogSink.new(sink_params)
+          )
+
+          execute { sinks.update_sink update_req }
+        end
+
+        def delete_sink name
+          delete_req = Google::Logging::V2::DeleteSinkRequest.new(
+            sink_name: sink_path(name)
+          )
+
+          execute { sinks.delete_sink delete_req }
+        end
+
+        def list_metrics token: nil, max: nil
+          list_params = { parent: project_path,
+                          page_token: token,
+                          page_size: max
+                        }.delete_if { |_, v| v.nil? }
+
+          list_req = Google::Logging::V2::ListLogMetricsRequest.new(list_params)
+
+          execute { metrics.list_log_metrics list_req }
+        end
+
+        def create_metric name, filter, description
+          metric_params = {
+            name: name,
+            description: description,
+            filter: filter
+          }.delete_if { |_, v| v.nil? }
+
+          create_req = Google::Logging::V2::CreateLogMetricRequest.new(
+            parent: project_path,
+            metric: Google::Logging::V2::LogMetric.new(metric_params)
+          )
+
+          execute { metrics.create_log_metric create_req }
+        end
+
+        def get_metric name
+          get_req = Google::Logging::V2::GetLogMetricRequest.new(
+            metric_name: metric_path(name)
+          )
+
+          execute { metrics.get_log_metric get_req }
+        end
+
+        def update_metric name, description, filter
+          metric_params = {
+            name: name,
+            description: description,
+            filter: filter
+          }.delete_if { |_, v| v.nil? }
+
+          update_req = Google::Logging::V2::UpdateLogMetricRequest.new(
+            metric_name: metric_path(name),
+            metric: Google::Logging::V2::LogMetric.new(metric_params)
+          )
+
+          execute { metrics.update_log_metric update_req }
+        end
+
+        def delete_metric name
+          delete_req = Google::Logging::V2::DeleteLogMetricRequest.new(
+            metric_name: metric_path(name)
+          )
+
+          execute { metrics.delete_log_metric delete_req }
+        end
+
+        def inspect
+          "#{self.class}(#{@project})"
+        end
+
+        protected
+
+        def project_path
+          "projects/#{@project}"
+        end
+
+        def log_path log_name
+          return nil if log_name.nil?
+          return log_name if log_name.empty?
+          return log_name if log_name.to_s.include? "/"
+          "#{project_path}/logs/#{log_name}"
+        end
+
+        def sink_path sink_name
+          return sink_name if sink_name.to_s.include? "/"
+          "#{project_path}/sinks/#{sink_name}"
+        end
+
+        def metric_path metric_name
+          return metric_name if metric_name.to_s.include? "/"
+          "#{project_path}/metrics/#{metric_name}"
+        end
+
+        def execute
+          Google::Cloud::Core::GrpcBackoff.new(retries: retries).execute do
+            yield
+          end
+        rescue GRPC::BadStatus => e
+          raise Google::Cloud::Error.from_error(e)
+        end
+      end
+    end
+  end
+end