google-cloud-logging 0.24.0 → 0.24.1

data/lib/google/cloud/logging/v2/doc/google/logging/v2/logging_config.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,
@@ -15,11 +15,10 @@
 module Google
   module Logging
     module V2
-      # Describes a sink used to export log entries outside of Stackdriver Logging.
-      # 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_time+ and
-      # +end_time+ are present, then +start_time+ must be less than +end_time+.
+      # Describes a sink used to export log entries to one of the following
+      # destinations in any project: a Cloud Storage bucket, a BigQuery dataset, or a
+      # Cloud Pub/Sub topic.  A logs filter controls which log entries are
+      # exported. The sink must be created within a project or organization.
       # @!attribute [rw] name
       #   @return [String]
       #     Required. The client-assigned sink identifier, unique within the
@@ -35,47 +34,61 @@ module Google
       #         "bigquery.googleapis.com/projects/[PROJECT_ID]/datasets/[DATASET]"
       #         "pubsub.googleapis.com/projects/[PROJECT_ID]/topics/[TOPIC_ID]"
       #
-      #     For more information,  see
+      #     The sink's +writer_identity+, set when the sink is created, must
+      #     have permission to write to the destination or else the log
+      #     entries are not exported.  For more information, see
       #     {Exporting Logs With Sinks}[https://cloud.google.com/logging/docs/api/tasks/exporting-logs].
       # @!attribute [rw] filter
       #   @return [String]
-      #     Optional. An {advanced logs filter}[https://cloud.google.com/logging/docs/view/advanced_filters].
-      #     Only log entries matching the filter are exported. The filter
-      #     must be consistent with the log entry format specified by the
-      #     +outputVersionFormat+ parameter, regardless of the format of the
-      #     log entry that was originally ingested by Stackdriver Logging.
-      #     The following example uses field names in the v2 log entry format:
+      #     Optional.
+      #     An {advanced logs filter}[https://cloud.google.com/logging/docs/view/advanced_filters].  The only
+      #     exported log entries are those that are in the resource owning the sink and
+      #     that match the filter. The filter must use the log entry format specified
+      #     by the +output_version_format+ parameter.  For example, in the v2 format:
       #
       #         logName="projects/[PROJECT_ID]/logs/[LOG_ID]" AND severity>=ERROR
       # @!attribute [rw] output_version_format
       #   @return [Google::Logging::V2::LogSink::VersionFormat]
-      #     Optional. The log entry version to use for this sink's exported log
-      #     entries.  This version does not have to correspond to the version of the
-      #     log entry that was written to Stackdriver Logging. If omitted, the
-      #     v2 format is used.
+      #     Optional. The log entry format to use for this sink's exported log
+      #     entries.  The v2 format is used by default.
+      #     **The v1 format is deprecated** and should be used only as part of a
+      #     migration effort to v2.
+      #     See {Migration to the v2 API}[https://cloud.google.com/logging/docs/api/v2/migration-to-v2].
       # @!attribute [rw] writer_identity
       #   @return [String]
-      #     Output only. 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.
+      #     Output only. An IAM identity—a service account or group—under
+      #     which Stackdriver Logging writes the exported log entries to the sink's
+      #     destination.  This field is set by
+      #     {sinks.create}[https://cloud.google.com/logging/docs/api/reference/rest/v2/projects.sinks/create]
+      #     and
+      #     {sinks.update}[https://cloud.google.com/logging/docs/api/reference/rest/v2/projects.sinks/update],
+      #     based on the setting of +unique_writer_identity+ in those methods.
+      #
+      #     Until you grant this identity write-access to the destination, log entry
+      #     exports from this sink will fail. For more information,
+      #     see {Granting access for a
+      #     resource}[https://cloud.google.com/iam/docs/granting-roles-to-service-accounts#granting_access_to_a_service_account_for_a_resource].
+      #     Consult the destination service's documentation to determine the
+      #     appropriate IAM roles to assign to the identity.
       # @!attribute [rw] start_time
       #   @return [Google::Protobuf::Timestamp]
-      #     Optional. The time at which this sink will begin exporting log entries.  If
-      #     this value is present, then log entries are exported only if +start_time+
-      #     <=+entry.timestamp+.
+      #     Optional. The time at which this sink will begin exporting log entries.
+      #     Log entries are exported only if their timestamp is not earlier than the
+      #     start time.  The default value of this field is the time the sink is
+      #     created or updated.
       # @!attribute [rw] end_time
       #   @return [Google::Protobuf::Timestamp]
-      #     Optional. Time at which this sink will stop exporting log entries.  If this
-      #     value is present, then log entries are exported only if +entry.timestamp+ <
-      #     +end_time+.
+      #     Optional. The time at which this sink will stop exporting log entries.  Log
+      #     entries are exported only if their timestamp is earlier than the end time.
+      #     If this field is not supplied, there is no end time.  If both a start time
+      #     and an end time are provided, then the end time must be later than the
+      #     start time.
       class LogSink
         # Available log entry formats. Log entries can be written to Stackdriver
         # Logging in either format and can be exported in either format.
         # Version 2 is the preferred format.
         module VersionFormat
-          # An unspecified version format will default to V2.
+          # An unspecified format version that will default to V2.
           VERSION_FORMAT_UNSPECIFIED = 0
 
           # +LogEntry+ version 2 format.
@@ -89,10 +102,8 @@ module Google
       # The parameters to +ListSinks+.
       # @!attribute [rw] parent
       #   @return [String]
-      #     Required. The resource name where this sink was created:
-      #
-      #         "projects/[PROJECT_ID]"
-      #         "organizations/[ORGANIZATION_ID]"
+      #     Required. The parent resource whose sinks are to be listed.
+      #     Examples: +"projects/my-logging-project"+, +"organizations/123456789"+.
       # @!attribute [rw] page_token
       #   @return [String]
       #     Optional. If present, then retrieve the next batch of results from the
@@ -120,10 +131,12 @@ module Google
       # The parameters to +GetSink+.
       # @!attribute [rw] sink_name
       #   @return [String]
-      #     Required. The resource name of the sink to return:
+      #     Required. The parent resource name of the sink:
       #
       #         "projects/[PROJECT_ID]/sinks/[SINK_ID]"
       #         "organizations/[ORGANIZATION_ID]/sinks/[SINK_ID]"
+      #
+      #     Example: +"projects/my-project-id/sinks/my-sink-id"+.
       class GetSinkRequest; end
 
       # The parameters to +CreateSink+.
@@ -133,24 +146,32 @@ module Google
       #
       #         "projects/[PROJECT_ID]"
       #         "organizations/[ORGANIZATION_ID]"
+      #
+      #     Examples: +"projects/my-logging-project"+, +"organizations/123456789"+.
       # @!attribute [rw] sink
       #   @return [Google::Logging::V2::LogSink]
       #     Required. The new sink, whose +name+ parameter is a sink identifier that
       #     is not already in use.
       # @!attribute [rw] unique_writer_identity
       #   @return [true, false]
-      #     Optional. 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. 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.
+      #
+      #     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
+      #     be a unique service account used only for exports from the new sink.  For
+      #     more information, see +writer_identity+ in LogSink.
       class CreateSinkRequest; end
 
       # The parameters to +UpdateSink+.
       # @!attribute [rw] sink_name
       #   @return [String]
-      #     Required. The resource name of the sink to update, including the parent
-      #     resource and the sink identifier:
+      #     Required. The full resource name of the sink to update, including the
+      #     parent resource and the sink identifier:
       #
       #         "projects/[PROJECT_ID]/sinks/[SINK_ID]"
       #         "organizations/[ORGANIZATION_ID]/sinks/[SINK_ID]"
@@ -159,27 +180,35 @@ module Google
       # @!attribute [rw] sink
       #   @return [Google::Logging::V2::LogSink]
       #     Required. The updated sink, whose name is the same identifier that appears
-      #     as part of +sinkName+.  If +sinkName+ does not exist, then
+      #     as part of +sink_name+.  If +sink_name+ does not exist, then
       #     this method creates a new sink.
       # @!attribute [rw] unique_writer_identity
       #   @return [true, false]
-      #     Optional. 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. See
+      #     {sinks.create}[https://cloud.google.com/logging/docs/api/reference/rest/v2/projects.sinks/create]
+      #     for a description of this field.  When updating a sink, the effect of this
+      #     field on the value of +writer_identity+ in the updated sink depends on both
+      #     the old and new values of this field:
+      #
+      #     +   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
+      #         +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.
       class UpdateSinkRequest; end
 
       # The parameters to +DeleteSink+.
       # @!attribute [rw] sink_name
       #   @return [String]
-      #     Required. The resource name of the sink to delete, including the parent
-      #     resource and the sink identifier:
+      #     Required. The full resource name of the sink to delete, including the
+      #     parent resource and the sink identifier:
       #
       #         "projects/[PROJECT_ID]/sinks/[SINK_ID]"
       #         "organizations/[ORGANIZATION_ID]/sinks/[SINK_ID]"
       #
