Add logos and overview section to crate readmes (#311)

jtescher · frigus02 · web-flow · commit bf28d41c5102 · 2020-10-27T09:03:56.000-07:00
Co-authored-by: Jan Kühle &lt;jkuehle90@gmail.com&gt;
diff --git a/README.md b/README.md
@@ -1,16 +1,28 @@
-# OpenTelemetry-Rust
+![OpenTelemetry — An observability framework for cloud-native software.][splash]
+
+[splash]: https://raw.githubusercontent.com/open-telemetry/opentelemetry-rust/master/assets/logo-text.png
+
+# OpenTelemetry Rust
+
+The Rust [OpenTelemetry](https://opentelemetry.io/) implementation.
 
 [![Crates.io: opentelemetry](https://img.shields.io/crates/v/opentelemetry.svg)](https://crates.io/crates/opentelemetry)
 [![Documentation](https://docs.rs/opentelemetry/badge.svg)](https://docs.rs/opentelemetry)
-[![Crates.io](https://img.shields.io/crates/l/opentelemetry)](./LICENSE)
+[![LICENSE](https://img.shields.io/crates/l/opentelemetry)](./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%3Amaster)
 [![Gitter chat](https://img.shields.io/badge/gitter-join%20chat%20%E2%86%92-brightgreen.svg)](https://gitter.im/open-telemetry/opentelemetry-rust)
 
-The Rust [OpenTelemetry](https://opentelemetry.io/) implementation.
+[Website](https://opentelemetry.io/) |
+[Chat](https://gitter.im/open-telemetry/opentelemetry-rust) |
+[Documentation](https://docs.rs/opentelemetry)
+
+## Overview
 
-OpenTelemetry provides a single set of APIs, libraries, agents, and collector
-services to capture distributed traces and metrics from your application. You
-can analyze them using [Prometheus], [Jaeger], and other observability tools.
+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.
 
 *Compiler support: [requires `rustc` 1.42+][msrv]*
 
diff --git a/assets/logo-text.png b/assets/logo-text.png
diff --git a/assets/logo.svg b/assets/logo.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" role="img" viewBox="-12.7 -12.7 1024.4 1024.4"><path fill="#f5a800" d="M528.7 545.9c-42 42-42 110.1.0 152.1s110.1 42 152.1.0 42-110.1.0-152.1-110.1-42-152.1.0zm113.7 113.8c-20.8 20.8-54.5 20.8-75.3.0s-20.8-54.5.0-75.3 54.5-20.8 75.3.0c20.8 20.7 20.8 54.5.0 75.3zm36.6-643-65.9 65.9c-12.9 12.9-12.9 34.1.0 47l257.3 257.3c12.9 12.9 34.1 12.9 47 0l65.9-65.9c12.9-12.9 12.9-34.1.0-47L725.9 16.7c-12.9-12.9-34-12.9-46.9.0zM217.3 858.8c11.7-11.7 11.7-30.8.0-42.5l-33.5-33.5c-11.7-11.7-30.8-11.7-42.5.0L72.1 852l-.1.1-19-19c-10.5-10.5-27.6-10.5-38 0-10.5 10.5-10.5 27.6.0 38l114 114c10.5 10.5 27.6 10.5 38 0s10.5-27.6.0-38l-19-19 .1-.1 69.2-69.2z"></path><path fill="#425cc7" d="M565.9 205.9 419.5 352.3c-13 13-13 34.4.0 47.4l90.4 90.4c63.9-46 153.5-40.3 211 17.2l73.2-73.2c13-13 13-34.4.0-47.4L613.3 205.9c-13-13.1-34.4-13.1-47.4.0zm-94 322.3-53.4-53.4c-12.5-12.5-33-12.5-45.5.0L184.7 663.2c-12.5 12.5-12.5 33 0 45.5l106.7 106.7c12.5 12.5 33 12.5 45.5.0L458 694.1c-25.6-52.9-21-116.8 13.9-165.9z"></path></svg>
diff --git a/opentelemetry-contrib/README.md b/opentelemetry-contrib/README.md
@@ -1,3 +1,27 @@
+![OpenTelemetry — An observability framework for cloud-native software.][splash]
+
+[splash]: https://raw.githubusercontent.com/open-telemetry/opentelemetry-rust/master/assets/logo-text.png
+
 # OpenTelemetry Contrib
 
-Contrib repo for OpenTelemetry Rust implementation.
+Community supported vendor integrations for applications instrumented with [`OpenTelemetry`].
+
+[![Crates.io: opentelemetry-contrib](https://img.shields.io/crates/v/opentelemetry-contrib.svg)](https://crates.io/crates/opentelemetry-contrib)
+[![Documentation](https://docs.rs/opentelemetry-contrib/badge.svg)](https://docs.rs/opentelemetry-contrib)
+[![LICENSE](https://img.shields.io/crates/l/opentelemetry-contrib)](./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%3Amaster)
+[![Gitter chat](https://img.shields.io/badge/gitter-join%20chat%20%E2%86%92-brightgreen.svg)](https://gitter.im/open-telemetry/opentelemetry-rust)
+
+[Documentation](https://docs.rs/opentelemetry-contrib) |
+[Chat](https://gitter.im/open-telemetry/opentelemetry-rust)
+
+## 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 additional propagators and exporters for sending telemetry data
+to vendors like [`Datadog`].
+
+[`Datadog`]: https://www.datadoghq.com/
+[`OpenTelemetry`]: https://crates.io/crates/opentelemetry
diff --git a/opentelemetry-contrib/src/lib.rs b/opentelemetry-contrib/src/lib.rs
@@ -14,6 +14,9 @@
     unused
 )]
 #![cfg_attr(docsrs, feature(doc_cfg), deny(broken_intra_doc_links))]
+#![doc(
+    html_logo_url = "https://raw.githubusercontent.com/open-telemetry/opentelemetry-rust/master/assets/logo.svg"
+)]
 #![cfg_attr(test, deny(warnings))]
 
 #[cfg(feature = "datadog")]
diff --git a/opentelemetry-jaeger/README.md b/opentelemetry-jaeger/README.md
@@ -1,12 +1,32 @@
+![OpenTelemetry — An observability framework for cloud-native software.][splash]
+
+[splash]: https://raw.githubusercontent.com/open-telemetry/opentelemetry-rust/master/assets/logo-text.png
+
 # OpenTelemetry Jaeger
 
-Collects OpenTelemetry spans and reports them to a given Jaeger `agent` or
-`collector` endpoint. See the [Jaeger Docs] for details about Jaeger and
-deployment information.
+[`Jaeger`] integration for applications instrumented with [`OpenTelemetry`].
+
+[![Crates.io: opentelemetry-jaeger](https://img.shields.io/crates/v/opentelemetry-jaeger.svg)](https://crates.io/crates/opentelemetry-jaeger)
+[![Documentation](https://docs.rs/opentelemetry-jaeger/badge.svg)](https://docs.rs/opentelemetry-jaeger)
+[![LICENSE](https://img.shields.io/crates/l/opentelemetry-jaeger)](./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%3Amaster)
+[![Gitter chat](https://img.shields.io/badge/gitter-join%20chat%20%E2%86%92-brightgreen.svg)](https://gitter.im/open-telemetry/opentelemetry-rust)
+
+[Documentation](https://docs.rs/opentelemetry-jaeger) |
+[Chat](https://gitter.im/open-telemetry/opentelemetry-rust)
+
+## 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 a trace pipeline and exporter for sending span information to a
+Jaeger `agent` or `collector` endpoint for processing and visualization.
 
 *Compiler support: [requires `rustc` 1.42+][msrv]*
 
-[Jaeger Docs]: https://www.jaegertracing.io/docs/
+[`Jaeger`]: https://www.jaegertracing.io/
+[`OpenTelemetry`]: https://crates.io/crates/opentelemetry
 [msrv]: #supported-rust-versions
 
 ### Quickstart
@@ -35,7 +55,7 @@ fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync + 'static>> {
 }
 ```
 
-![Jaeger UI](trace.png)
+![Jaeger UI](https://raw.githubusercontent.com/open-telemetry/opentelemetry-rust/master/opentelemetry-jaeger/trace.png)
 
 ## Performance
 
diff --git a/opentelemetry-jaeger/src/lib.rs b/opentelemetry-jaeger/src/lib.rs
@@ -167,6 +167,9 @@
     unused
 )]
 #![cfg_attr(docsrs, feature(doc_cfg), deny(broken_intra_doc_links))]
+#![doc(
+    html_logo_url = "https://raw.githubusercontent.com/open-telemetry/opentelemetry-rust/master/assets/logo.svg"
+)]
 #![cfg_attr(test, deny(warnings))]
 
 mod agent;
diff --git a/opentelemetry-otlp/README.md b/opentelemetry-otlp/README.md
@@ -1,13 +1,37 @@
+![OpenTelemetry — An observability framework for cloud-native software.][splash]
+
+[splash]: https://raw.githubusercontent.com/open-telemetry/opentelemetry-rust/master/assets/logo-text.png
+
 # OpenTelemetry Collector Rust Exporter
 
-The OTLP Exporter supports exporting trace and metric data in the OTLP format to
-the OpenTelemetry collector. The OpenTelemetry Collector offers a
+[`OTLP`] integration for applications instrumented with [`OpenTelemetry`].
+
+[![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%3Amaster)
+[![Gitter chat](https://img.shields.io/badge/gitter-join%20chat%20%E2%86%92-brightgreen.svg)](https://gitter.im/open-telemetry/opentelemetry-rust)
+
+[Documentation](https://docs.rs/opentelemetry-otlp) |
+[Chat](https://gitter.im/open-telemetry/opentelemetry-rust)
+
+## 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
diff --git a/opentelemetry-prometheus/README.md b/opentelemetry-prometheus/README.md
@@ -1,3 +1,27 @@
+![OpenTelemetry — An observability framework for cloud-native software.][splash]
+
+[splash]: https://raw.githubusercontent.com/open-telemetry/opentelemetry-rust/master/assets/logo-text.png
+
 # OpenTelemetry Prometheus 
 
-A Prometheus exporter implementation for OpenTelemetry Rust.
+[`Prometheus`] integration for applications instrumented with [`OpenTelemetry`].
+
+[![Crates.io: opentelemetry-prometheus](https://img.shields.io/crates/v/opentelemetry-prometheus.svg)](https://crates.io/crates/opentelemetry-prometheus)
+[![Documentation](https://docs.rs/opentelemetry-prometheus/badge.svg)](https://docs.rs/opentelemetry-prometheus)
+[![LICENSE](https://img.shields.io/crates/l/opentelemetry-prometheus)](./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%3Amaster)
+[![Gitter chat](https://img.shields.io/badge/gitter-join%20chat%20%E2%86%92-brightgreen.svg)](https://gitter.im/open-telemetry/opentelemetry-rust)
+
+[Documentation](https://docs.rs/opentelemetry-prometheus) |
+[Chat](https://gitter.im/open-telemetry/opentelemetry-rust)
+
+## 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 a pipeline and exporter for exposing metrics information to
+Prometheus for processing and visualization.
+
+[`Prometheus`]: https://prometheus.io
+[`OpenTelemetry`]: https://crates.io/crates/opentelemetry
diff --git a/opentelemetry-prometheus/src/lib.rs b/opentelemetry-prometheus/src/lib.rs
@@ -59,6 +59,9 @@
     unused
 )]
 #![cfg_attr(docsrs, feature(doc_cfg), deny(broken_intra_doc_links))]
+#![doc(
+    html_logo_url = "https://raw.githubusercontent.com/open-telemetry/opentelemetry-rust/master/assets/logo.svg"
+)]
 #![cfg_attr(test, deny(warnings))]
 
 use opentelemetry::global;
diff --git a/opentelemetry-semantic-conventions/README.md b/opentelemetry-semantic-conventions/README.md
@@ -1,3 +1,27 @@
+![OpenTelemetry — An observability framework for cloud-native software.][splash]
+
+[splash]: https://raw.githubusercontent.com/open-telemetry/opentelemetry-rust/master/assets/logo-text.png
+
 # OpenTelemetry Semantic Conventions
 
-OpenTelemetry semantic conventions are agreed standardized naming patterns for OpenTelemetry things. This crate aims to be the centralized place to interact with these conventions.
+Semantic conventions for applications instrumented with [`OpenTelemetry`].
+
+[![Crates.io: opentelemetry-semantic-conventions](https://img.shields.io/crates/v/opentelemetry-semantic-conventions.svg)](https://crates.io/crates/opentelemetry-semantic-conventions)
+[![Documentation](https://docs.rs/opentelemetry-semantic-conventions/badge.svg)](https://docs.rs/opentelemetry-semantic-conventions)
+[![LICENSE](https://img.shields.io/crates/l/opentelemetry-semantic-conventions)](./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%3Amaster)
+[![Gitter chat](https://img.shields.io/badge/gitter-join%20chat%20%E2%86%92-brightgreen.svg)](https://gitter.im/open-telemetry/opentelemetry-rust)
+
+[Documentation](https://docs.rs/opentelemetry-semantic-conventions) |
+[Chat](https://gitter.im/open-telemetry/opentelemetry-rust)
+
+## 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 standardized naming patterns for attributes, labels, and
+resources to help facilitate interoperability and compatibility with processing
+and visualization tools. 
+
+[`OpenTelemetry`]: https://crates.io/crates/opentelemetry
diff --git a/opentelemetry-semantic-conventions/src/lib.rs b/opentelemetry-semantic-conventions/src/lib.rs
@@ -13,6 +13,9 @@
     unused
 )]
 #![cfg_attr(test, deny(warnings))]
+#![doc(
+    html_logo_url = "https://raw.githubusercontent.com/open-telemetry/opentelemetry-rust/master/assets/logo.svg"
+)]
 
 pub mod resource;
 pub mod trace;
diff --git a/opentelemetry-zipkin/README.md b/opentelemetry-zipkin/README.md
@@ -1,11 +1,32 @@
+![OpenTelemetry — An observability framework for cloud-native software.][splash]
+
+[splash]: https://raw.githubusercontent.com/open-telemetry/opentelemetry-rust/master/assets/logo-text.png
+
 # OpenTelemetry Zipkin
 
-Collects OpenTelemetry spans and reports them to a given Zipkin collector
-endpoint. See the [Zipkin Docs] for details and deployment information.
+[`Zipkin`] integration for applications instrumented with [`OpenTelemetry`].
+
+[![Crates.io: opentelemetry-zipkin](https://img.shields.io/crates/v/opentelemetry-zipkin.svg)](https://crates.io/crates/opentelemetry-zipkin)
+[![Documentation](https://docs.rs/opentelemetry-zipkin/badge.svg)](https://docs.rs/opentelemetry-zipkin)
+[![LICENSE](https://img.shields.io/crates/l/opentelemetry-zipkin)](./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%3Amaster)
+[![Gitter chat](https://img.shields.io/badge/gitter-join%20chat%20%E2%86%92-brightgreen.svg)](https://gitter.im/open-telemetry/opentelemetry-rust)
+
+[Documentation](https://docs.rs/opentelemetry-zipkin) |
+[Chat](https://gitter.im/open-telemetry/opentelemetry-rust)
+
+## 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 a trace pipeline and exporter for sending span information to a
+Zipkin collector for processing and visualization.
 
 *Compiler support: [requires `rustc` 1.42+][msrv]*
 
-[Zipkin Docs]: https://zipkin.io/
+[`Zipkin`]: https://zipkin.io/
+[`OpenTelemetry`]: https://crates.io/crates/opentelemetry
 [msrv]: #supported-rust-versions
 
 ## Quickstart
diff --git a/opentelemetry-zipkin/src/lib.rs b/opentelemetry-zipkin/src/lib.rs
@@ -148,6 +148,9 @@
     unused
 )]
 #![cfg_attr(docsrs, feature(doc_cfg), deny(broken_intra_doc_links))]
+#![doc(
+    html_logo_url = "https://raw.githubusercontent.com/open-telemetry/opentelemetry-rust/master/assets/logo.svg"
+)]
 #![cfg_attr(test, deny(warnings))]
 
 #[macro_use]
diff --git a/src/lib.rs b/src/lib.rs
@@ -54,6 +54,9 @@
 )]
 #![allow(clippy::needless_doctest_main)]
 #![cfg_attr(docsrs, feature(doc_cfg), deny(broken_intra_doc_links))]
+#![doc(
+    html_logo_url = "https://raw.githubusercontent.com/open-telemetry/opentelemetry-rust/master/assets/logo.svg"
+)]
 #![cfg_attr(test, deny(warnings))]
 
 mod api;
