Merge branch 'main' into cijothomas/otlp-nits

Author: cijothomas

.github/workflows/ci.yml

@@ -40,6 +40,8 @@ jobs:
     - name: "Set rustup profile"
       run: rustup set profile minimal
     - uses: arduino/setup-protoc@v3
+      with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
     - name: Test
       run: bash ./scripts/test.sh
   lint:
@@ -52,6 +54,8 @@ jobs:
       with:
         components: rustfmt
     - uses: arduino/setup-protoc@v3
+      with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
     - uses: actions-rs/cargo@v1
       with:
         command: fmt
@@ -88,6 +92,8 @@ jobs:
       with:
         components: rustfmt
     - uses: arduino/setup-protoc@v3
+      with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
     - name: Build
       run: |
         cd ${{ matrix.example }}
@@ -126,6 +132,8 @@ jobs:
         with:
           components: rustfmt
       - uses: arduino/setup-protoc@v3
+        with:
+            repo-token: ${{ secrets.GITHUB_TOKEN }}
       - name: doc
         run: cargo doc --no-deps --all-features
         env:
@@ -144,6 +152,8 @@ jobs:
           toolchain: stable
           components: rustfmt,llvm-tools-preview
       - uses: arduino/setup-protoc@v3
+        with:
+            repo-token: ${{ secrets.GITHUB_TOKEN }}
       - name: cargo install cargo-llvm-cov
         uses: taiki-e/install-action@cargo-llvm-cov
       - name: cargo generate-lockfile

opentelemetry-otlp/CHANGELOG.md

@@ -11,10 +11,6 @@
 
 ### Added
 
