1. docker
  2. Commit cd426ebed79e29153eb29ea1ccb260e15db2fea5
Browse code

Add docs for label/env log-opts

Signed-off-by: Vincent Demeester <vincent@sbr.pm>

Vincent Demeester authored on 2015/10/13 15:39:47
Showing 3 changed files
docs/reference/logging/fluentd.md
History View file @ cd426eb
... ... 
@@ -73,6 +73,24 @@ Refer to the [log tag option documentation](log_tags.md) for customizing
73 73 
 the log tag format.
74 74
75 75
76 
+### labels and env
77 
+
78 
+The `labels` and `env` options takes a comma-separated list of keys. If there is collision between `label` and `env` keys, the value of the `env` takes precedence.
79 
+
80 
+To use attributes, specify them when you start the Docker daemon.
81 
+
82 
+```
83 
+docker daemon --log-driver=fluentd --log-opt labels=foo --log-opt env=foo,fizz
84 
+```
85 
+
86 
+Then, run a container and specify values for the `labels` or `env`.  For example, you might use this:
87 
+
88 
+```
89 
+docker run --label foo=bar -e fizz=buzz -d -P training/webapp python app.py
90 
+````
91 
+
92 
+This adds additional fields to the extra attributes of a logging message.
93 
+
76 94 
 ## Fluentd daemon management with Docker
77 95
78 96 
 About `Fluentd` itself, see [the project webpage](http://www.fluentd.org)
docs/reference/logging/journald.md
History View file @ cd426eb
... ... 
@@ -36,6 +36,31 @@ You can set the logging driver for a specific container by using the
36 36
37 37 
     docker run --log-driver=journald ...
38 38
39 
+## Options
40 
+
41 
+Users can use the `--log-opt NAME=VALUE` flag to specify additional
42 
+journald logging driver options.
43 
+
44 
+### labels and env
45 
+
46 
+The `labels` and `env` options takes a comma-separated list of keys. If there is collision between `label` and `env` keys, the value of the `env` takes precedence.
47 
+
48 
+To use attributes, specify them when you start the Docker daemon.
49 
+
50 
+```
51 
+docker daemon --log-driver=journald --log-opt labels=foo --log-opt env=foo,fizz
52 
+```
53 
+
54 
+Then, run a container and specify values for the `labels` or `env`.  For example, you might use this:
55 
+
56 
+```
57 
+docker run --label foo=bar -e fizz=buzz -d -P training/webapp python app.py
58 
+````
59 
+
60 
+This adds additional metadata in the journal with each message, one
61 
+for each key that matches.
62 
+
63 
+
39 64 
 ## Note regarding container names
40 65
41 66 
 The value logged in the `CONTAINER_NAME` field is the container name
docs/reference/logging/overview.md
History View file @ cd426eb
... ... 
@@ -27,12 +27,15 @@ container's logging driver. The following options are supported:
27 27
28 28 
 The `docker logs`command is available only for the `json-file` logging driver.
29 29
30 
+
30 31 
 ## json-file options
31 32
32 33 
 The following logging options are supported for the `json-file` logging driver:
33 34
34 35 
     --log-opt max-size=[0-9+][k|m|g]
35 36 
     --log-opt max-file=[0-9+]
37 
+    --log-opt labels=label1,label2
38 
+    --log-opt env=env1,env2
36 39
37 40 
 Logs that reach `max-size` are rolled over. You can set the size in kilobytes(k), megabytes(m), or gigabytes(g). eg `--log-opt max-size=50m`. If `max-size` is not set, then logs are not rolled over.
38 41
... ... 
@@ -41,6 +44,26 @@ Logs that reach `max-size` are rolled over. You can set the size in kilobytes(k)
41 41
42 42 
 If `max-size` and `max-file` are set, `docker logs` only returns the log lines from the newest log file.
43 43
44 
+The `labels` and `env` options add additional attributes for use with logging drivers that accept them. Each of these options takes a comma-separated list of keys. If there is collision between `label` and `env` keys, the value of the `env` takes precedence.
45 
+
46 
+To use attributes, specify them when you start the Docker daemon.
47 
+
48 
+```
49 
+docker daemon --log-driver=json-file --log-opt labels=foo --log-opt env=foo,fizz
50 
+```
51 
+
52 
+Then, run a container and specify values for the `labels` or `env`.  For example, you might use this:
53 
+
54 
+```
55 
+docker run --label foo=bar -e fizz=buzz -d -P training/webapp python app.py
56 
+````
57 
+
58 
+This adds additional fields depending on the driver, e.g. for
59 
+`json-file` that looks like:
60 
+
61 
+    "attrs":{"fizz":"buzz","foo":"bar"}
62 
+
63 
+
44 64 
 ## syslog options
45 65
46 66 
 The following logging options are supported for the `syslog` logging driver:
... ... 
@@ -100,6 +123,8 @@ The GELF logging driver supports the following options:
100 100
101 101 
     --log-opt gelf-address=udp://host:port
102 102 
     --log-opt tag="database"
103 
+    --log-opt labels=label1,label2
104 
+    --log-opt env=env1,env2
103 105
104 106 
 The `gelf-address` option specifies the remote GELF server address that the
105 107 
 driver connects to. Currently, only `udp` is supported as the transport and you must
... ... 
@@ -112,6 +137,15 @@ By default, Docker uses the first 12 characters of the container ID to tag log m
112 112 
 Refer to the [log tag option documentation](log_tags.md) for customizing
113 113 
 the log tag format.
114 114
115 
+The `labels` and `env` options are supported by the gelf logging
116 
+driver. It adds additional key on the `extra` fields, prefixed by an
117 
+underscore (`_`).
118 
+
119 
+    // […]
120 
+    "_foo": "bar",
121 
+    "_fizz": "buzz",
122 
+    // […]
123 
+
115 124
116 125 
 ## fluentd options
117 126
... ... 
@@ -128,6 +162,7 @@ If container cannot connect to the Fluentd daemon on the specified address,
128 128 
 the container stops immediately. For detailed information on working with this
129 129 
 logging driver, see [the fluentd logging driver](fluentd.md)
130 130
131 
+
131 132 
 ## Specify Amazon CloudWatch Logs options
132 133
133 134 
 The Amazon CloudWatch Logs logging driver supports the following options: