google-cloud-monitoring 0.29.3 → 0.29.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b792e40ae869d39f4135020eb9c7bab809f82dfbc7428cb0053c745979d90bd5
-  data.tar.gz: 80c0233b94b4e28111e3ad543e01fc7efdfd5ff9955f30c19fe3e09821c0dff8
+  metadata.gz: 441efddbf31ee031665e3cf1ad55dc495c83fbb4eda6e14921406b72cfa8b301
+  data.tar.gz: 2766134674f57e88798b27c4dbbd6384c17cf138b8d14c02392deaed60c35b76
 SHA512:
-  metadata.gz: 99da32cacf20be0bef15fe42e761e49d1a19a8df6a566c6bbe698b808a3f845ddd898ad62217e867b3be7930ae1e1d6b13f79597442d9a519ac02158e187e562
-  data.tar.gz: 9d3d18c4b1a2173c3aeeafdf0cd77a5e5624b4eef9269c9d4c8d6a6a3f29b41dc5dd557f0bc64c25704ecec142256952d289ebd2f0f01463cacd58b7808adee6
+  metadata.gz: 16bd2062fd76d895bdebb9d9a7ecb70a28d743e8589404ea4c6c4f3faf43caf478464af4784589ed9f051586513ac5e56a04c1888cb407710fac635b89202337
+  data.tar.gz: 706b996e2ff80685b5e12c6aa8905469a9269079300c3ab2374252914e88730e3c7fcf0bb19b2d6f0a6d41013b247a525687d59f3af8601fd3fe45343d650647

data/.yardopts

@@ -7,3 +7,5 @@
 ./lib/**/*.rb
 -
 README.md
+AUTHENTICATION.md
+LICENSE

data/AUTHENTICATION.md

@@ -0,0 +1,199 @@
+# Authentication
+
+In general, the google-cloud-monitoring library uses [Service
+Account](https://cloud.google.com/iam/docs/creating-managing-service-accounts)
+credentials to connect to Google Cloud services. When running within [Google
+Cloud Platform environments](#google-cloud-platform-environments)
+the credentials will be discovered automatically. When running on other
+environments, the Service Account credentials can be specified by providing the
+path to the [JSON
+keyfile](https://cloud.google.com/iam/docs/managing-service-account-keys) for
+the account (or the JSON itself) in [environment
+variables](#environment-variables). Additionally, Cloud SDK credentials can also
+be discovered automatically, but this is only recommended during development.
+
+## Quickstart
+
+1. [Create a service account and credentials](#creating-a-service-account).
+2. Set the [environment variable](#environment-variables).
+
+```sh
+export MONITORING_CREDENTIALS=/path/to/json`
+```
+
+3. Initialize the client.
+
+```ruby
+require "google/cloud/monitoring"
+
+client = Google::Cloud::Monitoring.new
+```
+
+## Project and Credential Lookup
+
+The google-cloud-monitoring library aims to make authentication
+as simple as possible, and provides several mechanisms to configure your system
+without providing **Project ID** and **Service Account Credentials** directly in
+code.
+
+**Project ID** is discovered in the following order:
+
+1. Specify project ID in method arguments
+2. Specify project ID in configuration
+3. Discover project ID in environment variables
+4. Discover GCE project ID
+5. Discover project ID in credentials JSON
+
+**Credentials** are discovered in the following order:
+
+1. Specify credentials in method arguments
+2. Specify credentials in configuration
+3. Discover credentials path in environment variables
+4. Discover credentials JSON in environment variables
+5. Discover credentials file in the Cloud SDK's path
+6. Discover GCE credentials
+
+### Google Cloud Platform environments
+
+While running on Google Cloud Platform environments such as Google Compute
+Engine, Google App Engine and Google Kubernetes Engine, no extra work is needed.
+The **Project ID** and **Credentials** and are discovered automatically. Code
+should be written as if already authenticated. Just be sure when you [set up the
+GCE instance][gce-how-to], you add the correct scopes for the APIs you want to
+access. For example:
+
+  * **All APIs**
+    * `https://www.googleapis.com/auth/cloud-platform`
+    * `https://www.googleapis.com/auth/cloud-platform.read-only`
+  * **BigQuery**
+    * `https://www.googleapis.com/auth/bigquery`
+    * `https://www.googleapis.com/auth/bigquery.insertdata`
+  * **Compute Engine**
+    * `https://www.googleapis.com/auth/compute`
+  * **Datastore**
+    * `https://www.googleapis.com/auth/datastore`
+    * `https://www.googleapis.com/auth/userinfo.email`
+  * **DNS**
+    * `https://www.googleapis.com/auth/ndev.clouddns.readwrite`
+  * **Pub/Sub**
+    * `https://www.googleapis.com/auth/pubsub`
+  * **Storage**
+    * `https://www.googleapis.com/auth/devstorage.full_control`
+    * `https://www.googleapis.com/auth/devstorage.read_only`
+    * `https://www.googleapis.com/auth/devstorage.read_write`
+
+### Environment Variables
+
+The **Project ID** and **Credentials JSON** can be placed in environment
+variables instead of declaring them directly in code. Each service has its own
+environment variable, allowing for different service accounts to be used for
+different services. (See the READMEs for the individual service gems for
+details.) The path to the **Credentials JSON** file can be stored in the
+environment variable, or the **Credentials JSON** itself can be stored for
+environments such as Docker containers where writing files is difficult or not
+encouraged.
+
+The environment variables that google-cloud-monitoring checks for project ID are:
+
+1. `MONITORING_PROJECT`
+2. `GOOGLE_CLOUD_PROJECT`
+
+The environment variables that google-cloud-monitoring checks for credentials are configured on {Google::Cloud::Monitoring::V3::Credentials}:
+
+1. `MONITORING_CREDENTIALS` - Path to JSON file, or JSON contents
+2. `MONITORING_KEYFILE` - Path to JSON file, or JSON contents
+3. `GOOGLE_CLOUD_CREDENTIALS` - Path to JSON file, or JSON contents
+4. `GOOGLE_CLOUD_KEYFILE` - Path to JSON file, or JSON contents
+5. `GOOGLE_APPLICATION_CREDENTIALS` - Path to JSON file
+
+```ruby
+require "google/cloud/monitoring"
+
+ENV["MONITORING_PROJECT"]     = "my-project-id"
+ENV["MONITORING_CREDENTIALS"] = "path/to/keyfile.json"
+
+client = Google::Cloud::Monitoring.new
+```
+
+### Configuration
+
+The **Project ID** and **Credentials JSON** can be configured instead of placing them in environment variables or providing them as arguments.
+
+```ruby
+require "google/cloud/monitoring"
+
+Google::Cloud::Monitoring.configure do |config|
+  config.project_id  = "my-project-id"
+  config.credentials = "path/to/keyfile.json"
+end
+
+client = Google::Cloud::Monitoring.new
+```
+
+### Cloud SDK
+
+This option allows for an easy way to authenticate during development. If
+credentials are not provided in code or in environment variables, then Cloud SDK
+credentials are discovered.
+
+To configure your system for this, simply:
+
+1. [Download and install the Cloud SDK](https://cloud.google.com/sdk)
+2. Authenticate using OAuth 2.0 `$ gcloud auth login`
+3. Write code as if already authenticated.
+
+**NOTE:** This is _not_ recommended for running in production. The Cloud SDK
+*should* only be used during development.
+
+[gce-how-to]: https://cloud.google.com/compute/docs/authentication#using
+[dev-console]: https://console.cloud.google.com/project
+
+[enable-apis]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/enable-apis.png
+
+[create-new-service-account]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/create-new-service-account.png
+[create-new-service-account-existing-keys]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/create-new-service-account-existing-keys.png
+[reuse-service-account]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/reuse-service-account.png
+
+## Creating a Service Account
+
+Google Cloud requires a **Project ID** and **Service Account Credentials** to
+connect to the APIs. You will use the **Project ID** and **JSON key file** to
+connect to most services with google-cloud-monitoring.
+
+If you are not running this client within [Google Cloud Platform
+environments](#google-cloud-platform-environments), you need a Google
+Developers service account.
+
+1. Visit the [Google Developers Console][dev-console].
+1. Create a new project or click on an existing project.
+1. Activate the slide-out navigation tray and select **API Manager**. From
+   here, you will enable the APIs that your application requires.
+
+   ![Enable the APIs that your application requires][enable-apis]
+
+   *Note: You may need to enable billing in order to use these services.*
+
+1. Select **Credentials** from the side navigation.
+
+   You should see a screen like one of the following.
+
+   ![Create a new service account][create-new-service-account]
+
+   ![Create a new service account With Existing Keys][create-new-service-account-existing-keys]
+
+   Find the "Add credentials" drop down and select "Service account" to be
+   guided through downloading a new JSON key file.
+
+   If you want to re-use an existing service account, you can easily generate a
+   new key file. Just select the account you wish to re-use, and click "Generate
+   new JSON key":
+
+   ![Re-use an existing service account][reuse-service-account]
+
+   The key file you download will be used by this library to authenticate API
+   requests and should be stored in a secure location.
+
+## Troubleshooting
+
+If you're having trouble authenticating you can ask for help by following the
+{file:TROUBLESHOOTING.md Troubleshooting Guide}.

data/README.md

@@ -26,16 +26,16 @@ $ gem install google-cloud-monitoring
 ```rb
 require "google/cloud/monitoring"
 
-metric_service_client = Google::Cloud::Monitoring::Metric.new
+metric_client = Google::Cloud::Monitoring::Metric.new
 formatted_name = Google::Cloud::Monitoring::V3::MetricServiceClient.project_path(project_id)
 
 # Iterate over all results.
-metric_service_client.list_monitored_resource_descriptors(formatted_name).each do |element|
+metric_client.list_monitored_resource_descriptors(formatted_name).each do |element|
   # Process element.
 end
 
 # Or iterate over results one page at a time.
-metric_service_client.list_monitored_resource_descriptors(formatted_name).each_page do |page|
+metric_client.list_monitored_resource_descriptors(formatted_name).each_page do |page|
   # Process each page at a time.
   page.each do |element|
     # Process element.

data/lib/google/cloud/monitoring.rb

@@ -48,16 +48,16 @@ module Google
     # ```rb
     # require "google/cloud/monitoring"
     #
-    # metric_service_client = Google::Cloud::Monitoring::Metric.new
+    # metric_client = Google::Cloud::Monitoring::Metric.new
     # formatted_name = Google::Cloud::Monitoring::V3::MetricServiceClient.project_path(project_id)
     #
     # # Iterate over all results.
-    # metric_service_client.list_monitored_resource_descriptors(formatted_name).each do |element|
+    # metric_client.list_monitored_resource_descriptors(formatted_name).each do |element|
     #   # Process element.
     # end
     #
     # # Or iterate over results one page at a time.
-    # metric_service_client.list_monitored_resource_descriptors(formatted_name).each_page do |page|
+    # metric_client.list_monitored_resource_descriptors(formatted_name).each_page do |page|
     #   # Process each page at a time.
     #   page.each do |element|
     #     # Process element.

data/lib/google/cloud/monitoring/v3.rb

@@ -54,16 +54,16 @@ module Google
       # ```rb
       # require "google/cloud/monitoring"
       #
-      # metric_service_client = Google::Cloud::Monitoring::Metric.new(version: :v3)
+      # metric_client = Google::Cloud::Monitoring::Metric.new(version: :v3)
       # formatted_name = Google::Cloud::Monitoring::V3::MetricServiceClient.project_path(project_id)
       #
       # # Iterate over all results.
-      # metric_service_client.list_monitored_resource_descriptors(formatted_name).each do |element|
+      # metric_client.list_monitored_resource_descriptors(formatted_name).each do |element|
       #   # Process element.
       # end
       #
       # # Or iterate over results one page at a time.
-      # metric_service_client.list_monitored_resource_descriptors(formatted_name).each_page do |page|
+      # metric_client.list_monitored_resource_descriptors(formatted_name).each_page do |page|
       #   # Process each page at a time.
       #   page.each do |element|
       #     # Process element.

data/lib/google/cloud/monitoring/v3/alert_policy_service_client.rb

@@ -78,12 +78,6 @@ module Google
           ].freeze
 
 
-          PROJECT_PATH_TEMPLATE = Google::Gax::PathTemplate.new(
-            "projects/{project}"
-          )
-
-          private_constant :PROJECT_PATH_TEMPLATE
-
           ALERT_POLICY_PATH_TEMPLATE = Google::Gax::PathTemplate.new(
             "projects/{project}/alertPolicies/{alert_policy}"
           )
@@ -96,14 +90,11 @@ module Google
 
           private_constant :ALERT_POLICY_CONDITION_PATH_TEMPLATE
 
-          # Returns a fully-qualified project resource name string.
-          # @param project [String]
-          # @return [String]
-          def self.project_path project
-            PROJECT_PATH_TEMPLATE.render(
-              :"project" => project
-            )
-          end
+          PROJECT_PATH_TEMPLATE = Google::Gax::PathTemplate.new(
+            "projects/{project}"
+          )
+
+          private_constant :PROJECT_PATH_TEMPLATE
 
           # Returns a fully-qualified alert_policy resource name string.
           # @param project [String]
@@ -129,6 +120,15 @@ module Google
             )
           end
 
+          # Returns a fully-qualified project resource name string.
+          # @param project [String]
+          # @return [String]
+          def self.project_path project
+            PROJECT_PATH_TEMPLATE.render(
+              :"project" => project
+            )
+          end
+
           # @param credentials [Google::Auth::Credentials, String, Hash, GRPC::Core::Channel, GRPC::Core::ChannelCredentials, Proc]
           #   Provides the means for authenticating requests made by the client. This parameter can
           #   be many types.
@@ -235,27 +235,42 @@ module Google
             @list_alert_policies = Google::Gax.create_api_call(
               @alert_policy_service_stub.method(:list_alert_policies),
               defaults["list_alert_policies"],
-              exception_transformer: exception_transformer
+              exception_transformer: exception_transformer,
+              params_extractor: proc do |request|
+                {'name' => request.name}
+              end
             )
             @get_alert_policy = Google::Gax.create_api_call(
               @alert_policy_service_stub.method(:get_alert_policy),
               defaults["get_alert_policy"],
-              exception_transformer: exception_transformer
+              exception_transformer: exception_transformer,
+              params_extractor: proc do |request|
+                {'name' => request.name}
+              end
             )
             @create_alert_policy = Google::Gax.create_api_call(
               @alert_policy_service_stub.method(:create_alert_policy),
               defaults["create_alert_policy"],
-              exception_transformer: exception_transformer
+              exception_transformer: exception_transformer,
+              params_extractor: proc do |request|
+                {'name' => request.name}
+              end
             )
             @delete_alert_policy = Google::Gax.create_api_call(
               @alert_policy_service_stub.method(:delete_alert_policy),
               defaults["delete_alert_policy"],
-              exception_transformer: exception_transformer
+              exception_transformer: exception_transformer,
+              params_extractor: proc do |request|
+                {'name' => request.name}
+              end
             )
             @update_alert_policy = Google::Gax.create_api_call(
               @alert_policy_service_stub.method(:update_alert_policy),
               defaults["update_alert_policy"],
-              exception_transformer: exception_transformer
+              exception_transformer: exception_transformer,
+              params_extractor: proc do |request|
+                {'alert_policy.name' => request.alert_policy.name}
+              end
             )
           end
 
@@ -307,16 +322,16 @@ module Google
           # @example
           #   require "google/cloud/monitoring"
           #
-          #   alert_policy_service_client = Google::Cloud::Monitoring::AlertPolicy.new(version: :v3)
+          #   alert_policy_client = Google::Cloud::Monitoring::AlertPolicy.new(version: :v3)
           #   formatted_name = Google::Cloud::Monitoring::V3::AlertPolicyServiceClient.project_path("[PROJECT]")
           #
           #   # Iterate over all results.
-          #   alert_policy_service_client.list_alert_policies(formatted_name).each do |element|
+          #   alert_policy_client.list_alert_policies(formatted_name).each do |element|
           #     # Process element.
           #   end
           #
           #   # Or iterate over results one page at a time.
-          #   alert_policy_service_client.list_alert_policies(formatted_name).each_page do |page|
+          #   alert_policy_client.list_alert_policies(formatted_name).each_page do |page|
           #     # Process each page at a time.
           #     page.each do |element|
           #       # Process element.
@@ -357,9 +372,9 @@ module Google
           # @example
           #   require "google/cloud/monitoring"
           #
-          #   alert_policy_service_client = Google::Cloud::Monitoring::AlertPolicy.new(version: :v3)
+          #   alert_policy_client = Google::Cloud::Monitoring::AlertPolicy.new(version: :v3)
           #   formatted_name = Google::Cloud::Monitoring::V3::AlertPolicyServiceClient.alert_policy_path("[PROJECT]", "[ALERT_POLICY]")
-          #   response = alert_policy_service_client.get_alert_policy(formatted_name)
+          #   response = alert_policy_client.get_alert_policy(formatted_name)
 
           def get_alert_policy \
               name,
@@ -400,12 +415,12 @@ module Google
           # @example
           #   require "google/cloud/monitoring"
           #
-          #   alert_policy_service_client = Google::Cloud::Monitoring::AlertPolicy.new(version: :v3)
+          #   alert_policy_client = Google::Cloud::Monitoring::AlertPolicy.new(version: :v3)
           #   formatted_name = Google::Cloud::Monitoring::V3::AlertPolicyServiceClient.project_path("[PROJECT]")
           #
           #   # TODO: Initialize `alert_policy`:
           #   alert_policy = {}
-          #   response = alert_policy_service_client.create_alert_policy(formatted_name, alert_policy)
+          #   response = alert_policy_client.create_alert_policy(formatted_name, alert_policy)
 
           def create_alert_policy \
               name,
@@ -438,9 +453,9 @@ module Google
           # @example
           #   require "google/cloud/monitoring"
           #
-          #   alert_policy_service_client = Google::Cloud::Monitoring::AlertPolicy.new(version: :v3)
+          #   alert_policy_client = Google::Cloud::Monitoring::AlertPolicy.new(version: :v3)
           #   formatted_name = Google::Cloud::Monitoring::V3::AlertPolicyServiceClient.alert_policy_path("[PROJECT]", "[ALERT_POLICY]")
-          #   alert_policy_service_client.delete_alert_policy(formatted_name)
+          #   alert_policy_client.delete_alert_policy(formatted_name)
 
           def delete_alert_policy \
               name,
@@ -501,11 +516,11 @@ module Google
           # @example
           #   require "google/cloud/monitoring"
           #
-          #   alert_policy_service_client = Google::Cloud::Monitoring::AlertPolicy.new(version: :v3)
+          #   alert_policy_client = Google::Cloud::Monitoring::AlertPolicy.new(version: :v3)
           #
           #   # TODO: Initialize `alert_policy`:
           #   alert_policy = {}
-          #   response = alert_policy_service_client.update_alert_policy(alert_policy)
+          #   response = alert_policy_client.update_alert_policy(alert_policy)
 
           def update_alert_policy \
               alert_policy,

data/lib/google/cloud/monitoring/v3/doc/google/api/distribution.rb

@@ -185,7 +185,7 @@ module Google
       #   @return [Array<Google::Protobuf::Any>]
       #     Contextual information about the example value. Examples are:
       #
-      #       Trace ID: type.googleapis.com/google.devtools.cloudtrace.v1.Trace
+      #       Trace: type.googleapis.com/google.monitoring.v3.SpanContext
       #
       #       Literal string: type.googleapis.com/google.protobuf.StringValue
       #