google-cloud-logging 1.2.3 → 1.3.0

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

@@ -14,9 +14,29 @@
 
 module Google
   module Logging
+    ##
+    # # Stackdriver Logging API Contents
+    #
+    # | Class | Description |
+    # | ----- | ----------- |
+    # | [LoggingServiceV2Client][] | The Stackdriver Logging API lets you write log entries and manage your logs, log sinks and logs-based metrics. |
+    # | [ConfigServiceV2Client][] | The Stackdriver Logging API lets you write log entries and manage your logs, log sinks and logs-based metrics. |
+    # | [MetricsServiceV2Client][] | The Stackdriver Logging API lets you write log entries and manage your logs, log sinks and logs-based metrics. |
+    # | [Data Types][] | Data types for Google::Cloud::Logging::V2 |
+    #
+    # [LoggingServiceV2Client]: https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-logging/latest/google/logging/v2/loggingservicev2client
+    # [ConfigServiceV2Client]: https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-logging/latest/google/logging/v2/configservicev2client
+    # [MetricsServiceV2Client]: https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-logging/latest/google/logging/v2/metricsservicev2client
+    # [Data Types]: https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-logging/latest/google/logging/v2/datatypes
+    #
     module V2
       # Describes a logs-based metric.  The value of the metric is the
       # number of log entries that match a logs filter in a given time interval.
+      #
+      # A logs-based metric can also be used to extract values from logs and create a
+      # a distribution of the values. The distribution records the statistics of the
+      # extracted values along with an optional histogram of the values as specified
+      # by the bucket options.
       # @!attribute [rw] name
       #   @return [String]
       #     Required. The client-assigned metric identifier.
@@ -29,7 +49,7 @@ module Google
       #     first character of the name.
       #
       #     The metric identifier in this field must not be
-      #     {URL-encoded}[https://en.wikipedia.org/wiki/Percent-encoding].
+      #     [URL-encoded](https://en.wikipedia.org/wiki/Percent-encoding).
       #     However, when the metric identifier appears as the +[METRIC_ID]+
       #     part of a +metric_name+ API parameter, then the metric identifier
       #     must be URL-encoded. Example:
@@ -39,18 +59,82 @@ 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"
       #
       #     The maximum length of the filter is 20000 characters.
+      # @!attribute [rw] metric_descriptor
+      #   @return [Google::Api::MetricDescriptor]
+      #     Optional. The metric descriptor associated with the logs-based metric.
+      #     If unspecified, it uses a default metric descriptor with a DELTA metric
+      #     kind, INT64 value type, with no labels and a unit of "1". Such a metric
+      #     counts the number of log entries matching the +filter+ expression.
+      #
+      #     The +name+, +type+, and +description+ fields in the +metric_descriptor+
+      #     are output only, and is constructed using the +name+ and +description+
+      #     field in the LogMetric.
+      #
+      #     To create a logs-based metric that records a distribution of log values, a
+      #     DELTA metric kind with a DISTRIBUTION value type must be used along with
+      #     a +value_extractor+ expression in the LogMetric.
+      #
+      #     Each label in the metric descriptor must have a matching label
+      #     name as the key and an extractor expression as the value in the
+      #     +label_extractors+ map.
+      #
+      #     The +metric_kind+ and +value_type+ fields in the +metric_descriptor+ cannot
+      #     be updated once initially configured. New labels can be added in the
+      #     +metric_descriptor+, but existing labels cannot be modified except for
+      #     their description.
+      # @!attribute [rw] value_extractor
+      #   @return [String]
+      #     Optional. A +value_extractor+ is required when using a distribution
+      #     logs-based metric to extract the values to record from a log entry.
+      #     Two functions are supported for value extraction: +EXTRACT(field)+ or
+      #     +REGEXP_EXTRACT(field, regex)+. The argument are:
+      #       1. field: The name of the log entry field from which the value is to be
+      #          extracted.
+      #       2. regex: A regular expression using the Google RE2 syntax
+      #          (https://github.com/google/re2/wiki/Syntax) with a single capture
+      #          group to extract data from the specified log entry field. The value
+      #          of the field is converted to a string before applying the regex.
+      #          It is an error to specify a regex that does not include exactly one
+      #          capture group.
+      #
+      #     The result of the extraction must be convertible to a double type, as the
+      #     distribution always records double values. If either the extraction or
+      #     the conversion to double fails, then those values are not recorded in the
+      #     distribution.
+      #
+      #     Example: +REGEXP_EXTRACT(jsonPayload.request, ".*quantity=(\d+).*")+
+      # @!attribute [rw] label_extractors
+      #   @return [Hash{String => String}]
+      #     Optional. A map from a label key string to an extractor expression which is
+      #     used to extract data from a log entry field and assign as the label value.
+      #     Each label key specified in the LabelDescriptor must have an associated
+      #     extractor expression in this map. The syntax of the extractor expression
+      #     is the same as for the +value_extractor+ field.
+      #
+      #     The extracted value is converted to the type defined in the label
+      #     descriptor. If the either the extraction or the type conversion fails,
+      #     the label will have a default value. The default value for a string
+      #     label is an empty string, for an integer label its 0, and for a boolean
+      #     label its +false+.
+      #
+      #     Note that there are upper bounds on the maximum number of labels and the
+      #     number of active time series that are allowed in a project.
+      # @!attribute [rw] bucket_options
+      #   @return [Google::Api::Distribution::BucketOptions]
+      #     Optional. The +bucket_options+ are required when the logs-based metric is
+      #     using a DISTRIBUTION value type and it describes the bucket boundaries
+      #     used to create a histogram of the extracted values.
       # @!attribute [rw] version
       #   @return [Google::Logging::V2::LogMetric::ApiVersion]
