google-cloud-logging 0.24.2 → 1.0.0

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

@@ -108,6 +108,16 @@ module Google
         # both are provided. Otherwise, construct a default monitored resource
         # based on the current environment.
         #
+        # @param [String] type Type of Google::Cloud::Logging::Resource
+        # @param [Hash<String, String>] labels Metadata lebels of
+        #   Google::Cloud::Logging::Resource
+        #
+        # @return [Google::Cloud::Logging::Resource] An Resource object with
+        #   type and labels
+        #
+        # @see https://cloud.google.com/logging/docs/api/v2/resource-list
+        #   Monitored Resources and Services
+        #
         # @example If both type and labels are provided, it returns resource:
         #   rc = Google::Cloud::Logging::Middleware.build_monitored_resource(
         #          "aws_ec2_instance",
@@ -142,15 +152,6 @@ module Google
         #   rc.type   #=> "global"
         #   rc.labels #=> {}
         #
-        # Reference https://cloud.google.com/logging/docs/api/ref_v2beta1/rest/v2beta1/MonitoredResource
-        # for a full list of monitoring resources
-        #
-        # @param [String] type Type of Google::Cloud::Logging::Resource
-        # @param [Hash<String, String>] labels Metadata lebels of
-        #   Google::Cloud::Logging::Resource
-        #
-        # @return [Google::Cloud::Logging::Resource] An Resource object with
-        #   type and labels
         def self.build_monitored_resource type = nil, labels = nil
           if type && labels
             Google::Cloud::Logging::Resource.new.tap do |r|
@@ -166,6 +167,12 @@ module Google
         # @private Extract information from current environment and construct
         # the correct monitoring resource types and labels.
         #
+        # @return [Google::Cloud::Logging::Resource] An Resource object with
+        #   correct type and labels
+        #
+        # @see https://cloud.google.com/logging/docs/api/v2/resource-list
+        #   Monitored Resources and Services
+        #
         # @example If running from GAE, returns default resource:
         #   rc = Google::Cloud::Logging::Middleware.send \
         #          :default_monitored_resource
@@ -193,25 +200,22 @@ module Google
         #   rc.type   #=> "global"
         #   rc.labels #=> {}
         #
-        # Reference https://cloud.google.com/logging/docs/api/ref_v2beta1/rest/v2beta1/MonitoredResource
-        # for a full list of monitoring resources
-        #
-        # @return [Google::Cloud::Logging::Resource] An Resource object with
-        #   correct type and labels
         def self.default_monitored_resource
           type, labels =
-            if Core::Environment.gae?
+            if Google::Cloud.env.app_engine?
               ["gae_app", {
-                module_id: Core::Environment.gae_module_id,
-                version_id: Core::Environment.gae_module_version }]
-            elsif Core::Environment.gke?
+                module_id: Google::Cloud.env.app_engine_service_id,
+                version_id: Google::Cloud.env.app_engine_service_version }]
+            elsif Google::Cloud.env.container_engine?
               ["container", {
-                cluster_name: Core::Environment.gke_cluster_name,
-                namespace_id: Core::Environment.gke_namespace_id || "default" }]
-            elsif Core::Environment.gce?
+                cluster_name: Google::Cloud.env.container_engine_cluster_name,
+                namespace_id: \
+                  Google::Cloud.env.container_engine_namespace_id || "default"
+              }]
+            elsif Google::Cloud.env.compute_engine?
               ["gce_instance", {
-                instance_id: Core::Environment.instance_id,
-                zone: Core::Environment.instance_zone }]
+                instance_id: Google::Cloud.env.instance_name,
+                zone: Google::Cloud.env.instance_zone }]
             else
               ["global", {}]
             end

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

@@ -14,9 +14,10 @@
 
 
 require "google/cloud/errors"
-require "google/cloud/core/environment"
+require "google/cloud/env"
 require "google/cloud/logging/service"
 require "google/cloud/logging/credentials"
+require "google/cloud/logging/log/list"
 require "google/cloud/logging/entry"
 require "google/cloud/logging/resource_descriptor"
 require "google/cloud/logging/sink"
@@ -81,7 +82,7 @@ module Google
           ENV["LOGGING_PROJECT"] ||
             ENV["GOOGLE_CLOUD_PROJECT"] ||
             ENV["GCLOUD_PROJECT"] ||
-            Google::Cloud::Core::Environment.project_id
+            Google::Cloud.env.project_id
         end
 
         ##
@@ -127,7 +128,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
@@ -382,6 +383,48 @@ module Google
           Logger.new shared_async_writer, log_name, resource, labels
         end
 
+        ##
+        # Lists log names. Use this method to retrieve log names from Cloud
+        # Logging.
+        #
+        # @param [String] resource The cloud resource from which to retrieve log
+        #   names. Optional. If `nil`, the ID of the receiving project instance
+        #   will be used. Examples: `"projects/my-project-1A"`,
+        #   `"projects/1234567890"`.
+        # @param [String] token A previously-returned page token representing
+        #   part of the larger set of results to view.
+        # @param [Integer] max Maximum number of log names to return.
+        #
+        # @return [Array<String>] A list of log names. For example,
+        #   `projects/my-project/syslog` or
+        #   `organizations/123/cloudresourcemanager.googleapis.com%2Factivity`.
+        #   (See {Google::Cloud::Logging::Log::List})
+        #
+        # @example
+        #   require "google/cloud/logging"
+        #
+        #   logging = Google::Cloud::Logging.new
+        #   logs = logging.logs
+        #   logs.each { |l| puts l }
+        #
+        # @example Retrieve all log names: (See {Log::List#all})
+        #   require "google/cloud/logging"
+        #
+        #   logging = Google::Cloud::Logging.new
+        #   logs = logging.logs
+        #
+        #   logs.all { |l| puts l }
+        #
+        def logs resource: nil, token: nil, max: nil
+          ensure_service!
+          list_grpc = service.list_logs resource: resource, token: token,
+                                        max: max
+          Log::List.from_grpc list_grpc, service, resource: resource, max: max
+        end
+        alias_method :find_logs, :logs
+        alias_method :log_names, :logs
+        alias_method :find_log_names, :logs
+
         ##
         # Deletes a log and all its log entries. The log will reappear if it
         # receives new entries.

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

@@ -24,25 +24,33 @@ module Google
       ##
       # Railtie
       #
-      # Google::Cloud::Logging::Railtie automatically add the
-      # Google::Cloud::Logging::Middleware to Rack in a Rails environment.
-      # The middleware will set env['rack.logger'] to a
-      # Google::Cloud::Logging::Logger instance to be used by the Rails
+      # Adds the {Google::Cloud::Logging::Middleware} to Rack in a Rails
+      # environment. The middleware will set `env['rack.logger']` to a
+      # {Google::Cloud::Logging::Logger} instance to be used by the Rails
       # application.
       #
       # The Middleware is only added when certain conditions are met. See
-      # {use_logging?} for detail.
+      # {use_logging?} for details.
+      #
+      # When loaded, the {Google::Cloud::Logging::Middleware} will be inserted
+      # before the `Rails::Rack::Logger Middleware`, which allows it to set the
+      # `env['rack.logger']` in place of Rails's default logger. The Railtie
+      # will also initialize the logger with correct GCP `project_id`
+      # and `keyfile` if they are defined in the Rails `environment.rb` file as
+      # follows:
+      #
+      # ```ruby
+      # config.google_cloud.logging.project_id = "my-gcp-project"
+      # config.google_cloud.logging.keyfile = "/path/to/secret.json"
+      # ```
       #
-      # When loaded, the Google::Cloud::Logging::Middleware will be inserted
-      # before the Rails::Rack::Logger Middleware, which allows it to set the
-      # env['rack.logger'] in place of Rails's default logger. The Railtie
-      # should also initialize the logger with correct GCP project_id
-      # and keyfile if they are defined in Rails environment.rb as follow:
-      #   config.google_cloud.logging.project_id = "my-gcp-project"
-      #   config.google_cloud.logging.keyfile = "/path/to/secret.json"
       # or
-      #   config.google_cloud.project_id = "my-gcp-project"
-      #   config.google_cloud.keyfile = "/path/to/secret.json"
+      #
+      # ```ruby
+      # config.google_cloud.project_id = "my-gcp-project"
+      # config.google_cloud.keyfile = "/path/to/secret.json"
+      # ```
+      #
       # If omitted, project_id will be initialized with default environment
       # variables.
       #
@@ -82,18 +90,27 @@ module Google
         ##
         # Determine whether to use Stackdriver Logging or not.
         #
-        # Returns true if valid GCP project_id is provided and underneath API is
-        # able to authenticate. Also either Rails needs to be in "production"
-        # environment or config.stackdriver.use_logging is explicitly true.
+        # Returns `true` if Stackdriver Logging is enabled for this application.
+        # That is, if all of the following are true:
+        #
+        # * A valid GCP `project_id` is available, either because the
+        #   application is hosted on Google Cloud or because it is set in the
+        #   configuration.
+        # * The API is able to authenticate, again either because the
+        #   application is hosted on Google Cloud or because an appropriate
+        #   keyfile is provided in the configuration.
+        # * Either the Rails environment is set to `production` or the
+        #   `config.google_cloud.use_logging` configuration is explicitly set to
+        #   `true`.
         #
         # @param [Rails::Railtie::Configuration] config The
-        #   Rails.application.config
+        #   `Rails.application.config`
         #
         # @return [Boolean] Whether to use Stackdriver Logging
         #
         def self.use_logging? config
           gcp_config = config.google_cloud
-          # Return false if config.stackdriver.use_logging is explicitly false
+          # Return false if config.google_cloud.use_logging is explicitly false
           return false if gcp_config.key?(:use_logging) &&
                           !gcp_config.use_logging
 
@@ -118,7 +135,7 @@ module Google
           end
 
           # Otherwise default to true if Rails is running in production or
-          # config.stackdriver.use_logging is true
+          # config.google_cloud.use_logging is true
           Rails.env.production? || gcp_config.use_logging
         end
       end

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

@@ -78,15 +78,15 @@ module Google
           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.
+          # 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 resource
-          # descriptors 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 resource descriptors. Default is no limit.

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

@@ -129,6 +129,21 @@ module Google
           end
         end
 
+        def list_logs resource: nil, token: nil, max: nil
+          parent = resource || "projects/#{@project}"
+          call_opts = default_options
+          if token
+            call_opts = Google::Gax::CallOptions.new(kwargs: default_headers,
+                                                     page_token: token)
+          end
+
+          execute do
+            paged_enum = logging.list_logs parent, page_size: max,
+                                                   options: call_opts
+            paged_enum.page.response
+          end
+        end
+
         def delete_log name
           execute do
             logging.delete_log log_path(name), options: default_options

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

@@ -75,15 +75,15 @@ module Google
           end
 
           ##
-          # Retrieves all sinks by repeatedly loading {#next} until {#next?}
-          # returns `false`. Calls the given block once for each sink, 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 sinks 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 sinks. Default is no limit.

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

@@ -1,10 +1,10 @@
-# Copyright 2016 Google Inc. All rights reserved.
+# 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
+#     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,
@@ -26,6 +26,7 @@ require "json"
 require "pathname"
 
 require "google/gax"
+
 require "google/logging/v2/logging_config_pb"
 
 module Google
@@ -216,8 +217,12 @@ module Google
           # Lists sinks.
           #
           # @param parent [String]
-          #   Required. The parent resource whose sinks are to be listed.
-          #   Examples: +"projects/my-logging-project"+, +"organizations/123456789"+.
+          #   Required. The parent resource whose sinks are to be listed:
+          #
+          #       "projects/[PROJECT_ID]"
+          #       "organizations/[ORGANIZATION_ID]"
+          #       "billingAccounts/[BILLING_ACCOUNT_ID]"
+          #       "folders/[FOLDER_ID]"
           # @param page_size [Integer]
           #   The maximum number of resources contained in the underlying API
           #   response. If page streaming is performed per-resource, this
@@ -268,10 +273,12 @@ module Google
           # Gets a sink.
           #
           # @param sink_name [String]
-          #   Required. The parent resource name of the sink:
+          #   Required. The resource name of the sink:
           #
           #       "projects/[PROJECT_ID]/sinks/[SINK_ID]"
           #       "organizations/[ORGANIZATION_ID]/sinks/[SINK_ID]"
+          #       "billingAccounts/[BILLING_ACCOUNT_ID]/sinks/[SINK_ID]"
+          #       "folders/[FOLDER_ID]/sinks/[SINK_ID]"
           #
           #   Example: +"projects/my-project-id/sinks/my-sink-id"+.
           # @param options [Google::Gax::CallOptions]
@@ -308,6 +315,8 @@ module Google
           #
           #       "projects/[PROJECT_ID]"
           #       "organizations/[ORGANIZATION_ID]"
+          #       "billingAccounts/[BILLING_ACCOUNT_ID]"
+          #       "folders/[FOLDER_ID]"
           #
           #   Examples: +"projects/my-logging-project"+, +"organizations/123456789"+.
           # @param sink [Google::Logging::V2::LogSink]
@@ -317,9 +326,9 @@ module Google
           #   Optional. Determines the kind of IAM identity returned as +writer_identity+
           #   in the new sink.  If this value is omitted or set to false, and if the
           #   sink's parent is a project, then the value returned as +writer_identity+ is
