Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Prefer arrays of name value pairs over objects #115

Merged
merged 7 commits into from
Sep 19, 2024
Merged
Changes from 4 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 21 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
@@ -15,8 +15,6 @@ The [examples](./examples) repository contains a variety of sample configuration
- [sdk-migration-config.yaml](./examples/sdk-migration-config.yaml): Includes env var substitution references to all [standard env vars](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:
@@ -70,6 +68,24 @@ Properties should be modeled using the most appropriate data structures and type

In instances where there is a type mismatch between the JSON schema and equivalent standard env var, an alternative version of the property may be provided to resolve the mismatch. For example, resource attributes are configured at `.resource.attributes`, but `.resource.attributes_list` is available with a format matching that of `OTEL_RESOURCE_ATTRIBUTES`. Alternative properties are reserved for cases where there is a demonstrated need for platforms to be able to participate in configuration and there is no reasonable alternative.

### Name-value pairs

When a type requires a configurable list of name-value pairs (i.e. resource attributes, HTTP headers), model using an array of objects, each with `name` and `value` properties. While an arrays of name-value objects is slightly more verbose an object where each key-value is an entry, it is preferred because:
jack-berg marked this conversation as resolved.
Show resolved Hide resolved

* Avoids user input as keys, which ensures conformity with the [snake_case properties](#property-name-case) rule.
* Allows both the names and the values to be targets for [env var substitution]. For example:

```yaml
tracer_provider:
processors:
- batch:
exporter:
otlp:
headers:
- name: ${AUTHORIZATION_HEADER_NAME:-api-key}
value: ${AUTHORIZATION_HEADER_VALUE}
```
marcalff marked this conversation as resolved.
Show resolved Hide resolved

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md)
@@ -89,3 +105,6 @@ Maintainers ([@open-telemetry/configuration-maintainers](https://github.com/orgs
- [Tyler Yahn](https://github.com/tsloughter), Splunk

*Find more about the maintainer role in [community repository](https://github.com/open-telemetry/community/blob/main/guides/contributor/membership.md#maintainer).*

[env var substitution]: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/file-configuration.md#environment-variable-substitution

3 changes: 2 additions & 1 deletion examples/anchors.yaml
Original file line number Diff line number Diff line change
@@ -8,7 +8,8 @@ exporters:
client_key: /app/cert.pem
client_certificate: /app/cert.pem
headers:
api-key: !!str 1234
- name: api-key
value: "1234"
compression: gzip
timeout: 10000

39 changes: 35 additions & 4 deletions examples/kitchen-sink.yaml
Original file line number Diff line number Diff line change
@@ -78,7 +78,8 @@ logger_provider:
#
# Environment variable: OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_LOGS_HEADERS
headers:
api-key: "1234"
- name: api-key
value: "1234"
# Configure compression.
#
# Environment variable: OTEL_EXPORTER_OTLP_COMPRESSION, OTEL_EXPORTER_OTLP_LOGS_COMPRESSION
@@ -186,7 +187,8 @@ meter_provider:
#
# Environment variable: OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_METRICS_HEADERS
headers:
api-key: !!str 1234
- name: api-key
value: "1234"
# Configure compression.
#
# Environment variable: OTEL_EXPORTER_OTLP_COMPRESSION, OTEL_EXPORTER_OTLP_METRICS_COMPRESSION
@@ -313,7 +315,8 @@ tracer_provider:
#
# Environment variable: OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_TRACES_HEADERS
headers:
api-key: !!str 1234
- name: api-key
value: "1234"
# Configure compression.
#
# Environment variable: OTEL_EXPORTER_OTLP_COMPRESSION, OTEL_EXPORTER_OTLP_TRACES_COMPRESSION
@@ -411,12 +414,40 @@ tracer_provider:
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
attributes:
# Configure `service.name` resource attribute
#
# Environment variable: OTEL_SERVICE_NAME
service.name: !!str "unknown_service"
- name: service-name
jack-berg marked this conversation as resolved.
Show resolved Hide resolved
value: unknown_service
# Configure other resource attributes with explicit types.
- name: string_key
value: value
type: string
- name: bool_key
value: true
type: bool
- name: int_key
value: 1
type: int
- name: double_key
value: 1.1
type: double
- name: string_array_key
value: ["value1", "value2"]
type: string_array
- name: bool_array_key
value: [ true, false ]
type: bool_array
- name: int_array_key
value: [ 1, 2 ]
type: int_array
- name: double_array_key
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.
9 changes: 5 additions & 4 deletions examples/sdk-config.yaml
Original file line number Diff line number Diff line change
@@ -16,7 +16,8 @@ resource:
# Configure resource attributes.
attributes:
# Configure `service.name` resource attribute
service.name: unknown_service
- name: service.name
value: unknown_service

# Configure general attribute limits. See also tracer_provider.limits, logger_provider.limits.
attribute_limits:
@@ -62,7 +63,7 @@ tracer_provider:
# Configure max time (in milliseconds) to wait for each export.
timeout: 10000
# Configure headers:
headers: {}
headers: []
# Configure span limits. See also attribute_limits.
limits:
# Configure max span attribute value size. Overrides attribute_limits.attribute_value_length_limit.
@@ -131,7 +132,7 @@ meter_provider:
# Configure max time (in milliseconds) to wait for each export.
timeout: 10000
# Configure headers:
headers: {}
headers: []
# Configure temporality preference.
temporality_preference: cumulative
# Configure default histogram aggregation.
@@ -170,7 +171,7 @@ logger_provider:
# Configure max time (in milliseconds) to wait for each export.
timeout: 10000
# Configure headers:
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.
9 changes: 5 additions & 4 deletions examples/sdk-migration-config.yaml
Original file line number Diff line number Diff line change
@@ -47,7 +47,8 @@ resource:
# Configure resource attributes. Entries have higher priority than entries from .resource.attributes_list.
attributes:
# Configure `service.name` resource attribute
service.name: ${OTEL_SERVICE_NAME:-unknown_service}
- 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.
@@ -97,7 +98,7 @@ tracer_provider:
# Configure max time (in milliseconds) to wait for each export.
timeout: ${OTEL_EXPORTER_OTLP_TRACES_TIMEOUT:-10000}
# Configure headers:
headers: {}
headers: []
# Configure span limits. See also attribute_limits.
limits:
# Configure max span attribute value size. Overrides attribute_limits.attribute_value_length_limit.
@@ -166,7 +167,7 @@ meter_provider:
# Configure max time (in milliseconds) to wait for each export.
timeout: ${OTEL_EXPORTER_OTLP_METRICS_TIMEOUT:-10000}
# Configure headers:
headers: {}
headers: []
# Configure temporality preference.
temporality_preference: ${OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE:-cumulative}
# Configure default histogram aggregation.
@@ -205,7 +206,7 @@ logger_provider:
# Configure max time (in milliseconds) to wait for each export.
timeout: ${OTEL_EXPORTER_OTLP_LOGS_TIMEOUT:-10000}
# Configure headers:
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.
29 changes: 19 additions & 10 deletions schema/common.json
Original file line number Diff line number Diff line change
@@ -4,15 +4,6 @@
"title": "Common",
"type": ["object", "null"],
"$defs": {
"Headers": {
"type": ["object", "null"],
"title": "Headers",
"patternProperties": {
".*": {
"type": ["string", "null"]
}
}
},
"IncludeExclude": {
"type": "object",
"additionalProperties": false,
@@ -43,6 +34,21 @@
}
}
},
"NameStringValuePair": {
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"type": "string"
},
"value": {
"type": ["string", "null"]
}
},
"required": [
"name", "value"
]
},
"Otlp": {
"type": ["object", "null"],
"additionalProperties": false,
@@ -64,7 +70,10 @@
"type": ["string", "null"]
},
"headers": {
"$ref": "#/$defs/Headers"
"type": "array",
"items": {
"$ref": "common.json#/$defs/NameStringValuePair"
}
},
"compression": {
"type": ["string", "null"]
5 changes: 4 additions & 1 deletion schema/meter_provider.json
Original file line number Diff line number Diff line change
@@ -170,7 +170,10 @@
"type": ["string", "null"]
},
"headers": {
"$ref": "common.json#/$defs/Headers"
"type": "array",
"items": {
"$ref": "common.json#/$defs/NameStringValuePair"
}
},
"compression": {
"type": ["string", "null"]
45 changes: 40 additions & 5 deletions schema/resource.json
Original file line number Diff line number Diff line change
@@ -6,7 +6,10 @@
"additionalProperties": false,
"properties": {
"attributes": {
"$ref": "#/$defs/Attributes"
"type": "array",
"items": {
"$ref": "#/$defs/AttributeNameValue"
}
},
"detectors": {
"$ref": "#/$defs/Detectors"
@@ -19,10 +22,42 @@
}
},
"$defs": {
"Attributes": {
"title": "Attributes",
"type": ["object", "null"],
"additionalProperties": true
"AttributeNameValue": {
"title": "AttributeNameValue",
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"type": "string"
},
"value": {
"oneOf": [
{"type": "string"},
{"type": "number"},
{"type": "boolean"},
{"type": "null"},
{"type": "array", "items": {"type": "string"}},
{"type": "array", "items": {"type": "boolean"}},
{"type": "array", "items": {"type": "number"}}
]
},
"type": {
"enum": [
null,
"string",
"bool",
"int",
"double",
"string_array",
"bool_array",
"int_array",
"double_array"
]
}
},
"required": [
"name", "value"
]
},
"Detectors": {
"title": "Detectors",
3 changes: 2 additions & 1 deletion validator/shelltests/hex_integer.yaml
Original file line number Diff line number Diff line change
@@ -9,7 +9,8 @@ resource:
# Configure resource attributes.
attributes:
# Configure `service.name` resource attribute
service.name: "${OTEL_SERVICE_NAME:-unknown_service}"
- name: service.name
value: "${OTEL_SERVICE_NAME:-unknown_service}"

attribute_limits:
# Configure max attribute value size.
3 changes: 2 additions & 1 deletion validator/shelltests/string_for_int.yaml
Original file line number Diff line number Diff line change
@@ -9,7 +9,8 @@ resource:
# Configure resource attributes.
attributes:
# Configure `service.name` resource attribute
service.name: "${OTEL_SERVICE_NAME:-unknown_service}"
- name: service.name
value: "${OTEL_SERVICE_NAME:-unknown_service}"

attribute_limits:
# Configure max attribute value size.