From 6936974177973c981747e8ebcc35802d3883e63d Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Thu, 11 May 2023 11:47:49 -0400 Subject: [PATCH] Fix links up to the logs/metrics/resources directories. --- .../logs/semantic_conventions/README.md | 2 +- .../semantic_conventions/feature-flags.md | 8 ++-- .../logs/semantic_conventions/media.md | 2 +- .../metrics/metric-requirement-level.md | 42 +++++++++++++++++++ .../metrics/semantic_conventions/README.md | 4 +- .../semantic_conventions/http-metrics.md | 8 ++-- .../runtime-environment-metrics.md | 2 +- .../resource/semantic_conventions/README.md | 8 ++-- .../trace/semantic_conventions/http.md | 16 +++---- 9 files changed, 67 insertions(+), 25 deletions(-) create mode 100644 specification/metrics/metric-requirement-level.md diff --git a/specification/logs/semantic_conventions/README.md b/specification/logs/semantic_conventions/README.md index c0fba6e39c..7b2809e57e 100644 --- a/specification/logs/semantic_conventions/README.md +++ b/specification/logs/semantic_conventions/README.md @@ -17,5 +17,5 @@ The following semantic conventions for events are defined: * [Events](events.md): Semantic attributes that must be used to represent Events using log data model. Apart from semantic conventions for logs, [traces](../../trace/semantic_conventions/README.md), and [metrics](../../metrics/semantic_conventions/README.md), -OpenTelemetry also defines the concept of overarching [Resources](../../resource/sdk.md) with their own +OpenTelemetry also defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/sdk.md) with their own [Resource Semantic Conventions](../../resource/semantic_conventions/README.md). diff --git a/specification/logs/semantic_conventions/feature-flags.md b/specification/logs/semantic_conventions/feature-flags.md index 8ea7c4a152..b14c6df10d 100644 --- a/specification/logs/semantic_conventions/feature-flags.md +++ b/specification/logs/semantic_conventions/feature-flags.md @@ -8,8 +8,8 @@ No changes to this document are allowed. **Status**: [Experimental](../../document-status.md) This document defines semantic conventions for recording feature flag evaluations as -a [log record](../data-model.md#log-and-event-record-definition) emitted through the -[Logger API](../bridge-api.md#emit-a-logrecord). +a [log record](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/data-model.md#log-and-event-record-definition) emitted through the +[Logger API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/bridge-api.md#emit-a-logrecord). This is useful when a flag is evaluated outside of a transaction context such as when the application loads or on a timer. To record a flag evaluation as a part of a transaction context, @@ -29,14 +29,14 @@ section of the trace semantic convention for feature flag evaluations. ## Recording an Evaluation Feature flag evaluations SHOULD be recorded as attributes on the -[LogRecord](../data-model.md#log-and-event-record-definition) passed to the [Logger](../bridge-api.md#logger) emit +[LogRecord](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/data-model.md#log-and-event-record-definition) passed to the [Logger](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/bridge-api.md#logger) emit operations. Evaluations MAY be recorded on "logs" or "events" depending on the context. ## Attributes The table below indicates which attributes should be added to the -[LogRecord](../data-model.md#log-and-event-record-definition) and their types. +[LogRecord](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/data-model.md#log-and-event-record-definition) and their types. The event name MUST be `feature_flag`. diff --git a/specification/logs/semantic_conventions/media.md b/specification/logs/semantic_conventions/media.md index 031c77a702..62d22c5cd3 100644 --- a/specification/logs/semantic_conventions/media.md +++ b/specification/logs/semantic_conventions/media.md @@ -26,7 +26,7 @@ This document describes attributes for log media in OpenTelemetry. Log media are ## Log Media -**Note:** The OpenTelemetry specification defines a [Resource](../../resource/sdk.md#resource-sdk) as `an immutable representation of the entity producing telemetry`. +**Note:** The OpenTelemetry specification defines a [Resource](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/sdk.md#resource-sdk) as `an immutable representation of the entity producing telemetry`. The following attributes do not describe entities that produce telemetry. Rather, they describe mechanisms of log transmission. As such, these should be recorded as Log Record attributes when applicable. They should not be recorded as Resource attributes. diff --git a/specification/metrics/metric-requirement-level.md b/specification/metrics/metric-requirement-level.md new file mode 100644 index 0000000000..2d1c0918c1 --- /dev/null +++ b/specification/metrics/metric-requirement-level.md @@ -0,0 +1,42 @@ +# Metric Requirement Levels + +This document is the same as [the specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/metric-requirement-level.md). + +**Status**: [Stable](../document-status.md) + +
+Table of Contents + + + +- [Required](#required) +- [Recommended](#recommended) +- [Opt-In](#opt-in) + + + +
+ +The following metric requirement levels are specified: + +- [Required](#required) +- [Recommended](#recommended) +- [Opt-In](#opt-in) + +## Required + +All instrumentations MUST emit the metric. +A semantic convention defining a Required metric expects that an absolute majority of instrumentation libraries and applications are able to efficiently emit it. + +## Recommended + +Instrumentations SHOULD emit the metric by default if it's readily available and can be efficiently emitted. Instrumentations MAY offer a configuration option to disable Recommended metrics. + +Instrumentations that decide not to emit `Recommended` metrics due to performance, security, privacy, or other consideration by default, SHOULD allow for opting in to emitting them as defined for the `Opt-In` requirement level if the metrics are logically applicable. + +## Opt-In + +Instrumentations SHOULD emit the metric if and only if the user configures the instrumentation to do so. +Instrumentation that doesn't support configuration MUST NOT emit `Opt-In` metrics. + +This attribute requirement level is recommended for metrics that are particularly expensive to retrieve or might pose a security or privacy risk. These should therefore only be enabled deliberately by a user making an informed decision. \ No newline at end of file diff --git a/specification/metrics/semantic_conventions/README.md b/specification/metrics/semantic_conventions/README.md index 1bd0f04143..6454a4cff1 100644 --- a/specification/metrics/semantic_conventions/README.md +++ b/specification/metrics/semantic_conventions/README.md @@ -40,7 +40,7 @@ The following semantic conventions surrounding metrics are defined: Apart from semantic conventions for metrics and [traces](../../trace/semantic_conventions/README.md), OpenTelemetry also -defines the concept of overarching [Resources](../../resource/sdk.md) with +defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/sdk.md) with their own [Resource Semantic Conventions](../../resource/semantic_conventions/README.md). @@ -102,7 +102,7 @@ usable. When building components that interoperate between OpenTelemetry and a system using the OpenMetrics exposition format, use the -[OpenMetrics Guidelines](../../compatibility/prometheus_and_openmetrics.md). +[OpenMetrics Guidelines](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/compatibility/prometheus_and_openmetrics.md). ### Pluralization diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md index 49de880337..ecf4e5132f 100644 --- a/specification/metrics/semantic_conventions/http-metrics.md +++ b/specification/metrics/semantic_conventions/http-metrics.md @@ -81,7 +81,7 @@ of `[ 0, 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, | [`network.protocol.version`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended | | [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [3] | `example.com` | Required | | [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | -| [`url.scheme`](../../common/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | +| `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | **[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. SHOULD include the [application root](/specification/trace/semantic_conventions/http.md#http-server-definitions) if there is one. @@ -124,7 +124,7 @@ This metric is optional. | `http.request.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | | [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [1] | `example.com` | Required | | [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [2] | `80`; `8080`; `443` | Conditionally Required: [3] | -| [`url.scheme`](../../common/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | +| `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | **[1]:** Determined by using the first of the following that applies @@ -166,7 +166,7 @@ This metric is optional. | [`network.protocol.version`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended | | [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [3] | `example.com` | Required | | [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | -| [`url.scheme`](../../common/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | +| `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | **[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. SHOULD include the [application root](/specification/trace/semantic_conventions/http.md#http-server-definitions) if there is one. @@ -213,7 +213,7 @@ This metric is optional. | [`network.protocol.version`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended | | [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [3] | `example.com` | Required | | [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | -| [`url.scheme`](../../common/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | +| `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | **[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. SHOULD include the [application root](/specification/trace/semantic_conventions/http.md#http-server-definitions) if there is one. diff --git a/specification/metrics/semantic_conventions/runtime-environment-metrics.md b/specification/metrics/semantic_conventions/runtime-environment-metrics.md index 7548c25fb6..cb5334b0ce 100644 --- a/specification/metrics/semantic_conventions/runtime-environment-metrics.md +++ b/specification/metrics/semantic_conventions/runtime-environment-metrics.md @@ -222,7 +222,7 @@ This metric is obtained by subscribing to [`GarbageCollectionNotificationInfo`](https://docs.oracle.com/javase/8/docs/jre/api/management/extension/com/sun/management/GarbageCollectionNotificationInfo.html) events provided by [`GarbageCollectorMXBean`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/GarbageCollectorMXBean.html). The duration value is obtained from [`GcInfo`](https://docs.oracle.com/javase/8/docs/jre/api/management/extension/com/sun/management/GcInfo.html#getDuration--) This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](../../metrics/api.md#instrument-advice) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-advice) of `[]` (single bucket histogram capturing count, sum, min, max). diff --git a/specification/resource/semantic_conventions/README.md b/specification/resource/semantic_conventions/README.md index b8e62e84f0..3ca3e1161f 100644 --- a/specification/resource/semantic_conventions/README.md +++ b/specification/resource/semantic_conventions/README.md @@ -7,7 +7,7 @@ No changes to this document are allowed. **Status**: [Mixed](../../document-status.md) -This document defines standard attributes for resources. These attributes are typically used in the [Resource](../sdk.md) and are also recommended to be used anywhere else where there is a need to describe a resource in a consistent manner. The majority of these attributes are inherited from +This document defines standard attributes for resources. These attributes are typically used in the [Resource](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/sdk.md) and are also recommended to be used anywhere else where there is a need to describe a resource in a consistent manner. The majority of these attributes are inherited from [OpenCensus Resource standard](https://github.com/census-instrumentation/opencensus-specs/blob/master/resource/StandardResources.md). @@ -45,7 +45,7 @@ This document defines standard attributes for resources. These attributes are ty Attributes are grouped logically by the type of the concept that they described. Attributes in the same group have a common prefix that ends with a dot. For example all attributes that describe Kubernetes properties start with "k8s." -See [Attribute Requirement Levels](../../common/attribute-requirement-level.md) for details on when attributes +See [Attribute Requirement Levels](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/common/attribute-requirement-level.md) for details on when attributes should be included. ## Attributes with Special Handling @@ -57,14 +57,14 @@ Given their significance some resource attributes are treated specifically as de ### Semantic Attributes with Dedicated Environment Variable These are the attributes which MAY be configurable via a dedicated environment variable -as specified in [OpenTelemetry Environment Variable Specification](../../configuration/sdk-environment-variables.md): +as specified in [OpenTelemetry Environment Variable Specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md): - [`service.name`](#service) ## Semantic Attributes with SDK-provided Default Value These are the attributes which MUST be provided by the SDK -as specified in the [Resource SDK specification](../sdk.md#sdk-provided-resource-attributes): +as specified in the [Resource SDK specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/sdk.md#sdk-provided-resource-attributes): - [`service.name`](#service) - [`telemetry.sdk` group](#telemetry-sdk) diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index 65a4b95bef..5e3996e5b1 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -167,7 +167,7 @@ For an HTTP client span, `SpanKind` MUST be `Client`. | [`server.socket.address`](span-general.md) | string | Physical server IP address or Unix socket address. | `10.5.3.2` | Recommended: If different than `server.address`. | | [`server.socket.domain`](span-general.md) | string | The domain name of an immediate peer. [5] | `proxy.example.com` | Recommended | | [`server.socket.port`](span-general.md) | int | Physical server port. | `16456` | Recommended: If different than `server.port`. | -| [`url.full`](../../common/url.md) | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [6] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv`; `//localhost` | Required | +| `url.full` | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [6] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv`; `//localhost` | Required | **[1]:** The resend count SHOULD be updated each time an HTTP request gets resent by the client, regardless of what was the cause of the resending (e.g. redirection, authorization failure, 503 Server Unavailable, network issues, or any other). @@ -194,7 +194,7 @@ Following attributes MUST be provided **at span creation time** (when provided a * [`server.address`](span-general.md) * [`server.port`](span-general.md) -* [`url.full`](../../common/url.md) +* `url.full` Note that in some cases host and port identifiers in the `Host` header might be different from the `server.address` and `server.port`, in this case instrumentation MAY populate `Host` header on `http.request.header.host` attribute even if it's not enabled by user. @@ -284,9 +284,9 @@ If the route cannot be determined, the `name` attribute MUST be set as defined i | [`server.port`](span-general.md) | int | Port of the local HTTP server that received the request. [5] | `80`; `8080`; `443` | Conditionally Required: [6] | | [`server.socket.address`](span-general.md) | string | Local socket address. Useful in case of a multi-IP host. | `10.5.3.2` | Opt-In | | [`server.socket.port`](span-general.md) | int | Local socket port. Useful in case of a multi-port host. | `16456` | Opt-In | -| [`url.path`](../../common/url.md) | string | The [URI path](https://www.rfc-editor.org/rfc/rfc3986#section-3.3) component [7] | `/search` | Required | -| [`url.query`](../../common/url.md) | string | The [URI query](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) component [8] | `q=OpenTelemetry` | Recommended | -| [`url.scheme`](../../common/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | +| `url.path` | string | The [URI path](https://www.rfc-editor.org/rfc/rfc3986#section-3.3) component [7] | `/search` | Required | +| `url.query` | string | The [URI query](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) component [8] | `q=OpenTelemetry` | Recommended | +| `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | **[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. SHOULD include the [application root](/specification/trace/semantic_conventions/http.md#http-server-definitions) if there is one. @@ -322,9 +322,9 @@ Following attributes MUST be provided **at span creation time** (when provided a * [`server.address`](span-general.md) * [`server.port`](span-general.md) -* [`url.path`](../../common/url.md) -* [`url.query`](../../common/url.md) -* [`url.scheme`](../../common/url.md) +* `url.path` +* `url.query` +* `url.scheme` `http.route` MUST be provided at span creation time if and only if it's already available. If it becomes available after span starts, instrumentation MUST populate it anytime before span ends.