Merge pull request #7579 from satnam6502/fluentd-es-image

Improve comment in Fluentd to ES logging config file

cluster/addons/fluentd-elasticsearch/fluentd-es-image/td-agent.conf

@@ -1,16 +1,15 @@
 # This configuration file for Fluentd / td-agent is used
 # to watch changes to Docker log files that live in the
-# directory /var/lib/docker/containers/ which are then submitted to
-# Elasticsearch (running on the machine %ES_HOST%:9200) which
-# assumes the installation of the fluentd-elasticsearch plug-in.
+# directory /var/lib/docker/containers/ and are symbolically
+# linked to from the /varlog directory using names that capture the
+# pod name and container name. These logs are then submitted to
+# Elasticsearch which assumes the installation of the fluentd-elasticsearch plug-in.
 # See https://github.com/uken/fluent-plugin-elasticsearch for
-# more information about the plug-in. This file needs to be
-# patched to replace ES_HOST with the name of the actual
-# machine running Elasticsearch.
+# more information about the plug-in.
 # Maintainer: Satnam Singh (satnam@google.com)
 #
-# Exampe
-# ======
+# Example
+# =======
 # A line in the Docker log file might like like this JSON:
 #
 # {"log":"2014/09/25 21:15:03 Got request with path wombat\n",
@@ -20,7 +19,7 @@
 # The time_format specification below makes sure we properly
 # parse the time format produced by Docker. This will be
 # submitted to Elasticsearch and should appear like:
-# $ curl 'http://elasticsearch:9200/_search?pretty'
+# $ curl 'http://elasticsearch-logging.default:9200/_search?pretty'
 # ...
 # {
 #      "_index" : "logstash-2014.09.25",
@@ -32,6 +31,35 @@
 #                 "@timestamp":"2014-09-25T22:45:50+00:00"}
 #    },
 # ...
+#
+# The record reformer is used to write the tag to focus on the pod name
+# and the Kubernetes container name. For example a Docker container's logs
+# might be in the directory:
+#  /var/lib/docker/containers/997599971ee6366d4a5920d25b79286ad45ff37a74494f262e3bc98d909d0a7b
+# and in the file:
+#  997599971ee6366d4a5920d25b79286ad45ff37a74494f262e3bc98d909d0a7b-json.log
+# where 997599971ee6... is the Docker ID of the running container.
+# The Kubernetes kubelet makes a symbolic link to this file on the host machine
+# in the /var/log/containers directory which includes the pod name and the Kubernetes
+# container name:
+#    synthetic-logger-0.25lps-pod_default-synth-lgr-997599971ee6366d4a5920d25b79286ad45ff37a74494f262e3bc98d909d0a7b.log 
+#    -> 
+#    /var/lib/docker/containers/997599971ee6366d4a5920d25b79286ad45ff37a74494f262e3bc98d909d0a7b/997599971ee6366d4a5920d25b79286ad45ff37a74494f262e3bc98d909d0a7b-json.log
+# The /var/log directory on the host is mapped to the /varlog directory in the container
+# running this instance of Fluentd and we end up collecting the file:
+#   /varlog/containers/synthetic-logger-0.25lps-pod_default-synth-lgr-997599971ee6366d4a5920d25b79286ad45ff37a74494f262e3bc98d909d0a7b.log
+# This results in the tag:
+#  varlog.containers.synthetic-logger-0.25lps-pod_default-synth-lgr-997599971ee6366d4a5920d25b79286ad45ff37a74494f262e3bc98d909d0a7b.log
+# The record reformer is used is discard the varlog.containers prefix and
+# the Docker container ID suffix and "kubernetes." is pre-pended giving the
+# final tag which is ingested into Elasticsearch:
+#   kubernetes.synthetic-logger-0.25lps-pod_default-synth-lgr
+# This makes it easier for users to search for logs by pod name or by
+# the name of the Kubernetes container regardless of how many times the
+# Kubernetes pod has been restarted (resulting in a several Docker container IDs).
+# TODO: Propagate the labels associated with a container along with its logs
+# so users can query logs using labels as well as or instead of the pod name
+# and container name.
 
 <source>
   type tail