Remove local stubs of semantic conventions. (#3711)

open-telemetry · Oct 3, 2023 · 89f9bf3 · 89f9bf3
1 parent 4d454c0
commit 89f9bf3
Show file tree

Hide file tree

Showing 73 changed files with 42 additions and 7,112 deletions.
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
@@ -27,9 +27,8 @@ specification/metrics/  @open-telemetry/technical-committee @open-telemetry/spec
 experimental/logs/      @open-telemetry/technical-committee @open-telemetry/specs-approvers @open-telemetry/specs-logs-approvers
 specification/logs/     @open-telemetry/technical-committee @open-telemetry/specs-approvers @open-telemetry/specs-logs-approvers
 
-# Semantic Conventions owners (global + trace/metrics/logs/semconv)
-semantic_conventions/ @open-telemetry/technical-committee @open-telemetry/specs-approvers @open-telemetry/specs-semconv-approvers
-specification/trace/semantic_conventions/ @open-telemetry/technical-committee @open-telemetry/specs-approvers @open-telemetry/specs-trace-approvers @open-telemetry/specs-semconv-approvers
-specification/metrics/semantic_conventions/ @open-telemetry/technical-committee @open-telemetry/specs-approvers @open-telemetry/specs-metrics-approvers @open-telemetry/specs-semconv-approvers
-specification/logs/semantic_conventions/ @open-telemetry/technical-committee @open-telemetry/specs-approvers @open-telemetry/specs-logs-approvers @open-telemetry/specs-semconv-approvers
-specification/resource/semantic_conventions/ @open-telemetry/technical-committee @open-telemetry/specs-approvers @open-telemetry/specs-semconv-approvers
+# Semantic Conventions owners (global)
+specification/semantic-conventions.md @open-telemetry/technical-committee @open-telemetry/specs-approvers @open-telemetry/specs-semconv-approvers
+specification/telemetry-stability.md @open-telemetry/technical-committee @open-telemetry/specs-approvers @open-telemetry/specs-semconv-approvers
+# Note: Common is about naming conventions, relevant to semconv
+specification/common/ @open-telemetry/technical-committee @open-telemetry/specs-approvers @open-telemetry/specs-semconv-approvers
diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md
@@ -241,7 +241,7 @@ Disclaimer: this list of features is still a work in progress, please refer to t
 | Create empty                                                                                                                                |          | +  | +    | +  | +      | +    | +      | +   | +    | +   | +    | +     |
 | [Merge (v2)](specification/resource/sdk.md#merge)                                                                                           |          | +  | +    |    | +      | +    | +      | +   | +    | +   | +    |       |
 | Retrieve attributes                                                                                                                         |          | +  | +    | +  | +      | +    | +      | +   | +    | +   | +    | +     |
-| [Default value](specification/resource/semantic_conventions/README.md#semantic-attributes-with-sdk-provided-default-value) for service.name |          | +  | +    |    | +      | +    | +      | +   |      | +   | +    |       |
+| [Default value](https://github.com/open-telemetry/semantic-conventions/tree/main/docs/resource#semantic-attributes-with-dedicated-environment-variable) for service.name |          | +  | +    |    | +      | +    | +      | +   |      | +   | +    |       |
 | [Resource detector](specification/resource/sdk.md#detecting-resource-information-from-the-environment) interface/mechanism                  |          | +  | +    | +  | +      | +    | +      | +   | +    | +   | +    | +     |
 | [Resource detectors populate Schema URL](specification/resource/sdk.md#detecting-resource-information-from-the-environment)                 |          | +  | +    |    |        |      | -      | +   |      |     | -    |       |
 

diff --git a/specification/common/attribute-naming.md b/specification/common/attribute-naming.md
@@ -65,7 +65,7 @@ Names SHOULD follow these rules:
   values: the executable name and command arguments.
 
 - When an attribute represents a measurement,
-  [Metric Name Pluralization Guidelines](../metrics/semantic_conventions/README.md#pluralization)
+  [Metric Name Pluralization Guidelines](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/metrics.md#pluralization)
   SHOULD be followed for the attribute name.
 
 ## Name Reuse Prohibition
@@ -83,11 +83,7 @@ denote old attribute names in rename operations).
   of a namespace.
 
 - When coming up with a new semantic convention make sure to check existing
-  namespaces for
-  [Resources](../resource/semantic_conventions/README.md),
-  [Spans](../trace/semantic_conventions/README.md),
-  and
-  [Metrics](../metrics/semantic_conventions/README.md)
+  namespaces ([Semantic Conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/README.md))
   to see if the new name fits.
 
 - When a new namespace is necessary consider whether it should be a top-level
@@ -111,11 +107,7 @@ denote old attribute names in rename operations).
 ## Recommendations for Application Developers
 
 As an application developer when you need to record an attribute first consult
-existing semantic conventions for
-[Resources](../resource/semantic_conventions/README.md),
-[Spans](../trace/semantic_conventions/README.md),
-and
-[Metrics](../metrics/semantic_conventions/README.md).
+existing [semantic conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/README.md).
 If an appropriate name does not exists you will need to come up with a new name.
 To do that consider a few options:
 

diff --git a/specification/common/attribute-requirement-level.md b/specification/common/attribute-requirement-level.md
@@ -34,7 +34,8 @@ For example, Metric attributes that may have high cardinality can only be define
 
 A semantic convention that refers to an attribute from another semantic convention MAY modify the requirement level within its own scope. Otherwise, requirement level from the referred semantic convention applies.
 
-For example, [Database semantic convention](../trace/semantic_conventions/database.md) references `network.transport` attribute defined in [General attributes](../trace/semantic_conventions/span-general.md) with `Conditionally Required` level on it.
+<!-- TODO(jsuereth) - make examples not break on changes to semconv -->
+For example, [Database semantic convention](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/database/README.md) references `network.transport` attribute defined in [General attributes](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/README.md) with `Conditionally Required` level on it.
 
 ## Required
 
@@ -50,7 +51,8 @@ All instrumentations MUST populate the attribute when the given condition is sat
 
 When a `Conditionally Required` attribute's condition is not satisfied, and there is no requirement to populate the attribute, semantic conventions MAY provide special instructions on how to handle it. If no instructions are given and if instrumentation can populate the attribute, instrumentation SHOULD use the `Opt-In` requirement level on the attribute.
 
-For example, `server.address` is `Conditionally Required` by the [Database convention](../trace/semantic_conventions/database.md) when available. When `server.socket.address` is available instead, instrumentation can do a DNS lookup, cache and populate `server.address`, but only if the user explicitly enables the instrumentation to do so, considering the performance issues that DNS lookups introduce.
+<!-- TODO(jsuereth) - make examples not break on changes to semconv -->
+For example, `server.address` is `Conditionally Required` by the [Database convention](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/database/README.md) when available. When `server.socket.address` is available instead, instrumentation can do a DNS lookup, cache and populate `server.address`, but only if the user explicitly enables the instrumentation to do so, considering the performance issues that DNS lookups introduce.
 
 ## Recommended
 

diff --git a/specification/compatibility/opencensus.md b/specification/compatibility/opencensus.md
@@ -17,7 +17,7 @@ instrumented codebases.
 Migrating from OpenCensus to OpenTelemetry may require breaking changes to the telemetry produced
 because of:
 
-* Different or new semantic conventions for names and attributes (e.g. [`grpc.io/server/server_latency`](https://github.com/census-instrumentation/opencensus-specs/blob/master/stats/gRPC.md#server) vs [`rpc.server.duration`](/specification/metrics/semantic_conventions/rpc-metrics.md#rpc-server))
+* Different or new semantic conventions for names and attributes (e.g. [`grpc.io/server/server_latency`](https://github.com/census-instrumentation/opencensus-specs/blob/master/stats/gRPC.md#server) vs [`rpc.server.duration`](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/rpc/rpc-metrics.md#metric-rpcserverduration))
 * Data model differences (e.g. OpenCensus supports [SumOfSquaredDeviations](https://github.com/census-instrumentation/opencensus-proto/blob/v0.3.0/src/opencensus/proto/metrics/v1/metrics.proto#L195), OTLP does not)
 * Instrumentation API feature differences (e.g. OpenCensus supports [context-based attributes](https://github.com/census-instrumentation/opencensus-specs/blob/master/stats/Record.md#recording-stats)), OTel does not)
 * Differences between equivalent OC and OTel exporters (e.g. the OpenTelemetry Prometheus exporter [adds type and unit suffixes](prometheus_and_openmetrics.md#metric-metadata-1); OpenCensus [does not](https://github.com/census-ecosystem/opencensus-go-exporter-prometheus/blob/v0.4.1/prometheus.go#L227))

diff --git a/specification/compatibility/opentracing.md b/specification/compatibility/opentracing.md
@@ -136,7 +136,7 @@ with **Child Of** type in the entire list is used as parent, else the
 the first `SpanContext` is used as parent. All values in the list
 MUST be added as [Link](../trace/api.md)s with the reference type value
 as a `Link` attribute, i.e.
-[opentracing.ref_type](../trace/semantic_conventions/compatibility.md#opentracing)
+[opentracing.ref_type](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/trace-compatibility.md#opentracing)
 set to `follows_from` or `child_of`.
 
 If a list of `Span` references is specified, the union of their
@@ -396,7 +396,7 @@ the pair set, or else fallback to use the `log` literal string.
 If pair set contains an `event=error` entry, the values MUST be
 [mapped](https://github.com/opentracing/specification/blob/master/semantic_conventions.md#log-fields-table)
 to an `Event` with the conventions outlined in the
-[Exception semantic conventions](../trace/semantic_conventions/exceptions.md) document:
+[Exception semantic conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/exceptions/exceptions-spans.md) document:
 
 - If an entry with `error.object` key exists and the value is a language-specific
   error object, a call to `RecordException(e)` is performed along the rest of

diff --git a/specification/compatibility/prometheus_and_openmetrics.md b/specification/compatibility/prometheus_and_openmetrics.md
@@ -402,7 +402,7 @@ labels distinguish targets and are expected to be present on metrics exposed on
 a Prometheus pull exporter (a ["federated"](https://prometheus.io/docs/prometheus/latest/federation/)
 Prometheus endpoint) or pushed via Prometheus remote-write. In OTLP, the
 `service.name`, `service.namespace`, and `service.instance.id` triplet is
-[required to be unique](../resource/semantic_conventions/README.md#service),
+[required to be unique](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/resource/README.md#service),
 which makes them good candidates to use to construct `job` and `instance`. In
 the collector Prometheus exporters, the `service.name` and `service.namespace`
 attributes MUST be combined as `<service.namespace>/<service.name>`, or

diff --git a/specification/configuration/sdk-environment-variables.md b/specification/configuration/sdk-environment-variables.md
@@ -77,8 +77,8 @@ For example, the value `12000` indicates 12000 milliseconds, i.e., 12 seconds.
 | Name                     | Description                                                                                                   | Default                                                                                                                                          | Notes                                                                                                                                                                                                                                                                                    |
 |--------------------------|---------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | OTEL_SDK_DISABLED        | Disable the SDK for all signals                                                                               | false                                                                                                                                            | Boolean value. If "true", a no-op SDK implementation will be used for all telemetry signals. Any other value or absence of the variable will have no effect and the SDK will remain enabled. This setting has no effect on propagators configured through the OTEL_PROPAGATORS variable. |
-| OTEL_RESOURCE_ATTRIBUTES | Key-value pairs to be used as resource attributes                                                             | See [Resource semantic conventions](../resource/semantic_conventions/README.md#semantic-attributes-with-sdk-provided-default-value) for details. | See [Resource SDK](../resource/sdk.md#specifying-resource-information-via-an-environment-variable) for more details.                                                                                                                                                                     |
-| OTEL_SERVICE_NAME        | Sets the value of the [`service.name`](../resource/semantic_conventions/README.md#service) resource attribute |                                                                                                                                                  | If `service.name` is also provided in `OTEL_RESOURCE_ATTRIBUTES`, then `OTEL_SERVICE_NAME` takes precedence.                                                                                                                                                                             |
+| OTEL_RESOURCE_ATTRIBUTES | Key-value pairs to be used as resource attributes                                                             | See [Resource semantic conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/resource/README.md#semantic-attributes-with-dedicated-environment-variable) for details. | See [Resource SDK](../resource/sdk.md#specifying-resource-information-via-an-environment-variable) for more details.                                                                                                                                                                     |
+| OTEL_SERVICE_NAME        | Sets the value of the [`service.name`](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/resource/README.md#service) resource attribute |                                                                                                                                                  | If `service.name` is also provided in `OTEL_RESOURCE_ATTRIBUTES`, then `OTEL_SERVICE_NAME` takes precedence.                                                                                                                                                                             |
 | OTEL_LOG_LEVEL           | Log level used by the SDK logger                                                                              | "info"                                                                                                                                           |                                                                                                                                                                                                                                                                                          |
 | OTEL_PROPAGATORS         | Propagators to be used as a comma-separated list                                                              | "tracecontext,baggage"                                                                                                                           | Values MUST be deduplicated in order to register a `Propagator` only once.                                                                                                                                                                                                               |
 | OTEL_TRACES_SAMPLER      | Sampler to be used for traces                                                                                 | "parentbased_always_on"                                                                                                                          | See [Sampling](../trace/sdk.md#sampling)                                                                                                                                                                                                                                                 |

diff --git a/specification/glossary.md b/specification/glossary.md
@@ -117,7 +117,7 @@ Synonym: *Auto-instrumentation*.
 Denotes the library that implements the *OpenTelemetry API*.
 
 See [Library Guidelines](library-guidelines.md#sdk-implementation) and
-[Library resource semantic conventions](resource/semantic_conventions/README.md#telemetry-sdk).
+[Library resource semantic conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/resource/README.md#telemetry-sdk).
 
 ### Constructors
 

diff --git a/specification/logs/README.md b/specification/logs/README.md
@@ -444,5 +444,4 @@ standard output.
 * [Logs SDK](./sdk.md)
 * [Logs Data Model](./data-model.md)
 * [Event API](./event-api.md)
-* [Semantic Conventions](./semantic_conventions/README.md)
 * [Trace Context in non-OTLP Log Formats](../compatibility/logging_trace_context.md)
diff --git a/specification/logs/data-model-appendix.md b/specification/logs/data-model-appendix.md
@@ -794,7 +794,7 @@ All other fields |                    |
 \* Not yet formalized into ECS.
 
 \*\* A resource that doesn’t exist in the
-[OpenTelemetry resource semantic convention](../resource/semantic_conventions/README.md).
+[OpenTelemetry resource semantic convention](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/resource/README.md).
 
 This is a selection of the most relevant fields. See
 [for the full reference](https://www.elastic.co/guide/en/ecs/current/ecs-field-reference.html)

diff --git a/specification/logs/data-model.md b/specification/logs/data-model.md
@@ -425,7 +425,7 @@ the record or about the infrastructure where the application runs. Data formats
 that represent this data model may be designed in a manner that allows the
 `Resource` field to be recorded only once per batch of log records that come
 from the same source. SHOULD follow OpenTelemetry
-[semantic conventions for Resources](../resource/semantic_conventions/README.md).
+[semantic conventions for Resources](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/resource/README.md).
 This field is optional.
 
 ### Field: `InstrumentationScope`
@@ -450,8 +450,7 @@ Description: Additional information about the specific event occurrence. Unlike
 the `Resource` field, which is fixed for a particular source, `Attributes` can
 vary for each occurrence of the event coming from the same source. Can contain
 information about the request context (other than TraceId/SpanId). SHOULD follow
-OpenTelemetry [semantic conventions for Log Attributes](./semantic_conventions/README.md) or
-[semantic conventions for Span Attributes](../trace/semantic_conventions/README.md).
+OpenTelemetry [semantic conventions for attributes](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/README.md).
 This field is optional.
 
 #### Errors and Exceptions
@@ -460,7 +459,7 @@ Additional information about errors and/or exceptions that are associated with
 a log record MAY be included in the structured data in the `Attributes` section
 of the record.
 If included, they MUST follow the OpenTelemetry
-[semantic conventions for exception-related attributes](./semantic_conventions/exceptions.md#attributes).
+[semantic conventions for exception-related attributes](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/exceptions/exceptions-logs.md).
 
 ## Example Log Records