From ea687543b1bd45a6516ad4950ed905b495de28c4 Mon Sep 17 00:00:00 2001 From: Jack Berg Date: Wed, 14 Feb 2024 18:16:24 -0600 Subject: [PATCH 1/6] Add simple scope configuration to Tracer, Meter, Logger --- specification/logs/sdk.md | 61 ++++++++++++++++++++++++++++++++--- specification/metrics/sdk.md | 55 +++++++++++++++++++++++++++++++- specification/trace/sdk.md | 62 ++++++++++++++++++++++++++++++++++-- 3 files changed, 170 insertions(+), 8 deletions(-) diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index 0cef89a29bd..2e3ccd20f87 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -11,9 +11,11 @@ * [LoggerProvider Creation](#loggerprovider-creation) * [Logger Creation](#logger-creation) * [Configuration](#configuration) + + [LoggerConfigProvider](#loggerconfigprovider) * [Shutdown](#shutdown) * [ForceFlush](#forceflush) - [Logger](#logger) + * [LoggerConfig](#loggerconfig) - [Additional LogRecord interfaces](#additional-logrecord-interfaces) * [ReadableLogRecord](#readablelogrecord) * [ReadWriteLogRecord](#readwritelogrecord) @@ -69,11 +71,16 @@ working `Logger` MUST be returned as a fallback rather than returning null or throwing an exception, its `name` SHOULD keep the original invalid value, and a message reporting that the specified value is invalid SHOULD be logged. +The `LoggerProvider` MUST compute the relevant [LoggerConfig](#loggerconfig) +using the configured [LoggerConfigProvider](#loggerconfigprovider), and adjust +the `Logger`'s behavior to conform to the `LoggerConfig`. + ### Configuration -Configuration (i.e. [LogRecordProcessors](#logrecordprocessor)) MUST be owned -by the the `LoggerProvider`. The configuration MAY be applied at the time of -`LoggerProvider` creation if appropriate. +Configuration ( +i.e. [LogRecordProcessors](#logrecordprocessor) and [LoggerConfigProvider](#loggerconfigprovider)) +MUST be owned by the `LoggerProvider`. The configuration MAY be applied at the +time of `LoggerProvider` creation if appropriate. The `LoggerProvider` MAY provide methods to update the configuration. If configuration is updated (e.g., adding a `LogRecordProcessor`), the updated @@ -83,6 +90,35 @@ after the configuration change). Note: Implementation-wise, this could mean that `Logger` instances have a reference to their `LoggerProvider` and access configuration only via this reference. +#### LoggerConfigProvider + +A `LoggerConfigProvider` is a function which computes +the [LoggerConfig](#loggerconfig) for a [Logger](#logger). + +The function MUST accept the following parameter: + +* `logger_scope`: + The [`InstrumentationScope`](../glossary.md#instrumentation-scope) of + the `Logger`. + +The function MUST return the relevant `LoggerConfig`, or some signal indicating +that the [default LoggerConfig](#loggerconfig) should be used. This signal MAY +be nil, null, empty, or an instance of the default `LoggerConfig` depending on +what is idiomatic in the language. + +This function is called when a `Logger` is first created, and for each +outstanding `Logger` when a `LoggerProvider`'s `LoggerConfigProvider` is +updated (if updating is supported). Therefore, it is important that it returns +quickly. + +`LoggerConfigProvider` is modeled as a function to maximize flexibility. +However, implementations MAY provide shorthand or helper functions to +accommodate common use cases: + +* Select one or more loggers by name, with exact match or pattern matching. +* Disable one or more specific loggers. +* Disable all loggers, and selectively enable one or more specific loggers. + ### Shutdown This method provides a way for provider to do any cleanup required. @@ -124,8 +160,23 @@ registered [LogRecordProcessors](#logrecordprocessor). ## Logger -Note that `Logger`s should not be responsible for configuration. This should be -the responsibility of the `LoggerProvider` instead. +`Logger` MUST behave according to the [LoggerConfig](#loggerconfig) computing +during [logger creation](#logger-creation). If the `LoggerProvider` supports +updating the [LoggerConfigProvider](#loggerconfigprovider), then upon update +the `Logger` MUST be updated to behave according to the new `LoggerConfig`. + +### LoggerConfig + +A `LoggerConfig` defines various configurable aspects of a `Logger`'s behavior. +It consists of the following parameters: + +* `disabled`: A boolean indication of whether the logger is enabled. + + If not explicitly set, the `disabled` parameter SHOULD default to `false` ( + i.e. `Logger`s are enabled by default). + + If a `Logger` is disabled, it MUST behave equivalently + to [No-op Logger](./noop.md#logger). ## Additional LogRecord interfaces diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 32971ceaca6..ef90dc521dd 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -15,6 +15,7 @@ linkTitle: SDK * [MeterProvider Creation](#meterprovider-creation) * [Meter Creation](#meter-creation) * [Configuration](#configuration) + + [MeterConfigProvider](#meterconfigprovider) * [Shutdown](#shutdown) * [ForceFlush](#forceflush) * [View](#view) @@ -41,6 +42,7 @@ linkTitle: SDK + [Synchronous instrument cardinality limits](#synchronous-instrument-cardinality-limits) + [Asynchronous instrument cardinality limits](#asynchronous-instrument-cardinality-limits) - [Meter](#meter) + * [MeterConfig](#meterconfig) * [Duplicate instrument registration](#duplicate-instrument-registration) + [Name conflict](#name-conflict) * [Instrument name](#instrument-name) @@ -128,10 +130,14 @@ When a Schema URL is passed as an argument when creating a `Meter` the emitted telemetry for that `Meter` MUST be associated with the Schema URL, provided that the emitted data format is capable of representing such association. +The `MeterProvider` MUST compute the relevant [MeterConfig](#meterconfig) +using the configured [MeterConfigProvider](#meterconfigprovider), and adjust +the `Meter`'s behavior to conform to the `MeterConfig`. + ### Configuration Configuration (i.e. [MetricExporters](#metricexporter), -[MetricReaders](#metricreader) and [Views](#view)) MUST be owned by the +[MetricReaders](#metricreader), [Views](#view), and [MeterConfigProvider](#meterconfigprovider)) MUST be owned by the `MeterProvider`. The configuration MAY be applied at the time of `MeterProvider` creation if appropriate. @@ -143,6 +149,35 @@ the configuration change). Note: Implementation-wise, this could mean that `Meter` instances have a reference to their `MeterProvider` and access configuration only via this reference. +#### MeterConfigProvider + +A `MeterConfigProvider` is a function which computes +the [MeterConfig](#meterconfig) for a [Meter](#meter). + +The function MUST accept the following parameter: + +* `meter_scope`: + The [`InstrumentationScope`](../glossary.md#instrumentation-scope) of + the `Meter`. + +The function MUST return the relevant `MeterConfig`, or some signal indicating +that the [default MeterConfig](#meterconfig) should be used. This signal MAY +be nil, null, empty, or an instance of the default `MeterConfig` depending on +what is idiomatic in the language. + +This function is called when a `Meter` is first created, and for each +outstanding `Meter` when a `MeterProvider`'s `MeterConfigProvider` is +updated (if updating is supported). Therefore, it is important that it returns +quickly. + +`MeterConfigProvider` is modeled as a function to maximize flexibility. +However, implementations MAY provide shorthand or helper functions to +accommodate common use cases: + +* Select one or more Meters by name, with exact match or pattern matching. +* Disable one or more specific Meters. +* Disable all Meters, and selectively enable one or more specific Meters. + ### Shutdown This method provides a way for provider to do any cleanup required. @@ -791,6 +826,24 @@ temporality. Distinct meters MUST be treated as separate namespaces for the purposes of detecting [duplicate instrument registrations](#duplicate-instrument-registration). +`Meter` MUST behave according to the [MeterConfig](#meterconfig) computing +during [Meter creation](#meter-creation). If the `MeterProvider` supports +updating the [MeterConfigProvider](#meterconfigprovider), then upon update +the `Meter` MUST be updated to behave according to the new `MeterConfig`. + +### MeterConfig + +A `MeterConfig` defines various configurable aspects of a `Meter`'s behavior. +It consists of the following parameters: + +* `disabled`: A boolean indication of whether the Meter is enabled. + + If not explicitly set, the `disabled` parameter SHOULD default to `false` ( + i.e. `Meter`s are enabled by default). + + If a `Meter` is disabled, it MUST behave equivalently + to [No-op Meter](./noop.md#Meter). + ### Duplicate instrument registration A _duplicate instrument registration_ occurs when more than one Instrument of diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 58d893e8907..032076b6517 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -14,8 +14,11 @@ linkTitle: SDK - [Tracer Provider](#tracer-provider) * [Tracer Creation](#tracer-creation) * [Configuration](#configuration) + + [TracerConfigProvider](#tracerconfigprovider) * [Shutdown](#shutdown) * [ForceFlush](#forceflush) +- [Tracer](#tracer) + * [TracerConfig](#tracerconfig) - [Additional Span Interfaces](#additional-span-interfaces) - [Sampling](#sampling) * [Recording Sampled reaction table](#recording-sampled-reaction-table) @@ -68,11 +71,15 @@ The input provided by the user MUST be used to create an [`InstrumentationScope`](../glossary.md#instrumentation-scope) instance which is stored on the created `Tracer`. +The `TracerProvider` MUST compute the relevant [TracerConfig](#tracerconfig) +using the configured [TracerConfigProvider](#tracerconfigprovider), and adjust +the `Tracer`'s behavior to conform to the `TracerConfig`. + ### Configuration Configuration (i.e., [SpanProcessors](#span-processor), [IdGenerator](#id-generators), -[SpanLimits](#span-limits) and [`Sampler`](#sampling)) MUST be owned by the -the `TracerProvider`. The configuration MAY be applied at the time of `TracerProvider` +[SpanLimits](#span-limits), [`Sampler`](#sampling), and [TracerConfigProvider](#tracerconfigprovider)) MUST be owned by the + `TracerProvider`. The configuration MAY be applied at the time of `TracerProvider` creation if appropriate. The TracerProvider MAY provide methods to update the configuration. If @@ -84,6 +91,35 @@ Note: Implementation-wise, this could mean that `Tracer` instances have a reference to their `TracerProvider` and access configuration only via this reference. +#### TracerConfigProvider + +A `TracerConfigProvider` is a function which computes +the [TracerConfig](#tracerconfig) for a [Tracer](#tracer). + +The function MUST accept the following parameter: + +* `tracer_scope`: + The [`InstrumentationScope`](../glossary.md#instrumentation-scope) of + the `Tracer`. + +The function MUST return the relevant `TracerConfig`, or some signal indicating +that the [default TracerConfig](#tracerconfig) should be used. This signal MAY +be nil, null, empty, or an instance of the default `TracerConfig` depending on +what is idiomatic in the language. + +This function is called when a `Tracer` is first created, and for each +outstanding `Tracer` when a `TracerProvider`'s `TracerConfigProvider` is +updated (if updating is supported). Therefore, it is important that it returns +quickly. + +`TracerConfigProvider` is modeled as a function to maximize flexibility. +However, implementations MAY provide shorthand or helper functions to +accommodate common use cases: + +* Select one or more Tracers by name, with exact match or pattern matching. +* Disable one or more specific Tracers. +* Disable all Tracers, and selectively enable one or more specific Tracers. + ### Shutdown This method provides a way for provider to do any cleanup required. @@ -116,6 +152,28 @@ make the flush timeout configurable. `ForceFlush` MUST invoke `ForceFlush` on all registered `SpanProcessors`. +## Tracer + +Note that `Tracer`s should not be responsible for configuration. This should be +the responsibility of the `TracerProvider` instead. +`Tracer` MUST behave according to the [TracerConfig](#tracerconfig) computing +during [Tracer creation](#tracer-creation). If the `TracerProvider` supports +updating the [TracerConfigProvider](#tracerconfigprovider), then upon update +the `Tracer` MUST be updated to behave according to the new `TracerConfig`. + +### TracerConfig + +A `TracerConfig` defines various configurable aspects of a `Tracer`'s behavior. +It consists of the following parameters: + +* `disabled`: A boolean indication of whether the Tracer is enabled. + + If not explicitly set, the `disabled` parameter SHOULD default to `false` ( + i.e. `Tracer`s are enabled by default). + + If a `Tracer` is disabled, it MUST behave equivalently + to [No-op Tracer](./api.md#behavior-of-the-api-in-the-absence-of-an-installed-sdk). + ## Additional Span Interfaces The [API-level definition for Span's interface](api.md#span-operations) From 48b7f898288cfa9848041337832c74aba41dc0ac Mon Sep 17 00:00:00 2001 From: Jack Berg Date: Thu, 15 Feb 2024 09:26:30 -0600 Subject: [PATCH 2/6] fix build --- specification/metrics/sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index ef90dc521dd..9199f1af2d2 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -842,7 +842,7 @@ It consists of the following parameters: i.e. `Meter`s are enabled by default). If a `Meter` is disabled, it MUST behave equivalently - to [No-op Meter](./noop.md#Meter). + to [No-op Meter](./noop.md#meter). ### Duplicate instrument registration From f0cf8a85d45c01bebbfea3a47fbe7f0778dc9c62 Mon Sep 17 00:00:00 2001 From: Jack Berg Date: Sun, 25 Feb 2024 09:22:49 -0600 Subject: [PATCH 3/6] Add experimental tags where appropriate --- specification/logs/sdk.md | 16 +++++++++++----- specification/metrics/sdk.md | 23 +++++++++++++++-------- specification/trace/sdk.md | 25 +++++++++++++++---------- 3 files changed, 41 insertions(+), 23 deletions(-) diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index 2e3ccd20f87..997c4e93bbd 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -1,6 +1,6 @@ # Logs SDK -**Status**: [Stable](../document-status.md) +**Status**: [Stable](../document-status.md), except where otherwise specified
Table of Contents @@ -71,14 +71,15 @@ working `Logger` MUST be returned as a fallback rather than returning null or throwing an exception, its `name` SHOULD keep the original invalid value, and a message reporting that the specified value is invalid SHOULD be logged. -The `LoggerProvider` MUST compute the relevant [LoggerConfig](#loggerconfig) -using the configured [LoggerConfigProvider](#loggerconfigprovider), and adjust +**Status**: [Experimental](../document-status.md) - The `LoggerProvider` MUST +compute the relevant [LoggerConfig](#loggerconfig) using the +configured [LoggerConfigProvider](#loggerconfigprovider), and adjust the `Logger`'s behavior to conform to the `LoggerConfig`. ### Configuration Configuration ( -i.e. [LogRecordProcessors](#logrecordprocessor) and [LoggerConfigProvider](#loggerconfigprovider)) +i.e. [LogRecordProcessors](#logrecordprocessor) and (**experimental**) [LoggerConfigProvider](#loggerconfigprovider)) MUST be owned by the `LoggerProvider`. The configuration MAY be applied at the time of `LoggerProvider` creation if appropriate. @@ -92,6 +93,8 @@ configuration only via this reference. #### LoggerConfigProvider +**Status**: [Experimental](../document-status.md) + A `LoggerConfigProvider` is a function which computes the [LoggerConfig](#loggerconfig) for a [Logger](#logger). @@ -160,13 +163,16 @@ registered [LogRecordProcessors](#logrecordprocessor). ## Logger -`Logger` MUST behave according to the [LoggerConfig](#loggerconfig) computing +**Status**: [Experimental](../document-status.md) - `Logger` MUST behave +according to the [LoggerConfig](#loggerconfig) computing during [logger creation](#logger-creation). If the `LoggerProvider` supports updating the [LoggerConfigProvider](#loggerconfigprovider), then upon update the `Logger` MUST be updated to behave according to the new `LoggerConfig`. ### LoggerConfig +**Status**: [Experimental](../document-status.md) + A `LoggerConfig` defines various configurable aspects of a `Logger`'s behavior. It consists of the following parameters: diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 9199f1af2d2..b258fbcecde 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -130,16 +130,18 @@ When a Schema URL is passed as an argument when creating a `Meter` the emitted telemetry for that `Meter` MUST be associated with the Schema URL, provided that the emitted data format is capable of representing such association. -The `MeterProvider` MUST compute the relevant [MeterConfig](#meterconfig) -using the configured [MeterConfigProvider](#meterconfigprovider), and adjust -the `Meter`'s behavior to conform to the `MeterConfig`. +**Status**: [Experimental](../document-status.md) - The `MeterProvider` MUST +compute the relevant [MeterConfig](#meterconfig) using the +configured [MeterConfigProvider](#meterconfigprovider), and adjust the `Meter`'s +behavior to conform to the `MeterConfig`. ### Configuration -Configuration (i.e. [MetricExporters](#metricexporter), -[MetricReaders](#metricreader), [Views](#view), and [MeterConfigProvider](#meterconfigprovider)) MUST be owned by the -`MeterProvider`. The configuration MAY be applied at the time of `MeterProvider` -creation if appropriate. +Configuration ( +i.e. [MetricExporters](#metricexporter), [MetricReaders](#metricreader), [Views](#view), +and (**experimental**) [MeterConfigProvider](#meterconfigprovider)) MUST be +owned by the `MeterProvider`. The configuration MAY be applied at the time +of `MeterProvider` creation if appropriate. The `MeterProvider` MAY provide methods to update the configuration. If configuration is updated (e.g., adding a `MetricReader`), the updated @@ -151,6 +153,8 @@ configuration only via this reference. #### MeterConfigProvider +**Status**: [Experimental](../document-status.md) + A `MeterConfigProvider` is a function which computes the [MeterConfig](#meterconfig) for a [Meter](#meter). @@ -826,13 +830,16 @@ temporality. Distinct meters MUST be treated as separate namespaces for the purposes of detecting [duplicate instrument registrations](#duplicate-instrument-registration). -`Meter` MUST behave according to the [MeterConfig](#meterconfig) computing +**Status**: [Experimental](../document-status.md) - `Meter` MUST behave +according to the [MeterConfig](#meterconfig) computing during [Meter creation](#meter-creation). If the `MeterProvider` supports updating the [MeterConfigProvider](#meterconfigprovider), then upon update the `Meter` MUST be updated to behave according to the new `MeterConfig`. ### MeterConfig +**Status**: [Experimental](../document-status.md) + A `MeterConfig` defines various configurable aspects of a `Meter`'s behavior. It consists of the following parameters: diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 032076b6517..b7b4d0fd3d8 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -4,7 +4,7 @@ linkTitle: SDK # Tracing SDK -**Status**: [Stable](../document-status.md) +**Status**: [Stable](../document-status.md), except where otherwise specified
Table of Contents @@ -71,16 +71,18 @@ The input provided by the user MUST be used to create an [`InstrumentationScope`](../glossary.md#instrumentation-scope) instance which is stored on the created `Tracer`. -The `TracerProvider` MUST compute the relevant [TracerConfig](#tracerconfig) -using the configured [TracerConfigProvider](#tracerconfigprovider), and adjust +**Status**: [Experimental](../document-status.md) - The `TracerProvider` MUST +compute the relevant [TracerConfig](#tracerconfig) using the +configured [TracerConfigProvider](#tracerconfigprovider), and adjust the `Tracer`'s behavior to conform to the `TracerConfig`. ### Configuration -Configuration (i.e., [SpanProcessors](#span-processor), [IdGenerator](#id-generators), -[SpanLimits](#span-limits), [`Sampler`](#sampling), and [TracerConfigProvider](#tracerconfigprovider)) MUST be owned by the - `TracerProvider`. The configuration MAY be applied at the time of `TracerProvider` -creation if appropriate. +Configuration ( +i.e., [SpanProcessors](#span-processor), [IdGenerator](#id-generators), [SpanLimits](#span-limits), [`Sampler`](#sampling), +and (**experimental**) [TracerConfigProvider](#tracerconfigprovider)) MUST be +owned by the `TracerProvider`. The configuration MAY be applied at the time +of `TracerProvider` creation if appropriate. The TracerProvider MAY provide methods to update the configuration. If configuration is updated (e.g., adding a `SpanProcessor`), @@ -93,6 +95,8 @@ reference. #### TracerConfigProvider +**Status**: [Experimental](../document-status.md) + A `TracerConfigProvider` is a function which computes the [TracerConfig](#tracerconfig) for a [Tracer](#tracer). @@ -154,15 +158,16 @@ make the flush timeout configurable. ## Tracer -Note that `Tracer`s should not be responsible for configuration. This should be -the responsibility of the `TracerProvider` instead. -`Tracer` MUST behave according to the [TracerConfig](#tracerconfig) computing +**Status**: [Experimental](../document-status.md) - `Tracer` MUST behave +according to the [TracerConfig](#tracerconfig) computing during [Tracer creation](#tracer-creation). If the `TracerProvider` supports updating the [TracerConfigProvider](#tracerconfigprovider), then upon update the `Tracer` MUST be updated to behave according to the new `TracerConfig`. ### TracerConfig +**Status**: [Experimental](../document-status.md) + A `TracerConfig` defines various configurable aspects of a `Tracer`'s behavior. It consists of the following parameters: From dd9e89471e41db0ed995ba93b3c89ec6478b3d09 Mon Sep 17 00:00:00 2001 From: Jack Berg Date: Wed, 13 Mar 2024 17:57:31 -0500 Subject: [PATCH 4/6] Rename to *Configurator --- specification/logs/sdk.md | 16 ++++++++-------- specification/metrics/sdk.md | 16 ++++++++-------- specification/trace/sdk.md | 16 ++++++++-------- 3 files changed, 24 insertions(+), 24 deletions(-) diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index 997c4e93bbd..c2f53b88807 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -11,7 +11,7 @@ * [LoggerProvider Creation](#loggerprovider-creation) * [Logger Creation](#logger-creation) * [Configuration](#configuration) - + [LoggerConfigProvider](#loggerconfigprovider) + + [LoggerConfigurator](#loggerconfigurator) * [Shutdown](#shutdown) * [ForceFlush](#forceflush) - [Logger](#logger) @@ -73,13 +73,13 @@ message reporting that the specified value is invalid SHOULD be logged. **Status**: [Experimental](../document-status.md) - The `LoggerProvider` MUST compute the relevant [LoggerConfig](#loggerconfig) using the -configured [LoggerConfigProvider](#loggerconfigprovider), and adjust +configured [LoggerConfigurator](#loggerconfigurator), and adjust the `Logger`'s behavior to conform to the `LoggerConfig`. ### Configuration Configuration ( -i.e. [LogRecordProcessors](#logrecordprocessor) and (**experimental**) [LoggerConfigProvider](#loggerconfigprovider)) +i.e. [LogRecordProcessors](#logrecordprocessor) and (**experimental**) [LoggerConfigurator](#loggerconfigurator)) MUST be owned by the `LoggerProvider`. The configuration MAY be applied at the time of `LoggerProvider` creation if appropriate. @@ -91,11 +91,11 @@ after the configuration change). Note: Implementation-wise, this could mean that `Logger` instances have a reference to their `LoggerProvider` and access configuration only via this reference. -#### LoggerConfigProvider +#### LoggerConfigurator **Status**: [Experimental](../document-status.md) -A `LoggerConfigProvider` is a function which computes +A `LoggerConfigurator` is a function which computes the [LoggerConfig](#loggerconfig) for a [Logger](#logger). The function MUST accept the following parameter: @@ -110,11 +110,11 @@ be nil, null, empty, or an instance of the default `LoggerConfig` depending on what is idiomatic in the language. This function is called when a `Logger` is first created, and for each -outstanding `Logger` when a `LoggerProvider`'s `LoggerConfigProvider` is +outstanding `Logger` when a `LoggerProvider`'s `LoggerConfigurator` is updated (if updating is supported). Therefore, it is important that it returns quickly. -`LoggerConfigProvider` is modeled as a function to maximize flexibility. +`LoggerConfigurator` is modeled as a function to maximize flexibility. However, implementations MAY provide shorthand or helper functions to accommodate common use cases: @@ -166,7 +166,7 @@ registered [LogRecordProcessors](#logrecordprocessor). **Status**: [Experimental](../document-status.md) - `Logger` MUST behave according to the [LoggerConfig](#loggerconfig) computing during [logger creation](#logger-creation). If the `LoggerProvider` supports -updating the [LoggerConfigProvider](#loggerconfigprovider), then upon update +updating the [LoggerConfigurator](#loggerconfigurator), then upon update the `Logger` MUST be updated to behave according to the new `LoggerConfig`. ### LoggerConfig diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index b258fbcecde..73a3a283361 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -15,7 +15,7 @@ linkTitle: SDK * [MeterProvider Creation](#meterprovider-creation) * [Meter Creation](#meter-creation) * [Configuration](#configuration) - + [MeterConfigProvider](#meterconfigprovider) + + [MeterConfigurator](#meterconfigurator) * [Shutdown](#shutdown) * [ForceFlush](#forceflush) * [View](#view) @@ -132,14 +132,14 @@ that the emitted data format is capable of representing such association. **Status**: [Experimental](../document-status.md) - The `MeterProvider` MUST compute the relevant [MeterConfig](#meterconfig) using the -configured [MeterConfigProvider](#meterconfigprovider), and adjust the `Meter`'s +configured [MeterConfigurator](#meterconfigurator), and adjust the `Meter`'s behavior to conform to the `MeterConfig`. ### Configuration Configuration ( i.e. [MetricExporters](#metricexporter), [MetricReaders](#metricreader), [Views](#view), -and (**experimental**) [MeterConfigProvider](#meterconfigprovider)) MUST be +and (**experimental**) [MeterConfigurator](#meterconfigurator)) MUST be owned by the `MeterProvider`. The configuration MAY be applied at the time of `MeterProvider` creation if appropriate. @@ -151,11 +151,11 @@ the configuration change). Note: Implementation-wise, this could mean that `Meter` instances have a reference to their `MeterProvider` and access configuration only via this reference. -#### MeterConfigProvider +#### MeterConfigurator **Status**: [Experimental](../document-status.md) -A `MeterConfigProvider` is a function which computes +A `MeterConfigurator` is a function which computes the [MeterConfig](#meterconfig) for a [Meter](#meter). The function MUST accept the following parameter: @@ -170,11 +170,11 @@ be nil, null, empty, or an instance of the default `MeterConfig` depending on what is idiomatic in the language. This function is called when a `Meter` is first created, and for each -outstanding `Meter` when a `MeterProvider`'s `MeterConfigProvider` is +outstanding `Meter` when a `MeterProvider`'s `MeterConfigurator` is updated (if updating is supported). Therefore, it is important that it returns quickly. -`MeterConfigProvider` is modeled as a function to maximize flexibility. +`MeterConfigurator` is modeled as a function to maximize flexibility. However, implementations MAY provide shorthand or helper functions to accommodate common use cases: @@ -833,7 +833,7 @@ Distinct meters MUST be treated as separate namespaces for the purposes of detec **Status**: [Experimental](../document-status.md) - `Meter` MUST behave according to the [MeterConfig](#meterconfig) computing during [Meter creation](#meter-creation). If the `MeterProvider` supports -updating the [MeterConfigProvider](#meterconfigprovider), then upon update +updating the [MeterConfigurator](#meterconfigurator), then upon update the `Meter` MUST be updated to behave according to the new `MeterConfig`. ### MeterConfig diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index b7b4d0fd3d8..d310a1bc6c2 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -14,7 +14,7 @@ linkTitle: SDK - [Tracer Provider](#tracer-provider) * [Tracer Creation](#tracer-creation) * [Configuration](#configuration) - + [TracerConfigProvider](#tracerconfigprovider) + + [TracerConfigurator](#tracerconfigurator) * [Shutdown](#shutdown) * [ForceFlush](#forceflush) - [Tracer](#tracer) @@ -73,14 +73,14 @@ is stored on the created `Tracer`. **Status**: [Experimental](../document-status.md) - The `TracerProvider` MUST compute the relevant [TracerConfig](#tracerconfig) using the -configured [TracerConfigProvider](#tracerconfigprovider), and adjust +configured [TracerConfigurator](#tracerconfigurator), and adjust the `Tracer`'s behavior to conform to the `TracerConfig`. ### Configuration Configuration ( i.e., [SpanProcessors](#span-processor), [IdGenerator](#id-generators), [SpanLimits](#span-limits), [`Sampler`](#sampling), -and (**experimental**) [TracerConfigProvider](#tracerconfigprovider)) MUST be +and (**experimental**) [TracerConfigurator](#tracerconfigurator)) MUST be owned by the `TracerProvider`. The configuration MAY be applied at the time of `TracerProvider` creation if appropriate. @@ -93,11 +93,11 @@ Note: Implementation-wise, this could mean that `Tracer` instances have a reference to their `TracerProvider` and access configuration only via this reference. -#### TracerConfigProvider +#### TracerConfigurator **Status**: [Experimental](../document-status.md) -A `TracerConfigProvider` is a function which computes +A `TracerConfigurator` is a function which computes the [TracerConfig](#tracerconfig) for a [Tracer](#tracer). The function MUST accept the following parameter: @@ -112,11 +112,11 @@ be nil, null, empty, or an instance of the default `TracerConfig` depending on what is idiomatic in the language. This function is called when a `Tracer` is first created, and for each -outstanding `Tracer` when a `TracerProvider`'s `TracerConfigProvider` is +outstanding `Tracer` when a `TracerProvider`'s `TracerConfigurator` is updated (if updating is supported). Therefore, it is important that it returns quickly. -`TracerConfigProvider` is modeled as a function to maximize flexibility. +`TracerConfigurator` is modeled as a function to maximize flexibility. However, implementations MAY provide shorthand or helper functions to accommodate common use cases: @@ -161,7 +161,7 @@ make the flush timeout configurable. **Status**: [Experimental](../document-status.md) - `Tracer` MUST behave according to the [TracerConfig](#tracerconfig) computing during [Tracer creation](#tracer-creation). If the `TracerProvider` supports -updating the [TracerConfigProvider](#tracerconfigprovider), then upon update +updating the [TracerConfigurator](#tracerconfigurator), then upon update the `Tracer` MUST be updated to behave according to the new `TracerConfig`. ### TracerConfig From 177e5bd1eccc1e0943fa4e98df2b265e6f91c4aa Mon Sep 17 00:00:00 2001 From: Jack Berg Date: Mon, 25 Mar 2024 13:29:57 -0500 Subject: [PATCH 5/6] PR feedback --- specification/logs/sdk.md | 6 +++--- specification/metrics/sdk.md | 6 +++--- specification/trace/sdk.md | 6 +++--- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index c2f53b88807..560ae8040ae 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -73,8 +73,8 @@ message reporting that the specified value is invalid SHOULD be logged. **Status**: [Experimental](../document-status.md) - The `LoggerProvider` MUST compute the relevant [LoggerConfig](#loggerconfig) using the -configured [LoggerConfigurator](#loggerconfigurator), and adjust -the `Logger`'s behavior to conform to the `LoggerConfig`. +configured [LoggerConfigurator](#loggerconfigurator), and create +a `Logger` whose behavior to conform to that `LoggerConfig`. ### Configuration @@ -164,7 +164,7 @@ registered [LogRecordProcessors](#logrecordprocessor). ## Logger **Status**: [Experimental](../document-status.md) - `Logger` MUST behave -according to the [LoggerConfig](#loggerconfig) computing +according to the [LoggerConfig](#loggerconfig) computed during [logger creation](#logger-creation). If the `LoggerProvider` supports updating the [LoggerConfigurator](#loggerconfigurator), then upon update the `Logger` MUST be updated to behave according to the new `LoggerConfig`. diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 92699180864..abc7a2b5a8f 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -132,8 +132,8 @@ that the emitted data format is capable of representing such association. **Status**: [Experimental](../document-status.md) - The `MeterProvider` MUST compute the relevant [MeterConfig](#meterconfig) using the -configured [MeterConfigurator](#meterconfigurator), and adjust the `Meter`'s -behavior to conform to the `MeterConfig`. +configured [MeterConfigurator](#meterconfigurator), and create +a `Meter` whose behavior to conform to that `MeterConfig`. ### Configuration @@ -835,7 +835,7 @@ Distinct meters MUST be treated as separate namespaces for the purposes of detec [duplicate instrument registrations](#duplicate-instrument-registration). **Status**: [Experimental](../document-status.md) - `Meter` MUST behave -according to the [MeterConfig](#meterconfig) computing +according to the [MeterConfig](#meterconfig) computed during [Meter creation](#meter-creation). If the `MeterProvider` supports updating the [MeterConfigurator](#meterconfigurator), then upon update the `Meter` MUST be updated to behave according to the new `MeterConfig`. diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index d310a1bc6c2..c40e8dc7ca2 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -73,8 +73,8 @@ is stored on the created `Tracer`. **Status**: [Experimental](../document-status.md) - The `TracerProvider` MUST compute the relevant [TracerConfig](#tracerconfig) using the -configured [TracerConfigurator](#tracerconfigurator), and adjust -the `Tracer`'s behavior to conform to the `TracerConfig`. +configured [TracerConfigurator](#tracerconfigurator), and create +a `Tracer` whose behavior to conform to that `TracerConfig`. ### Configuration @@ -159,7 +159,7 @@ make the flush timeout configurable. ## Tracer **Status**: [Experimental](../document-status.md) - `Tracer` MUST behave -according to the [TracerConfig](#tracerconfig) computing +according to the [TracerConfig](#tracerconfig) computed during [Tracer creation](#tracer-creation). If the `TracerProvider` supports updating the [TracerConfigurator](#tracerconfigurator), then upon update the `Tracer` MUST be updated to behave according to the new `TracerConfig`. From 56f37b7f59fb12d8cb3d1a370ad8b344ce0f7762 Mon Sep 17 00:00:00 2001 From: Jack Berg Date: Thu, 4 Apr 2024 16:56:33 -0500 Subject: [PATCH 6/6] Fix typo --- specification/logs/sdk.md | 2 +- specification/metrics/sdk.md | 2 +- specification/trace/sdk.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index 560ae8040ae..3b70550cbf0 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -74,7 +74,7 @@ message reporting that the specified value is invalid SHOULD be logged. **Status**: [Experimental](../document-status.md) - The `LoggerProvider` MUST compute the relevant [LoggerConfig](#loggerconfig) using the configured [LoggerConfigurator](#loggerconfigurator), and create -a `Logger` whose behavior to conform to that `LoggerConfig`. +a `Logger` whose behavior conforms to that `LoggerConfig`. ### Configuration diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index abc7a2b5a8f..a954f2ad6ab 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -133,7 +133,7 @@ that the emitted data format is capable of representing such association. **Status**: [Experimental](../document-status.md) - The `MeterProvider` MUST compute the relevant [MeterConfig](#meterconfig) using the configured [MeterConfigurator](#meterconfigurator), and create -a `Meter` whose behavior to conform to that `MeterConfig`. +a `Meter` whose behavior conforms to that `MeterConfig`. ### Configuration diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index c40e8dc7ca2..d9d58aaedd9 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -74,7 +74,7 @@ is stored on the created `Tracer`. **Status**: [Experimental](../document-status.md) - The `TracerProvider` MUST compute the relevant [TracerConfig](#tracerconfig) using the configured [TracerConfigurator](#tracerconfigurator), and create -a `Tracer` whose behavior to conform to that `TracerConfig`. +a `Tracer` whose behavior conforms to that `TracerConfig`. ### Configuration