Skip to content

Commit

Permalink
Make readme for api,sdk,stdout,otlp consistent (#1760)
Browse files Browse the repository at this point in the history 
Co-authored-by: Zhongyang Wu <zhongyang.wu@outlook.com>
  • Loading branch information
@cijothomas @TommyCpp
cijothomas and TommyCpp committed May 14, 2024
1 parent d34de1a commit a4d9211
Show file tree
Hide file tree
Showing 4 changed files with 157 additions and 138 deletions.
105 changes: 33 additions & 72 deletions opentelemetry-otlp/README.md
View file
Original file line number Diff line number Diff line change
@@ -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.
104 changes: 89 additions & 15 deletions opentelemetry-sdk/README.md
View file
Original file line number Diff line number Diff line change
@@ -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)
Expand All @@ -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.
80 changes: 30 additions & 50 deletions opentelemetry-stdout/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,71 +1,51 @@
# OpenTelemetry Stdout 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 Stdout

Exporters for applications instrumented with [`OpenTelemetry`].
This crate contains an [OpenTelemetry](https://opentelemetry.io/) exporter that
prints telemetry (logs, metrics and traces) to the standard output.

[![Crates.io: opentelemetry-stdout](https://img.shields.io/crates/v/opentelemetry-stdout.svg)](https://crates.io/crates/opentelemetry-stdout)
[![Documentation](https://docs.rs/opentelemetry-stdout/badge.svg)](https://docs.rs/opentelemetry-stdout)
[![LICENSE](https://img.shields.io/crates/l/opentelemetry-stdout)](./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 exporters that export to stdout or any implementation of
[`std::io::Write`].
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]*

[`std::io::Write`]: https://doc.rust-lang.org/std/io/trait.Write.html
[`OpenTelemetry`]: https://crates.io/crates/opentelemetry
[Prometheus]: https://prometheus.io
[Jaeger]: https://www.jaegertracing.io
[msrv]: #supported-rust-versions

### Quickstart

Export telemetry signals to stdout.

```rust
use opentelemetry::{
metrics::MeterProvider as _,
trace::{Span, Tracer, TracerProvider as _},
Context, KeyValue,
};
use opentelemetry_sdk::{
metrics::{MeterProvider, PeriodicReader},
runtime,
trace::{BatchSpanProcessor, TracerProvider},
};

fn init_trace() -> TracerProvider {
let exporter = opentelemetry_stdout::SpanExporter::default();
let processor = BatchSpanProcessor::builder(exporter, runtime::Tokio).build();
TracerProvider::builder()
.with_span_processor(processor)
.build()
}

fn init_metrics() -> MeterProvider {
let exporter = opentelemetry_stdout::MetricsExporter::default();
let reader = PeriodicReader::builder(exporter, runtime::Tokio).build();
MeterProvider::builder().with_reader(reader).build()
}

let tracer_provider = init_trace();
let meter_provider = init_metrics();
```

Recorded traces and metrics will now be sent to stdout:

```
{"resourceMetrics":{"resource":{"attributes":[{"key":"service.name","value":{"str..
{"resourceSpans":[{"resource":{"attributes":[{"key":"service.name","value":{"stri..
```
### What does this crate contain?

This crate includes exporters that support all three signals - Logs, Metrics,
and Traces — to standard output. It is intended solely for educational and
debugging purposes. Please note, this crate is not optimized for performance,
and the format of the output may change, making it unsuitable for production
environments

## Getting started

See [docs](https://docs.rs/opentelemetry-stdout).

## Supported Rust Versions

Expand Down
6 changes: 5 additions & 1 deletion opentelemetry/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,8 @@
# OpenTelemetry Rust
# OpenTelemetry Rust API

![OpenTelemetry — An observability framework for cloud-native software.][splash]

[splash]: https://raw.githubusercontent.com/open-telemetry/opentelemetry-rust/main/assets/logo-text.png

This crate contains the [OpenTelemetry](https://opentelemetry.io/) API for Rust.

Expand Down

0 comments on commit a4d9211

Please sign in to comment.