Merge branch 'main' into ot-support-jaeger-debug

open-telemetry · Jun 21, 2023 · fac8962 · fac8962
2 parents b02108c + 43ef7d0
commit fac8962
Show file tree

Hide file tree

Showing 22 changed files with 167 additions and 856 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -13,22 +13,78 @@ release.
 
 ### Metrics
 
+- Refine SDK MeterProvider configuration section.
+  ([#3522](https://github.com/open-telemetry/opentelemetry-specification/pull/3522))
+
+### Logs
+
+### Resource
+
+### Compatibility
+
+### OpenTelemetry Protocol
+
+### SDK Configuration
+
+- Extract Examplar section and mark it as Experimental.
+  ([#3533](https://github.com/open-telemetry/opentelemetry-specification/pull/3533))
+
+### Telemetry Schemas
+
+### Common
+
+### Supplemenatary Guidelines
+
+## v1.22.0 (2023-06-09)
+
+### Context
+
+- No changes.
+
+### Traces
+
+- No changes.
+
+### Metrics
+
+- Make recommendation to reserve aggregator normative.
+  ([#3526](https://github.com/open-telemetry/opentelemetry-specification/pull/3526))
+
 ### Logs
 
+- No changes.
+
 ### Resource
 
+- No changes.
+
 ### Compatibility
 
+- No changes.
+
 ### OpenTelemetry Protocol
 
+- Move OTLP specification to github.com/open-telemetry/opentelemetry-proto.
+  ([#3454](https://github.com/open-telemetry/opentelemetry-specification/pull/3454))
+
 ### SDK Configuration
 
+- No changes.
+
 ### Telemetry Schemas
 
+- No changes.
+
 ### Common
 
+- Explain why custom attributes are not recommended to be placed in OTel
+  namespaces.
+  ([#3507](https://github.com/open-telemetry/opentelemetry-specification/pull/3507))
+
 ### Supplemenatary Guidelines
 
+- No changes.
+
 ## v1.21.0 (2023-05-09)
 
 ### Context

diff --git a/Makefile b/Makefile
@@ -1,5 +1,5 @@
 # All documents to be used in spell check.
-ALL_DOCS := $(shell find . -type f -name '*.md' -not -path './.github/*' -not -path './node_modules/*' | sort)
+ALL_DOCS := $(shell find . -type f -name '*.md' -not -path './.github/*' -not -path './node_modules/*' -not -path '*semantic_conventions*' | sort)
 PWD := $(shell pwd)
 
 TOOLS_DIR := ./internal/tools

diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md
@@ -258,11 +258,13 @@ Disclaimer: this list of features is still a work in progress, please refer to t
 | TraceContext Propagator                                                          |          | +  | +    | +  | +      | +    | +      | +   | +    | +   | +    | +     |
 | B3 Propagator                                                                    |          | +  | +    | +  | +      | +    | +      | +   | +    | +   | +    | +     |
 | Jaeger Propagator                                                                |          | +  | +    | +  | +      | +    | +      |     | +    | +   | -    | -     |
+| OT Propagator                                                                    |          | +  | +    | +  | +      |      |        |     |      |     |      |       |
+| OpenCensus Binary Propagator                                                     |          | +  |      |    |        |      |        |     |      |     |      |       |
 | [TextMapPropagator](specification/context/api-propagators.md#textmap-propagator) |          | +  | +    |    |        | +    |        | +   |      |     |      |       |
 | Fields                                                                           |          | +  | +    | +  | +      | +    | +      | +   | +    | +   | +    | +     |
-| Setter argument                                                                  | X        | N/A| +    | +  | +      | +    | +      |     | N/A  | +   | +    | +     |
-| Getter argument                                                                  | X        | N/A| +    | +  | +      | +    | +      |     | N/A  | +   | +    | +     |
-| Getter argument returning Keys                                                   | X        | N/A| +    | +  | +      | +    | +      |     | N/A  | +   | -    | +     |
+| Setter argument                                                                  | X        | N/A| +    | +  | +      | +    | +      | +   | N/A  | +   | +    | +     |
+| Getter argument                                                                  | X        | N/A| +    | +  | +      | +    | +      | +   | N/A  | +   | +    | +     |
+| Getter argument returning Keys                                                   | X        | N/A| +    | +  | +      | +    | +      | +   | N/A  | +   | -    | +     |
 
 ## Environment Variables
 
@@ -282,7 +284,7 @@ Note: Support for environment variables is optional.
 | OTEL_EXPORTER_ZIPKIN_*                                   | -   | +    |     | +           | +    | -      | +   | -    | -   | +    | -     |
 | OTEL_TRACES_EXPORTER                                     | -   | +    | +   | +           | +    | +      | +   | -    | -   | -    |       |
 | OTEL_METRICS_EXPORTER                                    | -   | +    |     | +           | -    | -      | +   | -    | -   | -    | -     |
-| OTEL_LOGS_EXPORTER                                       | -   | +    |     | +           |      |        |     |      |     | -    |       |
+| OTEL_LOGS_EXPORTER                                       | -   | +    |     | +           |      |        | +   |      |     | -    |       |
 | OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT                          | +   | +    | +   | +           | +    | +      | +   | +    | -   | -    |       |
 | OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT                   | +   | +    | +   | +           | +    | +      | +   |      |     | -    |       |
 | OTEL_SPAN_EVENT_COUNT_LIMIT                              | +   | +    | +   | +           | +    | +      | +   | +    | -   | -    |       |
@@ -298,7 +300,7 @@ Note: Support for environment variables is optional.
 | OTEL_METRIC_EXPORT_INTERVAL                              | -   | +    |     |             |      |        | +   |      |     | -    |       |
 | OTEL_METRIC_EXPORT_TIMEOUT                               | -   | -    |     |             |      |        | +   |      |     | -    |       |
 | OTEL_METRICS_EXEMPLAR_FILTER                             | -   | +    |     |             |      |        | +   |      |     | -    |       |
-| OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE        | -   | +    | +   | +           |      |        |     |      |     | -    |       |
+| OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE        | -   | +    | +   | +           |      |        | +   |      |     | -    |       |
 | OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION |     | +    |     |             |      |        |     |      |     |      |       |
 
 ## Exporters
@@ -319,9 +321,9 @@ Note: Support for environment variables is optional.
 | Honors non-retryable responses                                                 | X        | +  | -    | -  | +           | +    | -      |     |      | -   | -    | -     |
 | Honors throttling response                                                     | X        | +  | -    | -  | +           | +    | -      |     |      | -   | -    | -     |
 | Multi-destination spec compliance                                              | X        | +  | -    |    | [-][py1109] |      | -      |     |      | -   | -    | -     |
-| SchemaURL in ResourceSpans and ScopeSpans                                      |          | +  | +    |    | +           |      | +      |     |      |     | -    |       |
-| SchemaURL in ResourceMetrics and ScopeMetrics                                  |          |    | +    |    | +           |      | -      |     |      |     | -    |       |
-| SchemaURL in ResourceLogs and ScopeLogs                                        |          |    | +    |    | +           |      | -      |     |      |     | -    |       |
+| SchemaURL in ResourceSpans and ScopeSpans                                      |          | +  | +    |    | +           |      | +      | +   |      |     | -    |       |
+| SchemaURL in ResourceMetrics and ScopeMetrics                                  |          |    | +    |    | +           |      | -      | +   |      |     | -    |       |
+| SchemaURL in ResourceLogs and ScopeLogs                                        |          |    | +    |    | +           |      | -      | +   |      |     | -    |       |
 | Honors the [user agent spec](specification/protocol/exporter.md#user-agent)    |          |    |      |    |             |      |        | +   |      |     |      |       |
 | **[Zipkin](specification/trace/sdk_exporters/zipkin.md)**                      | Optional | Go  | Java | JS  | Python | Ruby | Erlang | PHP | Rust | C++ | .NET | Swift |
 | Zipkin V1 JSON                                                                 | X        | -  | +    |    | +           | -    | -      | -   | -    | -   | -    | -     |
@@ -360,12 +362,12 @@ Languages not covered by the OpenTracing project do not need to be listed here,
 
 | Feature                                                                                                 |Go |Java|JS |Python|Ruby|PHP|Rust|C++|.NET|Swift|
 |---------------------------------------------------------------------------------------------------------|---|----|---|------|----|---|----|---|----|-----|
-| [Create OpenTracing Shim](specification/compatibility/opentracing.md#create-an-opentracing-tracer-shim) |   |    |   |      |    |   |    |   |    |     |
-| [Tracer](specification/compatibility/opentracing.md#tracer-shim)                                        |   |    |   |      |    |   |    |   |    |     |
-| [Span](specification/compatibility/opentracing.md#span-shim)                                            |   |    |   |      |    |   |    |   |    |     |
-| [SpanContext](specification/compatibility/opentracing.md#spancontext-shim)                              |   |    |   |      |    |   |    |   |    |     |
-| [ScopeManager](specification/compatibility/opentracing.md#scopemanager-shim)                            |   |    |   |      |    |   |    |   |    |     |
-| Error mapping for attributes/events                                                                     |   |    |   |      |    |   |    |   |    |     |
+| [Create OpenTracing Shim](specification/compatibility/opentracing.md#create-an-opentracing-tracer-shim) |   |    |   |      |    | + |    |   |    |     |
+| [Tracer](specification/compatibility/opentracing.md#tracer-shim)                                        |   |    |   |      |    | + |    |   |    |     |
+| [Span](specification/compatibility/opentracing.md#span-shim)                                            |   |    |   |      |    | + |    |   |    |     |
+| [SpanContext](specification/compatibility/opentracing.md#spancontext-shim)                              |   |    |   |      |    | + |    |   |    |     |
+| [ScopeManager](specification/compatibility/opentracing.md#scopemanager-shim)                            |   |    |   |      |    | + |    |   |    |     |
+| Error mapping for attributes/events                                                                     |   |    |   |      |    | + |    |   |    |     |
 | Migration to OpenTelemetry guide                                                                        |   |    |   |      |    |   |    |   |    |     |
 
 [py1003]: https://github.com/open-telemetry/opentelemetry-python/issues/1003

diff --git a/specification/common/attribute-naming.md b/specification/common/attribute-naming.md
@@ -133,6 +133,13 @@ To do that consider a few options:
   `myuniquemapapp.longitude` is likely fine). Make sure the application name
   does not clash with an existing semantic convention namespace.
 
+- It is not recommended to use existing OpenTelemetry semantic convention namespace
+  as a prefix for a new company- or application-specific attribute name. Doing so
+  may result in a name clash in the future, if OpenTelemetry decides to use that
+  same name for a different purpose or if some other third party instrumentation
+  decides to use that exact same attribute name and you combine that instrumentation
+  with your own.
+
 - The name may be generally applicable to applications in the industry. In that
   case consider submitting a proposal to this specification to add a new name to
   the semantic conventions, and if necessary also to add a new namespace.

diff --git a/specification/compatibility/prometheus_and_openmetrics.md b/specification/compatibility/prometheus_and_openmetrics.md
@@ -231,7 +231,7 @@ consecutive `_` characters MUST be replaced with a single `_` character.
 The Unit of an OTLP metric point SHOULD be converted to the equivalent unit in Prometheus when possible.  This includes:
 
 * Converting from abbreviations to full words (e.g. "ms" to "milliseconds").
-* Dropping the portions of the Unit within brackets (e.g. {packets}). Brackets MUST NOT be included in the resulting unit. A "count of foo" is considered unitless in Prometheus.
+* Dropping the portions of the Unit within brackets (e.g. {packet}). Brackets MUST NOT be included in the resulting unit. A "count of foo" is considered unitless in Prometheus.
 * Special case: Converting "1" to "ratio".
 * Converting "foo/bar" to "foo_per_bar".
 

diff --git a/specification/configuration/sdk-environment-variables.md b/specification/configuration/sdk-environment-variables.md
@@ -305,6 +305,10 @@ Known values for `OTEL_LOGS_EXPORTER` are:
 
 **Status**: [Mixed](../document-status.md)
 
+### Exemplar
+
+**Status**: [Experimental](../document-status.md)
+
 | Name            | Description | Default | Notes |
 |-----------------|---------|-------------|---------|
 | `OTEL_METRICS_EXEMPLAR_FILTER` | Filter for which measurements can become Exemplars. | `"trace_based"` | |

diff --git a/specification/logs/data-model-appendix.md b/specification/logs/data-model-appendix.md
@@ -64,7 +64,7 @@ this data model.
     <td>HOSTNAME</td>
     <td>string</td>
     <td>Describes the location where the event originated. Possible values are FQDN, IP address, etc.</td>
-    <td>Resource["host.hostname"]</td>
+    <td>Resource["host.name"]</td>
   </tr>
   <tr>
     <td>APP-NAME</td>
@@ -130,7 +130,7 @@ Rest of SDIDs -> Attributes["syslog.*"]</td>
     <td>Computer</td>
     <td>string</td>
     <td>The name of the computer on which the event occurred.</td>
-    <td>Resource["host.hostname"]</td>
+    <td>Resource["host.name"]</td>
   </tr>
   <tr>
     <td>EventID</td>
@@ -712,13 +712,13 @@ For example, on Windows this could be the host’s Active Directory domain or Ne
 <td>**Resource</td>
   </tr>
   <tr>
-    <td>host.hostname</td>
+    <td>host.name</td>
     <td>string</td>
     <td>Hostname of the host.
 
 It normally contains what the hostname command returns on the host machine.</td>
 
-<td>Resource["host.hostname"]</td>
+<td>Resource["host.name"]</td>
 
   </tr>
   <tr>

diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md
@@ -14,6 +14,7 @@ linkTitle: SDK
 - [MeterProvider](#meterprovider)
   * [MeterProvider Creation](#meterprovider-creation)
   * [Meter Creation](#meter-creation)
+  * [Configuration](#configuration)
   * [Shutdown](#shutdown)
   * [ForceFlush](#forceflush)
   * [View](#view)
@@ -112,11 +113,12 @@ 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.
 
-Configuration (i.e., [MetricExporters](#metricexporter),
-[MetricReaders](#metricreader) and [Views](#view)) MUST be managed solely by the
-`MeterProvider` and the SDK MUST provide a way to configure all options that are
-implemented by the SDK. This MAY be done at the time of MeterProvider creation
-if appropriate.
+### Configuration
+
+Configuration (i.e. [MetricExporters](#metricexporter),
+[MetricReaders](#metricreader) and [Views](#view)) 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
@@ -340,7 +342,7 @@ informs the SDK on the ways and means to compute
 [Aggregated Metrics](./data-model.md#opentelemetry-protocol-data-model)
 from incoming Instrument [Measurements](./api.md#measurement).
 
-Note: the term _aggregation_ is used instead of _aggregator_. It is recommended
+Note: the term _aggregation_ is used instead of _aggregator_. It is RECOMMENDED
 that implementors reserve the "aggregator" term for the future when the SDK
 allows custom aggregation implementations.
 
@@ -581,9 +583,8 @@ performing collection, such that observations made or produced by
 executing callbacks only apply to the intended `MetricReader` during
 collection.
 
-The implementation SHOULD disregard the accidental use of APIs
-appurtenant to asynchronous instruments outside of registered
-callbacks in the context of a single `MetricReader` collection.
+The implementation SHOULD disregard the use of asynchronous instrument
+APIs outside of registered callbacks.
 
 The implementation SHOULD use a timeout to prevent indefinite callback
 execution.

diff --git a/specification/metrics/semantic_conventions/runtime-environment-metrics.md b/specification/metrics/semantic_conventions/runtime-environment-metrics.md
@@ -306,7 +306,7 @@ This metric is obtained from [`ClassLoadingMXBean#getLoadedClassCount()`](https:
 
 This metric is [recommended](../metric-requirement-level.md#recommended).
 This metric is obtained from [`com.sun.management.OperatingSystemMXBean#getProcessCpuLoad()`](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getProcessCpuLoad()) on HotSpot
-and [`com.ibm.lang.management.OperatingSystemMXBean#getProcessCpuLoad()`](https://www.ibm.com/docs/api/v1/content/SSYKE2_8.0.0/com.ibm.java.api.80.doc/com.ibm.lang.management/com/ibm/lang/management/OperatingSystemMXBean.html#getProcessCpuLoad--) on J9.
+and [`com.ibm.lang.management.OperatingSystemMXBean#getProcessCpuLoad()`](https://www.ibm.com/docs/api/v1/content/SSYKE2_8.0.0/openj9/api/jdk8/jre/management/extension/com/ibm/lang/management/OperatingSystemMXBean.html#getProcessCpuLoad--) on J9.
 
 <!-- semconv metric.process.runtime.jvm.cpu.utilization(metric_table) -->
 | Name     | Instrument Type | Unit (UCUM) | Description    |
@@ -321,7 +321,7 @@ and [`com.ibm.lang.management.OperatingSystemMXBean#getProcessCpuLoad()`](https:
 
 This metric is [recommended](../metric-requirement-level.md#recommended).
 This metric is obtained from [`com.sun.management.OperatingSystemMXBean#getSystemCpuLoad()`](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getSystemCpuLoad()) on Java version 8..13, [`com.sun.management.OperatingSystemMXBean#getCpuLoad()`](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getCpuLoad()) on Java version 14+,
-and [`com.ibm.lang.management.OperatingSystemMXBean#getSystemCpuLoad()`](https://www.ibm.com/docs/api/v1/content/SSYKE2_8.0.0/com.ibm.java.api.80.doc/com.ibm.lang.management/com/ibm/lang/management/OperatingSystemMXBean.html#getSystemCpuLoad--) on J9.
+and [`com.ibm.lang.management.OperatingSystemMXBean#getSystemCpuLoad()`](https://www.ibm.com/docs/api/v1/content/SSYKE2_8.0.0/openj9/api/jdk8/jre/management/extension/com/ibm/lang/management/OperatingSystemMXBean.html#getSystemCpuLoad--) on J9.
 
 <!-- semconv metric.process.runtime.jvm.system.cpu.utilization(metric_table) -->
 | Name     | Instrument Type | Unit (UCUM) | Description    |

diff --git a/specification/protocol/README.md b/specification/protocol/README.md
@@ -1,8 +1,11 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: Protocol
+--->
+
 # OpenTelemetry Protocol
 
-This is the specification of new OpenTelemetry protocol (OTLP).
+The OpenTelemetry protocol (OTLP) specification has moved to
+[github.com/open-telemetry/opentelemetry-proto/docs/README.md](https://github.com/open-telemetry/opentelemetry-proto/blob/main/docs/README.md).
 
-- [Design Goals](design-goals.md).
-- [Requirements](requirements.md).
-- [Specification](otlp.md).
-- [SDK Exporter](exporter.md).
+For additional OTLP implementation requirements in the OpenTelemetry SDKs, see
+[SDK Exporter](exporter.md).