Edit doc

Author: bjsignalfx

cmd/otelcol/main_test.go

@@ -16,8 +16,14 @@
 package main
 
 import (
+	"fmt"
+	"log"
 	"os"
+	"os/exec"
 	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
 )
 
 func TestContains(t *testing.T) {
@@ -142,3 +148,34 @@ func TestSetMemoryLimit(t *testing.T) {
 
 	HelperTestSetMemoryLimit("200", t)
 }
+
+func TestConfigPathAndYamlEnvVarsTogetherNotAllowed(t *testing.T) {
+	expectedErr := fmt.Sprintf("Specifying env vars %s and %s simultaneously is not allowed", configEnvVarName, configYamlEnvVarName)
+	stdErr, exitCode := getExecErr(t, "TestConfigPathAndYamlEnvVarsTogetherNotAllowed", func(t *testing.T) {
+		// Setting both config file path and config YAML env vars
+		os.Setenv(configYamlEnvVarName, "service:  \\nextensions:  \\n- health_check")
+		os.Setenv(configEnvVarName, "path/to/config/file")
+		setConfigSource()
+	})
+
+	require.NotZero(t, exitCode)
+	assert.Containsf(t, stdErr, expectedErr, "Standard error does not contain the expected error")
+}
+
+// getExecErr should be called once in a test at the beginning and the failing code placed in func failingCode.
+// getExecErr runs the test in a subprocess then returns the output of executing failingCode.
+func getExecErr(t *testing.T, testName string, failingCode func(*testing.T)) (string, int) {
+	if os.Getenv(testName) == "1" {
+		failingCode(t)
+		os.Exit(0)
+	}
+	path, arg := os.Args[0], "-test.run="+testName
+	cmd := exec.Command(path, arg)
+	cmd.Env = append(os.Environ(), testName+"=1")
+	stdErr, err := cmd.CombinedOutput()
+	exitErr := err.(*exec.ExitError)
+	if exitErr.ExitCode() == 0 {
+		log.Fatal("Failing code exited with zero exit code")
+	}
+	return string(stdErr), exitErr.ExitCode()
+}

docs/getting-started/linux-manual.md

@@ -140,9 +140,11 @@ $ docker run --rm -e SPLUNK_ACCESS_TOKEN=12345 -e SPLUNK_REALM=us0 \
 ### Custom Configuration
 
 When changes to the default configuration file is needed, a custom
-configuration file can specified and used instead. Use the `SPLUNK_CONFIG`
-environment variable or the `--config` command line argument to provide a
-custom configuration.
+configuration file can be specified and used instead. Use the `SPLUNK_CONFIG`
+environment variable or the `--config` command line argument to provide the 
+path to a YAML file containing the custom configuration. Environment variable
+`SPLUNK_CONFIG_YAML` can be used provide the custom configuration YAML directly
+to the exclusion of `SPLUNK_CONFIG`.
 
 > Command line arguments take precedence over environment variables. This
 > applies to `--config` and `--mem-ballast-size-mib`.
@@ -160,11 +162,29 @@ $ docker run --rm -e SPLUNK_ACCESS_TOKEN=12345 -e SPLUNK_REALM=us0 \
 
 > Use of a SemVer tag over `latest` is highly recommended.
 
-In the case of Docker, a volume mount may be required to load custom
-configuration as shown above.
+In the case of Docker, a volume mount may be required to store the custom
+configuration file as shown above.
 
 If the custom configuration includes a `memory_limiter` processor then the
 `ballast_size_mib` parameter should be the same as the
 `SPLUNK_BALLAST_SIZE_MIB` environment variable. See
 [gateway_config.yaml](../../cmd/otelcol/config/collector/gateway_config.yaml)
 as an example.
+
+Using `SPLUNK_CONFIG_YAML` instead of `SPLUNK_CONFIG` would be something like:
+
+```bash
+$ SPLUNK_CONFIG_YAML="extensions:\n  health_check:\n    endpoint: 0.0.0.0:13133"
+
+$ docker run --rm -e SPLUNK_ACCESS_TOKEN=12345 -e SPLUNK_REALM=us0 \
+    -e SPLUNK_CONFIG_YAML=${SPLUNK_CONFIG_YAML} -p 13133:13133 -p 14250:14250 \
+    -p 14268:14268 -p 4317:4317 -p 6060:6060 -p 7276:7276 -p 8888:8888 \
+    -p 9080:9080 -p 9411:9411 -p 9943:9943 \
+    --name otelcol quay.io/signalfx/splunk-otel-collector:latest
+```
+Where `SPLUNK_CONFIG_YAML` is the one-line version of the multi-line configuration YAML below:
+```yaml
+extensions:
+  health_check:
+     endpoint: 0.0.0.0:13133
+```