From bd77a425ba229eab0c53283d02f10b4123b3d009 Mon Sep 17 00:00:00 2001
From: Ben Tasker <88340935+btasker@users.noreply.github.com>
Date: Wed, 25 Jan 2023 20:16:55 +0000
Subject: [PATCH] docs(outputs.elasticsearch): detail overriding timezone
 (#12551)

---
 plugins/outputs/elasticsearch/README.md | 28 +++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/plugins/outputs/elasticsearch/README.md b/plugins/outputs/elasticsearch/README.md
index a9e056b01..f13de755f 100644
--- a/plugins/outputs/elasticsearch/README.md
+++ b/plugins/outputs/elasticsearch/README.md
@@ -156,6 +156,34 @@ This plugin will format the events in the following way:
 }
 ```
 
+### Timestamp Timezone
+
+Elasticsearch documents use RFC3339 timestamps, which include timezone
+information (for example `2017-01-01T00:00:00-08:00`). By default, the Telegraf
+system's configured timezone will be used.
+
+However, this may not always be desirable: Elasticsearch preserves timezone
+information and includes it when returning associated documents. This can cause
+issues for some pipelines. In particular, those that do not parse retrieved
+timestamps and instead assume that the timezone returned will always be
+consistent.
+
+Telegraf honours the timezone configured in the environment variable `TZ`, so
+the timezone sent to Elasticsearch can be amended without needing to change the
+timezone configured in the host system:
+
+```sh
+export TZ="America/Los_Angeles"
+export TZ="UTC"
+```
+
+If Telegraf is being run as a system service, this can be configured in the
+following way on Linux:
+
+```sh
+echo TZ="UTC" | sudo tee -a /etc/default/telegraf
+```
+
 ## OpenSearch Support
 
 OpenSearch is a fork of Elasticsearch hosted by AWS. The OpenSearch server will