Document add_cloud_metadata processor

libbeat/docs/processors-config.asciidoc

@@ -227,11 +227,12 @@ not:
 
 ==== Actions
 
-The supported filter actions are:
+The supported actions are:
 
  * <<include-fields,`include_fields`>>
  * <<drop-fields,`drop_fields`>>
  * <<drop-event,`drop_event`>>
+ * <<add-cloud-metadata,`add_cloud_metadata`>>
 
 See <<exported-fields>> for the full list of possible fields.
 
@@ -291,3 +292,82 @@ processors:
         condition
 ------
 
+[[add-cloud-metadata]]
+===== add_cloud_metadata
+
+The `add_cloud_metadata` action enriches each event with instance metadata from
+the machine's hosting provider. At startup it will detect the hosting provider
+and cache the instance metadata.
+
+Three cloud providers are supported.
+
+- Amazon Elastic Compute Cloud (EC2)
+- Digital Ocean
+- Google Compute Engine (GCE)
+
+The simple configuration below enables the processor.
+
+[source,yaml]
+--------------------------------------------------------------------------------
+processors:
+- add_cloud_metadata:
+--------------------------------------------------------------------------------
+
+The `add_cloud_metadata` action has one optional configuration setting named
+`timeout` that specifies the maximum amount of time to wait for a successful
+response when detecting the hosting provider. The default timeout value is `3s`.
+If a timeout occurs then no instance metadata will be added to the events. This
+makes it possible to enable this processor for all your deployments (in the
+cloud or on-premise).
+
+The metadata that is added to events varies by hosting provider. Below are
+examples for each of the supported providers.
+
+_EC2_
+
+[source,json]
+--------------------------------------------------------------------------------
+{
+  "meta": {
+    "cloud": {
+      "availability_zone": "us-east-1c",
+      "instance_id": "i-4e123456",
+      "machine_type": "t2.medium",
+      "provider": "ec2",
+      "region": "us-east-1"
+    }
+  }
+}
+--------------------------------------------------------------------------------
+
+_Digital Ocean_
+
+[source,json]
+--------------------------------------------------------------------------------
+{
+  "meta": {
+    "cloud": {
+      "instance_id": "1234567",
+      "provider": "digitalocean",
+      "region": "nyc2"
+    }
+  }
+}
+--------------------------------------------------------------------------------
+
+_GCE_
+
+[source,json]
+--------------------------------------------------------------------------------
+{
+  "meta": {
+    "cloud": {
+      "availability_zone": "projects/1234567890/zones/us-east1-b",
+      "instance_id": "1234556778987654321",
+      "machine_type": "projects/1234567890/machineTypes/f1-micro",
+      "project_id": "my-dev",
+      "provider": "gce"
+    }
+  }
+}
+--------------------------------------------------------------------------------