-      #     Output only. The API version that created or updated this metric.
-      #     The version also dictates the syntax of the filter expression. When a value
-      #     for this field is missing, the default value of V2 should be assumed.
+      #     Deprecated. The API version that created or updated this metric.
+      #     The v2 format is used by default and cannot be changed.
       class LogMetric
         # Stackdriver Logging API version.
         module ApiVersion

data/lib/google/cloud/logging/v2/doc/google/protobuf/any.rb

@@ -49,6 +49,16 @@ module Google
     #       any.Unpack(foo)
     #       ...
     #
+    #  Example 4: Pack and unpack a message in Go
+    #
+    #      foo := &pb.Foo{...}
+    #      any, err := ptypes.MarshalAny(foo)
+    #      ...
+    #      foo := &pb.Foo{}
+    #      if err := ptypes.UnmarshalAny(any, foo); err != nil {
+    #        ...
+    #      }
+    #
     # The pack methods provided by protobuf library will by default use
     # 'type.googleapis.com/full.type.name' as the type URL and the unpack
     # methods only use the fully qualified type name after the last '/'
@@ -77,7 +87,7 @@ module Google
     # If the embedded message type is well-known and has a custom JSON
     # representation, that representation will be embedded adding a field
     # +value+ which holds the custom JSON in addition to the +@type+
-    # field. Example (for message Google::Protobuf::Duration):
+    # field. Example (for message {Google::Protobuf::Duration}):
     #
     #     {
     #       "@type": "type.googleapis.com/google.protobuf.Duration",
@@ -96,7 +106,7 @@ module Google
     #       qualified name of the type (as in +path/google.protobuf.Duration+).
     #       The name should be in a canonical form (e.g., leading "." is
     #       not accepted).
-    #     * An HTTP GET on the URL must yield a Google::Protobuf::Type
+    #     * An HTTP GET on the URL must yield a {Google::Protobuf::Type}
     #       value in binary format, or produce an error.
     #     * Applications are allowed to cache lookup results based on the
     #       URL, or have them precompiled into a binary to avoid any

data/lib/google/cloud/logging/v2/doc/google/protobuf/duration.rb

@@ -21,6 +21,8 @@ module Google
     # two Timestamp values is a Duration and it can be added or subtracted
     # from a Timestamp. Range is approximately +-10,000 years.
     #
+    # = Examples
+    #
     # Example 1: Compute Duration from two Timestamps in pseudo code.
     #
     #     Timestamp start = ...;
@@ -60,10 +62,21 @@ module Google
     #     td = datetime.timedelta(days=3, minutes=10)
     #     duration = Duration()
     #     duration.FromTimedelta(td)
