Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ requirements and recommendations.
## Sign the CLA

Before you can contribute, you will need to sign the [Contributor License
Agreement](https://identity.linuxfoundation.org/projects/cncf).
Agreement](https://easycla.lfx.linuxfoundation.org/).

## Proposing a change

Expand Down Expand Up @@ -56,7 +56,7 @@ Be sure to clearly define the specification requirements using appropriate
keywords as defined in [Notation Conventions and
Compliance](./specification/README.md#notation-conventions-and-compliance),
while making sure to heed the guidance laid out in
[RFC2119](https://tools.ietf.org/html/rfc2119) about the sparing use of
[RFC2119](https://datatracker.ietf.org/doc/html/rfc2119) about the sparing use of
imperatives:

> Imperatives of the type defined in this memo must be used with care
Expand Down Expand Up @@ -211,7 +211,7 @@ Everyone is welcome to contribute to the OpenTelemetry specification via GitHub
pull requests (PRs).

To [create a new
PR](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request),
PR](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request),
fork the project in GitHub and clone the upstream repo:

```sh
Expand All @@ -236,7 +236,7 @@ $ git push fork feature
Open a pull request against the main `opentelemetry-specification` repo.

If the PR is not ready for review, please mark it as
[`draft`](https://github.blog/2019-02-14-introducing-draft-pull-requests/).
[`draft`](https://github.blog/news-insights/product-news/introducing-draft-pull-requests/).

For non-trivial changes, please update the [CHANGELOG](./CHANGELOG.md).

Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ For details, see [CONTRIBUTING.md](CONTRIBUTING.md), in particular read
Questions that need additional attention can be brought to the regular
specifications meeting. EU and US timezone friendly meeting is held every
Tuesday at 8 AM Pacific time. Meeting notes are held in the [Google
doc](https://docs.google.com/document/d/1pdvPeKjA8v8w_fGKAN68JjWBmVJtPCpqdi9IZrd6eEo).
doc](https://docs.google.com/document/d/1pdvPeKjA8v8w_fGKAN68JjWBmVJtPCpqdi9IZrd6eEo/edit).
APAC timezone friendly meetings are held on request. See
[OpenTelemetry calendar](https://github.com/open-telemetry/community#calendar).

Expand Down
2 changes: 1 addition & 1 deletion development/trace/zpages.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@

zPages are an in-process alternative to external exporters. When included, they collect and aggregate tracing and metrics information in the background; this data is served on web pages when requested.

The idea of "zPages" originates from one of OpenTelemetry's predecessors, [OpenCensus](https://opencensus.io/). You can read more about zPages from the OpenCensus docs [here](https://opencensus.io/zpages) or the OTEP [here](../../oteps/0110-z-pages.md). OpenCensus has different zPage implementations in [Java](https://opencensus.io/zpages/java/), [Go](https://opencensus.io/zpages/go/), and [Node](https://opencensus.io/zpages/node/) and there has been similar internal solutions developed at companies like Uber. Within OpenTelemetry, zPages are available in Go and Rust. The OTel Collector also has [an implementation](https://github.com/open-telemetry/opentelemetry-collector/tree/master/extension/zpagesextension) of zPages.
The idea of "zPages" originates from one of OpenTelemetry's predecessors, [OpenCensus](https://opencensus.io/). You can read more about zPages from the OpenCensus docs [here](https://opencensus.io/zpages/) or the OTEP [here](../../oteps/0110-z-pages.md). OpenCensus has different zPage implementations in [Java](https://opencensus.io/zpages/java/), [Go](https://opencensus.io/zpages/go/), and [Node](https://opencensus.io/zpages/node/) and there has been similar internal solutions developed at companies like Uber. Within OpenTelemetry, zPages are available in Go and Rust. The OTel Collector also has [an implementation](https://github.com/open-telemetry/opentelemetry-collector/tree/main/extension/zpagesextension) of zPages.

zPages are uniquely useful in a couple of different ways. One is that they're more lightweight and quicker compared to installing external tracing systems like Jaeger and Zipkin, yet they still share useful ways to debug and gain insight into instrumented applications; these uses depend on the type of zPage, which is detailed below. For high throughput applications, zPages can also analyze more telemetry with the limited set of supported scenarios than external exporters; this is because zPages are in-memory while external exporters are typically configured to send a subset of telemetry for reach analysis to save costs.

Expand Down
2 changes: 1 addition & 1 deletion oteps/0001-telemetry-without-manual-instrumentation.md
Original file line number Diff line number Diff line change
Expand Up @@ -89,7 +89,7 @@ There are some languages that will have OpenTelemetry support before they have D

### Governance of the auto-instrumentation libraries

Each `auto-instr-foo` repository must have at least one [Maintainer](https://github.com/open-telemetry/community/blob/master/community-membership.md#maintainer) in common with the main `opentelemetry-foo` language repository. There are no other requirements or constraints about the set of maintainers/approvers for the main language repository and the respective auto-instrumentation repository; in particular, there may be maintainers/approvers of the main language repository that are not maintainers/approvers for the auto-instrumentation repository, and vice versa.
Each `auto-instr-foo` repository must have at least one [Maintainer](https://github.com/open-telemetry/community/blob/main/community-membership.md#maintainer) in common with the main `opentelemetry-foo` language repository. There are no other requirements or constraints about the set of maintainers/approvers for the main language repository and the respective auto-instrumentation repository; in particular, there may be maintainers/approvers of the main language repository that are not maintainers/approvers for the auto-instrumentation repository, and vice versa.

### Mini-FAQ about this proposal

Expand Down
4 changes: 2 additions & 2 deletions oteps/0007-no-out-of-band-reporting.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,5 +57,5 @@ instance configured with it's own `Resource`.
* [opentelemetry-specification/62](https://github.com/open-telemetry/opentelemetry-specification/issues/62)
* [opentelemetry-specification/61](https://github.com/open-telemetry/opentelemetry-specification/issues/61)

[otelsvc-receiver]: https://github.com/open-telemetry/opentelemetry-service#config-receivers
[create-metric]: https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/metrics/api.md#create-metric
[otelsvc-receiver]: https://github.com/open-telemetry/opentelemetry-collector#config-receivers
[create-metric]: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#create-metric
4 changes: 2 additions & 2 deletions oteps/0016-named-tracers.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ For an operator of an application using OpenTelemetry, there is currently no way

### Instrumentation library identification

If an instrumentation library hasn't implemented [semantic conventions](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/overview.md#semantic-conventions) correctly or those conventions change over time, it's currently hard to interpret and sanitize data produced by it selectively. The produced Spans or Metrics cannot later be associated with the library which reported them, either in the processing pipeline or the backend.
If an instrumentation library hasn't implemented [semantic conventions](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/overview.md#semantic-conventions) correctly or those conventions change over time, it's currently hard to interpret and sanitize data produced by it selectively. The produced Spans or Metrics cannot later be associated with the library which reported them, either in the processing pipeline or the backend.

### Disable instrumentation of pre-instrumented libraries

Expand Down Expand Up @@ -50,7 +50,7 @@ Meter meter = OpenTelemetry.getMeterProvider().getMeter("io.opentelemetry.contri

These factories (`TracerProvider` and `MeterProvider`) replace the global `Tracer` / `Meter` singleton objects as ubiquitous points to request Tracer and Meter instances.

The _name_ used to create a Tracer or Meter must identify the _instrumentation_ libraries (also referred to as _integrations_) and not the library being instrumented. These instrumentation libraries could be libraries developed in an OpenTelemetry repository, a 3rd party implementation, or even auto-injected code (see [Open Telemetry Without Manual Instrumentation OTEP](https://github.com/open-telemetry/oteps/blob/master/text/0001-telemetry-without-manual-instrumentation.md)). See also the examples for identifiers at the end.
The _name_ used to create a Tracer or Meter must identify the _instrumentation_ libraries (also referred to as _integrations_) and not the library being instrumented. These instrumentation libraries could be libraries developed in an OpenTelemetry repository, a 3rd party implementation, or even auto-injected code (see [Open Telemetry Without Manual Instrumentation OTEP](https://github.com/open-telemetry/oteps/blob/main/text/0001-telemetry-without-manual-instrumentation.md)). See also the examples for identifiers at the end.
If a library (or application) has instrumentation built-in, it is both the instrumenting and instrumented library and should pass its own name here. In all other cases (and to distinguish them from that case), the distinction between instrumenting and instrumented library is very important. For example, if an HTTP library `com.example.http` is instrumented by either `io.opentelemetry.contrib.examplehttp`, then it is important that the Tracer is not named `com.example.http`, but `io.opentelemetry.contrib.examplehttp` after the actual instrumentation library.

If no name (null or empty string) is specified, following the suggestions in ["error handling proposal"](https://github.com/open-telemetry/opentelemetry-specification/pull/153), a "smart default" will be applied and a default Tracer / Meter implementation is returned.
Expand Down
10 changes: 5 additions & 5 deletions oteps/0035-opentelemetry-protocol.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ OTLP is a general-purpose telemetry data delivery protocol designed in the scope

OTLP defines the encoding of telemetry data and the protocol used to exchange data between the client and the server.

This specification defines how OTLP is implemented over [gRPC](https://grpc.io/) and specifies corresponding [Protocol Buffers](https://developers.google.com/protocol-buffers/docs/overview) schema. Future extensions to OTLP may define implementations over other transports. For details of gRPC service definition see section [gRPC Transport](#grpc-service-definition).
This specification defines how OTLP is implemented over [gRPC](https://grpc.io/) and specifies corresponding [Protocol Buffers](https://protobuf.dev/overview/) schema. Future extensions to OTLP may define implementations over other transports. For details of gRPC service definition see section [gRPC Transport](#grpc-service-definition).

OTLP is a request/response style protocols: the clients send requests, the server replies with corresponding responses. This document defines one requests and response type: `Export`.

Expand Down Expand Up @@ -93,7 +93,7 @@ When an error is returned by the server it falls into 2 broad categories: retrya

- Not-retryable errors indicate that processing of telemetry data failed and the client MUST NOT retry sending the same telemetry data. The telemetry data MUST be dropped. This can happen, for example, when the request contains bad data and cannot be deserialized or otherwise processed by the server. The client SHOULD maintain a counter of such dropped data.

When using gRPC transport the server SHOULD indicate retryable errors using code [Unavailable](https://godoc.org/google.golang.org/grpc/codes) and MAY supply additional [details via status](https://godoc.org/google.golang.org/grpc/status#Status.WithDetails) using [RetryInfo](https://github.com/googleapis/googleapis/blob/6a8c7914d1b79bd832b5157a09a9332e8cbd16d4/google/rpc/error_details.proto#L40) containing 0 value of RetryDelay. Here is a sample Go code to illustrate:
When using gRPC transport the server SHOULD indicate retryable errors using code [Unavailable](https://pkg.go.dev/google.golang.org/grpc/codes) and MAY supply additional [details via status](https://pkg.go.dev/google.golang.org/grpc/status#Status.WithDetails) using [RetryInfo](https://github.com/googleapis/googleapis/blob/6a8c7914d1b79bd832b5157a09a9332e8cbd16d4/google/rpc/error_details.proto#L40) containing 0 value of RetryDelay. Here is a sample Go code to illustrate:

```go
// Do this on server side.
Expand All @@ -106,7 +106,7 @@ When using gRPC transport the server SHOULD indicate retryable errors using code
return st.Err()
```

To indicate not-retryable errors the server is recommended to use code [InvalidArgument](https://godoc.org/google.golang.org/grpc/codes) and MAY supply additional [details via status](https://godoc.org/google.golang.org/grpc/status#Status.WithDetails) using [BadRequest](https://github.com/googleapis/googleapis/blob/6a8c7914d1b79bd832b5157a09a9332e8cbd16d4/google/rpc/error_details.proto#L119). Other gRPC status code may be used if it is more appropriate. Here is a sample Go code to illustrate:
To indicate not-retryable errors the server is recommended to use code [InvalidArgument](https://pkg.go.dev/google.golang.org/grpc/codes) and MAY supply additional [details via status](https://pkg.go.dev/google.golang.org/grpc/status#Status.WithDetails) using [BadRequest](https://github.com/googleapis/googleapis/blob/6a8c7914d1b79bd832b5157a09a9332e8cbd16d4/google/rpc/error_details.proto#L119). Other gRPC status code may be used if it is more appropriate. Here is a sample Go code to illustrate:

```go
// Do this on server side.
Expand Down Expand Up @@ -148,7 +148,7 @@ OTLP allows backpressure signalling.

If the server is unable to keep up with the pace of data it receives from the client then it SHOULD signal that fact to the client. The client MUST then throttle itself to avoid overwhelming the server.

To signal backpressure when using gRPC transport, the server SHOULD return an error with code [Unavailable](https://godoc.org/google.golang.org/grpc/codes) and MAY supply additional [details via status](https://godoc.org/google.golang.org/grpc/status#Status.WithDetails) using [RetryInfo](https://github.com/googleapis/googleapis/blob/6a8c7914d1b79bd832b5157a09a9332e8cbd16d4/google/rpc/error_details.proto#L40). Here is a sample Go code to illustrate:
To signal backpressure when using gRPC transport, the server SHOULD return an error with code [Unavailable](https://pkg.go.dev/google.golang.org/grpc/codes) and MAY supply additional [details via status](https://pkg.go.dev/google.golang.org/grpc/status#Status.WithDetails) using [RetryInfo](https://github.com/googleapis/googleapis/blob/6a8c7914d1b79bd832b5157a09a9332e8cbd16d4/google/rpc/error_details.proto#L40). Here is a sample Go code to illustrate:

```go
// Do this on server side.
Expand Down Expand Up @@ -265,7 +265,7 @@ Both FlatBuffers and Capnproto are worth to be re-evaluated for future versions

It is also worth researching transports other than gRPC. Other transports are not included in this RFC due to time limitations.

Experimental implementation of OTLP over WebSockets exists and was researched as an alternate. WebSockets were not chosen as the primary transport for OTLP due to lack or immaturity of certain capabilities (such as [lack of universal support](https://github.com/gorilla/websocket#gorilla-websocket-compared-with-other-packages) for [RFC 7692](https://tools.ietf.org/html/rfc7692) message compression extension). Despite limitations the experimental implementation demonstrated good performance and WebSocket transport will be considered for inclusion in a future OTLP Extensions RFC.
Experimental implementation of OTLP over WebSockets exists and was researched as an alternate. WebSockets were not chosen as the primary transport for OTLP due to lack or immaturity of certain capabilities (such as [lack of universal support](https://github.com/gorilla/websocket#gorilla-websocket-compared-with-other-packages) for [RFC 7692](https://datatracker.ietf.org/doc/html/rfc7692) message compression extension). Despite limitations the experimental implementation demonstrated good performance and WebSocket transport will be considered for inclusion in a future OTLP Extensions RFC.

## Open Questions

Expand Down
2 changes: 1 addition & 1 deletion oteps/0038-version-semantic-attribute.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,4 +29,4 @@ to construct schema-appropriate values.

## Prior art and alternatives

Tagging service resources with their version is generally suggested by analysis tools -- see [JAEGER_TAGS](https://www.jaegertracing.io/docs/1.8/client-features/) for an example -- but lacks standardization.
Tagging service resources with their version is generally suggested by analysis tools -- see [JAEGER_TAGS](https://www.jaegertracing.io/docs/1.8/client-libraries/client-features/) for an example -- but lacks standardization.
4 changes: 2 additions & 2 deletions oteps/0099-otlp-http.md
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,7 @@ specific failure cases and HTTP status codes that should be used.

Response body for all `HTTP 4xx` and `HTTP 5xx` responses MUST be a
ProtoBuf-encoded
[Status](https://godoc.org/google.golang.org/genproto/googleapis/rpc/status#Status)
[Status](https://pkg.go.dev/google.golang.org/genproto/googleapis/rpc/status#Status)
message that describes the problem.

This specification does not use `Status.code` field and the server MAY omit
Expand Down Expand Up @@ -121,7 +121,7 @@ response.
If the server receives more requests than the client is allowed or the server is
overloaded the server SHOULD respond with `HTTP 429 Too Many Requests` or
`HTTP 503 Service Unavailable` and MAY include
["Retry-After"](https://tools.ietf.org/html/rfc7231#section-7.1.3) header with a
["Retry-After"](https://datatracker.ietf.org/doc/html/rfc7231#section-7.1.3) header with a
recommended time interval in seconds to wait before retrying.

The client SHOULD honour the waiting interval specified in "Retry-After" header
Expand Down
4 changes: 2 additions & 2 deletions oteps/0111-auto-resource-detection.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ A default implementation of a detector that reads resource data from the
`OTEL_RESOURCE` environment variable will be included in the SDK. The
environment variable will contain of a list of key value pairs, and these are
expected to be represented in a format similar to the [W3C
Baggage](https://github.com/w3c/baggage/blob/master/baggage/HTTP_HEADER_FORMAT.md#header-content),
Baggage](https://github.com/w3c/baggage/blob/main/baggage/HTTP_HEADER_FORMAT.md#header-content),
except that additional semi-colon delimited metadata is not supported, i.e.:
`key1=value1,key2=value2`. If the user does not specify any resource, this
detector will be run by default.
Expand Down Expand Up @@ -149,7 +149,7 @@ specification](https://github.com/census-instrumentation/opencensus-specs/blob/m
### Existing OpenTelemetry implementations

- Resource detection implementation in JS SDK
[here](https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-resources):
[here](https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-resources):
The JS implementation is very similar to this proposal. This proposal states
that the SDK will allow detectors to be passed into telemetry providers
directly instead of just having a global `DetectResources` function which the
Expand Down
Loading
Loading