Add sdk-config.yaml starter template w/ references to env vars (#76)

* Update schema to accept null values * Add sdk-config.yaml starter template * Split out starter with env vars and without * Fix typos, add links to examples from readme * Fix typo * Clarify comment in sdk-migration-config.yaml * Use signal specific env vars, ensure all endpoints include correct path * typos --------- Co-authored-by: Alex Boten <223565+codeboten@users.noreply.github.com>
open-telemetry · Jul 19, 2024 · cc7cd37 · cc7cd37
1 parent 6709017
commit cc7cd37
Show file tree

Hide file tree

Showing 15 changed files with 531 additions and 122 deletions.
diff --git a/.gitignore b/.gitignore
@@ -21,3 +21,6 @@
 # Node.js files for tools (e.g. markdown-toc)
 node_modules/
 package-lock.json
+
+# Output directory after applying env substitution
+out
diff --git a/Makefile b/Makefile
@@ -1,5 +1,6 @@
 SCHEMA_FILES := $(shell find . -path './schema/*.json' -exec basename {} \; | sort)
-EXAMPLE_FILES := $(shell find . -path './examples/*.yaml' | sort)
+EXAMPLE_FILES := $(shell find . -path './examples/*.yaml' -exec basename {} \; | sort)
+$(shell mkdir -p out)
 
 .PHONY: all
 all: install-tools compile-schema validate-examples
@@ -16,7 +17,8 @@ compile-schema:
 validate-examples:
 	@if ! npm ls ajv-cli; then npm install; fi
 	@for f in $(EXAMPLE_FILES); do \
-		npx --no ajv-cli validate --spec=draft2020 --allow-matching-properties --errors=text -s ./schema/opentelemetry_configuration.json -r "./schema/!(opentelemetry_configuration.json)" -d $$f \
+	    npx envsub ./examples/$$f ./out/$$f || exit 1; \
+		npx --no ajv-cli validate --spec=draft2020 --allow-matching-properties --errors=text -s ./schema/opentelemetry_configuration.json -r "./schema/!(opentelemetry_configuration.json)" -d ./out/$$f \
 		    || exit 1; \
 	done
 

diff --git a/README.md b/README.md
@@ -8,6 +8,15 @@ This repository contains the JSON schema that defines the OpenTelemetry configur
 - code generation
 - broad support across languages
 
+## Starter templates
+
+The [examples](./examples) repository contains a variety of sample configuration files to help get started and illustrate useful patterns. The following are noteworthy:
+
+- [sdk-migration-config.yaml](./examples/sdk-migration-config.yaml): Includes env var substitution references to all [standard environment variables](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md) which map cleanly to file configuration (see notes in the example for the set of env vars which are not referenced). Note, SDKs parsing configuration files ignore all env vars besides those referenced via [env var substitution][]. This is a great starting point for transitioning from env var based configuration to file based configuration.
+- [sdk-config.yaml](./examples/sdk-config.yaml): Represents the typical default configuration. This is a good starting point if you are not using env var based configuration or wish to transition fully to file based configuration. Note, SDKs parsing configuration files ignore all env vars besides those referenced via [env var substitution][].
+
+[env var substitution]: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/file-configuration.md#environment-variable-substitution
+
 ## Code generation
 
 There are [several tools](https://json-schema.org/implementations.html) available to generate code from a JSON schema. The following shows an example for generating code from the JSON schema in Go:

diff --git a/examples/anchors.yaml b/examples/anchors.yaml
@@ -4,7 +4,6 @@ file_format: "0.1"
 exporters:
   otlp: &otlp-exporter
     protocol: http/protobuf
-    endpoint: http://localhost:4318
     certificate: /app/cert.pem
     client_key: /app/cert.pem
     client_certificate: /app/cert.pem
@@ -20,6 +19,7 @@ logger_provider:
           otlp:
             # expand the otlp-exporter anchor
             <<: *otlp-exporter
+            endpoint: http://localhost:4318/v1/logs
 
 meter_provider:
   readers:
@@ -30,6 +30,7 @@ meter_provider:
           otlp:
             # expand the otlp-exporter anchor and add metric specific configuration
             <<: *otlp-exporter
+            endpoint: http://localhost:4318/v1/metrics
             temporality_preference: delta
             default_histogram_aggregation: base2_exponential_bucket_histogram
 
@@ -40,3 +41,4 @@ tracer_provider:
           otlp:
             # expand the otlp-exporter anchor
             <<: *otlp-exporter
+            endpoint: http://localhost:4318/v1/traces
diff --git a/examples/kitchen-sink.yaml b/examples/kitchen-sink.yaml
@@ -61,7 +61,7 @@ logger_provider:
             # Configure endpoint.
             #
             # Environment variable: OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_LOGS_ENDPOINT
-            endpoint: http://localhost:4318
+            endpoint: http://localhost:4318/v1/logs
             # Configure certificate.
             #
             # Environment variable: OTEL_EXPORTER_OTLP_CERTIFICATE, OTEL_EXPORTER_OTLP_LOGS_CERTIFICATE
@@ -169,7 +169,7 @@ meter_provider:
             # Configure endpoint.
             #
             # Environment variable: OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_METRICS_ENDPOINT
-            endpoint: http://localhost:4318
+            endpoint: http://localhost:4318/v1/metrics
             # Configure certificate.
             #
             # Environment variable: OTEL_EXPORTER_OTLP_CERTIFICATE, OTEL_EXPORTER_OTLP_METRICS_CERTIFICATE
@@ -293,7 +293,7 @@ tracer_provider:
             # Configure endpoint.
             #
             # Environment variable: OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_TRACES_ENDPOINT
-            endpoint: http://localhost:4318
+            endpoint: http://localhost:4318/v1/traces
             # Configure certificate.
             #
             # Environment variable: OTEL_EXPORTER_OTLP_CERTIFICATE, OTEL_EXPORTER_OTLP_TRACES_CERTIFICATE

diff --git a/examples/sdk-config.yaml b/examples/sdk-config.yaml
@@ -0,0 +1,179 @@
+# sdk-config.yaml is a typical starting point for configuring the SDK, including exporting to
+# localhost via OTLP.
+
+# NOTE: With the exception of env var substitution syntax (i.e. ${MY_ENV}), SDKs ignore
+# environment variables when interpreting config files. This including ignoring all env
+# vars defined in https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/.
+
+# The file format version
+file_format: "0.1"
+
+# Configure if the SDK is disabled or not.
+disabled: false
+
+# Configure resource for all signals.
+resource:
+  # Configure resource attributes.
+  attributes:
+    # Configure `service.name` resource attribute
+    service.name: unknown_service
+
+# Configure general attribute limits. See also tracer_provider.limits, logger_provider.limits.
+attribute_limits:
+  # Configure max attribute value size.
+  attribute_value_length_limit:
+  # Configure max attribute count.
+  attribute_count_limit: 128
+
+# Configure text map context propagators.
+propagator:
+  composite: [tracecontext, baggage]
+
+# Configure tracer provider.
+tracer_provider:
+  # Configure span processors.
+  processors:
+    # Configure a batch span processor.
+    - batch:
+        # Configure delay interval (in milliseconds) between two consecutive exports.
+        schedule_delay: 5000
+        # Configure maximum allowed time (in milliseconds) to export data.
+        export_timeout: 30000
+        # Configure maximum queue size.
+        max_queue_size: 2048
+        # Configure maximum batch size.
+        max_export_batch_size: 512
+        # Configure exporter.
+        exporter:
+          # Configure exporter to be OTLP.
+          otlp:
+            # Configure protocol.
+            protocol: http/protobuf
+            # Configure endpoint.
+            endpoint: http://localhost:4318/v1/traces
+            # Configure certificate.
+            certificate:
+            # Configure mTLS private client key.
+            client_key:
+            # Configure mTLS client certificate.
+            client_certificate:
+            # Configure compression.
+            compression: gzip
+            # Configure max time (in milliseconds) to wait for each export.
+            timeout: 10000
+            # Configure headers:
+            headers: {}
+  # Configure span limits. See also attribute_limits.
+  limits:
+    # Configure max span attribute value size. Overrides attribute_limits.attribute_value_length_limit.
+    attribute_value_length_limit:
+    # Configure max span attribute count. Overrides attribute_limits.attribute_count_limit.
+    attribute_count_limit: 128
+    # Configure max span event count.
+    event_count_limit: 128
+    # Configure max span link count.
+    link_count_limit: 128
+    # Configure max attributes per span event.
+    event_attribute_count_limit: 128
+    # Configure max attributes per span link.
+    link_attribute_count_limit: 128
+  # Configure the sampler.
+  sampler:
+    # Configure sampler to be parent_based. Known values include: always_off, always_on, jaeger_remote, parent_based, trace_id_ratio_based.
+    parent_based:
+      # Configure root sampler.
+      root:
+        # Configure sampler to be always_on.
+        always_on: {}
+      # Configure remote_parent_sampled sampler.
+      remote_parent_sampled:
+        # Configure sampler to be always_on.
+        always_on: {}
+      # Configure remote_parent_not_sampled sampler.
+      remote_parent_not_sampled:
+        # Configure sampler to be always_off.
+        always_off: {}
+      # Configure local_parent_sampled sampler.
+      local_parent_sampled:
+        # Configure sampler to be always_on.
+        always_on: {}
+      # Configure local_parent_not_sampled sampler.
+      local_parent_not_sampled:
+        # Configure sampler to be always_off.
+        always_off: {}
+
+# Configure meter provider.
+meter_provider:
+  # Configure metric readers.
+  readers:
+    # Configure a periodic metric reader.
+    - periodic:
+        # Configure delay interval (in milliseconds) between start of two consecutive exports.
+        interval: 60000
+        # Configure maximum allowed time (in milliseconds) to export data.
+        timeout: 30000
+        # Configure exporter.
+        exporter:
+          # Configure exporter to be OTLP.
+          otlp:
+            # Configure protocol.
+            protocol: http/protobuf
+            # Configure endpoint.
+            endpoint: http://localhost:4318/v1/metrics
+            # Configure certificate.
+            certificate:
+            # Configure mTLS private client key.
+            client_key:
+            # Configure mTLS client certificate.
+            client_certificate:
+            # Configure compression.
+            compression: gzip
+            # Configure max time (in milliseconds) to wait for each export.
+            timeout: 10000
+            # Configure headers:
+            headers: {}
+            # Configure temporality preference.
+            temporality_preference: cumulative
+            # Configure default histogram aggregation.
+            default_histogram_aggregation: explicit_bucket_histogram
+
+# Configure logger provider.
+logger_provider:
+  # Configure log record processors.
+  processors:
+    # Configure a batch log record processor.
+    - batch:
+        # Configure delay interval (in milliseconds) between two consecutive exports.
+        schedule_delay: 1000
+        # Configure maximum allowed time (in milliseconds) to export data.
+        export_timeout: 30000
+        # Configure maximum queue size.
+        max_queue_size: 2048
+        # Configure maximum batch size.
+        max_export_batch_size: 512
+        # Configure exporter.
+        exporter:
+          # Configure exporter to be OTLP.
+          otlp:
+            # Configure protocol.
+            protocol: http/protobuf
+            # Configure endpoint.
+            endpoint: http://localhost:4318/v1/logs
+            # Configure certificate.
+            certificate:
+            # Configure mTLS private client key.
+            client_key:
+            # Configure mTLS client certificate.
+            client_certificate:
+            # Configure compression.
+            compression: gzip
+            # Configure max time (in milliseconds) to wait for each export.
+            timeout: 10000
+            # Configure headers:
+            headers: {}
+  # Configure log record limits. See also attribute_limits.
+  limits:
+    # Configure max log record attribute value size. Overrides attribute_limits.attribute_value_length_limit.
+    attribute_value_length_limit:
+    # Configure max log record attribute count. Overrides attribute_limits.attribute_count_limit.
+    attribute_count_limit: 128