diff --git a/.github/workflows/build-check.yaml b/.github/workflows/build-check.yaml index 8af8478..1341719 100644 --- a/.github/workflows/build-check.yaml +++ b/.github/workflows/build-check.yaml @@ -21,3 +21,21 @@ jobs: - name: validate example run: make validate-examples + + - name: generate descriptions + run: make generate-descriptions + + - name: check for diff + run: | + # need to "git add" to detect any changes to descriptions which are not checked in + # select files from both /examples + git add examples** + if git diff --cached --quiet + then + echo "No diff detected." + else + echo "Diff detected - did you run 'make generate-descriptions'?" + echo $(git diff --cached --name-only) + echo $(git diff --cached) + exit 1 + fi diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 679627f..1cba3a1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -27,6 +27,67 @@ You can perform all checks locally using this command: make all ``` +## Description generation + +The [./examples](./examples) directory contains a variety of examples, which +include important comments describing the semantics of the configuration +properties. In order to keep these comments consistent across examples, we have +tooling which automatically generates comments for each property. + +How it works: + +* The [./schema/type_descriptions.yaml](./schema/type_descriptions.yaml) file + defines descriptions for each of the properties of each type defines in + the [JSON schema](./schema) data model. +* The [./scripts/generate-descriptions.js](./scripts/generate-comments.js) is a + script which for a given input configuration file will: + * Parse the YAML. + * Walk through each key / value pair, and for each: + * Compute the JSON dot notation location of the current key / value pair. + * Find the first matching rule + in [type_description.yaml](./schema/type_descriptions.yaml). Iterate + through the rules and evaluate the key / value pair dot notation location + against each of the rule's `path_patterns`. + * Inject / overwrite comments for its properties according + to `type_descriptions.yaml`. + * Write the resulting content to specified output file or to the console. + +The `make generate-descriptions` command runs this process against each file +in `./examples` and overwrites each file in the process. + +**NOTE:** The [build](./.github/workflows/build-check.yaml) will fail +if `make generate-descriptions` produces any changes which are not checked into +version control. + +To run against a single file: + +- Install the latest LTS release of **[Node](https://nodejs.org/)**. + For example, using **[nvm][]** under Linux run: + + ```bash + nvm install --lts + ``` + +- Install tooling packages: + + ```bash + npm install + ``` + +- Run the script: + +```shell +npm run-script generate-descriptions -- /absolute/path/to/input/file.yaml /absolute/path/to/output/file.yaml +``` + +Optionally, include the `--debug` parameter. This prints out information about +each key value pair, including the computed dot notation location, the matched +rule, the previous description, the new description, etc. + +```shell +npm run-script generate-comments -- /absolute/path/to/input/file.yaml /absolute/path/to/output/file.yaml --debug +``` + ## Pull requests A PR is ready to merge when: diff --git a/Makefile b/Makefile index 2f6c4a4..a21da1f 100644 --- a/Makefile +++ b/Makefile @@ -3,7 +3,7 @@ EXAMPLE_FILES := $(shell find . -path './examples/*.yaml' -exec basename {} \; | $(shell mkdir -p out) .PHONY: all -all: install-tools compile-schema validate-examples +all: install-tools compile-schema generate-descriptions validate-examples include validator/Makefile @@ -11,7 +11,7 @@ include validator/Makefile compile-schema: @if ! npm ls ajv-cli; then npm install; fi @for f in $(SCHEMA_FILES); do \ - npx --no ajv-cli compile --spec=draft2020 --allow-matching-properties -s ./schema/$$f -r "./schema/!($$f)" \ + npx --no ajv-cli compile --spec=draft2020 --allow-matching-properties -s ./schema/$$f -r "./schema/!($$f|*.yaml)" \ || exit 1; \ done @@ -20,10 +20,17 @@ validate-examples: @if ! npm ls ajv-cli; then npm install; fi @for f in $(EXAMPLE_FILES); do \ 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 \ + npx --no ajv-cli validate --spec=draft2020 --allow-matching-properties --errors=text -s ./schema/opentelemetry_configuration.json -r "./schema/!(opentelemetry_configuration.json|*.yaml)" -d ./out/$$f \ || exit 1; \ done +.PHONY: generate-descriptions +generate-descriptions: + @if ! npm ls minimatch yaml; then npm install; fi + @for f in $(EXAMPLE_FILES); do \ + npm run-script generate-descriptions -- $(shell pwd)/examples/$$f $(shell pwd)/examples/$$f || exit 1; \ + done + .PHONY: install-tools install-tools: npm install diff --git a/examples/anchors.yaml b/examples/anchors.yaml index d956f41..5dbde23 100644 --- a/examples/anchors.yaml +++ b/examples/anchors.yaml @@ -1,5 +1,6 @@ # anchors.yaml demonstrates anchor substitution to reuse OTLP exporter configuration across signals. +# The file format version. file_format: "0.1" exporters: otlp: &otlp-exporter @@ -13,33 +14,52 @@ exporters: compression: gzip timeout: 10000 +# Configure logger provider. logger_provider: + # Configure log record processors. processors: - - batch: + - # Configure a batch log record processor. + batch: + # Configure exporter. exporter: + # Configure exporter to be OTLP. otlp: - # expand the otlp-exporter anchor <<: *otlp-exporter + # Configure endpoint. endpoint: http://localhost:4318/v1/logs +# Configure meter provider. meter_provider: + # Configure metric readers. readers: - - periodic: + - # Configure a periodic metric reader. + periodic: + # Configure delay interval (in milliseconds) between start of two consecutive exports. interval: 5000 + # Configure maximum allowed time (in milliseconds) to export data. timeout: 30000 + # Configure exporter. exporter: + # Configure exporter to be OTLP. otlp: - # expand the otlp-exporter anchor and add metric specific configuration <<: *otlp-exporter + # Configure endpoint. endpoint: http://localhost:4318/v1/metrics + # Configure temporality preference. temporality_preference: delta + # Configure default histogram aggregation. default_histogram_aggregation: base2_exponential_bucket_histogram +# Configure tracer provider. tracer_provider: + # Configure span processors. processors: - - batch: + - # Configure a batch span processor. + batch: + # Configure exporter. exporter: + # Configure exporter to be OTLP. otlp: - # expand the otlp-exporter anchor <<: *otlp-exporter + # Configure endpoint. endpoint: http://localhost:4318/v1/traces diff --git a/examples/kitchen-sink.yaml b/examples/kitchen-sink.yaml index 4e418a5..dd5677d 100644 --- a/examples/kitchen-sink.yaml +++ b/examples/kitchen-sink.yaml @@ -5,133 +5,86 @@ # # Configuration values are set to their defaults when default values are defined. -# The file format version +# The file format version. file_format: "0.1" -# Configure if the SDK is disabled or not. This is not required to be provided -# to ensure the SDK isn't disabled, the default value when this is not provided -# is for the SDK to be enabled. -# -# Environment variable: OTEL_SDK_DISABLED +# Configure if the SDK is disabled or not. This is not required to be provided to ensure the SDK isn't disabled, the default value when this is not provided is for the SDK to be enabled. disabled: false # Configure general attribute limits. See also tracer_provider.limits, logger_provider.limits. attribute_limits: # Configure max attribute value size. - # - # Environment variable: OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT attribute_value_length_limit: 4096 # Configure max attribute count. - # - # Environment variable: OTEL_ATTRIBUTE_COUNT_LIMIT attribute_count_limit: 128 # Configure logger provider. logger_provider: # Configure log record processors. processors: - # Configure a batch log record processor. - - batch: + - # Configure a batch log record processor. + batch: # Configure delay interval (in milliseconds) between two consecutive exports. - # - # Environment variable: OTEL_BLRP_SCHEDULE_DELAY schedule_delay: 5000 # Configure maximum allowed time (in milliseconds) to export data. - # - # Environment variable: OTEL_BLRP_EXPORT_TIMEOUT export_timeout: 30000 # Configure maximum queue size. - # - # Environment variable: OTEL_BLRP_MAX_QUEUE_SIZE max_queue_size: 2048 # Configure maximum batch size. - # - # Environment variable: OTEL_BLRP_MAX_EXPORT_BATCH_SIZE max_export_batch_size: 512 # Configure exporter. - # - # Environment variable: OTEL_LOGS_EXPORTER exporter: # Configure exporter to be OTLP. otlp: # Configure protocol. - # - # Environment variable: OTEL_EXPORTER_OTLP_PROTOCOL, OTEL_EXPORTER_OTLP_LOGS_PROTOCOL protocol: http/protobuf # Configure endpoint. - # - # Environment variable: OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_LOGS_ENDPOINT endpoint: http://localhost:4318/v1/logs # Configure certificate. - # - # Environment variable: OTEL_EXPORTER_OTLP_CERTIFICATE, OTEL_EXPORTER_OTLP_LOGS_CERTIFICATE certificate: /app/cert.pem # Configure mTLS private client key. - # - # Environment variable: OTEL_EXPORTER_OTLP_CLIENT_KEY, OTEL_EXPORTER_OTLP_LOGS_CLIENT_KEY client_key: /app/cert.pem # Configure mTLS client certificate. - # - # Environment variable: OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE, OTEL_EXPORTER_OTLP_LOGS_CLIENT_CERTIFICATE client_certificate: /app/cert.pem - # Configure headers. - # - # Environment variable: OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_LOGS_HEADERS + # Configure headers. Entries have higher priority than entries from .headers_list. headers: - name: api-key value: "1234" # Configure headers. Entries have lower priority than entries from .headers. - # - # The value is a list of comma separated key-value pairs, matching the format of OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_LOGS_HEADERS. See https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md#general-sdk-configuration for details. + # The value is a list of comma separated key-value pairs matching the format of OTEL_EXPORTER_OTLP_HEADERS. See https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md#configuration-options for details. headers_list: "api-key=1234" # Configure compression. - # - # Environment variable: OTEL_EXPORTER_OTLP_COMPRESSION, OTEL_EXPORTER_OTLP_LOGS_COMPRESSION compression: gzip # Configure max time (in milliseconds) to wait for each export. - # - # Environment variable: OTEL_EXPORTER_OTLP_TIMEOUT, OTEL_EXPORTER_OTLP_LOGS_TIMEOUT timeout: 10000 # Configure client transport security for the exporter's connection. - # - # Environment variable: OTEL_EXPORTER_OTLP_INSECURE, OTEL_EXPORTER_OTLP_LOGS_INSECURE insecure: false - # Configure a simple span processor. - - simple: + - # Configure a simple log record processor. + simple: # Configure exporter. exporter: # Configure exporter to be console. console: {} # Configure log record limits. See also attribute_limits. limits: - # Configure max log record attribute value size. Overrides attribute_limits.attribute_value_length_limit. - # - # Environment variable: OTEL_LOGRECORD_ATTRIBUTE_VALUE_LENGTH_LIMIT + # Configure max attribute value size. Overrides .attribute_limits.attribute_value_length_limit. attribute_value_length_limit: 4096 - # Configure max log record attribute count. Overrides attribute_limits.attribute_count_limit. - # - # Environment variable: OTEL_LOGRECORD_ATTRIBUTE_COUNT_LIMIT + # Configure max attribute count. Overrides .attribute_limits.attribute_count_limit. attribute_count_limit: 128 # Configure meter provider. meter_provider: # Configure metric readers. readers: - # Configure a pull-based metric reader. - - pull: + - # Configure a pull based metric reader. + pull: # Configure exporter. - # - # Environment variable: OTEL_METRICS_EXPORTER exporter: # Configure exporter to be prometheus. prometheus: # Configure host. - # - # Environment variable: OTEL_EXPORTER_PROMETHEUS_HOST host: localhost # Configure port. - # - # Environment variable: OTEL_EXPORTER_PROMETHEUS_PORT port: 9464 # Configure Prometheus Exporter to produce metrics without a unit suffix or UNIT metadata. without_units: false @@ -141,96 +94,73 @@ meter_provider: without_scope_info: false # Configure Prometheus Exporter to add resource attributes as metrics attributes. with_resource_constant_labels: - # Configure resource attributes to be included, in this example attributes starting with service. + # Configure resource attributes to be included. If not set, no resource attributes are included. + # Attribute keys from resources are evaluated to match as follows: + # * If the value of the attribute key exactly matches. + # * If the value of the attribute key matches the wildcard pattern, where '?' matches any single character and '*' matches any number of characters including none. included: - "service*" - # Configure resource attributes to be excluded, in this example attribute service.attr1. Applies after .with_resource_constant_labels.included (i.e. excluded has higher priority than included). + # Configure resource attributes to be excluded. Applies after .with_resource_constant_labels.included (i.e. excluded has higher priority than included). + # Attribute keys from resources are evaluated to match as follows: + # * If the value of the attribute key exactly matches. + # * If the value of the attribute key matches the wildcard pattern, where '?' matches any single character and '*' matches any number of characters including none. excluded: - "service.attr1" # Configure metric producers. producers: - # Configure metric producer to be opencensus - - opencensus: {} - # Configure a periodic metric reader. - - periodic: + - # Configure metric producer to be opencensus. + opencensus: {} + - # Configure a periodic metric reader. + periodic: # Configure delay interval (in milliseconds) between start of two consecutive exports. - # - # Environment variable: OTEL_METRIC_EXPORT_INTERVAL interval: 5000 # Configure maximum allowed time (in milliseconds) to export data. - # - # Environment variable: OTEL_METRIC_EXPORT_TIMEOUT timeout: 30000 # Configure exporter. - # - # Environment variable: OTEL_METRICS_EXPORTER exporter: # Configure exporter to be OTLP. otlp: # Configure protocol. - # - # Environment variable: OTEL_EXPORTER_OTLP_PROTOCOL, OTEL_EXPORTER_OTLP_METRICS_PROTOCOL protocol: http/protobuf # Configure endpoint. - # - # Environment variable: OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_METRICS_ENDPOINT endpoint: http://localhost:4318/v1/metrics # Configure certificate. - # - # Environment variable: OTEL_EXPORTER_OTLP_CERTIFICATE, OTEL_EXPORTER_OTLP_METRICS_CERTIFICATE certificate: /app/cert.pem # Configure mTLS private client key. - # - # Environment variable: OTEL_EXPORTER_OTLP_CLIENT_KEY, OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEY client_key: /app/cert.pem # Configure mTLS client certificate. - # - # Environment variable: OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE, OTEL_EXPORTER_OTLP_METRICS_CLIENT_CERTIFICATE client_certificate: /app/cert.pem - # Configure headers. - # - # Environment variable: OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_METRICS_HEADERS + # Configure headers. Entries have higher priority than entries from .headers_list. headers: - name: api-key value: "1234" # Configure headers. Entries have lower priority than entries from .headers. - # - # The value is a list of comma separated key-value pairs, matching the format of OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_METRICS_HEADERS. See https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md#general-sdk-configuration for details. + # The value is a list of comma separated key-value pairs matching the format of OTEL_EXPORTER_OTLP_HEADERS. See https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md#configuration-options for details. headers_list: "api-key=1234" # Configure compression. - # - # Environment variable: OTEL_EXPORTER_OTLP_COMPRESSION, OTEL_EXPORTER_OTLP_METRICS_COMPRESSION compression: gzip # Configure max time (in milliseconds) to wait for each export. - # - # Environment variable: OTEL_EXPORTER_OTLP_TIMEOUT, OTEL_EXPORTER_OTLP_METRICS_TIMEOUT timeout: 10000 # Configure client transport security for the exporter's connection. - # - # Environment variable: OTEL_EXPORTER_OTLP_INSECURE, OTEL_EXPORTER_OTLP_METRICS_INSECURE insecure: false # Configure temporality preference. - # - # Environment variable: OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE temporality_preference: delta # Configure default histogram aggregation. - # - # Environment variable: OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION default_histogram_aggregation: base2_exponential_bucket_histogram # Configure metric producers. producers: - # Configure metric producer to be prometheus - - prometheus: {} - # Configure a periodic metric reader. - - periodic: + - # Configure metric producer to be prometheus. + prometheus: {} + - # Configure a periodic metric reader. + periodic: # Configure exporter. exporter: # Configure exporter to be console. console: {} # Configure views. Each view has a selector which determines the instrument(s) it applies to, and a configuration for the resulting stream(s). views: - # Configure a view. - - selector: + - # Configure view selector. + selector: # Configure instrument name selection criteria. instrument_name: my-instrument # Configure instrument type selection criteria. @@ -243,7 +173,7 @@ meter_provider: meter_version: 1.0.0 # Configure meter schema url selection criteria. meter_schema_url: https://opentelemetry.io/schemas/1.16.0 - # Configure stream. + # Configure view stream. stream: # Configure metric name of the resulting stream(s). name: new_instrument_name @@ -254,159 +184,121 @@ meter_provider: # Configure aggregation to be explicit_bucket_histogram. explicit_bucket_histogram: # Configure bucket boundaries. - boundaries: [ 0.0, 5.0, 10.0, 25.0, 50.0, 75.0, 100.0, 250.0, 500.0, 750.0, 1000.0, 2500.0, 5000.0, 7500.0, 10000.0 ] + boundaries: + [ + 0.0, + 5.0, + 10.0, + 25.0, + 50.0, + 75.0, + 100.0, + 250.0, + 500.0, + 750.0, + 1000.0, + 2500.0, + 5000.0, + 7500.0, + 10000.0 + ] # Configure record min and max. record_min_max: true # Configure attribute keys retained in the resulting stream(s). attribute_keys: - # Configure list of attribute keys that are retained in the resulting stream(s). - # All other attributes not matching will be dropped. + # Configure list of attribute keys to include in the resulting stream(s). All other attributes are dropped. If not set, stream attributes are not configured. included: - key1 - key2 - # Configure list of attribute keys that are excluded in the resulting stream(s), in this example attribute key3. Applies after .attribute_keys.included (i.e. excluded has higher priority than included). + # Configure list of attribute keys to exclude from the resulting stream(s). Applies after .attribute_keys.included (i.e. excluded has higher priority than included). excluded: - key3 # Configure text map context propagators. -# -# Environment variable: OTEL_PROPAGATORS propagator: - composite: [tracecontext, baggage, b3, b3multi, jaeger, xray, ottrace] + # Configure the set of propagators to include in the composite text map propagator. + composite: [ tracecontext, baggage, b3, b3multi, jaeger, xray, ottrace ] # Configure tracer provider. tracer_provider: # Configure span processors. processors: - # Configure a batch span processor. - - batch: + - # Configure a batch span processor. + batch: # Configure delay interval (in milliseconds) between two consecutive exports. - # - # Environment variable: OTEL_BSP_SCHEDULE_DELAY schedule_delay: 5000 # Configure maximum allowed time (in milliseconds) to export data. - # - # Environment variable: OTEL_BSP_EXPORT_TIMEOUT export_timeout: 30000 # Configure maximum queue size. - # - # Environment variable: OTEL_BSP_MAX_QUEUE_SIZE max_queue_size: 2048 # Configure maximum batch size. - # - # Environment variable: OTEL_BSP_MAX_EXPORT_BATCH_SIZE max_export_batch_size: 512 # Configure exporter. - # - # Environment variable: OTEL_TRACES_EXPORTER exporter: # Configure exporter to be OTLP. otlp: # Configure protocol. - # - # Environment variable: OTEL_EXPORTER_OTLP_PROTOCOL, OTEL_EXPORTER_OTLP_TRACES_PROTOCOL protocol: http/protobuf # Configure endpoint. - # - # Environment variable: OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_TRACES_ENDPOINT endpoint: http://localhost:4318/v1/traces # Configure certificate. - # - # Environment variable: OTEL_EXPORTER_OTLP_CERTIFICATE, OTEL_EXPORTER_OTLP_TRACES_CERTIFICATE certificate: /app/cert.pem # Configure mTLS private client key. - # - # Environment variable: OTEL_EXPORTER_OTLP_CLIENT_KEY, OTEL_EXPORTER_OTLP_TRACES_CLIENT_KEY client_key: /app/cert.pem # Configure mTLS client certificate. - # - # Environment variable: OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE, OTEL_EXPORTER_OTLP_TRACES_CLIENT_CERTIFICATE client_certificate: /app/cert.pem - # Configure headers. - # - # Environment variable: OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_TRACES_HEADERS + # Configure headers. Entries have higher priority than entries from .headers_list. headers: - name: api-key value: "1234" # Configure headers. Entries have lower priority than entries from .headers. - # - # The value is a list of comma separated key-value pairs, matching the format of OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_TRACES_HEADERS. See https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md#general-sdk-configuration for details. + # The value is a list of comma separated key-value pairs matching the format of OTEL_EXPORTER_OTLP_HEADERS. See https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md#configuration-options for details. headers_list: "api-key=1234" # Configure compression. - # - # Environment variable: OTEL_EXPORTER_OTLP_COMPRESSION, OTEL_EXPORTER_OTLP_TRACES_COMPRESSION compression: gzip # Configure max time (in milliseconds) to wait for each export. - # - # Environment variable: OTEL_EXPORTER_OTLP_TIMEOUT, OTEL_EXPORTER_OTLP_TRACES_TIMEOUT timeout: 10000 # Configure client transport security for the exporter's connection. - # - # Environment variable: OTEL_EXPORTER_OTLP_INSECURE, OTEL_EXPORTER_OTLP_TRACES_INSECURE insecure: false - # Configure a batch span processor. - - batch: + - # Configure a batch span processor. + batch: # Configure exporter. - # - # Environment variable: OTEL_TRACES_EXPORTER exporter: # Configure exporter to be zipkin. zipkin: # Configure endpoint. - # - # Environment variable: OTEL_EXPORTER_ZIPKIN_ENDPOINT endpoint: http://localhost:9411/api/v2/spans # Configure max time (in milliseconds) to wait for each export. - # - # Environment variable: OTEL_EXPORTER_ZIPKIN_TIMEOUT timeout: 10000 - # Configure a simple span processor. - - simple: + - # Configure a simple span processor. + simple: # Configure exporter. exporter: # Configure exporter to be console. console: {} # Configure span limits. See also attribute_limits. limits: - # Configure max span attribute value size. Overrides attribute_limits.attribute_value_length_limit. - # - # Environment variable: OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT + # Configure max attribute value size. Overrides .attribute_limits.attribute_value_length_limit. attribute_value_length_limit: 4096 - # Configure max span attribute count. Overrides attribute_limits.attribute_count_limit. - # - # Environment variable: OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT + # Configure max attribute count. Overrides .attribute_limits.attribute_count_limit. attribute_count_limit: 128 # Configure max span event count. - # - # Environment variable: OTEL_SPAN_EVENT_COUNT_LIMIT event_count_limit: 128 # Configure max span link count. - # - # Environment variable: OTEL_SPAN_LINK_COUNT_LIMIT link_count_limit: 128 # Configure max attributes per span event. - # - # Environment variable: OTEL_EVENT_ATTRIBUTE_COUNT_LIMIT event_attribute_count_limit: 128 # Configure max attributes per span link. - # - # Environment variable: OTEL_LINK_ATTRIBUTE_COUNT_LIMIT 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. - # - # Environment variable: OTEL_TRACES_SAMPLER=parentbased_* + # Configure sampler to be parent_based. parent_based: # Configure root sampler. - # - # Environment variable: OTEL_TRACES_SAMPLER=parentbased_traceidratio root: # Configure sampler to be trace_id_ratio_based. trace_id_ratio_based: # Configure trace_id_ratio. - # - # Environment variable: OTEL_TRACES_SAMPLER_ARG=traceidratio=0.0001 ratio: 0.0001 # Configure remote_parent_sampled sampler. remote_parent_sampled: @@ -428,17 +320,10 @@ tracer_provider: # Configure resource for all signals. resource: # Configure resource attributes. Entries have higher priority than entries from .resource.attributes_list. - # - # Each entry must contain .name and .value, and may optionally include .type, which defaults to "string" if not set. The value must match the type. Known types include: string, bool, int, double, string_array, bool_array, int_array, double_array. - # - # Environment variable: OTEL_RESOURCE_ATTRIBUTES + # Entries must contain .name nand .value, and may optionally include .type, which defaults ot "string" if not set. The value must match the type. Values for .type include: string, bool, int, double, string_array, bool_array, int_array, double_array. attributes: - # Configure `service.name` resource attribute - # - # Environment variable: OTEL_SERVICE_NAME - name: service.name value: unknown_service - # Configure other resource attributes with explicit types. - name: string_key value: value type: string @@ -452,7 +337,7 @@ resource: value: 1.1 type: double - name: string_array_key - value: ["value1", "value2"] + value: [ "value1", "value2" ] type: string_array - name: bool_array_key value: [ true, false ] @@ -464,44 +349,37 @@ resource: value: [ 1.1, 2.2 ] type: double_array # Configure resource attributes. Entries have lower priority than entries from .resource.attributes. - # - # The value is a list of comma separated key-value pairs, matching the format of OTEL_RESOURCE_ATTRIBUTES. See https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md#general-sdk-configuration for details. + # The value is a list of comma separated key-value pairs matching the format of OTEL_RESOURCE_ATTRIBUTES. See https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md#general-sdk-configuration for details. attributes_list: "service.namespace=my-namespace,service.version=1.0.0" # Configure resource detectors. detectors: # Configure attributes provided by resource detectors. attributes: # Configure list of attribute key patterns to include from resource detectors. If not set, all attributes are included. - # # Attribute keys from resource detectors are evaluated to match as follows: - # * If the value of the attribute key exactly matches. - # * If the value of the attribute key matches the wildcard pattern, where '?' matches any single character and '*' matches any number of characters including none. + # * If the value of the attribute key exactly matches. + # * If the value of the attribute key matches the wildcard pattern, where '?' matches any single character and '*' matches any number of characters including none. included: - process.* # Configure list of attribute key patterns to exclude from resource detectors. Applies after .resource.detectors.attributes.included (i.e. excluded has higher priority than included). - # # Attribute keys from resource detectors are evaluated to match as follows: - # * If the value of the attribute key exactly matches. - # * If the value of the attribute key matches the wildcard pattern, where '?' matches any single character and '*' matches any number of characters including none. + # * If the value of the attribute key exactly matches. + # * If the value of the attribute key matches the wildcard pattern, where '?' matches any single character and '*' matches any number of characters including none. excluded: - process.command_args - # Configure the resource schema URL. + # Configure resource schema URL. schema_url: https://opentelemetry.io/schemas/1.16.0 # Configure instrumentation. instrumentation: # Configure general SemConv options that may apply to multiple languages and instrumentations. - # # Instrumenation may merge general config options with the language specific configuration at .instrumentation.. general: # Configure instrumentations following the peer semantic conventions. - # # See peer semantic conventions: https://opentelemetry.io/docs/specs/semconv/attributes-registry/peer/ peer: # Configure the service mapping for instrumentations following peer.service semantic conventions. - # # Each entry is a key value pair where "peer" defines the IP address and "service" defines the corresponding logical name of the service. - # # See peer.service semantic conventions: https://opentelemetry.io/docs/specs/semconv/general/attributes/#general-remote-service-attributes service_mapping: - peer: 1.2.3.4 @@ -509,7 +387,6 @@ instrumentation: - peer: 2.3.4.5 service: BarService # Configure instrumentations following the http semantic conventions. - # # See http semantic conventions: https://opentelemetry.io/docs/specs/semconv/http/ http: # Configure instrumentations following the http client semantic conventions. @@ -532,10 +409,6 @@ instrumentation: response_captured_headers: - Content-Type - Content-Encoding - # Configure language-specific instrumentation libraries. - # - # Keys may refer to instrumentation libraries or collections of related configuration. Because there is no central schema defining the keys or their contents, instrumentation must carefully document their schema and avoid key collisions with other instrumentations. - # # Configure C++ language-specific instrumentation libraries. cpp: # Configure the instrumentation corresponding to key "example". diff --git a/examples/sdk-config.yaml b/examples/sdk-config.yaml index 8a61ec9..c46f869 100644 --- a/examples/sdk-config.yaml +++ b/examples/sdk-config.yaml @@ -5,17 +5,17 @@ # 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 +# The file format version. file_format: "0.1" -# Configure if the SDK is disabled or not. +# Configure if the SDK is disabled or not. This is not required to be provided to ensure the SDK isn't disabled, the default value when this is not provided is for the SDK to be enabled. disabled: false # Configure resource for all signals. resource: - # Configure resource attributes. + # Configure resource attributes. Entries have higher priority than entries from .resource.attributes_list. + # Entries must contain .name nand .value, and may optionally include .type, which defaults ot "string" if not set. The value must match the type. Values for .type include: string, bool, int, double, string_array, bool_array, int_array, double_array. attributes: - # Configure `service.name` resource attribute - name: service.name value: unknown_service @@ -28,14 +28,15 @@ attribute_limits: # Configure text map context propagators. propagator: - composite: [tracecontext, baggage] + # Configure the set of propagators to include in the composite text map propagator. + composite: [ tracecontext, baggage ] # Configure tracer provider. tracer_provider: # Configure span processors. processors: - # Configure a batch span processor. - - batch: + - # 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. @@ -62,13 +63,14 @@ tracer_provider: compression: gzip # Configure max time (in milliseconds) to wait for each export. timeout: 10000 - # Configure headers: + # Configure headers. Entries have higher priority than entries from .headers_list. 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. + # Configure max 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. + + # Configure max attribute count. Overrides .attribute_limits.attribute_count_limit. attribute_count_limit: 128 # Configure max span event count. event_count_limit: 128 @@ -80,7 +82,7 @@ tracer_provider: 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. + # Configure sampler to be parent_based. parent_based: # Configure root sampler. root: @@ -107,8 +109,8 @@ tracer_provider: meter_provider: # Configure metric readers. readers: - # Configure a periodic metric reader. - - periodic: + - # 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. @@ -131,7 +133,7 @@ meter_provider: compression: gzip # Configure max time (in milliseconds) to wait for each export. timeout: 10000 - # Configure headers: + # Configure headers. Entries have higher priority than entries from .headers_list. headers: [] # Configure temporality preference. temporality_preference: cumulative @@ -142,8 +144,8 @@ meter_provider: logger_provider: # Configure log record processors. processors: - # Configure a batch log record processor. - - batch: + - # 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. @@ -170,11 +172,12 @@ logger_provider: compression: gzip # Configure max time (in milliseconds) to wait for each export. timeout: 10000 - # Configure headers: + # Configure headers. Entries have higher priority than entries from .headers_list. 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. + # Configure max 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. + + # Configure max attribute count. Overrides .attribute_limits.attribute_count_limit. attribute_count_limit: 128 diff --git a/examples/sdk-migration-config.yaml b/examples/sdk-migration-config.yaml index abacca8..f657648 100644 --- a/examples/sdk-migration-config.yaml +++ b/examples/sdk-migration-config.yaml @@ -35,22 +35,21 @@ # - OTEL_EXPORTER_OTLP_COMPRESSION # - OTEL_EXPORTER_OTLP_TIMEOUT -# The file format version +# The file format version The file format version. file_format: "0.1" -# Configure if the SDK is disabled or not. +# Configure if the SDK is disabled or not. This is not required to be provided to ensure the SDK isn't disabled, the default value when this is not provided is for the SDK to be enabled. disabled: ${OTEL_SDK_DISABLED:-false} # Configure resource for all signals. resource: # Configure resource attributes. Entries have higher priority than entries from .resource.attributes_list. + # Entries must contain .name nand .value, and may optionally include .type, which defaults ot "string" if not set. The value must match the type. Values for .type include: string, bool, int, double, string_array, bool_array, int_array, double_array. attributes: - # Configure `service.name` resource attribute - name: service.name value: ${OTEL_SERVICE_NAME:-unknown_service} # Configure resource attributes. Entries have lower priority than entries from .resource.attributes. - # - # The value is a list of comma separated key-value pairs, matching the format of OTEL_RESOURCE_ATTRIBUTES. See https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md#general-sdk-configuration for details. + # The value is a list of comma separated key-value pairs matching the format of OTEL_RESOURCE_ATTRIBUTES. See https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md#general-sdk-configuration for details. attributes_list: ${OTEL_RESOURCE_ATTRIBUTES} # Configure general attribute limits. See also tracer_provider.limits, logger_provider.limits. @@ -62,14 +61,15 @@ attribute_limits: # Configure text map context propagators. propagator: - composite: [tracecontext, baggage] + # Configure the set of propagators to include in the composite text map propagator. + composite: [ tracecontext, baggage ] # Configure tracer provider. tracer_provider: # Configure span processors. processors: - # Configure a batch span processor. - - batch: + - # Configure a batch span processor. + batch: # Configure delay interval (in milliseconds) between two consecutive exports. schedule_delay: ${OTEL_BSP_SCHEDULE_DELAY:-5000} # Configure maximum allowed time (in milliseconds) to export data. @@ -96,17 +96,16 @@ tracer_provider: compression: ${OTEL_EXPORTER_OTLP_TRACES_COMPRESSION:-gzip} # Configure max time (in milliseconds) to wait for each export. timeout: ${OTEL_EXPORTER_OTLP_TRACES_TIMEOUT:-10000} - # Configure headers: + # Configure headers. Entries have higher priority than entries from .headers_list. headers: [] # Configure headers. Entries have lower priority than entries from .headers. - # - # The value is a list of comma separated key-value pairs, matching the format of OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_TRACES_HEADERS. See https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md#general-sdk-configuration for details. + # The value is a list of comma separated key-value pairs matching the format of OTEL_EXPORTER_OTLP_HEADERS. See https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md#configuration-options for details. headers_list: ${OTEL_EXPORTER_OTLP_TRACES_HEADERS} # Configure span limits. See also attribute_limits. limits: - # Configure max span attribute value size. Overrides attribute_limits.attribute_value_length_limit. + # Configure max attribute value size. Overrides .attribute_limits.attribute_value_length_limit. attribute_value_length_limit: ${OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT} - # Configure max span attribute count. Overrides attribute_limits.attribute_count_limit. + # Configure max attribute count. Overrides .attribute_limits.attribute_count_limit. attribute_count_limit: ${OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT:-128} # Configure max span event count. event_count_limit: ${OTEL_SPAN_EVENT_COUNT_LIMIT:-128} @@ -118,7 +117,7 @@ tracer_provider: link_attribute_count_limit: ${OTEL_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. + # Configure sampler to be parent_based. parent_based: # Configure root sampler. root: @@ -145,8 +144,8 @@ tracer_provider: meter_provider: # Configure metric readers. readers: - # Configure a periodic metric reader. - - periodic: + - # Configure a periodic metric reader. + periodic: # Configure delay interval (in milliseconds) between start of two consecutive exports. interval: ${OTEL_METRIC_EXPORT_INTERVAL:-60000} # Configure maximum allowed time (in milliseconds) to export data. @@ -169,11 +168,10 @@ meter_provider: compression: ${OTEL_EXPORTER_OTLP_METRICS_COMPRESSION:-gzip} # Configure max time (in milliseconds) to wait for each export. timeout: ${OTEL_EXPORTER_OTLP_METRICS_TIMEOUT:-10000} - # Configure headers. + # Configure headers. Entries have higher priority than entries from .headers_list. headers: [] # Configure headers. Entries have lower priority than entries from .headers. - # - # The value is a list of comma separated key-value pairs, matching the format of OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_METRICS_HEADERS. See https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md#general-sdk-configuration for details. + # The value is a list of comma separated key-value pairs matching the format of OTEL_EXPORTER_OTLP_HEADERS. See https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md#configuration-options for details. headers_list: ${OTEL_EXPORTER_OTLP_METRICS_HEADERS} # Configure temporality preference. temporality_preference: ${OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE:-cumulative} @@ -184,8 +182,8 @@ meter_provider: logger_provider: # Configure log record processors. processors: - # Configure a batch log record processor. - - batch: + - # Configure a batch log record processor. + batch: # Configure delay interval (in milliseconds) between two consecutive exports. schedule_delay: ${OTEL_BLRP_SCHEDULE_DELAY:-1000} # Configure maximum allowed time (in milliseconds) to export data. @@ -212,15 +210,14 @@ logger_provider: compression: ${OTEL_EXPORTER_OTLP_LOGS_COMPRESSION:-gzip} # Configure max time (in milliseconds) to wait for each export. timeout: ${OTEL_EXPORTER_OTLP_LOGS_TIMEOUT:-10000} - # Configure headers. + # Configure headers. Entries have higher priority than entries from .headers_list. headers: [] # Configure headers. Entries have lower priority than entries from .headers. - # - # The value is a list of comma separated key-value pairs, matching the format of OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_LOGS_HEADERS. See https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md#general-sdk-configuration for details. + # The value is a list of comma separated key-value pairs matching the format of OTEL_EXPORTER_OTLP_HEADERS. See https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md#configuration-options for details. headers_list: ${OTEL_EXPORTER_OTLP_LOGS_HEADERS} # Configure log record limits. See also attribute_limits. limits: - # Configure max log record attribute value size. Overrides attribute_limits.attribute_value_length_limit. + # Configure max attribute value size. Overrides .attribute_limits.attribute_value_length_limit. attribute_value_length_limit: ${OTEL_LOGRECORD_ATTRIBUTE_VALUE_LENGTH_LIMIT} - # Configure max log record attribute count. Overrides attribute_limits.attribute_count_limit. + # Configure max attribute count. Overrides .attribute_limits.attribute_count_limit. attribute_count_limit: ${OTEL_LOGRECORD_ATTRIBUTE_COUNT_LIMIT:-128} diff --git a/package.json b/package.json index 0122c0b..f215bc7 100644 --- a/package.json +++ b/package.json @@ -1,8 +1,12 @@ { + "scripts": { + "generate-descriptions": "node scripts/generate-descriptions.js" + }, "devDependencies": { "ajv-cli": "^5.0.0" }, "dependencies": { - "envsub": "^4.1.0" + "envsub": "^4.1.0", + "yaml": "^2.4.5" } } diff --git a/schema/type_descriptions.yaml b/schema/type_descriptions.yaml new file mode 100644 index 0000000..5abfefa --- /dev/null +++ b/schema/type_descriptions.yaml @@ -0,0 +1,420 @@ +# This file contains an array of objects defining the descriptions of properties for types defined in the schema. +# See "description generation" in CONTRIBUTING.md for more details. +# +# Example rule: +# - type: MyType # The type name corresponding to the JSON Schema Title. +# property_descriptions: # Mapping of the type's properties and their descriptions. +# propertyA: The propertyA description. # The description for MyType.propertyA. +# propertyB: The propertyB description. # The description for MyType.propertyB +# path_patterns: # Array of patterns where this type occurs in the schema. Each key-value in an example configuration file is transformed +# - .foo # into its JSON dot-notation location in the file, which is matched against these patterns. Each pattern is turned in a regex, + # after escaping special characters and replacing "*" with ".*". + +# START OpenTelemetryConfiguration +- type: OpenTelemetryConfiguration + property_descriptions: + file_format: The file format version. + disabled: Configure if the SDK is disabled or not. This is not required to be provided to ensure the SDK isn't disabled, the default value when this is not provided is for the SDK to be enabled. + resource: Configure resource for all signals. + propagator: Configure text map context propagators. + attribute_limits: Configure general attribute limits. See also tracer_provider.limits, logger_provider.limits. + logger_provider: Configure logger provider. + tracer_provider: Configure tracer provider. + meter_provider: Configure meter provider. + instrumentation: Configure instrumentation. + path_patterns: + - . + +- type: Resource + property_descriptions: + attributes: > + Configure resource attributes. Entries have higher priority than entries from .resource.attributes_list. + + Entries must contain .name nand .value, and may optionally include .type, which defaults ot "string" if not set. The value must match the type. Values for .type include: string, bool, int, double, string_array, bool_array, int_array, double_array. + attributes_list: > + Configure resource attributes. Entries have lower priority than entries from .resource.attributes. + + The value is a list of comma separated key-value pairs matching the format of OTEL_RESOURCE_ATTRIBUTES. See https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md#general-sdk-configuration for details. + detectors: Configure resource detectors. + schema_url: Configure resource schema URL. + path_patterns: + - .resource + +- type: Detectors + property_descriptions: + attributes: Configure attributes provided by resource detectors. + path_patterns: + - .resource.detectors + +- type: DetectorAttributes + property_descriptions: + included: > + Configure list of attribute key patterns to include from resource detectors. If not set, all attributes are included. + + Attribute keys from resource detectors are evaluated to match as follows: + * If the value of the attribute key exactly matches. + * If the value of the attribute key matches the wildcard pattern, where '?' matches any single character and '*' matches any number of characters including none. + excluded: > + Configure list of attribute key patterns to exclude from resource detectors. Applies after .resource.detectors.attributes.included (i.e. excluded has higher priority than included). + + Attribute keys from resource detectors are evaluated to match as follows: + * If the value of the attribute key exactly matches. + * If the value of the attribute key matches the wildcard pattern, where '?' matches any single character and '*' matches any number of characters including none. + path_patterns: + - .resource.detectors.attributes + +- type: AttributeLimits + property_descriptions: + attribute_value_length_limit: Configure max attribute value size. + attribute_count_limit: Configure max attribute count. + path_patterns: + - .attribute_limits + +- type: Propagator + property_descriptions: + composite: Configure the set of propagators to include in the composite text map propagator. + path_patterns: + - .propagator +# END OpenTelemetryConfiguration + +# START LoggerProvider +- type: LoggerProvider + property_descriptions: + processors: Configure log record processors. + limits: Configure log record limits. See also attribute_limits. + path_patterns: + - .logger_provider + +- type: LogRecordProcessor + property_descriptions: + batch: Configure a batch log record processor. + simple: Configure a simple log record processor. + path_patterns: + - .logger_provider.processors[] + +- type: BatchLogRecordProcessor + property_descriptions: + schedule_delay: Configure delay interval (in milliseconds) between two consecutive exports. + export_timeout: Configure maximum allowed time (in milliseconds) to export data. + max_queue_size: Configure maximum queue size. + max_export_batch_size: Configure maximum batch size. + exporter: Configure exporter. + path_patterns: + - .logger_provider.processors[].batch + +- type: SimpleLogRecordProcessor + property_descriptions: + exporter: Configure exporter. + path_patterns: + - .logger_provider.processors[].simple + +- type: LogRecordExporter + property_descriptions: + otlp: Configure exporter to be OTLP. + console: Configure exporter to be console. + path_patterns: + - .logger_provider.processors[].*.exporter + +- type: LogRecordLimits + property_descriptions: + attribute_value_length_limit: Configure max attribute value size. Overrides .attribute_limits.attribute_value_length_limit. + attribute_count_limit: Configure max attribute count. Overrides .attribute_limits.attribute_count_limit. + path_patterns: + - .logger_provider.limits +# END LoggerProvider + +# START TracerProvider +- type: TracerProvider + property_descriptions: + processors: Configure span processors. + limits: Configure span limits. See also attribute_limits. + sampler: Configure the sampler. + path_patterns: + - .tracer_provider + +- type: SpanProcessor + property_descriptions: + batch: Configure a batch span processor. + simple: Configure a simple span processor. + path_patterns: + - .tracer_provider.processors[] + +- type: BatchSpanProcessor + property_descriptions: + schedule_delay: Configure delay interval (in milliseconds) between two consecutive exports. + export_timeout: Configure maximum allowed time (in milliseconds) to export data. + max_queue_size: Configure maximum queue size. + max_export_batch_size: Configure maximum batch size. + exporter: Configure exporter. + path_patterns: + - .tracer_provider.processors[].batch + +- type: SimpleSpanProcessor + property_descriptions: + exporter: Configure exporter. + path_patterns: + - .tracer_provider.processors[].simple + +- type: SpanExporter + property_descriptions: + otlp: Configure exporter to be OTLP. + zipkin: Configure exporter to be zipkin. + console: Configure exporter to be console. + path_patterns: + - .tracer_provider.processors[].*.exporter + +- type: Zipkin + property_descriptions: + endpoint: Configure endpoint. + timeout: Configure max time (in milliseconds) to wait for each export. + path_patterns: + - .tracer_provider.processors[].*.exporter.zipkin + +- type: SpanLimits + property_descriptions: + attribute_value_length_limit: Configure max attribute value size. Overrides .attribute_limits.attribute_value_length_limit. + attribute_count_limit: Configure max attribute count. Overrides .attribute_limits.attribute_count_limit. + event_count_limit: Configure max span event count. + link_count_limit: Configure max span link count. + event_attribute_count_limit: Configure max attributes per span event. + link_attribute_count_limit: Configure max attributes per span link. + path_patterns: + - .tracer_provider.limits + +- type: Sampler + property_descriptions: + parent_based: Configure sampler to be parent_based. + trace_id_ratio_based: Configure sampler to be trace_id_ratio_based. + always_on: Configure sampler to be always_on. + always_off: Configure sampler to be always_off. + root: Configure root sampler. + remote_parent_sampled: Configure remote_parent_sampled sampler. + remote_parent_not_sampled: Configure remote_parent_not_sampled sampler. + local_parent_sampled: Configure local_parent_sampled sampler. + local_parent_not_sampled: Configure local_parent_not_sampled sampler. + ratio: Configure trace_id_ratio. + path_patterns: + - .tracer_provider.sampler + - .tracer_provider.sampler.* +# END TracerProvider + +# START MeterProvider +- type: MeterProvider + property_descriptions: + readers: Configure metric readers. + views: Configure views. Each view has a selector which determines the instrument(s) it applies to, and a configuration for the resulting stream(s). + path_patterns: + - .meter_provider + +- type: MetricReader + property_descriptions: + pull: Configure a pull based metric reader. + periodic: Configure a periodic metric reader. + producers: Configure metric producers. + path_patterns: + - .meter_provider.readers[] + +- type: PullMetricReader + property_descriptions: + exporter: Configure exporter. + path_patterns: + - .meter_provider.readers[].pull + +- type: PeriodicMetricReader + property_descriptions: + interval: Configure delay interval (in milliseconds) between start of two consecutive exports. + timeout: Configure maximum allowed time (in milliseconds) to export data. + exporter: Configure exporter. + path_patterns: + - .meter_provider.readers[].periodic + +- type: MetricProducer + property_descriptions: + opencensus: Configure metric producer to be opencensus. + prometheus: Configure metric producer to be prometheus. + path_patterns: + - .meter_provider.readers[].producers[] + +- type: MetricExporter + property_descriptions: + prometheus: Configure exporter to be prometheus. + otlp: Configure exporter to be OTLP. + console: Configure exporter to be console. + path_patterns: + - .meter_provider.readers[].*.exporter + +- type: Prometheus + property_descriptions: + host: Configure host. + port: Configure port. + without_units: Configure Prometheus Exporter to produce metrics without a unit suffix or UNIT metadata. + without_type_suffix: Configure Prometheus Exporter to produce metrics without a type suffix. + without_scope_info: Configure Prometheus Exporter to produce metrics without a scope info metric. + with_resource_constant_labels: Configure Prometheus Exporter to add resource attributes as metrics attributes. + path_patterns: + - .meter_provider.readers[].pull.exporter.prometheus +- type: PrometheusIncludeExclude + property_descriptions: + included: > + Configure resource attributes to be included. If not set, no resource attributes are included. + + Attribute keys from resources are evaluated to match as follows: + * If the value of the attribute key exactly matches. + * If the value of the attribute key matches the wildcard pattern, where '?' matches any single character and '*' matches any number of characters including none. + excluded: > + Configure resource attributes to be excluded. Applies after .with_resource_constant_labels.included (i.e. excluded has higher priority than included). + + Attribute keys from resources are evaluated to match as follows: + * If the value of the attribute key exactly matches. + * If the value of the attribute key matches the wildcard pattern, where '?' matches any single character and '*' matches any number of characters including none. + path_patterns: + - .meter_provider.readers[].pull.exporter.prometheus.with_resource_constant_labels + +- type: View + property_descriptions: + selector: Configure view selector. + stream: Configure view stream. + path_patterns: + - .meter_provider.views[] + +- type: Selector + property_descriptions: + instrument_name: Configure instrument name selection criteria. + instrument_type: Configure instrument type selection criteria. + unit: Configure the instrument unit selection criteria. + meter_name: Configure meter name selection criteria. + meter_version: Configure meter version selection criteria. + meter_schema_url: Configure meter schema url selection criteria. + path_patterns: + - .meter_provider.views[].selector + +- type: Stream + property_descriptions: + name: Configure metric name of the resulting stream(s). + description: Configure metric description of the resulting stream(s). + aggregation: > + Configure aggregation of the resulting stream(s). Known values include: default, drop, explicit_bucket_histogram, base2_exponential_bucket_histogram, last_value, sum. + attribute_keys: Configure attribute keys retained in the resulting stream(s). + path_patterns: + - .meter_provider.views[].stream + +- type: StreamIncludeExclude + property_descriptions: + included: > + Configure list of attribute keys to include in the resulting stream(s). All other attributes are dropped. If not set, stream attributes are not configured. + excluded: > + Configure list of attribute keys to exclude from the resulting stream(s). Applies after .attribute_keys.included (i.e. excluded has higher priority than included). + path_patterns: + - .meter_provider.views[].stream.attribute_keys + +- type: StreamAggregation + property_descriptions: + explicit_bucket_histogram: Configure aggregation to be explicit_bucket_histogram. + path_patterns: + - .meter_provider.views[].stream.aggregation + +- type: StreamAggregationExplicitBucketHistogram + property_descriptions: + boundaries: Configure bucket boundaries. + record_min_max: Configure record min and max. + path_patterns: + - .meter_provider.views[].stream.aggregation.explicit_bucket_histogram +# END meter_provider + +# START common +- type: Otlp + property_descriptions: + protocol: Configure protocol. + endpoint: Configure endpoint. + certificate: Configure certificate. + client_key: Configure mTLS private client key. + client_certificate: Configure mTLS client certificate. + headers: Configure headers. Entries have higher priority than entries from .headers_list. + headers_list: > + Configure headers. Entries have lower priority than entries from .headers. + + The value is a list of comma separated key-value pairs matching the format of OTEL_EXPORTER_OTLP_HEADERS. See https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md#configuration-options for details. + compression: Configure compression. + timeout: Configure max time (in milliseconds) to wait for each export. + insecure: Configure client transport security for the exporter's connection. + temporality_preference: Configure temporality preference. + default_histogram_aggregation: Configure default histogram aggregation. + path_patterns: + - .tracer_provider.processors[].*.exporter.otlp + - .logger_provider.processors[].*.exporter.otlp + - .meter_provider.readers[].periodic.exporter.otlp +# END common + +# START Instrumentation +- type: Instrumentation + property_descriptions: + general: > + Configure general SemConv options that may apply to multiple languages and instrumentations. + + Instrumenation may merge general config options with the language specific configuration at .instrumentation.. + cpp: Configure C++ language-specific instrumentation libraries. + dotnet: Configure .NET language-specific instrumentation libraries. + erlang: Configure Erlang language-specific instrumentation libraries. + go: Configure Go language-specific instrumentation libraries. + java: Configure Java language-specific instrumentation libraries. + js: Configure JavaScript language-specific instrumentation libraries. + php: Configure PHP language-specific instrumentation libraries. + python: Configure Python language-specific instrumentation libraries. + ruby: Configure Ruby language-specific instrumentation libraries. + rust: Configure Rust language-specific instrumentation libraries. + swift: Configure Swift language-specific instrumentation libraries. + path_patterns: + - .instrumentation + +- type: GeneralInstrumentation + property_descriptions: + peer: > + Configure instrumentations following the peer semantic conventions. + + See peer semantic conventions: https://opentelemetry.io/docs/specs/semconv/attributes-registry/peer/ + http: > + Configure instrumentations following the http semantic conventions. + + See http semantic conventions: https://opentelemetry.io/docs/specs/semconv/http/ + path_patterns: + - .instrumentation.general + +- type: GeneralInstrumentationPeer + property_descriptions: + service_mapping: > + Configure the service mapping for instrumentations following peer.service semantic conventions. + + Each entry is a key value pair where "peer" defines the IP address and "service" defines the corresponding logical name of the service. + + See peer.service semantic conventions: https://opentelemetry.io/docs/specs/semconv/general/attributes/#general-remote-service-attributes + path_patterns: + - .instrumentation.general.peer + +- type: GeneralInstrumentationHttp + property_descriptions: + client: Configure instrumentations following the http client semantic conventions. + server: Configure instrumentations following the http server semantic conventions. + path_patterns: + - .instrumentation.general.http + +- type: GeneralInstrumentationHttpClient + property_descriptions: + request_captured_headers: Configure headers to capture for outbound http requests. + response_captured_headers: Configure headers to capture for outbound http responses. + path_patterns: + - .instrumentation.general.http.client + +- type: GeneralInstrumentationHttpServer + property_descriptions: + request_captured_headers: Configure headers to capture for inbound http requests. + response_captured_headers: Configure headers to capture for outbound http responses. + path_patterns: + - .instrumentation.general.http.server + +- type: LanguageSpecificInstrumentation + property_descriptions: + example: Configure the instrumentation corresponding to key "example". + path_patterns: + - .instrumentation.* +# END Instrumentation + diff --git a/scripts/generate-descriptions.js b/scripts/generate-descriptions.js new file mode 100644 index 0000000..f3623a1 --- /dev/null +++ b/scripts/generate-descriptions.js @@ -0,0 +1,171 @@ +const fs = require('node:fs'); +const yaml = require('yaml'); + +// Extract input file arg or throw +const usageString = "Usage: \n npm run-script generate-comments -- /absolute/path/to/input/file.yaml /absolute/path/to/output/file.yaml"; +if (process.argv.length < 3) { + throw new Error("Missing file to generate comments for. " + usageString); +} +const inputFile = process.argv[2]; +if (!fs.existsSync(inputFile)) { + throw new Error("File \"" + inputFile + "\" not found."); +} + +// Extract output file arg +let outputFile = null; +if (process.argv.length >= 4 && process.argv[3].startsWith("/")) { + outputFile = process.argv[3]; +} + +// Extract options +const options = { + debug: false +} +for (let i = 3; i < process.argv.length; i++) { + if (process.argv[i] === '--debug') { + options['debug'] = true; + } +} + +// Read and validate description rules +const typeDescriptionsContent = fs.readFileSync(__dirname + "/../schema/type_descriptions.yaml", "utf-8"); +const typeDescriptionsYaml = yaml.parse(typeDescriptionsContent); +const rulesByType = {}; +typeDescriptionsYaml.forEach(rule => { + const type = rule.type; + if (!(typeof type === 'string') && !(type instanceof String)) { + throw new Error("rule must have type: " + JSON.stringify(rule)); + } + if (type in rulesByType) { + throw new Error("multiple rules with type: " + type); + } + rulesByType[type] = rule; + if (!('property_descriptions' in rule)) { + throw new Error("rule missing property_description:" + JSON.stringify(rule)); + } + if (!('path_patterns' in rule)) { + throw new Error("rule missing path_patterns:" + JSON.stringify(rule)); + } + debug("\nRule for type: " + type); + debug(" property_descriptions:") + Object.entries(rule.property_descriptions) + .forEach(([property, description]) => debug(" " + property + ": " + description)); + debug(" path_patterns: \n" + rule.path_patterns.map(entry => " - " + toRegex(entry)).join("\n")); +}) + +// Read in the input file +const fileContent = fs.readFileSync(inputFile, "utf-8"); +const fileDoc = yaml.parseDocument(fileContent); +let counter = 0; +let lastNode = null; +// Visit each key/value pair in the input file YAML, attempting to match against description rules +// and setting a comment with the description from the matching rule +yaml.visit(fileDoc, { + Pair: (key, node, path) => { + if (yaml.isSeq(node.value)) { + node.value.items.forEach(item => item.commentBefore = null); + } + let prevLastNode = lastNode; + lastNode = node; + counter++; + // Compute the parenPath, a string representation of the location of this key/value pair in the document + // For example, the following sample YAML is annotated with the parentPath at each node + // parent: # . + // child: value # .parent + // child_arr: # .parent + // - arr_key: value # .parent.child_arr[] + const parentPath = pathToString(path); + const propertyKey = node.key.value; + debug(""); + debug("parentPath: " + parentPath ); + debug("propertyKey: " + propertyKey); + debug("currentNodePath: " + parentPath + (parentPath === "." ? "" : ".") + propertyKey); + // Iterate through the rules and find the first with a matching entry in rule.path_patterns + const matchingRule = typeDescriptionsYaml.find((rule) => { + const matchingPathPattern = rule['path_patterns'].find((pathPattern) => { + const regex = new RegExp(toRegex(pathPattern)); + return regex.test(parentPath); + }); + return matchingPathPattern !== undefined; + }); + // Exit early if no matching rule + if (matchingRule === undefined) { + debug("no matching rule") + return; + } + debug("matched rule: " + matchingRule.type); + // Check if there is a description for the current propertyKey in the matching rule + // Exit early if none registered + const description = matchingRule['property_descriptions'][propertyKey]; + if (description === undefined) { + debug("no matching property") + return; + } + // Format the description + let formattedDescription = description.replace(/\n$/, '').split('\n').map(line => ' ' + line).join('\n'); + // If we're on the first element, prefix the formatted description with the existing commentBefore to retain the comments at the top of the file + if (counter === 1 && node.key.commentBefore) { + const index = node.key.commentBefore.lastIndexOf(formattedDescription); + formattedDescription = (index === -1) + ? node.key.commentBefore + formattedDescription + : node.key.commentBefore.substring(0, index) + formattedDescription; + } + debug("description previously set to:\n" + node.key.commentBefore); + debug("updating description to:\n" + formattedDescription) + // Set the description + node.key.commentBefore = formattedDescription; + node.value.commentBefore = null; + // yaml parser sometimes misidentifies a pair's commentBefore as the previously processed pair.value.comment + // we detect and fix that by keeping a reference to the previous node and looking for this case + if (prevLastNode !== null && prevLastNode.value.comment === formattedDescription) { + node.key.spaceBefore = null; + prevLastNode.value.comment = null; + } + } +}); + +// Print the output, or write it to a file +if (outputFile === null) { + console.log("No output file arg set, logging to console."); + console.log(String(fileDoc)) +} else { + console.log("Writing output to \"" + outputFile + "\""); + fs.writeFileSync(outputFile, String(fileDoc)) +} + +// Helper functions + +// Converts an input pattern to a regular expression. +// Converts any "*" to a ".*". +// Escapes all other regex special characters. +// Prefixes with "^", and adds "$" suffix. +function toRegex(pattern) { + let parts = pattern.split("*"); + if (parts.length === 0) parts = [pattern]; + const escaped = parts + .map(chunk => chunk.replace(/[-[\]{}()*+?.,\\^$|]/g, "\\$&")) + .join("(.*)"); + return "^" + escaped + "$"; +} + +// Log the message to the console if the script was run with `--debug` argument +function debug(message) { + if (options.debug) { + console.debug(message); + } +} + +// Convert an array of path elements JSON dot notation +function pathToString(path) { + const elements = [] + path.slice().forEach(entry => { + if (yaml.isSeq(entry)) { + elements.push("[]"); + } + if (yaml.isPair(entry)) { + elements.push("."); + elements.push(entry.key.value); + } + }); + return elements.length === 0 ? "." : elements.join(""); +} diff --git a/validator/Makefile b/validator/Makefile index 23f8ec9..d09d79d 100644 --- a/validator/Makefile +++ b/validator/Makefile @@ -1,6 +1,5 @@ ROOT_DIR :=$(realpath $(shell dirname $(lastword $(MAKEFILE_LIST)))) PARENT_DIR :=$(realpath ${ROOT_DIR}/../) -SCHEMA_DIR :=${ROOT_DIR}/../schema CURRENT_GIT_REF :=$(shell git rev-parse --short HEAD) DOCKER_IMAGE_TAG :=${CURRENT_GIT_REF} DOCKER_BUILD_ARGS :=-f ${ROOT_DIR}/Dockerfile -t otel_config_validator:${DOCKER_IMAGE_TAG} -t otel_config_validator:current @@ -9,7 +8,8 @@ EXAMPLE_FILES := $(shell find ${ROOT_DIR}/../examples -name "*.yaml" -exec basen $(shell mkdir -p out) validator-copy-schema: - cp -R ${SCHEMA_DIR} ${ROOT_DIR}/ + mkdir -p ${ROOT_DIR}/schema + find ${PARENT_DIR} -path '*/schema/*.json' ! -path '*/validator/schema/*.json' -exec cp '{}' "${ROOT_DIR}/schema/" ';' validator: validator-copy-schema go build -C ${ROOT_DIR} ${ROOT_DIR}