-- Aded `http/json` support for all signals ([#1585])
-
-[#1585]: https://github.com/open-telemetry/opentelemetry-rust/pull/1585
-
 - Added `DeltaTemporalitySelector` ([#1568])
 - Add `webkpi-roots` features to `reqwest` and `tonic` backends
 

opentelemetry-otlp/Cargo.toml

@@ -72,7 +72,7 @@ tls-webkpi-roots = ["tls", "tonic/tls-webpki-roots"]
 
 # http binary
 http-proto = ["prost", "opentelemetry-http", "opentelemetry-proto/gen-tonic-messages", "http", "trace", "metrics"]
-# http json
+# http json This does not work today due to known issue. See https://github.com/open-telemetry/opentelemetry-rust/issues/1763.
 http-json = ["serde_json", "prost", "opentelemetry-http", "opentelemetry-proto/gen-tonic-messages", "opentelemetry-proto/with-serde", "http", "trace", "metrics"]
 reqwest-blocking-client = ["reqwest/blocking", "opentelemetry-http/reqwest"]
 reqwest-client = ["reqwest", "opentelemetry-http/reqwest"]

opentelemetry-otlp/README.md

@@ -1,93 +1,54 @@
+# OpenTelemetry OTLP Exporter
+
 ![OpenTelemetry — An observability framework for cloud-native software.][splash]
 
 [splash]: https://raw.githubusercontent.com/open-telemetry/opentelemetry-rust/main/assets/logo-text.png
 
-# OpenTelemetry Collector Rust Exporter
-
-[`OTLP`] integration for applications instrumented with [`OpenTelemetry`].
+This crate contains the [OpenTelemetry](https://opentelemetry.io/) Exporter
+implementation for
+[OTLP](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md).
 
 [![Crates.io: opentelemetry-otlp](https://img.shields.io/crates/v/opentelemetry-otlp.svg)](https://crates.io/crates/opentelemetry-otlp)
 [![Documentation](https://docs.rs/opentelemetry-otlp/badge.svg)](https://docs.rs/opentelemetry-otlp)
 [![LICENSE](https://img.shields.io/crates/l/opentelemetry-otlp)](./LICENSE)
 [![GitHub Actions CI](https://github.com/open-telemetry/opentelemetry-rust/workflows/CI/badge.svg)](https://github.com/open-telemetry/opentelemetry-rust/actions?query=workflow%3ACI+branch%3Amain)
+[![codecov](https://codecov.io/gh/open-telemetry/opentelemetry-rust/branch/main/graph/badge.svg)](https://codecov.io/gh/open-telemetry/opentelemetry-rust)
 [![Slack](https://img.shields.io/badge/slack-@cncf/otel/rust-brightgreen.svg?logo=slack)](https://cloud-native.slack.com/archives/C03GDP0H023)
 
 ## Overview
 
-[`OpenTelemetry`] is a collection of tools, APIs, and SDKs used to instrument,
-generate, collect, and export telemetry data (metrics, logs, and traces) for
-analysis in order to understand your software's performance and behavior.
-
-This crate provides an exporter for sending trace and metric data in the OTLP
-format to the OpenTelemetry collector. The OpenTelemetry Collector offers a
-vendor-agnostic implementation on how to receive, process, and export telemetry
-data. In addition, it removes the need to run, operate, and maintain multiple
-agents/collectors in order to support open-source telemetry data formats (e.g.
-Jaeger, Prometheus, etc.) sending to multiple open-source or commercial
-back-ends.
-
-[`OTLP`]: https://github.com/open-telemetry/opentelemetry-collector
-[`OpenTelemetry`]: https://crates.io/crates/opentelemetry
-
-## Quickstart
-
-First make sure you have a running version of the opentelemetry collector you
-want to send data to:
-
-```shell
-$ docker run -p 4317:4317 otel/opentelemetry-collector-dev:latest
-```
-
-Then install a new pipeline with the recommended defaults to start exporting
-telemetry:
-
-```rust
-use opentelemetry::trace::Tracer;
-
-fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync + 'static>> {
-    // use tonic as grpc layer here.
-    let tracer = opentelemetry_otlp::new_pipeline()
-      .tracing()
-      .with_exporter(opentelemetry_otlp::new_exporter().tonic())
-      .install_simple()?;
-
-    tracer.in_span("doing_work", |cx| {
-        // Traced app logic here...
-    });
-
-    Ok(())
-}
-```
+OpenTelemetry is an Observability framework and toolkit designed to create and
+manage telemetry data such as traces, metrics, and logs. OpenTelemetry is
+vendor- and tool-agnostic, meaning that it can be used with a broad variety of
+Observability backends, including open source tools like [Jaeger] and
+[Prometheus], as well as commercial offerings.
 
-## Performance
+OpenTelemetry is *not* an observability backend like Jaeger, Prometheus, or other
+commercial vendors. OpenTelemetry is focused on the generation, collection,
+management, and export of telemetry. A major goal of OpenTelemetry is that you
+can easily instrument your applications or systems, no matter their language,
+infrastructure, or runtime environment. Crucially, the storage and visualization
+of telemetry is intentionally left to other tools.
 
-For optimal performance, a batch exporter is recommended as the simple exporter
-will export each span synchronously on drop. You can enable the [`rt-tokio`],
-[`rt-tokio-current-thread`] or [`rt-async-std`] features and specify a runtime
-on the pipeline builder to have a batch exporter configured for you
-automatically.
+*Compiler support: [requires `rustc` 1.64+][msrv]*
 
-```toml
-[dependencies]
-opentelemetry_sdk = { version = "*", features = ["async-std"] }
-opentelemetry-otlp = { version = "*", features = ["grpc-tonic"] }
-```
+[Prometheus]: https://prometheus.io
+[Jaeger]: https://www.jaegertracing.io
+[msrv]: #supported-rust-versions
 
-```rust
-let tracer = opentelemetry_otlp::new_pipeline()
-    .install_batch(opentelemetry_sdk::runtime::AsyncStd)?;
-```
+## Getting started
 
-[`tokio`]: https://tokio.rs
-[`async-std`]: https://async.rs
+See [docs](https://docs.rs/opentelemetry-otlp).
 
-## Kitchen Sink Full Configuration
+## Supported Rust Versions
 
-[Example](https://docs.rs/opentelemetry-otlp/latest/opentelemetry_otlp/#kitchen-sink-full-configuration)
-showing how to override all configuration options.
+OpenTelemetry is built against the latest stable release. The minimum supported
+version is 1.64. The current OpenTelemetry version is not guaranteed to build
+on Rust versions earlier than the minimum supported version.
 
-Generally there are two parts of configuration. One is metrics config
-or tracing config. Users can config it via [`OtlpTracePipeline`]
-or [`OtlpMetricPipeline`]. The other is exporting configuration.
-Users can set those configurations using [`OtlpExporterPipeline`] based
-on the choice of exporters.
+The current stable Rust compiler and the three most recent minor versions
+before it will always be supported. For example, if the current stable compiler
+version is 1.49, the minimum supported version will not be increased past 1.46,
+three minor versions prior. Increasing the minimum supported compiler version
+is not considered a semver breaking change as long as doing so complies with
+this policy.

opentelemetry-otlp/src/lib.rs

@@ -104,7 +104,6 @@
 //! The following feature flags offer additional configurations on http:
 //!
 //! * `http-proto`: Use http as transport layer, protobuf as body format.
-//! * `http-json`: Use http as transport layer, JSON as body format.
 //! * `reqwest-blocking-client`: Use reqwest blocking http client.
 //! * `reqwest-client`: Use reqwest http client.
 //! * `reqwest-rustls`: Use reqwest with TLS with system trust roots via `rustls-native-certs` crate.

opentelemetry-sdk/README.md

@@ -1,10 +1,11 @@
+# OpenTelemetry Rust SDK
+
 ![OpenTelemetry — An observability framework for cloud-native software.][splash]
 
 [splash]: https://raw.githubusercontent.com/open-telemetry/opentelemetry-rust/main/assets/logo-text.png
 
-# OpenTelemetry Rust SDK
-
-The Rust [OpenTelemetry](https://opentelemetry.io/) implementation.
+This crate contains the [OpenTelemetry](https://opentelemetry.io/) SDK
+implementation for Rust.
 
 [![Crates.io: opentelemetry-sdk](https://img.shields.io/crates/v/opentelemetry_sdk.svg)](https://crates.io/crates/opentelemetry_sdk)
 [![Documentation](https://docs.rs/opentelemetry_sdk/badge.svg)](https://docs.rs/opentelemetry_sdk)
@@ -15,27 +16,100 @@ The Rust [OpenTelemetry](https://opentelemetry.io/) implementation.
 
 ## Overview
 
-OpenTelemetry is a collection of tools, APIs, and SDKs used to instrument,
-generate, collect, and export telemetry data (metrics, logs, and traces) for
-analysis in order to understand your software's performance and behavior. You
-can export and analyze them using [Prometheus], [Jaeger], and other
-observability tools.
+OpenTelemetry is an Observability framework and toolkit designed to create and
+manage telemetry data such as traces, metrics, and logs. OpenTelemetry is
+vendor- and tool-agnostic, meaning that it can be used with a broad variety of
+Observability backends, including open source tools like [Jaeger] and
+[Prometheus], as well as commercial offerings.
+
+OpenTelemetry is *not* an observability backend like Jaeger, Prometheus, or other
+commercial vendors. OpenTelemetry is focused on the generation, collection,
+management, and export of telemetry. A major goal of OpenTelemetry is that you
+can easily instrument your applications or systems, no matter their language,
+infrastructure, or runtime environment. Crucially, the storage and visualization
+of telemetry is intentionally left to other tools.
 
 *Compiler support: [requires `rustc` 1.64+][msrv]*
 
 [Prometheus]: https://prometheus.io
 [Jaeger]: https://www.jaegertracing.io
 [msrv]: #supported-rust-versions
 
-## OpenTelemetry Benchmarks
+### What does this crate contain?
+
+This crate is official SDK implementation of OpenTelemetry encompassing several
+aspects of OpenTelemetry, such as context management and propagation, logging,
+tracing, and metrics. It follows the [OpenTelemetry
+specification](https://github.com/open-telemetry/opentelemetry-specification).
+Here's a breakdown of its components:
+
+- **[Propagators
+  Implementation](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/context/api-propagators.md):**
+  While the `opentelemetry` crate contained the API, this crate contains the actual implementation.
+- **[Logs SDK](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/sdk.md):**
+  Implements the Logs SDK specification.
+- **[Tracing
+  SDK](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md):**
+  Implements the Tracing SDK specification.
+- **[Metrics
+  SDK](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md):**
+  Implements the Metrics SDK specification.
 
-From the root directory, run the following command:
+This crate lights up the telemetry, by replacing the facade or no-op
+implementation from `opentelemetry` crate. In many ways, one can think of
+`opentelemetry` as the crate containing the "traits" along with a no-op
+implementation, and this (`opentelemetry-sdk`) crate containing a real
+implementation to replace the default no-ops.
 
-```sh
-cargo bench
-```
+This crate defines the telemetry pipeline, and makes telemetry available for
+processors etc., but the actual exporting of telemetry requires additional
+crates, such as
+[opentelemetry-stdout](https://crates.io/crates/opentelemetry-stdout),
+[opentelemetry-otlp](https://crates.io/crates/opentelemetry-otlp) etc.
+
+### Related crates
+
+Unless you are a plugin (custom Samplers, Processors etc.) author, you will almost always need to use additional
+crates along with this. Given this crate has no exporting capability, an
+OpenTelemetry Exporter is almost always required. OpenTelemetry provides the following exporters:
+
+- **[opentelemetry-stdout](https://crates.io/crates/opentelemetry-stdout):**
+  Prints telemetry to stdout, primarily used for learning/debugging purposes.
+- **[opentelemetry-otlp](https://crates.io/crates/opentelemetry-otlp):** Exports
+  telemetry (logs, metrics and traces) in the [OTLP
+  format](https://github.com/open-telemetry/opentelemetry-specification/tree/main/specification/protocol)
+  to an endpoint accepting OTLP. This could be the [OTel
+  Collector](https://github.com/open-telemetry/opentelemetry-collector),
+  telemetry backends like [Jaeger](https://www.jaegertracing.io/),
+  [Prometheus](https://prometheus.io/docs/prometheus/latest/feature_flags/#otlp-receiver)
+  or [vendor specific endpoints](https://opentelemetry.io/ecosystem/vendors/).
+- **[opentelemetry-zipkin](https://crates.io/crates/opentelemetry-zipkin):**
+  Exports telemetry (traces only) to Zipkin following [OpenTelemetry to Zipkin
+  specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk_exporters/zipkin.md).
+- **[opentelemetry-prometheus](https://crates.io/crates/opentelemetry-prometheus):**
+  Exports telemetry (metrics only) to Prometheus following [OpenTelemetry to
+  Prometheus
+  specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk_exporters/prometheus.md).
+
+OpenTelemetry Rust also has a [contrib
+repo](https://github.com/open-telemetry/opentelemetry-rust-contrib), where
+additional exporters could be found. Check [OpenTelemetry
+Registry](https://opentelemetry.io/ecosystem/registry/?language=rust) for
+additional exporters and other related components as well.
+
+## Getting started
+
+See [docs](https://docs.rs/opentelemetry-sdk).
 
 ## Supported Rust Versions
-OpenTelemetry is built against the latest stable release. The minimum supported version is 1.64. The current OpenTelemetry version is not guaranteed to build on Rust versions earlier than the minimum supported version.
 
-The current stable Rust compiler and the three most recent minor versions before it will always be supported. For example, if the current stable compiler version is 1.64, the minimum supported version will not be increased past 1.46, three minor versions prior. Increasing the minimum supported compiler version is not considered a semver breaking change as long as doing so complies with this policy.
+OpenTelemetry is built against the latest stable release. The minimum supported
+version is 1.64. The current OpenTelemetry version is not guaranteed to build
+on Rust versions earlier than the minimum supported version.
+
+The current stable Rust compiler and the three most recent minor versions
+before it will always be supported. For example, if the current stable compiler
+version is 1.49, the minimum supported version will not be increased past 1.46,
+three minor versions prior. Increasing the minimum supported compiler version
+is not considered a semver breaking change as long as doing so complies with
+this policy.