index.asciidoc in logstash-input-google_pubsub-1.1.0

- old
+ new

@@ -136,11 +136,43 @@
     }
 }
 output { stdout { codec => rubydebug } }
 ----------------------------------
 
+==== Metadata and Attributes
 
+The original Pub/Sub message is preserved in the special Logstash 
+`[@metadata][pubsub_message]` field so you can fetch:
+
+* Message attributes
+* The origiginal base64 data
+* Pub/Sub message ID for de-duplication
+* Publish time
+
+You MUST extract any fields you want in a filter prior to the data being sent
+to an output because Logstash deletes `@metadata` fields otherwise.
+
+See the PubsubMessage
+https://cloud.google.com/pubsub/docs/reference/rest/v1/PubsubMessage[documentation]
+for a full description of the fields.
+
+Example to get the message ID:
+
+[source,ruby]
+----------------------------------	
+input {google_pubsub {...}}
+
+filter {
+  mutate {
+    add_field => { "messageId" => "%{[@metadata][pubsub_message][messageId]}" }
+  }
+}
+
+output {...}
+----------------------------------
+
+
 [id="plugins-{type}s-{plugin}-options"]
 ==== Google_pubsub Input Configuration Options
 
 This plugin supports the following configuration options plus the <<plugins-{type}s-{plugin}-common-options>> described later.
 
@@ -150,10 +182,11 @@
 | <<plugins-{type}s-{plugin}-json_key_file>> |a valid filesystem path|No
 | <<plugins-{type}s-{plugin}-max_messages>> |<<number,number>>|Yes
 | <<plugins-{type}s-{plugin}-project_id>> |<<string,string>>|Yes
 | <<plugins-{type}s-{plugin}-subscription>> |<<string,string>>|Yes
 | <<plugins-{type}s-{plugin}-topic>> |<<string,string>>|Yes
+| <<plugins-{type}s-{plugin}-include_metadata>> |<<boolean,boolean>>|No
 |=======================================================================
 
 Also see <<plugins-{type}s-{plugin}-common-options>> for a list of options supported by all
 input plugins.
 
@@ -207,11 +240,17 @@
 Google Cloud Pub/Sub Topic and Subscription.
 Note that the topic must be created manually with Cloud Logging
 pre-configured export to PubSub configured to use the defined topic.
 The subscription will be created automatically by the plugin.
 
+[id="plugins-{type}s-{plugin}-include_metadata"]
+===== `include_metadata` 
 
+  * Value type is <<boolean,boolean>>
+  * Default value is `false`.
 
+If set true, will include the full message data in the `[@metadata][pubsub_message]` field.
+
 [id="plugins-{type}s-{plugin}-common-options"]
 include::{include_path}/{type}.asciidoc[]
 
-:default_codec!:
\ No newline at end of file
+:default_codec!: