Add add_locale processor to add local timezone to an event (#3902)

The `add_locale` processor adds the host machine's configured timezone to the event under the `beat.timezone` field.

This field can be used to apply transformations to the event that are based on the machine's local time. For example, you can then correctly interpret the timestamp placed in logs by syslog.

Fixes #3867

CHANGELOG.asciidoc

@@ -88,6 +88,7 @@ https://github.com/elastic/beats/compare/v5.1.1...master[Check the HEAD diff]
 - Disabled date detection in Elasticsearch index templates. Date fields must be explicitly defined in index templates. {pull}3528[3528]
 - Using environment variables in the configuration file is now GA, instead of experimental. {pull}3525[3525]
 - Initialize a beats UUID from file on startup. {pull}3615[3615]
+- Add new `add_locale` processor to export the local timezone with an event. {pull}3902[3902]
 
 *Filebeat*
 

filebeat/docs/fields.asciidoc

@@ -304,6 +304,12 @@ The name of the Beat sending the log messages. If the Beat name is set in the co
 The hostname as returned by the operating system on which the Beat is running.
 
 
+[float]
+=== beat.timezone
+
+The timezone as returned by the operating system on which the Beat is running.
+
+
 [float]
 === beat.version
 

filebeat/filebeat.full.yml

@@ -419,6 +419,11 @@ filebeat.prospectors:
 #processors:
 #- add_cloud_metadata:
 #
+# The following example enriches each event with the local timezone.
+#
+#processors:
+#- add_locale:
+#
 
 #================================ Outputs ======================================
 

heartbeat/docs/fields.asciidoc

@@ -36,6 +36,12 @@ The name of the Beat sending the log messages. If the Beat name is set in the co
 The hostname as returned by the operating system on which the Beat is running.
 
 
+[float]
+=== beat.timezone
+
+The timezone as returned by the operating system on which the Beat is running.
+
+
 [float]
 === beat.version
 

heartbeat/heartbeat.full.yml

@@ -267,6 +267,11 @@ heartbeat.scheduler:
 #processors:
 #- add_cloud_metadata:
 #
+# The following example enriches each event with the local timezone.
+#
+#processors:
+#- add_locale:
+#
 
 #================================ Outputs ======================================
 

libbeat/_meta/config.full.yml

@@ -69,6 +69,11 @@
 #processors:
 #- add_cloud_metadata:
 #
+# The following example enriches each event with the local timezone.
+#
+#processors:
+#- add_locale:
+#
 
 #================================ Outputs ======================================
 

libbeat/_meta/fields.common.yml

@@ -15,6 +15,10 @@
       description: >
         The hostname as returned by the operating system on which the Beat is
         running.
+    - name: beat.timezone
+      description: >
+        The timezone as returned by the operating system on which the Beat is
+        running.
     - name: beat.version
       description: >
         The version of the beat that generated this event.

libbeat/beat/beat.go

@@ -63,6 +63,7 @@ import (
 	// Register default processors.
 	_ "github.com/elastic/beats/libbeat/processors/actions"
 	_ "github.com/elastic/beats/libbeat/processors/add_cloud_metadata"
+	_ "github.com/elastic/beats/libbeat/processors/add_locale"
 
 	// Register default monitoring reporting
 	_ "github.com/elastic/beats/libbeat/monitoring/report/elasticsearch"

libbeat/docs/processors-config.asciidoc

@@ -253,6 +253,7 @@ not:
 The supported processors are:
 
  * <<add-cloud-metadata,`add_cloud_metadata`>>
+ * <<add-locale,`add_locale`>>
  * <<decode-json-fields,`decode_json_fields`>>
  * <<drop-event,`drop_event`>>
  * <<drop-fields,`drop_fields`>>
@@ -340,6 +341,23 @@ _GCE_
 }
 -------------------------------------------------------------------------------
 
+[[add-locale]]
+=== add_locale
+
+The `add_locale` processor enriches each event with the machine's time zone.
+
+The simple configuration below enables the processor.
+
+[source,yaml]
+-------------------------------------------------------------------------------
+processors:
+- add_locale:
+-------------------------------------------------------------------------------
+
+NOTE: Please consider that `add_locale` differentiates between DST and regular time.
+For example `CET` and `CEST`.
+
+
 [[decode-json-fields]]
 === decode_json_fields
 

libbeat/processors/add_locale/add_locale.go

@@ -0,0 +1,29 @@
+package actions
+
+import (
+	"time"
+
+	"github.com/elastic/beats/libbeat/common"
+	"github.com/elastic/beats/libbeat/processors"
+)
+
+type addLocale struct{}
+
+func init() {
+	processors.RegisterPlugin("add_locale", newAddLocale)
+}
+
+func newAddLocale(c common.Config) (processors.Processor, error) {
+	return addLocale{}, nil
+}
+
+func (l addLocale) Run(event common.MapStr) (common.MapStr, error) {
+	zone, _ := time.Now().Zone()
+	event.Put("beat.timezone", zone)
+
+	return event, nil
+}
+
+func (l addLocale) String() string {
+	return "add_locale"
+}

libbeat/processors/add_locale/add_locale_test.go

@@ -0,0 +1,59 @@
+package actions
+
+import (
+	"testing"
+	"time"
+
+	"github.com/elastic/beats/libbeat/common"
+	"github.com/elastic/beats/libbeat/logp"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestExportTimeZone(t *testing.T) {
+	var testConfig = common.NewConfig()
+
+	input := common.MapStr{}
+
+	zone, _ := time.Now().In(time.Local).Zone()
+
+	actual := getActualValue(t, testConfig, input)
+
+	expected := common.MapStr{
+		"beat": map[string]string{
+			"timezone": zone,
+		},
+	}
+
+	assert.Equal(t, expected.String(), actual.String())
+}
+
+func getActualValue(t *testing.T, config *common.Config, input common.MapStr) common.MapStr {
+	if testing.Verbose() {
+		logp.LogInit(logp.LOG_DEBUG, "", false, true, []string{"*"})
+	}
+
+	p, err := newAddLocale(*config)
+	if err != nil {
+		logp.Err("Error initializing add_locale")
+		t.Fatal(err)
+	}
+
+	actual, err := p.Run(input)
+
+	return actual
+}
+
+func BenchmarkConstruct(b *testing.B) {
+	var testConfig = common.NewConfig()
+
+	input := common.MapStr{}
+
+	p, err := newAddLocale(*testConfig)
+	if err != nil {
+		b.Fatal(err)
+	}
+
+	for i := 0; i < b.N; i++ {
+		_, err = p.Run(input)
+	}
+}

metricbeat/docs/fields.asciidoc

@@ -383,6 +383,12 @@ The name of the Beat sending the log messages. If the Beat name is set in the co
 The hostname as returned by the operating system on which the Beat is running.
 
 
+[float]
+=== beat.timezone
+
+The timezone as returned by the operating system on which the Beat is running.
+
+
 [float]
 === beat.version
 

metricbeat/metricbeat.full.yml

@@ -404,6 +404,11 @@ metricbeat.modules:
 #processors:
 #- add_cloud_metadata:
 #
+# The following example enriches each event with the local timezone.
+#
+#processors:
+#- add_locale:
+#
 
 #================================ Outputs ======================================
 

packetbeat/docs/fields.asciidoc

@@ -375,6 +375,12 @@ The name of the Beat sending the log messages. If the Beat name is set in the co
 The hostname as returned by the operating system on which the Beat is running.
 
 
+[float]
+=== beat.timezone
+
+The timezone as returned by the operating system on which the Beat is running.
+
+
 [float]
 === beat.version
 

packetbeat/packetbeat.full.yml

@@ -524,6 +524,11 @@ packetbeat.protocols:
 #processors:
 #- add_cloud_metadata:
 #
+# The following example enriches each event with the local timezone.
+#
+#processors:
+#- add_locale:
+#
 
 #================================ Outputs ======================================
 

winlogbeat/docs/fields.asciidoc

@@ -37,6 +37,12 @@ The name of the Beat sending the log messages. If the Beat name is set in the co
 The hostname as returned by the operating system on which the Beat is running.
 
 
+[float]
+=== beat.timezone
+
+The timezone as returned by the operating system on which the Beat is running.
+
+
 [float]
 === beat.version
 

winlogbeat/winlogbeat.full.yml

@@ -98,6 +98,11 @@ winlogbeat.event_logs:
 #processors:
 #- add_cloud_metadata:
 #
+# The following example enriches each event with the local timezone.
+#
+#processors:
+#- add_locale:
+#
 
 #================================ Outputs ======================================