-      #     It is an error if the sink does not exist.
+      #     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.
       class DeleteSinkRequest; end
     end
   end

data/lib/google/cloud/logging/v2/doc/google/logging/v2/logging_metrics.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,
@@ -16,7 +16,7 @@ module Google
   module Logging
     module V2
       # Describes a logs-based metric.  The value of the metric is the
-      # number of log entries that match a logs filter.
+      # number of log entries that match a logs filter in a given time interval.
       # @!attribute [rw] name
       #   @return [String]
       #     Required. The client-assigned metric identifier.
@@ -39,7 +39,8 @@ module Google
       #     Optional. A description of this metric, which is used in documentation.
       # @!attribute [rw] filter
       #   @return [String]
-      #     Required. An {advanced logs filter}[https://cloud.google.com/logging/docs/view/advanced_filters].
+      #     Required. An {advanced logs filter}[https://cloud.google.com/logging/docs/view/advanced_filters]
+      #     which is used to match log entries.
       #     Example:
       #
       #         "resource.type=gae_app AND severity>=ERROR"

data/lib/google/cloud/logging/v2/doc/google/protobuf/any.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,

data/lib/google/cloud/logging/v2/doc/google/protobuf/duration.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,

data/lib/google/cloud/logging/v2/doc/google/protobuf/timestamp.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,

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

@@ -45,8 +45,6 @@ module Google
           # The default port of the service.
           DEFAULT_SERVICE_PORT = 443
 
-          CODE_GEN_NAME_VERSION = "gapic/0.1.0".freeze
-
           DEFAULT_TIMEOUT = 30
 
           PAGE_DESCRIPTORS = {
@@ -57,11 +55,27 @@ module Google
             "list_monitored_resource_descriptors" => Google::Gax::PageDescriptor.new(
               "page_token",
               "next_page_token",
-              "resource_descriptors")
+              "resource_descriptors"),
+            "list_logs" => Google::Gax::PageDescriptor.new(
+              "page_token",
+              "next_page_token",
+              "log_names")
           }.freeze
 
           private_constant :PAGE_DESCRIPTORS
 
