Cleanup and clarify config spec

- Ensure all config vars are in table format
- Prefer SPLUNK prefix
- Fix deployment environment typo

Addresses open-telemetry#7 open-telemetry#8

Author: flands

README.md

@@ -14,15 +14,19 @@ The following components are currently in scope:
 - [Configuration](docs/configuration.md)
 - [Repository](docs/repository.md)
 
+GDI projects MUST adopt GDI specification changes by their next minor release
+and within three months (whichever is sooner). The GDI specification and GDI
+projects MUST remove any deprecated specification at the next major release.
+
 ## Terms
 
 - Collector: A single binary that can be deployed as an agent or gateway.
-  Refers to `splunk-otel-collector`.
+  Refers to `splunk-otel-collector` project.
 - GDI: Getting Data In
 - GDI Project: A project in the `signalfx` GitHub that starts with
   `splunk-otel-\*`
 - Instrumentation Library: The way to emit telemetry data from an application.
-  Refers to `splunk-otel-<language>`.
+  Refers to `splunk-otel-<language>` projects.
 - Maintainer: Someone responsible for the specification or a project
 - Specification: A set of requirements for projects
 - Project: A GitHub repository

docs/configuration.md

@@ -16,20 +16,19 @@ If a GDI project requires an immediate configuration variable that is not
 available in the OpenTelemetry specification and not available in the GDI
 specification, the project MAY introduce a project-specific configuration
 variable until the GDI specification maintainers make a decision. Any
-project-specific configuration variable defined MUST NOT be marked as stable
-unless added to the GDI specification. Upon resolution by the GDI
-specification, the GDI project MUST change the project-specific configuration
-variable by the project's next minor release. This change MAY result in a
-breaking change so caution should be exhibited when considering
-project-specific configuration variables.
-
-If a Splunk-specific configuration variable is declared as stable in the GDI
-specification and later the OpenTelemetry specification declares a similar
-variable as stable, the GDI specification variable MUST be marked as deprecated
-by the next minor release. GDI projects MUST add the stable OpenTelemetry
-configuration variable and deprecate the Splunk-specific configuration variable
-by the next minor release. The GDI specification and GDI projects MUST remove
-the deprecated configuration variable at the next major release.
+project-specific configuration variable defined SHOULD be prefixed with
+`SPLUNK_` and MUST NOT be marked as stable unless added to the GDI
+specification. Upon resolution by the GDI specification, the GDI project MUST
+change the project-specific configuration variable by the project's next minor
+release. This change MAY result in a breaking change so caution should be
+exhibited when considering project-specific configuration variables.
+
+Splunk-specific configuration variables defined in the GDI specification MUST
+be prefixed with `SPLUNK_`. If a Splunk-specific configuration variable is
+declared as stable in the GDI specification and later the OpenTelemetry
+specification declares a similar variable as stable, the GDI specification
+MUST adopt the OpenTelemetry configuration variable and SHOULD mark the GDI
+specification configuration variable as deprecated by the next minor release.
 
 In addition to defining Splunk-specification configuration variables, the GDI
 specification MAY require specific OpenTelemetry configuration variables be
@@ -43,44 +42,37 @@ supported including a specific default value.
 | Name                | Type   | Default value | Required | Description                                    |
 | :-----------------: | :----: | :-----------: | :------: | :-----------------------------------:          |
 | SPLUNK_ACCESS_TOKEN | string |               | Yes [1]  | Access token added to exported data.           |
-| SPLUNK_CONFIG       | string |               | No       | Configuration file to use.                     |
+| SPLUNK_CONFIG       | string |               | No  [2]  | Configuration file to use.                     |
 | SPLUNK_REALM        | string |               | Yes [1]  | Realm configured for the exporter endpoint.    |
 
-- [1]: Required whenever the Collector is configured to export data to a Splunk
-  back-end. This is the default behavior for the Collector. If the Collector is
-  configured as an agent and the agent is configured to send to a Collector
-  running as a gateway then this is not required. If `SPLUNK_CONFIG` is defined
-  then this is not required.
+- [1]: If the Collector is configured to export data to a Splunk back-end these
+  options MUST be defined with valid values (this is the default behavior for
+  the Collector). If the Collector is configured as an agent and the agent is
+  configured to send to a Collector running as a gateway then these options are
+  not required. If `SPLUNK_CONFIG` is defined then these options are not
+  required.
+- [2]: Either `SPLUNK_ACCESS_TOKEN` and `SPLUNK_REALM` MUST be defined or
+  `SPLUNK_CONFIG` MUST be defined. If `SPLUNK_ACCESS_TOKEN` and `SPLUNK_REALM`
+  is defined, `SPLUNK_CONFIG` MAY be defined.
 
 ### Instrumentation Libraries
 
-| Name                                 | Type    | Default value | Required | Description                                                |
-| :----------------------------------: | :----:  | :-----------: | :------: | :--------------------------------------------------------: |
-| SPLUNK_ACCESS_TOKEN                  | string  |               | No [1]   | Access token added to exported data.                       |
-| SPLUNK_CONTEXT_SERVER_TIMING_ENABLED | boolean | `false`       | No       | Whether `Server-Timing` header is added to HTTP responses. |
+| Name                                 | Type    | Default value                    | Required | Description                                                                                         |
+| :----------------------------------: | :----:  | :-----------:                    | :------: | :--------------------------------------------------------:                                          |
+| OTEL_EXPORTER_JAEGER_ENDPOINT        | string  | `http://localhost:9080/v1/trace` | Yes      | Where to export data if `OTEL_TRACES_EXPORTER=jaeger-thrift-splunk`.                                |
+| OTEL_EXPORTER_OTLP_ENDPOINT          | string  | `localhost:4317`                 | No       | Where to export data if `OTEL_TRACES_EXPORTER=otlp`.                                                |
+| OTEL_RESOURCE_ATTRIBUTES             | string  | `unknown_service[:<process>]`    | Yes      | Key/Value resource information. MUST define `service.name`. SHOULD define `deployment.environment`. |
+| OTEL_TRACES_EXPORTER                 | string  | `jaeger-thrift-splunk`           | Yes      | Exported data format. MUST support `jaeger-thrift-splunk` and `otlp`.                               |
+| SPLUNK_ACCESS_TOKEN                  | string  |                                  | No [1]   | Access token added to exported data.                                                                |
+| SPLUNK_CONTEXT_SERVER_TIMING_ENABLED | boolean | `false`                          | No [2]   | Whether `Server-Timing` header is added to HTTP responses.                                          |
 
 - [1]: Not required if another system performs the authentication. For example,
   instrumentation libraries SHOULD send data to a locally running agent. The
   agent can define the access token that is used. If the component is
   configured to send data directly to a SaaS endpoint then this variable MUST
   be defined.
-
-In addition, the following OpenTelemetry options MUST be supported:
-
-- [OTEL_EXPORTER_JAEGER_ENDPOINT]
-  - MUST default to `http://localhost:9080/v1/trace`
-- [OTEL_EXPORTER_OTLP_ENDPOINT]
-  - MUST default to `localhost:4317`
-- [OTEL_RESOURCE_ATTRIBUTES]
-  - MUST allow `service.name` to be defined and MUST offer a default, non-empty value
-  - MUST allow `deployment.server` to be defined and MUST not send unless explicitly defined
-  - MUST NOT suggest `deployment` to be used as the key
-- [OTEL_TRACE_ENABLED]
-  - MUST default to `true`
-  - MUST support `false` which disables emitting spans
-- [OTEL_TRACES_EXPORTER]
-  - MUST offer `jaeger-thrift-splunk` and `otlp` as values
-  - MUST default to `jaeger-thrift-splunk` value
+- [2]: If stitching of RUM spans and APM spans is desired then this parameter
+  MUST be set to `true`.
 
 ## Environment variable alternatives