+    #
+    # = JSON Mapping
+    #
+    # In JSON format, the Duration type is encoded as a string rather than an
+    # object, where the string ends in the suffix "s" (indicating seconds) and
+    # is preceded by the number of seconds, with nanoseconds expressed as
+    # fractional seconds. For example, 3 seconds with 0 nanoseconds should be
+    # encoded in JSON format as "3s", while 3 seconds and 1 nanosecond should
+    # be expressed in JSON format as "3.000000001s", and 3 seconds and 1
+    # microsecond should be expressed in JSON format as "3.000001s".
     # @!attribute [rw] seconds
     #   @return [Integer]
     #     Signed seconds of the span of time. Must be from -315,576,000,000
-    #     to +315,576,000,000 inclusive.
+    #     to +315,576,000,000 inclusive. Note: these bounds are computed from:
+    #     60 sec/min * 60 min/hr * 24 hr/day * 365.25 days/year * 10000 years
     # @!attribute [rw] nanos
     #   @return [Integer]
     #     Signed fractions of a second at nanosecond resolution of the span

data/lib/google/cloud/logging/v2/doc/google/protobuf/field_mask.rb

@@ -0,0 +1,223 @@
+# 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 Protobuf
+    # +FieldMask+ represents a set of symbolic field paths, for example:
+    #
+    #     paths: "f.a"
+    #     paths: "f.b.d"
+    #
+    # Here +f+ represents a field in some root message, +a+ and +b+
+    # fields in the message found in +f+, and +d+ a field found in the
+    # message in +f.b+.
+    #
+    # Field masks are used to specify a subset of fields that should be
+    # returned by a get operation or modified by an update operation.
+    # Field masks also have a custom JSON encoding (see below).
+    #
+    # = Field Masks in Projections
+    #
+    # When used in the context of a projection, a response message or
+    # sub-message is filtered by the API to only contain those fields as
+    # specified in the mask. For example, if the mask in the previous
+    # example is applied to a response message as follows:
+    #
+    #     f {
+    #       a : 22
+    #       b {
+    #         d : 1
+    #         x : 2
+    #       }
+    #       y : 13
+    #     }
+    #     z: 8
+    #
+    # The result will not contain specific values for fields x,y and z
+    # (their value will be set to the default, and omitted in proto text
+    # output):
+    #
+    #
+    #     f {
+    #       a : 22
+    #       b {
+    #         d : 1
+    #       }
+    #     }
+    #
+    # A repeated field is not allowed except at the last position of a
+    # paths string.
+    #
+    # If a FieldMask object is not present in a get operation, the
+    # operation applies to all fields (as if a FieldMask of all fields
+    # had been specified).
+    #
+    # Note that a field mask does not necessarily apply to the
+    # top-level response message. In case of a REST get operation, the
+    # field mask applies directly to the response, but in case of a REST
+    # list operation, the mask instead applies to each individual message
+    # in the returned resource list. In case of a REST custom method,
+    # other definitions may be used. Where the mask applies will be
+    # clearly documented together with its declaration in the API.  In
+    # any case, the effect on the returned resource/resources is required
+    # behavior for APIs.
+    #
+    # = Field Masks in Update Operations
+    #
+    # A field mask in update operations specifies which fields of the
+    # targeted resource are going to be updated. The API is required
+    # to only change the values of the fields as specified in the mask
+    # and leave the others untouched. If a resource is passed in to
+    # describe the updated values, the API ignores the values of all
+    # fields not covered by the mask.
+    #
+    # If a repeated field is specified for an update operation, the existing
+    # repeated values in the target resource will be overwritten by the new values.
+    # Note that a repeated field is only allowed in the last position of a +paths+
+    # string.
+    #
+    # If a sub-message is specified in the last position of the field mask for an
+    # update operation, then the existing sub-message in the target resource is
+    # overwritten. Given the target message:
+    #
+    #     f {
+    #       b {
+    #         d : 1
+    #         x : 2
+    #       }
+    #       c : 1
+    #     }
+    #
+    # And an update message:
+    #
+    #     f {
+    #       b {
+    #         d : 10
+    #       }
+    #     }
+    #
+    # then if the field mask is:
+    #
+    #  paths: "f.b"
+    #
+    # then the result will be:
+    #
+    #     f {
+    #       b {
+    #         d : 10
+    #       }
+    #       c : 1
+    #     }
+    #
+    # However, if the update mask was:
+    #
+    #  paths: "f.b.d"
+    #
+    # then the result would be:
+    #
+    #     f {
+    #       b {
+    #         d : 10
+    #         x : 2
+    #       }
+    #       c : 1
+    #     }
+    #
+    # In order to reset a field's value to the default, the field must
+    # be in the mask and set to the default value in the provided resource.
+    # Hence, in order to reset all fields of a resource, provide a default
+    # instance of the resource and set all fields in the mask, or do
+    # not provide a mask as described below.
+    #
+    # If a field mask is not present on update, the operation applies to
+    # all fields (as if a field mask of all fields has been specified).
+    # Note that in the presence of schema evolution, this may mean that
+    # fields the client does not know and has therefore not filled into
+    # the request will be reset to their default. If this is unwanted
+    # behavior, a specific service may require a client to always specify
+    # a field mask, producing an error if not.
+    #
+    # As with get operations, the location of the resource which
+    # describes the updated values in the request message depends on the
+    # operation kind. In any case, the effect of the field mask is
+    # required to be honored by the API.
+    #
+    # == Considerations for HTTP REST
+    #
+    # The HTTP kind of an update operation which uses a field mask must
+    # be set to PATCH instead of PUT in order to satisfy HTTP semantics
+    # (PUT must only be used for full updates).
+    #
+    # = JSON Encoding of Field Masks
+    #
+    # In JSON, a field mask is encoded as a single string where paths are
+    # separated by a comma. Fields name in each path are converted
+    # to/from lower-camel naming conventions.
+    #
+    # As an example, consider the following message declarations:
+    #
+    #     message Profile {
+    #       User user = 1;
+    #       Photo photo = 2;
+    #     }
+    #     message User {
+    #       string display_name = 1;
+    #       string address = 2;
+    #     }
+    #
+    # In proto a field mask for +Profile+ may look as such:
+    #
+    #     mask {
+    #       paths: "user.display_name"
+    #       paths: "photo"
+    #     }
+    #
+    # In JSON, the same mask is represented as below:
+    #
+    #     {
+    #       mask: "user.displayName,photo"
+    #     }
+    #
+    # = Field Masks and Oneof Fields
+    #
+    # Field masks treat fields in oneofs just as regular fields. Consider the
+    # following message:
+    #
+    #     message SampleMessage {
+    #       oneof test_oneof {
+    #         string name = 4;
+    #         SubMessage sub_message = 9;
+    #       }
+    #     }
+    #
+    # The field mask can be:
+    #
+    #     mask {
+    #       paths: "name"
+    #     }
+    #
+    # Or:
+    #
+    #     mask {
+    #       paths: "sub_message"
+    #     }
+    #
+    # Note that oneof type names ("test_oneof" in this case) cannot be used in
+    # paths.
+    # @!attribute [rw] paths
+    #   @return [Array<String>]
+    #     The set of field mask paths.
+    class FieldMask; end
+  end
+end