-          #   +cloud-logs@google.com+, the same identity used before the addition of
-          #   writer identities to this API. The sink's destination must be in the same
-          #   project as the sink itself.
+          #   the same group or service account used by Stackdriver Logging before the
+          #   addition of writer identities to this API. The sink's destination must be
+          #   in the same project as the sink itself.
           #
           #   If this field is set to true, or if the sink is owned by a non-project
           #   resource such as an organization, then the value of +writer_identity+ will
@@ -369,6 +378,8 @@ module Google
           #
           #       "projects/[PROJECT_ID]/sinks/[SINK_ID]"
           #       "organizations/[ORGANIZATION_ID]/sinks/[SINK_ID]"
+          #       "billingAccounts/[BILLING_ACCOUNT_ID]/sinks/[SINK_ID]"
+          #       "folders/[FOLDER_ID]/sinks/[SINK_ID]"
           #
           #   Example: +"projects/my-project-id/sinks/my-sink-id"+.
           # @param sink [Google::Logging::V2::LogSink]
@@ -384,9 +395,9 @@ module Google
           #
           #   +   If the old and new values of this field are both false or both true,
           #       then there is no change to the sink's +writer_identity+.
-          #   +   If the old value was false and the new value is true, then
+          #   +   If the old value is false and the new value is true, then
           #       +writer_identity+ is changed to a unique service account.
-          #   +   It is an error if the old value was true and the new value is false.
+          #   +   It is an error if the old value is true and the new value is false.
           # @param options [Google::Gax::CallOptions]
           #   Overrides the default settings for this call, e.g, timeout,
           #   retries, etc.
@@ -425,10 +436,10 @@ module Google
           #
           #       "projects/[PROJECT_ID]/sinks/[SINK_ID]"
           #       "organizations/[ORGANIZATION_ID]/sinks/[SINK_ID]"
+          #       "billingAccounts/[BILLING_ACCOUNT_ID]/sinks/[SINK_ID]"
+          #       "folders/[FOLDER_ID]/sinks/[SINK_ID]"
           #
-          #   It is an error if the sink does not exist.  Example:
-          #   +"projects/my-project-id/sinks/my-sink-id"+.  It is an error if
-          #   the sink does not exist.
+          #   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.

data/lib/google/cloud/logging/v2/config_service_v2_client_config.json

@@ -6,7 +6,9 @@
           "DEADLINE_EXCEEDED",
           "UNAVAILABLE"
         ],
-        "non_idempotent": []
+        "non_idempotent": [
+          "UNAVAILABLE"
+        ]
       },
       "retry_params": {
         "default": {

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

@@ -22,6 +22,8 @@ module Google
       #
       #         "projects/[PROJECT_ID]/logs/[LOG_ID]"
       #         "organizations/[ORGANIZATION_ID]/logs/[LOG_ID]"
+      #         "billingAccounts/[BILLING_ACCOUNT_ID]/logs/[LOG_ID]"
+      #         "folders/[FOLDER_ID]/logs/[LOG_ID]"
       #
       #     +[LOG_ID]+ must be URL-encoded within +log_name+. Example:
       #     +"organizations/1234567890/logs/cloudresourcemanager.googleapis.com%2Factivity"+.
@@ -55,18 +57,22 @@ module Google
       # @!attribute [rw] timestamp
       #   @return [Google::Protobuf::Timestamp]
       #     Optional. The time the event described by the log entry occurred.  If
-      #     omitted, Stackdriver Logging will use the time the log entry is received.
+      #     omitted in a new log entry, Stackdriver Logging will insert the time the
+      #     log entry is received.  Stackdriver Logging might reject log entries whose
+      #     time stamps are more than a couple of hours in the future. Log entries
+      #     with time stamps in the past are accepted.
       # @!attribute [rw] severity
       #   @return [Google::Logging::Type::LogSeverity]
       #     Optional. The severity of the log entry. The default value is
       #     +LogSeverity.DEFAULT+.
       # @!attribute [rw] insert_id
       #   @return [String]
-      #     Optional. A unique ID for the log entry. If you provide this
-      #     field, the logging service considers other log entries in the
-      #     same project with the same ID as duplicates which can be removed.  If
-      #     omitted, Stackdriver Logging will generate a unique ID for this
-      #     log entry.
+      #     Optional. A unique identifier for the log entry. If you provide a value,
+      #     then Stackdriver Logging considers other log entries in the same project,
+      #     with the same +timestamp+, and with the same +insert_id+ to be duplicates
+      #     which can be removed.  If omitted in new log entries, then Stackdriver
+      #     Logging will insert its own unique identifier. The +insert_id+ is used
+      #     to order log entries that have the same +timestamp+ value.
       # @!attribute [rw] http_request
       #   @return [Google::Logging::Type::HttpRequest]
       #     Optional. Information about the HTTP request associated with this