From 8e0a1ab9a4ebdb10e839a62280e3196928e17651 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Mon, 4 Nov 2024 23:13:19 +0100 Subject: [PATCH] More lint. --- oteps/0111-auto-resource-detection.md | 2 +- oteps/0119-standard-system-metrics.md | 2 +- oteps/0152-telemetry-schemas.md | 7 ++--- oteps/0156-columnar-encoding.md | 4 +-- oteps/0182-otlp-remote-parent.md | 2 +- ...-elastic-common-schema-in-opentelemetry.md | 26 +++++++++---------- oteps/0202-events-and-logs-api.md | 4 +-- oteps/0225-configuration.md | 2 +- oteps/0227-separate-semantic-conventions.md | 14 +++++----- oteps/0258-env-context-baggage-carriers.md | 4 +-- oteps/0265-event-vision.md | 4 +-- oteps/0266-move-oteps-to-spec.md | 4 +-- oteps/entities/0256-entities-data-model.md | 6 ++--- oteps/entities/0264-resource-and-entities.md | 4 +-- oteps/logs/0091-logs-vocabulary.md | 6 ++--- oteps/logs/0092-logs-vision.md | 4 +-- oteps/logs/0097-log-data-model.md | 8 +++--- oteps/logs/0150-logging-library-sdk.md | 10 +++---- ...-metric-instrument-optional-refinements.md | 6 ++--- .../0098-metric-instruments-explained.md | 2 +- .../0146-metrics-prototype-scenarios.md | 12 ++++----- oteps/profiles/0239-profiles-data-model.md | 1 - oteps/trace/0002-remove-spandata.md | 2 +- oteps/trace/0168-sampling-propagation.md | 8 +++--- oteps/trace/0170-sampling-probability.md | 2 -- .../0173-messaging-semantic-conventions.md | 16 ++++++------ oteps/trace/0174-http-semantic-conventions.md | 18 ++++++------- ...emantic-conventions-context-propagation.md | 2 +- ...ing-semantic-conventions-span-structure.md | 14 +++++----- .../0235-sampling-threshold-in-trace-state.md | 6 ++--- 30 files changed, 98 insertions(+), 104 deletions(-) diff --git a/oteps/0111-auto-resource-detection.md b/oteps/0111-auto-resource-detection.md index 1359bfd30da..c4fad09e728 100644 --- a/oteps/0111-auto-resource-detection.md +++ b/oteps/0111-auto-resource-detection.md @@ -157,7 +157,7 @@ specification](https://github.com/census-instrumentation/opencensus-specs/blob/m resource detection code is currently in the JS resource package, so this would need to be separated. - Environment variable resource detection in Java SDK - [here](https://github.com/open-telemetry/opentelemetry-java/blob/master/sdk/src/main/java/io/opentelemetry/sdk/resources/EnvVarResource.java): + [here](https://github.com/open-telemetry/opentelemetry-java/blob/main/sdk-extensions/autoconfigure/src/main/java/io/opentelemetry/sdk/autoconfigure/ResourceConfiguration.java): This implementation does not currently include a detector interface, but is used by default for tracer and meter providers diff --git a/oteps/0119-standard-system-metrics.md b/oteps/0119-standard-system-metrics.md index 3eda895b468..5e79f8c38be 100644 --- a/oteps/0119-standard-system-metrics.md +++ b/oteps/0119-standard-system-metrics.md @@ -28,7 +28,7 @@ There are already a few implementations of system and/or runtime metric collecti * This package does not export metrics with labels, instead exporting individual metrics. * [Overview of collected metrics](https://docs.google.com/spreadsheets/d/1r50cC9ass0A8SZIg2ZpLdvZf6HmQJsUSXFOu-rl4yaY/edit#gid=0). - **Python** - * Python [has instrumentation](https://github.com/open-telemetry/opentelemetry-python/tree/master/ext/opentelemetry-ext-system-metrics) to collect some system and runtime metrics. + * Python [has instrumentation](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-system-metrics) to collect some system and runtime metrics. * Collects system CPU, memory, and network metrics. * Collects runtime CPU, memory, and GC metrics. * Makes use of labels, similar to the Collector. diff --git a/oteps/0152-telemetry-schemas.md b/oteps/0152-telemetry-schemas.md index 230ce958434..344ad4bb255 100644 --- a/oteps/0152-telemetry-schemas.md +++ b/oteps/0152-telemetry-schemas.md @@ -25,14 +25,14 @@ * [Schema File Format Number](#schema-file-format-number) * [OTLP Changes](#otlp-changes) * [API and SDK Changes](#api-and-sdk-changes) -* [OpenTelemetry Schema 1.0.0](#opentelemetry-schema-100) +* [OpenTelemetry Schema](#opentelemetry-schema) * [Performance Impact](#performance-impact) * [Open Questions](#open-questions) * [Future Possibilities](#future-possibilities) * [Parent Schema](#parent-schema) - * [Collector Processor](#collector-processor) * [Current State in Schema](#current-state-in-schema) * [Other Transformation Types](#other-transformation-types) + * [Version Convertability](#version-convertability) * [Alternates Considered](#alternates-considered) * [Name Aliases](#name-aliases) * [Schema Negotiation](#schema-negotiation) @@ -816,9 +816,6 @@ Since 1.2.0 is the first published version of OpenTelemetry schema there are no "changes" section and we omitted all previous versions from the file since there is nothing to record for earlier versions. -This file SHOULD be available for retrieval at -[https://opentelemetry.io/schemas/1.2.0](https://opentelemetry.io/schemas/1.2.0) - All OpenTelemetry instrumentation solutions will follow this schema. ## Performance Impact diff --git a/oteps/0156-columnar-encoding.md b/oteps/0156-columnar-encoding.md index e9950be7f3b..e42c1c8b60f 100644 --- a/oteps/0156-columnar-encoding.md +++ b/oteps/0156-columnar-encoding.md @@ -624,7 +624,7 @@ Specifically: When Arrow is enabled, the OTelArrow receiver listens for both the standard unary gRPC service OTLP and OTel Arrow stream services. Each stream uses an instance of the OTel-Arrow-Adapter's -[Consumer](https://pkg.go.dev/github.com/f5/otel-arrow-adapter@v0.0.0-20230112224802-dafb6df21c97/pkg/otel/arrow_record#Consumer). Sets +[Consumer](https://pkg.go.dev/github.com/f5/otel-arrow-adapter/pkg/otel/arrow_record#Consumer). Sets `client.Metadata` in the Context. #### OTelArrow/gRPC Exporter @@ -637,7 +637,7 @@ restarting, while honoring the caller's context deadline, to avoid delays introd through the `exporterhelper` mechanism. Each stream uses an instance of the OTel-Arrow-Adapter's -[Producer](https://pkg.go.dev/github.com/f5/otel-arrow-adapter@v0.0.0-20230112224802-dafb6df21c97/pkg/otel/arrow_record#Producer). +[Producer](https://pkg.go.dev/github.com/f5/otel-arrow-adapter/pkg/otel/arrow_record#Producer). When a stream fails specifically because the server does not recognize the Arrow service, it will not restart. When all streams have failed in this manner, the connection downgrades by closing a channel, at which point the exporter behaves diff --git a/oteps/0182-otlp-remote-parent.md b/oteps/0182-otlp-remote-parent.md index c1bc2c8a82b..5bcfa3b1e50 100644 --- a/oteps/0182-otlp-remote-parent.md +++ b/oteps/0182-otlp-remote-parent.md @@ -54,7 +54,7 @@ A span can be considered an entry-point span if it has no parent (`parent_span_i The first part would be to update the trace protobuf, adding a `boolean parent_span_is_remote` field to the [`Span` message](https://github.com/open-telemetry/opentelemetry-proto/blob/b43e9b18b76abf3ee040164b55b9c355217151f3/opentelemetry/proto/trace/v1/trace.proto#L84). -[`SpanContext.IsRemote`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#isremote) identifies whether span context has been propagated from a remote parent. +[`SpanContext.IsRemote`](../specification/trace/api.md#isremote) identifies whether span context has been propagated from a remote parent. The OTLP exporter in each SDK would need to be updated to record this in the new `parent_span_is_remote` field. For backwards compatibility with older OTLP versions, the protobuf field should be `nullable` (`true`, `false`, or unspecified) diff --git a/oteps/0199-support-elastic-common-schema-in-opentelemetry.md b/oteps/0199-support-elastic-common-schema-in-opentelemetry.md index d9e0fb66ea3..a48cfcae655 100644 --- a/oteps/0199-support-elastic-common-schema-in-opentelemetry.md +++ b/oteps/0199-support-elastic-common-schema-in-opentelemetry.md @@ -44,7 +44,7 @@ In addition to the use case of structured logs, the maturity of ECS for SIEM (Se Another significant use case is providing first-class support for Kubernetes application logs, system logs, and application introspection events. We would also like to see support for structured events (e.g. [k8seventsreceiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/k8seventsreceiver)) and using 'content-type' to identify event types. -We'd like to see different categories of structured logs being well-supported in the [OTel Log Data Model](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/data-model.md), presumably through [semantic conventions for log attributes](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/data-model.md#field-attributes). For example, NGINX access logs and Apache access logs should be processed the same way as structured logs. This would help in trace and metric correlation with such log data as well as it would help grow the ecosystem of curated UIs provided by observability backends and monitoring dashboards (e.g. one single HTTP access log dashboard benefiting Apache httpd, Nginx, and HAProxy). +We'd like to see different categories of structured logs being well-supported in the [OTel Log Data Model](../specification/logs/data-model.md), presumably through [semantic conventions for log attributes](../specification/logs/data-model.md#field-attributes). For example, NGINX access logs and Apache access logs should be processed the same way as structured logs. This would help in trace and metric correlation with such log data as well as it would help grow the ecosystem of curated UIs provided by observability backends and monitoring dashboards (e.g. one single HTTP access log dashboard benefiting Apache httpd, Nginx, and HAProxy). ## Customer Motivation @@ -147,7 +147,7 @@ Example of a Nginx Access Log entry structured with ECS ## Principles -| Description | [OTel Logs and Event Record](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/data-model.md#log-and-event-record-definition) | [Elastic Common Schema (ECS)](https://www.elastic.co/guide/en/ecs/current/ecs-reference.html) | +| Description | [OTel Logs and Event Record](../specification/logs/data-model.md#log-and-event-record-definition) | [Elastic Common Schema (ECS)](https://www.elastic.co/guide/en/ecs/current/ecs-reference.html) | |-------------|-------------|--------| | Metadata shared by all the Log Messages / Spans / Metrics of an application instance | Resource Attributes | ECS fields | | Metadata specific to each Log Message / Span / Metric data point | Attributes | ECS Fields | @@ -158,7 +158,7 @@ Example of a Nginx Access Log entry structured with ECS ## Data Types -| Category | OTel Logs and Event Record (all or a subset of GRPC data types) | ECS Data Types | +| Category | OTel Logs and Event Record (all or a subset of GRPC data types) | ECS Data Types | |---|---|---| | Text | string | text, match_only_text, keyword constant_keyword, wildcard | | Dates | uint64 nanoseconds since Unix epoch | date, date_nanos | @@ -177,7 +177,7 @@ As the markdown code of the tables is hard to read and maintain with very long l - @@ -185,7 +185,7 @@ As the markdown code of the tables is hard to read and maintain with very long l - @@ -193,7 +193,7 @@ As the markdown code of the tables is hard to read and maintain with very long l - @@ -209,7 +209,7 @@ As the markdown code of the tables is hard to read and maintain with very long l - @@ -217,7 +217,7 @@ As the markdown code of the tables is hard to read and maintain with very long l - @@ -225,7 +225,7 @@ As the markdown code of the tables is hard to read and maintain with very long l - @@ -235,9 +235,9 @@ As the markdown code of the tables is hard to read and maintain with very long l @@ -290,5 +290,5 @@ Some areas that need to be addressed in the long run as ECS is integrated into O ensuring the OTel specification incorporates the changes to accommodate ECS, and a process for handling breaking changes if any (the proposal [Define semantic conventions and instrumentation stability #2180](https://github.com/open-telemetry/opentelemetry-specification/pull/2180) should tackle this point). Also, migration of existing naming (e.g. Prometheus exporter) to standardized convention (see -[Semantic Conventions for System Metrics](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/semantic_conventions/system-metrics.md) , -[Semantic Conventions for OS Process Metrics](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/semantic_conventions/process-metrics.md)). +[Semantic Conventions for System Metrics](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/system/system-metrics.md) , +[Semantic Conventions for OS Process Metrics](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/system/process-metrics.md)). diff --git a/oteps/0202-events-and-logs-api.md b/oteps/0202-events-and-logs-api.md index 6d1cd2e1878..b41151e7c27 100644 --- a/oteps/0202-events-and-logs-api.md +++ b/oteps/0202-events-and-logs-api.md @@ -20,7 +20,7 @@ Here are a few situations that require recording of Events, there will be more. - Standalone events that occur when there is no span in progress, such as errors, user interaction events and web vitals. - Recording kubernetes events - Collector Entity events [link](https://docs.google.com/document/d/1Tg18sIck3Nakxtd3TFFcIjrmRO_0GLMdHXylVqBQmJA/edit) -- Few other event systems described in [example mappings](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/data-model.md#appendix-a-example-mappings) in the data model. +- Few other event systems described in [example mappings](../specification/logs/data-model.md#appendix-a-example-mappings) in the data model. ### Can the current Log API interfaces be used for events? @@ -46,7 +46,7 @@ All Events will have a name and a domain. The name is MANDATORY. The domain will ### Events and Logs API -We also propose having an API interface for creating Events and Logs. Currently, there is only an SDK called [LogEmitterProvider](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/logging-library-sdk.md#logemitterprovider) for creating `LogRecord`s. +We also propose having an API interface for creating Events and Logs. Currently, there is only an SDK called [LoggerProvider](../specification/logs/sdk.md#loggerprovider) for creating `LogRecord`s. However, there is a question of whether OTel should have an API for logs. A part of the OTel community thinks that we should not have a full-fledged logging API unless there is a language that doesn't already have a plethora of logging libraries and APIs to choose from where it might make sense to define one. Further, we will not be able to have the [rich set of configuration options](https://logging.apache.org/log4j/2.x/manual/configuration.html) that some popular logging frameworks provide so the logging API in OTel will only become yet another API. However, it was noted that the Log Appender API is very similar to the API for Events and so instead of having API for Events and API for Log Appenders separately it was agreed to have one API for Events and Logs, and that the API for Logs is targeted only to Log Appenders. This will also keep it consistent with Traces and Metrics in having one API for each signal. diff --git a/oteps/0225-configuration.md b/oteps/0225-configuration.md index 6630d2fbab7..c48d49c264d 100644 --- a/oteps/0225-configuration.md +++ b/oteps/0225-configuration.md @@ -119,7 +119,7 @@ Create a `Configurer` from a [configuration model](#configuration-model). #### Get TracerProvider, MeterProvider, LoggerProvider -Interpret the [configuration model](#configuration-model) and return SDK TracerProvider, MeterProvider, LoggerProvider which strictly reflect the configuration object's details and ignores the [opentelemetry environment variable configuration scheme](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/sdk-environment-variables.md). +Interpret the [configuration model](#configuration-model) and return SDK TracerProvider, MeterProvider, LoggerProvider which strictly reflect the configuration object's details and ignores the [opentelemetry environment variable configuration scheme](../specification/configuration/sdk-environment-variables.md). ### Configuration model diff --git a/oteps/0227-separate-semantic-conventions.md b/oteps/0227-separate-semantic-conventions.md index ff144b58da1..427c019d0e2 100644 --- a/oteps/0227-separate-semantic-conventions.md +++ b/oteps/0227-separate-semantic-conventions.md @@ -27,7 +27,7 @@ This would *initially* have the following structure: - `trace/` - Contents of `{specification}/trace/semantic_conventions` - `metrics/` - Contents of `{specification}/metrics/semantic_conventions` - `logs/`- Contents of `{specification}/logs/semantic_conventions` - - `schemas/` - A new location for [Telemetry Schemas](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/schemas/README.md) + - `schemas/` - A new location for [Telemetry Schemas](https://github.com/open-telemetry/semantic-conventions/tree/main/schemas) to live. This directory will be hosted at `https://opentelemetry.io/schemas/` @@ -48,7 +48,7 @@ There will also be the following exceptions in the specification: specification. Specifically `service.name`. - The specification may elevate some semantic conventions as necessary for compatibility requirements, e.g. `service.instance.id` and - [Prometheus Compatibility](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/compatibility/prometheus_and_openmetrics.md). + [Prometheus Compatibility](../specification/compatibility/prometheus_and_openmetrics.md). These exceptions exist because: @@ -115,13 +115,13 @@ Initially this repository would have the following ownership: - [Sean Marcinak](https://github.com/MovieStoreGuy), Atlassian - [Ted Young](https://github.com/tedsuo), Lightstep - Approvers (HTTP Only) - - [Trask Stalnaker](github.com/trask) + - [Trask Stalnaker](https://github.com/trask) - Approvers (SchemaUrl Files) - - [Tigran Najaryan](github.com/tigrannajaryan) + - [Tigran Najaryan](https://github.com/tigrannajaryan) - Maintainers - - [Josh Suereth](github.com/jsuereth) - - [Armin Ruech](github.com/arminru) - - [Reiley Yang](github.com/reyang) + - [Josh Suereth](https://github.com/jsuereth) + - [Armin Ruech](https://github.com/arminru) + - [Reiley Yang](https://github.com/reyang) That is, Maintenance would initially continue to fall on (a subset of) the Technical Committee. Approvers would start with existing semconv approvers in diff --git a/oteps/0258-env-context-baggage-carriers.md b/oteps/0258-env-context-baggage-carriers.md index 598c7dbfbaf..50adcd5292e 100644 --- a/oteps/0258-env-context-baggage-carriers.md +++ b/oteps/0258-env-context-baggage-carriers.md @@ -41,7 +41,7 @@ Adding arbitrary [Text Map propagation][tmp] through environment variable carrie the OpenTelemetry Specification will enable distributed tracing within the above listed systems. -There has already been a significant amount of [Prior Art](#prior-art) built +There has already been a significant amount of [Prior Art](#prior-art-and-alternatives) built within the industry and **within OpenTelemetry** to accomplish the immediate needs, however, OpenTelemetry at this time does not define the specification for this form of propagation. @@ -270,7 +270,7 @@ mentioned in [opentelemetry-specification #740](https://github.com/open-telemetr * [Jenkins OpenTelemetry Plugin](https://github.com/jenkinsci/opentelemetry-plugin) * [otel-cli generic wrapper](https://github.com/equinix-labs/otel-cli) -* [Maven OpenTelemetry Extension](https://github.com/cyrille-leclerc/opentelemetry-maven-extension) +* [Maven OpenTelemetry Extension](https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/maven-extension) * [Ansible OpenTelemetry Plugin](https://github.com/ansible-collections/community.general/pull/3091) * [go-test-trace](https://github.com/rakyll/go-test-trace/commit/22493612be320e0a01c174efe9b2252924f6dda9) * [Concourse CI](https://github.com/concourse/docs/pull/462) diff --git a/oteps/0265-event-vision.md b/oteps/0265-event-vision.md index b6050e7c921..297866c813c 100644 --- a/oteps/0265-event-vision.md +++ b/oteps/0265-event-vision.md @@ -27,7 +27,7 @@ OpenTelemetry SHOULD provide a way to bypass the OpenTelemetry Logs API entirely directly via existing language-specific logging libraries, if that library has the capability to do so. OpenTelemetry will recommend that -[instrumentation libraries](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/glossary.md#instrumentation-library) +[instrumentation libraries](../specification/glossary.md#instrumentation-library) use the OpenTelemetry Logs API to emit OpenTelemetry Events rather than using other logging libraries to emit OpenTelemetry Events. This recommendation aims to provide users with a simple and consistent onboarding experience that avoids mixing approaches. @@ -74,6 +74,6 @@ The state of this OTEP represents the option that we think will be the least con * How do OpenTelemetry Events relate to raw metric events? (e.g. [opentelemetry-specification/617](https://github.com/open-telemetry/opentelemetry-specification/issues/617)). * How do OpenTelemetry Events relate to raw span events? - (e.g. a [streaming SDK](https://github.com/search?q=repo%3Aopen-telemetry%2Fopentelemetry-specification+%22streaming+sdk%22&type=issues)). + (e.g. a streaming SDK). * Should event name be captured as an attribute or as a top-level field? * How will Event / Span Event interoperability work in the presence of sampling (e.g. since Span Events are sampled along with Spans)? diff --git a/oteps/0266-move-oteps-to-spec.md b/oteps/0266-move-oteps-to-spec.md index 997bf501a97..3bfead0311c 100644 --- a/oteps/0266-move-oteps-to-spec.md +++ b/oteps/0266-move-oteps-to-spec.md @@ -1,6 +1,6 @@ # Move OTEPS to the Specification repository -Let's move OTEP documentation and PRs back into the github.com/open-telemetry/opentelemetry-specification repository. +Let's move OTEP documentation and PRs back into the https://github.com/open-telemetry/opentelemetry-specification repository. ## Motivation @@ -25,7 +25,7 @@ As OpenTelemetry is stabilizing, the need for OTEPs to live outside the specific - New contributors to OpenTelemetry often can't find recorded decision that exist in OTEPs. - Getting reviews from folks used to checking the Specification repository, but not the less-frequently-worked-on OTEP repository. -To solve these, let's move OTEPs into a directory within the [specification repository](github.com/open-telemetry/opentelemetry-specification). +To solve these, let's move OTEPs into a directory within the [specification repository](https://github.com/open-telemetry/opentelemetry-specification). We would also update all tooling and expected reviews to match existing standards for OTEPs. Given the maintainers of OTEPs are the same as maintainers of the specification, this should not change the bar for acceptance. diff --git a/oteps/entities/0256-entities-data-model.md b/oteps/entities/0256-entities-data-model.md index 034d29e31f5..51d5a00faae 100644 --- a/oteps/entities/0256-entities-data-model.md +++ b/oteps/entities/0256-entities-data-model.md @@ -122,7 +122,7 @@ MUST not change during the lifetime of the entity. The Id must contain at least one attribute.

Follows OpenTelemetry common +href="../../specification/common/README.md#attribute">common attribute definition. SHOULD follow OpenTelemetry semantic conventions for attributes. @@ -139,7 +139,7 @@ MAY change over the lifetime of the entity. MAY be empty. These attributes are not part of entity's identity.

Follows any +href="../../specification/logs/data-model.md#type-any">any value definition in the OpenTelemetry spec - it can be a scalar value, byte array, an array or map of values. Arbitrary deep nesting of values for arrays and maps is allowed. @@ -682,7 +682,7 @@ There are a couple of reasons: ### Attribute Data Type The data model requires the Attributes field to use the extended -[any](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/data-model.md#type-any) +[any](../../specification/logs/data-model.md#type-any) attribute values, that allows more complex data types. This is different from the data type used by the Id field, which is more restricted in the shape. diff --git a/oteps/entities/0264-resource-and-entities.md b/oteps/entities/0264-resource-and-entities.md index 13df0c0012c..6cb0e70b9c5 100644 --- a/oteps/entities/0264-resource-and-entities.md +++ b/oteps/entities/0264-resource-and-entities.md @@ -92,7 +92,7 @@ The SDK Resource Provider is responsible for running all configured Resource and - Entity merging will occur first resulting in an "Entity Merged" Resource (See [algorithm here](#entity-merging-and-resource)). - Resource detectors otherwise follow existing merge semantics. - The Specification merge rules will be updated to account for violations prevalent in ALL implementation of resource detection. - - Specifically: This means the [rules around merging Resource across schema-url will be dropped](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/sdk.md#merge). Instead only conflicting attributes will be dropped. + - Specifically: This means the [rules around merging Resource across schema-url will be dropped](../../specification/resource/sdk.md#merge). Instead only conflicting attributes will be dropped. - SchemaURL on Resource will be deprecated with entity-specific schema-url replacing it. SDKs will only fill out SchemaURL on Resource when SchemaURL matches across all entities discovered. Additionally, only existing stable resource attributes can be used in Resource SchemaURL in stable OpenTelemetry components (Specifially `service.*` and `sdk.*` are the only stabilized resource convnetions). Given prevalent concerns of implementations around Resource merge specification, we suspect impact of this deprecation to be minimal, and existing usage was within the "experimental" phase of semantic conventions. - An OOTB ["Env Variable Entity Detector"](#environment-variable-detector) will be specified and provided vs. requiring SDK wide ENV variables for resource detection. - *Additionally, Resource Provider would be responsible for understanding Entity lifecycle events, for Entities whose lifetimes do not match or exceed the SDK's own lifetime (e.g. browser session).* @@ -317,7 +317,7 @@ This proposal motivates a Resource Provider in the SDK whose job could include m ### How to deal with Prometheus Compatibility for non-SDK telemetry? -Today, [Prometheus compatibility](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/compatibility/prometheus_and_openmetrics.md) relies on two key attributes in Resource: `service.name` and `service.instance.id`. These are not guaranteed to exist outside of OpenTelemetry SDK generation. While this question is not fully answered, we believe outlining identity in all resources within OpenTelemetry allows us to define a solution in the future while preserving compatibility with what works today. +Today, [Prometheus compatibility](../../specification/compatibility/prometheus_and_openmetrics.md) relies on two key attributes in Resource: `service.name` and `service.instance.id`. These are not guaranteed to exist outside of OpenTelemetry SDK generation. While this question is not fully answered, we believe outlining identity in all resources within OpenTelemetry allows us to define a solution in the future while preserving compatibility with what works today. Here's a list of requirements for the solution: diff --git a/oteps/logs/0091-logs-vocabulary.md b/oteps/logs/0091-logs-vocabulary.md index 6131ef1ee99..b9934a3c363 100644 --- a/oteps/logs/0091-logs-vocabulary.md +++ b/oteps/logs/0091-logs-vocabulary.md @@ -9,7 +9,7 @@ avoid the chaos experienced by the builders of the Tower of Babel. ## Proposal -OpenTelemetry specification already contains a [vocabulary](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/overview.md) +OpenTelemetry specification already contains a [vocabulary](../../specification/overview.md) for Traces, Metrics and other relevant concepts. This proposal is to add the following concepts to the vocabulary. @@ -31,8 +31,8 @@ additional qualifiers should be used (e.g. `Log Record`). ### Embedded Log -`Log Records` embedded inside a [Span](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md#span) -object, in the [Events](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md#add-events) list. +`Log Records` embedded inside a [Span](../../specification/trace/api.md#span) +object, in the [Events](../../specification/trace/api.md#add-events) list. ### Standalone Log diff --git a/oteps/logs/0092-logs-vision.md b/oteps/logs/0092-logs-vision.md index e7736f1f0ee..72b906623e0 100644 --- a/oteps/logs/0092-logs-vision.md +++ b/oteps/logs/0092-logs-vision.md @@ -44,7 +44,7 @@ We will produce mapping recommendations for commonly used log formats. ## Log Protocol Armed with the Log Data model we will aim to design a high performance protocol -for logs, which will pursue the same [design goals](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/protocol/design-goals.md) +for logs, which will pursue the same [design goals](https://github.com/open-telemetry/opentelemetry-proto/blob/main/docs/design-goals.md) as we had for the traces and metrics protocol. Most notably the protocol will aim to be highly reliable, have low resource @@ -111,7 +111,7 @@ system logs, infrastructure logs, third-party and first-party application logs. ### Standalone and Embedded Logs -OpenTelemetry will support both logs embedded inside [Spans](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md#span) +OpenTelemetry will support both logs embedded inside [Spans](../../specification/trace/api.md#span) and standalone logs recorded elsewhere. The support of embedded logs is important for OpenTelemetry's primary use cases, where errors and exceptions need to be embedded in Spans. The support of standalone logs is important for diff --git a/oteps/logs/0097-log-data-model.md b/oteps/logs/0097-log-data-model.md index b3e15255c48..10ca034180e 100644 --- a/oteps/logs/0097-log-data-model.md +++ b/oteps/logs/0097-log-data-model.md @@ -404,7 +404,7 @@ occurrence of the event coming from the same source. This field is optional. Type: key/value pair list. Description: Describes the source of the log, aka -[resource](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/overview.md#resources). +[resource](../../specification/overview.md#resources). "key" of each pair is a `string` and "value" is of `any` type. Multiple occurrences of events coming from the same event source can happen across time and they all have the same value of `Resource`. Can contain for example @@ -413,7 +413,7 @@ 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](https://github.com/open-telemetry/opentelemetry-specification/tree/master/specification/resource/semantic_conventions). +[semantic conventions for Resources](https://github.com/open-telemetry/semantic-conventions/tree/main/docs/resource). This field is optional. ### Field: `Attributes` @@ -426,7 +426,7 @@ 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 Attributes](https://github.com/open-telemetry/opentelemetry-specification/tree/master/specification/trace/semantic_conventions). +[semantic conventions for Attributes](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/attribute-naming.md). This field is optional. ## Example Log Records @@ -1324,7 +1324,7 @@ It may contain what hostname returns on Unix systems, the fully qualified, or a \* Not yet formalized into ECS. \*\* A resource that doesn’t exist in the -[OpenTelemetry resource semantic convention](https://github.com/open-telemetry/opentelemetry-specification/tree/master/specification/resource/semantic_conventions). +[OpenTelemetry resource semantic convention](https://github.com/open-telemetry/semantic-conventions/tree/main/docs/resource). 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/oteps/logs/0150-logging-library-sdk.md b/oteps/logs/0150-logging-library-sdk.md index 00a67988be4..2c7d4033406 100644 --- a/oteps/logs/0150-logging-library-sdk.md +++ b/oteps/logs/0150-logging-library-sdk.md @@ -24,11 +24,11 @@ guidelines on how to create the prototypes. The specification defines how the OpenTelemetry Logging Library SDK exposes its functionality to authors of extensions to language-specific 3rd party logging libraries and to end users that want to produce logs in the -[OpenTelemetry manner](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/overview.md). +[OpenTelemetry manner](../../specification/logs/README.md). The specification defines SDK elements that to some extent mirror the OpenTelemetry -[Trace SDK](https://github.com/open-telemetry/opentelemetry-specification/tree/main/specification/trace). +[Trace SDK](../../specification/trace). This ensures uniformity and consistency of the OpenTelemetry specification and of the implementations across traces and logs. For additional clarity the definitions in this document refer to the Trace analogs where appropriate. @@ -90,7 +90,7 @@ Methods: ### LogRecord See LogRecord -[data model](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/data-model.md) +[data model](../../specification/logs/data-model.md) for the list of fields. Open Question: should LoggerName field be added to the data model to allow @@ -133,7 +133,7 @@ Methods: An Appender implementation can be used to allow emitting log records via OpenTelemetry Logging Library exporters. This approach is typically used for applications which are fine with changing the log transport and is -[one of the supported](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/overview.md#direct-to-collector) +[one of the supported](../../specification/logs/README.md#direct-to-collector) log collection approaches. The Appender implementation will typically acquire a LogEmitter from the global @@ -142,7 +142,7 @@ received from the application. For languages with implicit Context, the Appender may call Context API to get the currently -[active Span](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#context-interaction) +[active Span](../../specification/trace/api.md#context-interaction) and populate TraceId, SpanId, TraceFlags fields of the LogRecord before emitting it. The log library may also have an alternate way to inject the context into log records (e.g. MDC in Log4j). diff --git a/oteps/metrics/0088-metric-instrument-optional-refinements.md b/oteps/metrics/0088-metric-instrument-optional-refinements.md index 47672a33eb9..46bff0eb82c 100644 --- a/oteps/metrics/0088-metric-instrument-optional-refinements.md +++ b/oteps/metrics/0088-metric-instrument-optional-refinements.md @@ -54,8 +54,8 @@ refinements) use callbacks to capture measurements. All measurement APIs produce metric events consisting of [timestamp, instrument descriptor, label set, and numerical -value](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/metrics/api.md#metric-event-format). Synchronous instrument -events additionally have [Context](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/context/context.md), describing +value](../../specification/metrics/api.md#metric-event-format). Synchronous instrument +events additionally have [Context](../../specification/context/README.md), describing properties of the associated trace and distributed correlation values. ### Terminology: Kinds of Aggregation @@ -108,7 +108,7 @@ without referring to the collection interval and without ambiguity. Measure instruments do not define a Last Value relationship. One reason is that [synchronous events can happen -simultaneously](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/metrics/api.md#time). +simultaneously](../../specification/metrics/api.md#time). For Measure instruments, it is possible to compute an aggregation that computes the last-captured value in a collection interval, but it is diff --git a/oteps/metrics/0098-metric-instruments-explained.md b/oteps/metrics/0098-metric-instruments-explained.md index a1f5dccade9..f5b359b8044 100644 --- a/oteps/metrics/0098-metric-instruments-explained.md +++ b/oteps/metrics/0098-metric-instruments-explained.md @@ -30,7 +30,7 @@ The following table summarizes the final proposed standard instruments resulting There are three synchronous instruments and three asynchronous instruments in this proposal, although a hypothetical 10 instruments were discussed in [OTEP 88][otep-88]. Although we consider them rational and logical, two categories of instrument are excluded in this proposal: synchronous cumulative instruments and asynchronous delta instruments. -Synchronous cumulative instruments are excluded from the standard based on the [OpenTelemetry library performance guidelines](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/performance.md). To report a cumulative value correctly at runtime requires a degree of order dependence--thus synchronization--that OpenTelemetry API will not itself admit. In a hypothetical example, if two actors both synchronously modify a sum and were to capture it using a synchronous cumulative metric event, the OpenTelemetry library would have to guarantee those measurements were processed in order. The library guidelines do not support this level of synchronization; we cannot block for the sake of instrumentation, therefore we do not support synchronous cumulative instruments. +Synchronous cumulative instruments are excluded from the standard based on the [OpenTelemetry library performance guidelines](../../specification/performance.md). To report a cumulative value correctly at runtime requires a degree of order dependence--thus synchronization--that OpenTelemetry API will not itself admit. In a hypothetical example, if two actors both synchronously modify a sum and were to capture it using a synchronous cumulative metric event, the OpenTelemetry library would have to guarantee those measurements were processed in order. The library guidelines do not support this level of synchronization; we cannot block for the sake of instrumentation, therefore we do not support synchronous cumulative instruments. Asynchronous delta instruments are excluded from the standard based on the lack of motivating examples, but we could also justify this as a desire to keep asynchronous callbacks stateless. An observer has to have memory in order to compute deltas; it is simpler for asynchronous code to report cumulative values. diff --git a/oteps/metrics/0146-metrics-prototype-scenarios.md b/oteps/metrics/0146-metrics-prototype-scenarios.md index 15651d072a4..1c112b111b6 100644 --- a/oteps/metrics/0146-metrics-prototype-scenarios.md +++ b/oteps/metrics/0146-metrics-prototype-scenarios.md @@ -3,9 +3,9 @@ With the stable release of the tracing specification, the OpenTelemetry community is willing to spend more energy on metrics API/SDK. The goal is to get the metrics API/SDK specification to -[`Experimental`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/versioning-and-stability.md#experimental) +[`Experimental`](../../specification/versioning-and-stability.md#experimental) state by end of 5/2021, and make it -[`Stable`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/versioning-and-stability.md#stable) +[`Stable`](../../specification/versioning-and-stability.md#stable) before end of 2021: * By end of 5/31/2021, we should have a good confidence that we can recommend @@ -15,12 +15,12 @@ before end of 2021: We might introduce additional features but there should be a high bar. * By end of 9/30/2021, we should mark the metrics API/SDK specification as - [`Feature-freeze`](https://github.com/open-telemetry/opentelemetry-specification/blob/1afab39e5658f807315abf2f3256809293bfd421/specification/document-status.md#feature-freeze), + [`Feature-freeze`](../../specification/document-status.md#feature-freeze), and focus on bug fixing or editorial changes. * By end of 11/30/2021, we want to have a stable release of metrics API/SDK specification, with multiple language SIGs providing RC (release candidate) or - [stable](https://github.com/open-telemetry/opentelemetry-specification/blob/9047c91412d3d4b7f28b0f7346d8c5034b509849/specification/versioning-and-stability.md#stable) + [stable](../../specification/versioning-and-stability.md#stable) clients. In this document, we will focus on two scenarios that we use for prototyping @@ -171,7 +171,7 @@ Both libraries will provide out-of-box metrics, the metrics have two categories: #### Server Climate Control Library Note: the **Host Name** should leverage [`OpenTelemetry -Resource`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/sdk.md), +Resource`](../../specification/resource/sdk.md), so it should be covered by the metrics SDK rather than API, and strictly speaking it is not considered as a "dimension" from the SDK perspective. @@ -208,7 +208,7 @@ can accept negative recordings and that they can be aggregated appropriately. **Received HTTP requests:** Note: the **Client Type** is passed in via the [`OpenTelemetry -Baggage`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/baggage/api.md), +Baggage`](../../specification/baggage/api.md), strictly speaking it is not part of the metrics API, but it is considered as a "dimension" from the metrics SDK perspective. diff --git a/oteps/profiles/0239-profiles-data-model.md b/oteps/profiles/0239-profiles-data-model.md index 284bf665aec..dff615e8a20 100644 --- a/oteps/profiles/0239-profiles-data-model.md +++ b/oteps/profiles/0239-profiles-data-model.md @@ -47,7 +47,6 @@ Introduces Data Model for Profiles signal to OpenTelemetry. * ["large" Profile](#large-profile) * [Conclusions](#conclusions) * [Semantic Conventions](#semantic-conventions) - * [Attributes](#attributes) * [Profile Types](#profile-types) * [Profile Units](#profile-units) * [Decision Log](#decision-log) diff --git a/oteps/trace/0002-remove-spandata.md b/oteps/trace/0002-remove-spandata.md index d128e06861c..1a7c9b5b61e 100644 --- a/oteps/trace/0002-remove-spandata.md +++ b/oteps/trace/0002-remove-spandata.md @@ -12,7 +12,7 @@ SpanData has a couple of use cases. The first use case revolves around creating a span synchronously but needing to change the start time to a more accurate timestamp. For example, in an HTTP server, you might record the time the first byte was received, parse the headers, determine the span name, and then create the span. The moment the span was created isn't representative of when the request actually began, so the time the first byte was received would become the span's start time. Since the current API doesn't allow start timestamps, you'd need to create a SpanData object. The big downside is that you don't end up with an active span object. -The second use case comes from the need to construct and report out of band spans, meaning that you're creating "custom" spans for an operation you don't own. One good example of this is a span sink that takes in structured logs that contain correlation IDs and a duration (e.g. from splunk) and [converts them](https://github.com/lightstep/splunktospan/blob/58ef9bca81933a47605a51047b12742e2d13aa8f/splunktospan/span.py#L43) to spans for your tracing system. [Another example](https://github.com/lightstep/haproxy_log2span/blob/761da5bf3e4b6cce56039d65439ae7db57f48603/lib/lib.go#L292) is running a sidecar on an HAProxy machine, tailing the request logs, and creating spans. SpanData allows you to report the out of band reporting case, whereas you can’t with the current Span API as you cannot set the start and end timestamp. +The second use case comes from the need to construct and report out of band spans, meaning that you're creating "custom" spans for an operation you don't own. One good example of this is a span sink that takes in structured logs that contain correlation IDs and a duration (e.g. from splunk) and converts them to spans for your tracing system. Another example is running a sidecar on an HAProxy machine, tailing the request logs, and creating spans. SpanData allows you to report the out of band reporting case, whereas you can’t with the current Span API as you cannot set the start and end timestamp. I'd like to propose getting rid of SpanData and `tracer.recordSpanData()` and replacing it by allowing `tracer.startSpan()` to accept a start timestamp option and `span.end()` to accept end timestamp option. This reduces the API surface, consolidating on a single span type. Options would meet the requirements for out of band reporting. diff --git a/oteps/trace/0168-sampling-propagation.md b/oteps/trace/0168-sampling-propagation.md index 9d9d520b231..2d8db37cef7 100644 --- a/oteps/trace/0168-sampling-propagation.md +++ b/oteps/trace/0168-sampling-propagation.md @@ -12,13 +12,13 @@ parent sampling probability associated with a context in order to build span-to-metrics pipelines when the built-in `ParentBased` Sampler is used. Further motivation for supporting span-to-metrics pipelines is presented in [OTEP -170](https://github.com/open-telemetry/oteps/blob/main/text/trace/0170-sampling-probability.md). +170](0170-sampling-probability.md). A consistent trace sampling decision is one that can be carried out at any node in a trace, which supports collecting partial traces. OpenTelemetry specifies a built-in `TraceIDRatioBased` Sampler that aims to accomplish this goal but was left incomplete (see a -[TODO](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md#traceidratiobased) +[TODO](../../specification/trace/sdk.md#traceidratiobased) in the v1.0 Trace specification). We propose a Sampler option to propagate the necessary information @@ -44,7 +44,7 @@ Ertl](https://arxiv.org/pdf/2107.07703.pdf). ### Adjusted count The concept of adjusted count is introduced in [OTEP -170](./0170-sampling_probability.md). Briefly, adjusted count is defined +170](./0170-sampling-probability.md). Briefly, adjusted count is defined in terms of the sampling probability, where: | Sampling probability | Adjusted count | Notes | @@ -89,7 +89,7 @@ probabilities is the negative base-2 logarithm of the probability: | 63 | 0 | [As specified in OTEP 170 for the Trace data -model](https://github.com/open-telemetry/oteps/blob/main/text/trace/0170-sampling-probability.md), +model](0170-sampling-probability.md), parent sampling probability can be stored in exported Span data to enable span-to-metrics pipelines to be built. Because `tracestate` is already encoded in the OpenTelemetry Span, this proposal is requires diff --git a/oteps/trace/0170-sampling-probability.md b/oteps/trace/0170-sampling-probability.md index 86b86e5807a..8f325323291 100644 --- a/oteps/trace/0170-sampling-probability.md +++ b/oteps/trace/0170-sampling-probability.md @@ -868,8 +868,6 @@ K. Thompson](https://www.wiley.com/en-us/Sampling%2C+3rd+Edition-p-9780470402313 [A Generalization of Sampling Without Replacement From a Finite Universe](https://www.jstor.org/stable/2280784), JSTOR (1952) -[Performance Is A Shape. Cost Is A Number: Sampling](https://docs.lightstep.com/otel/performance-is-a-shape-cost-is-a-number-sampling), 2020 blog post, Joshua MacDonald - [Priority sampling for estimation of arbitrary subset sums](https://dl.acm.org/doi/abs/10.1145/1314690.1314696) [Stream sampling for variance-optimal estimation of subset sums](https://arxiv.org/abs/0803.0473). diff --git a/oteps/trace/0173-messaging-semantic-conventions.md b/oteps/trace/0173-messaging-semantic-conventions.md index 51afefc05a3..091cfcd28b2 100644 --- a/oteps/trace/0173-messaging-semantic-conventions.md +++ b/oteps/trace/0173-messaging-semantic-conventions.md @@ -1,9 +1,9 @@ # Scenarios for Tracing semantic conventions for messaging This document aims to capture scenarios and a road map, both of which will -serve as a basis for [stabilizing](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/versioning-and-stability.md#stable) -the [existing semantic conventions for messaging](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/messaging.md), -which are currently in an [experimental](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/versioning-and-stability.md#experimental) +serve as a basis for [stabilizing](../../specification/versioning-and-stability.md#stable) +the [existing semantic conventions for messaging](https://github.com/open-telemetry/semantic-conventions/tree/main/docs/messaging), +which are currently in an [experimental](../../specification/versioning-and-stability.md#experimental) state. The goal is to declare messaging semantic conventions stable before the end of 2021. @@ -19,14 +19,14 @@ and Service Bus, Amazon SQS, SNS, and Kinesis. Bringing the existing experimental semantic conventions for messaging to a stable state is a crucial step for users and instrumentation authors, as it -allows them to rely on [stability guarantees](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/versioning-and-stability.md#not-defined-semantic-conventions-stability), +allows them to rely on [stability guarantees](../../specification/versioning-and-stability.md#not-defined-semantic-conventions-stability), and thus to ship and use stable instrumentation. ## Roadmap 1. This OTEP, consisting of scenarios and a proposed roadmap, is approved and merged. -2. [Stability guarantees](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/versioning-and-stability.md#not-defined-semantic-conventions-stability) +2. [Stability guarantees](../../specification/versioning-and-stability.md#not-defined-semantic-conventions-stability) for semantic conventions are approved and merged. This is not strictly related to semantic conventions for messaging but is a prerequisite for stabilizing any semantic conventions. @@ -37,9 +37,9 @@ and thus to ship and use stable instrumentation. in this document is approved and merged. 5. Proposed specification changes are verified by prototypes for the scenarios and examples below. -6. The [specification for messaging semantic conventions for tracing](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/messaging.md) +6. The [specification for messaging semantic conventions for tracing](https://github.com/open-telemetry/semantic-conventions/tree/main/docs) are updated according to the OTEP mentioned above and are declared - [stable](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/versioning-and-stability.md#stable). + [stable](../../specification/versioning-and-stability.md#stable). The steps in the roadmap don't necessarily need to happen in the given order, some steps can be worked on in parallel. @@ -261,4 +261,4 @@ in the future. * [CloudEvents](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md) * [Message-Driven (in contrast to Event-Driven)](https://www.reactivemanifesto.org/glossary#Message-Driven) * [Asynchronous message passing](https://en.wikipedia.org/wiki/Message_passing#Asynchronous_message_passing) -* [Existing semantic conventions for messaging](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/messaging.md) +* [Existing semantic conventions for messaging](https://github.com/open-telemetry/semantic-conventions/tree/main/docs/messaging) diff --git a/oteps/trace/0174-http-semantic-conventions.md b/oteps/trace/0174-http-semantic-conventions.md index d55b63d4401..f2f34b94874 100644 --- a/oteps/trace/0174-http-semantic-conventions.md +++ b/oteps/trace/0174-http-semantic-conventions.md @@ -1,9 +1,9 @@ # Scenarios and Open Questions for Tracing semantic conventions for HTTP This document aims to capture scenarios/open questions and a road map, both of -which will serve as a basis for [stabilizing](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/versioning-and-stability.md#stable) -the [existing semantic conventions for HTTP](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/http.md), -which are currently in an [experimental](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/versioning-and-stability.md#experimental) +which will serve as a basis for [stabilizing](../../specification/versioning-and-stability.md#stable) +the [existing semantic conventions for HTTP](https://github.com/open-telemetry/semantic-conventions/tree/main/docs/http), +which are currently in an [experimental](../../specification/versioning-and-stability.md#experimental) state. The goal is to declare HTTP semantic conventions stable before the end of Q1 2022. @@ -16,7 +16,7 @@ and guidelines for instrumenting HTTP communication. Bringing the existing experimental semantic conventions for HTTP to a stable state is a crucial step for users and instrumentation authors, as it -allows them to rely on [stability guarantees](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/versioning-and-stability.md#not-defined-semantic-conventions-stability), +allows them to rely on [stability guarantees](../../specification/versioning-and-stability.md#not-defined-semantic-conventions-stability), and thus to ship and use stable instrumentation. > NOTE. This OTEP captures a scope for changes should be done to existing @@ -26,7 +26,7 @@ experimental semantic conventions for HTTP, but does not propose solutions. 1. This OTEP, consisting of scenarios/open questions and a proposed roadmap, is approved and merged. -2. [Stability guarantees](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/versioning-and-stability.md#not-defined-semantic-conventions-stability) +2. [Stability guarantees](../../specification/versioning-and-stability.md#not-defined-semantic-conventions-stability) for semantic conventions are approved and merged. This is not strictly related to semantic conventions for HTTP but is a prerequisite for stabilizing any semantic conventions. @@ -34,9 +34,9 @@ experimental semantic conventions for HTTP, but does not propose solutions. document are approved and merged. 4. Proposed specification changes are verified by prototypes for the scenarios and examples below. -5. The [specification for HTTP semantic conventions for tracing](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/http.md) +5. The [specification for HTTP semantic conventions for tracing](https://github.com/open-telemetry/semantic-conventions/tree/main/docs/http) are updated according to this OTEP and are declared - [stable](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/versioning-and-stability.md#stable). + [stable](../../specification/versioning-and-stability.md#stable). The steps in the roadmap don't necessarily need to happen in the given order, some steps can be worked on in parallel. @@ -60,8 +60,8 @@ for `SpanKind.CLIENT`. > > * `http.url` > * `http.scheme`, `http.host`, `http.target` -> * `http.scheme`, [`net.peer.name`](span-general.md), [`net.peer.port`](span-general.md), `http.target` -> * `http.scheme`, [`net.peer.ip`](span-general.md), [`net.peer.port`](span-general.md), `http.target` +> * `http.scheme`, `net.peer.name`, `net.peer.port`, `http.target` +> * `http.scheme`, `net.peer.ip`, `net.peer.port`, `http.target` As a result, users that write queries against raw data or Zipkin/Jaeger don't have consistent story across instrumentations and languages. e.g. they'd need to diff --git a/oteps/trace/0205-messaging-semantic-conventions-context-propagation.md b/oteps/trace/0205-messaging-semantic-conventions-context-propagation.md index 626d5dcd984..4a18ff9d5a9 100644 --- a/oteps/trace/0205-messaging-semantic-conventions-context-propagation.md +++ b/oteps/trace/0205-messaging-semantic-conventions-context-propagation.md @@ -20,7 +20,7 @@ supported by messaging semantic conventions. ## Terminology -For terms used in this document, refer to [OTEP 173](#0173-messaging-semantic-conventions.md#terminology). +For terms used in this document, refer to [OTEP 173](0173-messaging-semantic-conventions.md#terminology). ## Motivation diff --git a/oteps/trace/0220-messaging-semantic-conventions-span-structure.md b/oteps/trace/0220-messaging-semantic-conventions-span-structure.md index ddaa406a418..48a1c2087f2 100644 --- a/oteps/trace/0220-messaging-semantic-conventions-span-structure.md +++ b/oteps/trace/0220-messaging-semantic-conventions-span-structure.md @@ -6,8 +6,8 @@ for messaging scenarios, and at defining how those spans relate to each other. This OTEP is based on [OTEP 0173](0173-messaging-semantic-conventions.md), which defines basic terms and describes messaging scenarios that should be supported by messaging semantic conventions. It also relies on context -propagation requirements put forth in the existing [semantic conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/specification/trace/semantic_conventions/messaging.md#context-propagation) -and detailed in [OTEP 0205](0205-messaging-semantic-conventions-context-propagation). +propagation requirements put forth in the existing [semantic conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/messaging/messaging-spans.md#context-propagation) +and detailed in [OTEP 0205](0205-messaging-semantic-conventions-context-propagation.md). * [Terminology](#terminology) * [Motivation](#motivation) @@ -25,7 +25,7 @@ and detailed in [OTEP 0205](0205-messaging-semantic-conventions-context-propagat ## Terminology -For terms used in this document, refer to [OTEP 173](#0173-messaging-semantic-conventions.md#terminology). +For terms used in this document, refer to [OTEP 173](0173-messaging-semantic-conventions.md#terminology). ## Motivation @@ -140,7 +140,7 @@ There are four different scenarios for injecting a creation context into a messa ### Consumer -Existing semantic conventions [prescribe the use of "Process" spans](https://github.com/open-telemetry/semantic-conventions/blob/main/specification/trace/semantic_conventions/messaging.md#operation-names) +Existing semantic conventions [prescribe the use of "Process" spans](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/messaging/messaging-spans.md#span-name) for correlating producer with consumer traces. However, for many use cases, it is not possible to rely on the presence of "Process" spans: there are cases where a dedicated processing operation cannot be identified, or where @@ -254,7 +254,7 @@ For further details about each of those operations refer to the [section about t ### Span kind -[Span kinds](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#spankind) +[Span kinds](../../specification/trace/api.md#spankind) SHOULD be set according to the following table, based on the operation a span describes. | Operation name | Span kind| @@ -265,7 +265,7 @@ SHOULD be set according to the following table, based on the operation a span de | `deliver` | `CONSUMER` | | `settle` | (see below) | -The kind of `settle` spans should be set according to the [generic specification about span kinds](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#spankind), +The kind of `settle` spans should be set according to the [generic specification about span kinds](../../specification/trace/api.md#spankind), e. g. it should be set to `CLIENT` if the `settle` spans models a synchronous call to the intermediary. @@ -415,7 +415,7 @@ build on the foundation that this OTEP lays. ## Prior art -The existing semantic conventions for messaging contain a [list of examples](https://github.com/open-telemetry/semantic-conventions/blob/main/specification/trace/semantic_conventions/messaging.md#examples), +The existing semantic conventions for messaging contain a [list of examples](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/messaging/messaging-spans.md#examples), each specifying the spans with their attributes and relationships that should be created for a given messaging scenario. diff --git a/oteps/trace/0235-sampling-threshold-in-trace-state.md b/oteps/trace/0235-sampling-threshold-in-trace-state.md index 014744a734b..cec19441f6f 100644 --- a/oteps/trace/0235-sampling-threshold-in-trace-state.md +++ b/oteps/trace/0235-sampling-threshold-in-trace-state.md @@ -7,7 +7,7 @@ In this context, consistency means that a positive sampling decision made for a ## Explanation -The existing, experimental [specification for probability sampling using TraceState](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/tracestate-probability-sampling.md) is limited to powers-of-two probabilities, and is designed to work without making assumptions about TraceID randomness. +The existing, experimental [specification for probability sampling using TraceState](../../specification/trace/tracestate-probability-sampling.md) is limited to powers-of-two probabilities, and is designed to work without making assumptions about TraceID randomness. This system can only achieve non-power-of-two sampling using interpolation between powers of two, which is unnecessarily restrictive. In existing sampling systems, sampling probabilities like 1%, 10%, and 75% are common, and it should be possible to express these without interpolation. There is also a need for consistent sampling in the collection path (outside of the head-sampling paths) and using inherent randomness in the traceID is a less-expensive solution than referencing a custom `r-value` from the tracestate in every span. @@ -84,14 +84,14 @@ Sampling Decisions MUST be propagated by setting the value of the `th` key in th There are two categories of sampler: -- **Head samplers:** Implementations of [`Sampler`](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.29.0/specification/trace/sdk.md#sampler), called by a `Tracer` during span creation. +- **Head samplers:** Implementations of [`Sampler`](../../specification/trace/sdk.md#sampler), called by a `Tracer` during span creation. - **Downstream samplers:** Any component that, given an ended Span, decides whether to drop or forward ("sample") it on to the next component in the system. Also known as "collection-path samplers" or "sampling processors". _Tail samplers_ are a special class of downstream samplers that buffer the spans in a trace and select a sampling probability for the trace as a whole using data from any span in the buffered trace. This section defines behavior for each kind of sampler. ### Head samplers -A head sampler is responsible for computing the `rv` and `th` values in a new span's initial [`TraceState`](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.29.0/specification/trace/api.md#tracestate). Notable inputs to that computation include the parent span's trace state (if a parent span exists) and the new span's trace ID. +A head sampler is responsible for computing the `rv` and `th` values in a new span's initial [`TraceState`](../../specification/trace/api.md#tracestate). Notable inputs to that computation include the parent span's trace state (if a parent span exists) and the new span's trace ID. First, a consistent `Sampler` decides which sampling probability to use. The sampler MAY select any value of T. If a valid `SpanContext` is provided in the call to `ShouldSample` (indicating that the span being created will be a child span),

OTel Logs and Event Record + OTel Logs and Event Record Elastic Common Schema (ECS)
Timestamp (uint64 nanoseconds since Unix epoch) + Timestamp (uint64 nanoseconds since Unix epoch) @timestamp (date)
TraceId (byte sequence), SpanId (byte sequence) + TraceId (byte sequence), SpanId (byte sequence) trace.id (keyword), span.id (keyword)
SeverityText (string) + SeverityText (string) log.syslog.severity.name (keyword), log.level (keyword)
SeverityNumber (number) + SeverityNumber (number) log.syslog.severity.code
Body (any) + Body (any) message (match_only_text)
process.cpu.load (not specified but collected by OTel Collector)
-process.cpu.time (async counter) +process.cpu.time (async counter)
-system.cpu.utilization +system.cpu.utilization 		host.cpu.usage (scaled_float) with a slightly different measurement than what OTel metrics measure