data/lib/google/cloud/logging/v2/doc/google/protobuf/timestamp.rb

@@ -24,7 +24,9 @@ module Google
     # 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z.
     # By restricting to that range, we ensure that we can convert to
     # and from  RFC 3339 date strings.
-    # See {https://www.ietf.org/rfc/rfc3339.txt}[https://www.ietf.org/rfc/rfc3339.txt].
+    # See [https://www.ietf.org/rfc/rfc3339.txt](https://www.ietf.org/rfc/rfc3339.txt).
+    #
+    # = Examples
     #
     # Example 1: Compute Timestamp from POSIX +time()+.
     #
@@ -65,6 +67,29 @@ module Google
     #
     #     timestamp = Timestamp()
     #     timestamp.GetCurrentTime()
+    #
+    # = JSON Mapping
+    #
+    # In JSON format, the Timestamp type is encoded as a string in the
+    # [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the
+    # format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z"
+    # where {year} is always expressed using four digits while {month}, {day},
+    # {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional
+    # seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution),
+    # are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone
+    # is required, though only UTC (as indicated by "Z") is presently supported.
+    #
+    # For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past
+    # 01:30 UTC on January 15, 2017.
+    #
+    # In JavaScript, one can convert a Date object to this format using the
+    # standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString]
+    # method. In Python, a standard +datetime.datetime+ object can be converted
+    # to this format using [+strftime+](https://docs.python.org/2/library/time.html#time.strftime)
+    # with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one
+    # can use the Joda Time's [+ISODateTimeFormat.dateTime()+](
+    # http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime())
+    # to obtain a formatter capable of generating timestamps in this format.
     # @!attribute [rw] seconds
     #   @return [Integer]
     #     Represents seconds of UTC time since Unix epoch