write_stackdriver plugin: Centralize HTTP calls, add API error handling.

[collectd.git] / src / collectd.conf.pod

diff --git a/src/collectd.conf.pod b/src/collectd.conf.pod
index 7ff36b2..da8e873 100644 (file)
--- a/src/collectd.conf.pod
+++ b/src/collectd.conf.pod
@@ -10323,7 +10323,7 @@ B<Synopsis:>
  <Plugin write_stackdriver>
    CredentialFile "/path/to/service_account.json"
    <Resource "global">
-     project_id "monitored_project"
+     Label "project_id" "monitored_project"
    </Resource>
  </Plugin>
 
@@ -10334,9 +10334,35 @@ B<Synopsis:>
 Path to a JSON credentials file holding the credentials for a GCP service
 account.
 
-If not specified, I<Application Default Credentials>. If running on GCE,
-B<Email> may be set to chose a different service account associated with the
-instance.
+If B<CredentialFile> is not specified, the plugin uses I<Application Default
+Credentials>. That means which credentials are used depends on the environment:
+
+=over 4
+
+=item
+
+The environment variable C<GOOGLE_APPLICATION_CREDENTIALS> is checked. If this
+variable is specified it should point to a JSON file that defines the
+credentials.
+
+=item
+
+The path C<${HOME}/.config/gcloud/application_default_credentials.json> is
+checked. This where credentials used by the I<gcloud> command line utility are
+stored. You can use C<gcloud auth application-default login> to create these
+credentials.
+
+Please note that these credentials are often of your personal account, not a
+service account, and are therefore unfit to be used in a production
+environment.
+
+=item
+
+When running on GCE, the built-in service account associated with the virtual
+machine instance is used.
+See also the B<Email> option below.
+
+=back
 
 =item B<Project> I<Project>
 
@@ -10348,41 +10374,62 @@ number. You can look up both on the I<Developer Console>.
 This setting is optional. If not set, the project ID is read from the
 credentials file or determined from the GCE's metadata service.
 
-=item B<Email> I<Email>
+=item B<Email> I<Email> (GCE only)
+
+Choses the GCE I<Service Account> used for authentication.
 
-Email address of an GCE I<Service Account>. This setting is only effective when
-running on GCE and using I<Application Default Credentials> (see
-B<CredentialFile> above).
+Each GCE instance has a C<default> I<Service Account> but may also be
+associated with additional I<Service Accounts>. This is often used to restrict
+the permissions of services running on the GCE instance to the required
+minimum. The I<write_stackdriver plugin> requires the
+C<https://www.googleapis.com/auth/monitoring> scope. When multiple I<Service
+Accounts> are available, this option selects which one is used by
+I<write_stackdriver plugin>.
 
 =item B<Resource> I<ResourceType>
 
-Configures the I<Monitored Resource> to use when storing metrics. This option
-takes a I<ResourceType> and arbitrary string options which are used as labels.
+Configures the I<Monitored Resource> to use when storing metrics.
+More information on I<Monitored Resources> and I<Monitored Resource Types> are
+available at L<https://cloud.google.com/monitoring/api/resources>.
+
+This block takes one string argument, the I<ResourceType>. Inside the block are
+one or more B<Label> options which configure the resource labels.
 
-On GCE, defaults to the equivalent of this config:
+This block is optional. The default value depends on the runtime environment:
+on GCE, the C<gce_instance> resource type is used, otherwise the C<global>
+resource type ist used:
+
+=over 4
+
+=item
+
+B<On GCE>, defaults to the equivalent of this config:
 
   <Resource "gce_instance">
-    project_id "${meta/project/project-id}"
-    instance_id "${meta/instance/id}"
-    zone "${meta/instance/zone}"
+    Label "project_id" "<project_id>"
+    Label "instance_id" "<instance_id>"
+    Label "zone" "<zone>"
   </Resource>
 
-Where C<${meta/...}> are values read from the meta data service.
+The values for I<project_id>, I<instance_id> and I<zone> are read from the GCE
+metadata service.
 
-When not running on GCE, defaults to the equivalent of this config:
+=item
+
+B<Elsewhere>, i.e. not on GCE, defaults to the equivalent of this config:
 
   <Resource "global">
-    project_id "${Project}"
+    Label "project_id" "<Project>"
   </Resource>
 
-Where C<${Project}> refers to the B<Project> option.
+Where I<Project> refers to the value of the B<Project> option or the project ID
+inferred from the B<CredentialFile>.
 
-See L<https://cloud.google.com/monitoring/api/resources> for more information
-on I<Monitored Resource Types>.
+=back
 
 =item B<Url> I<Url>
 
-URL of the I<Google Cloud Monitoring> API. Defaults to
+URL of the I<Stackdriver Monitoring> API. Defaults to
 C<https://monitoring.googleapis.com/v3>.
 
 =back