+          BUNDLE_DESCRIPTORS = {
+            "write_log_entries" => Google::Gax::BundleDescriptor.new(
+              "entries",
+              [
+                "logName",
+                "resource",
+                "labels"
+              ])
+          }.freeze
+
+          private_constant :BUNDLE_DESCRIPTORS
+
           # The scopes needed to make gRPC calls to all of the methods defined in
           # this service.
           ALL_SCOPES = [
@@ -140,10 +154,6 @@ module Google
           #   or the specified config is missing data points.
           # @param timeout [Numeric]
           #   The default timeout, in seconds, for calls made through this client.
-          # @param app_name [String]
-          #   The codename of the calling service.
-          # @param app_version [String]
-          #   The version of the calling service.
           def initialize \
               service_path: SERVICE_ADDRESS,
               port: DEFAULT_SERVICE_PORT,
@@ -152,8 +162,10 @@ module Google
               scopes: ALL_SCOPES,
               client_config: {},
               timeout: DEFAULT_TIMEOUT,
-              app_name: "gax",
-              app_version: Google::Gax::VERSION
+              app_name: nil,
+              app_version: nil,
+              lib_name: nil,
+              lib_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
@@ -161,9 +173,16 @@ module Google
             require "google/logging/v2/logging_services_pb"
 
 
-            google_api_client = "#{app_name}/#{app_version} " \
-              "#{CODE_GEN_NAME_VERSION} gax/#{Google::Gax::VERSION} " \
-              "ruby/#{RUBY_VERSION}".freeze
+            if app_name || app_version
+              warn "`app_name` and `app_version` are no longer being used in the request headers."
+            end
+
+            google_api_client = "gl-ruby/#{RUBY_VERSION}"
+            google_api_client << " #{lib_name}/#{lib_version}" if lib_name
+            google_api_client << " gapic/ gax/#{Google::Gax::VERSION}"
+            google_api_client << " grpc/#{GRPC::VERSION}"
+            google_api_client.freeze
+
             headers = { :"x-goog-api-client" => google_api_client }
             client_config_file = Pathname.new(__dir__).join(
               "logging_service_v2_client_config.json"
@@ -175,6 +194,7 @@ module Google
                 client_config,
                 Google::Gax::Grpc::STATUS_CODE_NAMES,
                 timeout,
+                bundle_descriptors: BUNDLE_DESCRIPTORS,
                 page_descriptors: PAGE_DESCRIPTORS,
                 errors: Google::Gax::Grpc::API_ERRORS,
                 kwargs: headers
@@ -205,6 +225,10 @@ module Google
               @logging_service_v2_stub.method(:list_monitored_resource_descriptors),
               defaults["list_monitored_resource_descriptors"]
             )
+            @list_logs = Google::Gax.create_api_call(
+              @logging_service_v2_stub.method(:list_logs),
+              defaults["list_logs"]
+            )
           end
 
           # Service calls
@@ -322,18 +346,18 @@ module Google
             @write_log_entries.call(req, options)
           end
 
-          # Lists log entries.  Use this method to retrieve log entries from Cloud
-          # Logging.  For ways to export log entries, see
+          # Lists log entries.  Use this method to retrieve log entries from
+          # Stackdriver Logging.  For ways to export log entries, see
           # {Exporting Logs}[https://cloud.google.com/logging/docs/export].
           #
           # @param project_ids [Array<String>]
-          #   Deprecated. One or more project identifiers or project numbers from which
-          #   to retrieve log entries.  Example: +"my-project-1A"+. 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.
+          #   Deprecated. Use +resource_names+ instead.  One or more project identifiers
+          #   or project numbers from which to retrieve log entries.  Example:
+          #   +"my-project-1A"+. If present, these project identifiers are converted to
+          #   resource name format and added to the list of resources in
+          #   +resource_names+.
           # @param resource_names [Array<String>]
-          #   Required. One or more cloud resources from which to retrieve log
+          #   Required. Names of one or more resources from which to retrieve log
           #   entries:
           #
           #       "projects/[PROJECT_ID]"
@@ -343,7 +367,10 @@ module Google
           # @param filter [String]
           #   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.
+          #   match the filter are returned.  An empty filter matches all log entries in
+          #   the resources listed in +resource_names+. Referencing a parent resource
+          #   that is not listed in +resource_names+ will cause the filter to return no
+          #   results.
           #   The maximum length of the filter is 20000 characters.
           # @param order_by [String]
           #   Optional. How the results should be sorted.  Presently, the only permitted
@@ -405,7 +432,8 @@ module Google
             @list_log_entries.call(req, options)
           end
 
-          # Lists the monitored resource descriptors used by Stackdriver Logging.
+          # Lists the descriptors for monitored resource types used by Stackdriver
+          # Logging.
           #
           # @param page_size [Integer]
           #   The maximum number of resources contained in the underlying API
@@ -450,6 +478,61 @@ module Google
             }.delete_if { |_, v| v.nil? })
             @list_monitored_resource_descriptors.call(req, options)
           end
+
+          # Lists the logs in projects or organizations.
+          # Only logs that have entries are listed.
+          #
+          # @param parent [String]
+          #   Required. The resource name that owns the logs:
+          #
+          #       "projects/[PROJECT_ID]"
+          #       "organizations/[ORGANIZATION_ID]"
+          # @param page_size [Integer]
+          #   The maximum number of resources contained in the underlying API
+          #   response. If page streaming is performed per-resource, this
+          #   parameter does not affect the return value. If page streaming is
+          #   performed per-page, this determines the maximum number of
+          #   resources in a page.
+          # @param options [Google::Gax::CallOptions]
+          #   Overrides the default settings for this call, e.g, timeout,
+          #   retries, etc.
+          # @return [Google::Gax::PagedEnumerable<String>]
+          #   An enumerable of String instances.
+          #   See Google::Gax::PagedEnumerable documentation for other
+          #   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_client"
+          #
+          #   LoggingServiceV2Client = Google::Cloud::Logging::V2::LoggingServiceV2Client
+          #
+          #   logging_service_v2_client = LoggingServiceV2Client.new
+          #   formatted_parent = LoggingServiceV2Client.project_path("[PROJECT]")
+          #
+          #   # Iterate over all results.
+          #   logging_service_v2_client.list_logs(formatted_parent).each do |element|
+          #     # Process element.
+          #   end
+          #
+          #   # Or iterate over results one page at a time.
+          #   logging_service_v2_client.list_logs(formatted_parent).each_page do |page|
+          #     # Process each page at a time.
+          #     page.each do |element|
+          #       # Process element.
+          #     end
+          #   end
+
+          def list_logs \
+              parent,
+              page_size: nil,
+              options: nil
+            req = Google::Logging::V2::ListLogsRequest.new({
+              parent: parent,
+              page_size: page_size
+            }.delete_if { |_, v| v.nil? })
+            @list_logs.call(req, options)
+          end
         end
       end
     end