Merge pull request #25786 from splunk/splunk-logging-driver-raw-format-using-json

Splunk Logging Driver: formats and verifyconnection
Upstream-commit: 78771b62255456bef110a3e310eb20165e5ece9f
Component: engine

components/engine/docs/admin/logging/splunk.md

@@ -42,6 +42,8 @@ logging driver options:
 | `splunk-capath`             | optional | Path to root certificate.                                                                                                                                                                                          |
 | `splunk-caname`             | optional | Name to use for validating server certificate; by default the hostname of the `splunk-url` will be used.                                                                                                           |
 | `splunk-insecureskipverify` | optional | Ignore server certificate validation.                                                                                                                                                                              |
+| `splunk-format`             | optional | Message format. Can be `inline`, `json` or `raw`. Defaults to `inline`.                                                                                                                                            |
+| `splunk-verify-connection`   | optional | Verify on start, that docker can connect to Splunk server. Defaults to true.                                                                                                                                       |
 | `tag`                       | optional | Specify tag for message, which interpret some markup. Default value is `{{.ID}}` (12 characters of the container ID). Refer to the [log tag option documentation](log_tags.md) for customizing the log tag format. |
 | `labels`                    | optional | Comma-separated list of keys of labels, which should be included in message, if these labels are specified for container.                                                                                          |
 | `env`                       | optional | Comma-separated list of keys of environment variables, which should be included in message, if these variables are specified for container.                                                                        |
@@ -66,3 +68,67 @@ The `SplunkServerDefaultCert` is automatically generated by Splunk certificates.
         --env "TEST=false"
         --label location=west
         your/application
+
+### Message formats
+
+By default Logging Driver sends messages as `inline` format, where each message
+will be embedded as a string, for example
+
+```
+{
+    "attrs": {
+        "env1": "val1",
+        "label1": "label1"
+    },
+    "tag": "MyImage/MyContainer",
+    "source":  "stdout",
+    "line": "my message"
+}
+{
+    "attrs": {
+        "env1": "val1",
+        "label1": "label1"
+    },
+    "tag": "MyImage/MyContainer",
+    "source":  "stdout",
+    "line": "{\"foo\": \"bar\"}"
+}
+```
+
+In case if your messages are JSON objects you may want to embed them in the
+message we send to Splunk. By specifying `--log-opt splunk-format=json` driver
+will try to parse every line as a JSON object and send it as embedded object. In
+case if it cannot parse it - message will be send as `inline`. For example
+
+
+```
+{
+    "attrs": {
+        "env1": "val1",
+        "label1": "label1"
+    },
+    "tag": "MyImage/MyContainer",
+    "source":  "stdout",
+    "line": "my message"
+}
+{
+    "attrs": {
+        "env1": "val1",
+        "label1": "label1"
+    },
+    "tag": "MyImage/MyContainer",
+    "source":  "stdout",
+    "line": {
+        "foo": "bar"
+    }
+}
+```
+
+Third format is a `raw` message. You can specify it by using
+`--log-opt splunk-format=raw`. Attributes (environment variables and labels) and
+tag will be prefixed to the message. For example
+
+```
+MyImage/MyContainer env1=val1 label1=label1 my message
+MyImage/MyContainer env1=val1 label1=label1 {"foo": "bar"}
+```