Skip to content

Commit 9e96cff

Browse files
cijothomascijothomas
authored
Merge branch 'main' into cijothomas/release-may-2024
2 parents 53ea97f + a4d9211 commit 9e96cff

File tree

4 files changed

+157
-138
lines changed

4 files changed

+157
-138
lines changed

‎opentelemetry-otlp/README.md

+33-72
Original file line numberDiff line numberDiff line change
@@ -1,93 +1,54 @@
1+
# OpenTelemetry OTLP Exporter
2+
13
![OpenTelemetry — An observability framework for cloud-native software.][splash]
24

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

5-
# OpenTelemetry Collector Rust Exporter
6-
7-
[`OTLP`] integration for applications instrumented with [`OpenTelemetry`].
7+
This crate contains the [OpenTelemetry](https://opentelemetry.io/) Exporter
8+
implementation for
9+
[OTLP](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md).
810

911
[![Crates.io: opentelemetry-otlp](https://img.shields.io/crates/v/opentelemetry-otlp.svg)](https://crates.io/crates/opentelemetry-otlp)
1012
[![Documentation](https://docs.rs/opentelemetry-otlp/badge.svg)](https://docs.rs/opentelemetry-otlp)
1113
[![LICENSE](https://img.shields.io/crates/l/opentelemetry-otlp)](./LICENSE)
1214
[![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)
15+
[![codecov](https://codecov.io/gh/open-telemetry/opentelemetry-rust/branch/main/graph/badge.svg)](https://codecov.io/gh/open-telemetry/opentelemetry-rust)
1316
[![Slack](https://img.shields.io/badge/slack-@cncf/otel/rust-brightgreen.svg?logo=slack)](https://cloud-native.slack.com/archives/C03GDP0H023)
1417

1518
## Overview
1619

17-
[`OpenTelemetry`] is a collection of tools, APIs, and SDKs used to instrument,
18-
generate, collect, and export telemetry data (metrics, logs, and traces) for
19-
analysis in order to understand your software's performance and behavior.
20-
21-
This crate provides an exporter for sending trace and metric data in the OTLP
22-
format to the OpenTelemetry collector. The OpenTelemetry Collector offers a
23-
vendor-agnostic implementation on how to receive, process, and export telemetry
24-
data. In addition, it removes the need to run, operate, and maintain multiple
25-
agents/collectors in order to support open-source telemetry data formats (e.g.
26-
Jaeger, Prometheus, etc.) sending to multiple open-source or commercial
27-
back-ends.
28-
29-
[`OTLP`]: https://github.com/open-telemetry/opentelemetry-collector
30-
[`OpenTelemetry`]: https://crates.io/crates/opentelemetry
31-
32-
## Quickstart
33-
34-
First make sure you have a running version of the opentelemetry collector you
35-
want to send data to:
36-
37-
```shell
38-
$ docker run -p 4317:4317 otel/opentelemetry-collector-dev:latest
39-
```
40-
41-
Then install a new pipeline with the recommended defaults to start exporting
42-
telemetry:
43-
44-
```rust
45-
use opentelemetry::trace::Tracer;
46-
47-
fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync + 'static>> {
48-
// use tonic as grpc layer here.
49-
let tracer = opentelemetry_otlp::new_pipeline()
50-
.tracing()
51-
.with_exporter(opentelemetry_otlp::new_exporter().tonic())
52-
.install_simple()?;
53-
54-
tracer.in_span("doing_work", |cx| {
55-
// Traced app logic here...
56-
});
57-
58-
Ok(())
59-
}
60-
```
20+
OpenTelemetry is an Observability framework and toolkit designed to create and
21+
manage telemetry data such as traces, metrics, and logs. OpenTelemetry is
22+
vendor- and tool-agnostic, meaning that it can be used with a broad variety of
23+
Observability backends, including open source tools like [Jaeger] and
24+
[Prometheus], as well as commercial offerings.
6125

62-
## Performance
26+
OpenTelemetry is *not* an observability backend like Jaeger, Prometheus, or other
27+
commercial vendors. OpenTelemetry is focused on the generation, collection,
28+
management, and export of telemetry. A major goal of OpenTelemetry is that you
29+
can easily instrument your applications or systems, no matter their language,
30+
infrastructure, or runtime environment. Crucially, the storage and visualization
31+
of telemetry is intentionally left to other tools.
6332

64-
For optimal performance, a batch exporter is recommended as the simple exporter
65-
will export each span synchronously on drop. You can enable the [`rt-tokio`],
66-
[`rt-tokio-current-thread`] or [`rt-async-std`] features and specify a runtime
67-
on the pipeline builder to have a batch exporter configured for you
68-
automatically.
33+
*Compiler support: [requires `rustc` 1.64+][msrv]*
6934

70-
```toml
71-
[dependencies]
72-
opentelemetry_sdk = { version = "*", features = ["async-std"] }
73-
opentelemetry-otlp = { version = "*", features = ["grpc-tonic"] }
74-
```
35+
[Prometheus]: https://prometheus.io
36+
[Jaeger]: https://www.jaegertracing.io
37+
[msrv]: #supported-rust-versions
7538

76-
```rust
77-
let tracer = opentelemetry_otlp::new_pipeline()
78-
.install_batch(opentelemetry_sdk::runtime::AsyncStd)?;
79-
```
39+
## Getting started
8040

81-
[`tokio`]: https://tokio.rs
82-
[`async-std`]: https://async.rs
41+
See [docs](https://docs.rs/opentelemetry-otlp).
8342

84-
## Kitchen Sink Full Configuration
43+
## Supported Rust Versions
8544

86-
[Example](https://docs.rs/opentelemetry-otlp/latest/opentelemetry_otlp/#kitchen-sink-full-configuration)
87-
showing how to override all configuration options.
45+
OpenTelemetry is built against the latest stable release. The minimum supported
46+
version is 1.64. The current OpenTelemetry version is not guaranteed to build
47+
on Rust versions earlier than the minimum supported version.
8848

89-
Generally there are two parts of configuration. One is metrics config
90-
or tracing config. Users can config it via [`OtlpTracePipeline`]
91-
or [`OtlpMetricPipeline`]. The other is exporting configuration.
92-
Users can set those configurations using [`OtlpExporterPipeline`] based
93-
on the choice of exporters.
49+
The current stable Rust compiler and the three most recent minor versions
50+
before it will always be supported. For example, if the current stable compiler
51+
version is 1.49, the minimum supported version will not be increased past 1.46,
52+
three minor versions prior. Increasing the minimum supported compiler version
53+
is not considered a semver breaking change as long as doing so complies with
54+
this policy.

‎opentelemetry-sdk/README.md

+89-15
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
1+
# OpenTelemetry Rust SDK
2+
13
![OpenTelemetry — An observability framework for cloud-native software.][splash]
24

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

5-
# OpenTelemetry Rust SDK
6-
7-
The Rust [OpenTelemetry](https://opentelemetry.io/) implementation.
7+
This crate contains the [OpenTelemetry](https://opentelemetry.io/) SDK
8+
implementation for Rust.
89

910
[![Crates.io: opentelemetry-sdk](https://img.shields.io/crates/v/opentelemetry_sdk.svg)](https://crates.io/crates/opentelemetry_sdk)
1011
[![Documentation](https://docs.rs/opentelemetry_sdk/badge.svg)](https://docs.rs/opentelemetry_sdk)
@@ -15,27 +16,100 @@ The Rust [OpenTelemetry](https://opentelemetry.io/) implementation.
1516

1617
## Overview
1718

18-
OpenTelemetry is a collection of tools, APIs, and SDKs used to instrument,
19-
generate, collect, and export telemetry data (metrics, logs, and traces) for
20-
analysis in order to understand your software's performance and behavior. You
21-
can export and analyze them using [Prometheus], [Jaeger], and other
22-
observability tools.
19+
OpenTelemetry is an Observability framework and toolkit designed to create and
20+
manage telemetry data such as traces, metrics, and logs. OpenTelemetry is
21+
vendor- and tool-agnostic, meaning that it can be used with a broad variety of
22+
Observability backends, including open source tools like [Jaeger] and
23+
[Prometheus], as well as commercial offerings.
24+
25+
OpenTelemetry is *not* an observability backend like Jaeger, Prometheus, or other
26+
commercial vendors. OpenTelemetry is focused on the generation, collection,
27+
management, and export of telemetry. A major goal of OpenTelemetry is that you
28+
can easily instrument your applications or systems, no matter their language,
29+
infrastructure, or runtime environment. Crucially, the storage and visualization
30+
of telemetry is intentionally left to other tools.
2331

2432
*Compiler support: [requires `rustc` 1.64+][msrv]*
2533

2634
[Prometheus]: https://prometheus.io
2735
[Jaeger]: https://www.jaegertracing.io
2836
[msrv]: #supported-rust-versions
2937

30-
## OpenTelemetry Benchmarks
38+
### What does this crate contain?
39+
40+
This crate is official SDK implementation of OpenTelemetry encompassing several
41+
aspects of OpenTelemetry, such as context management and propagation, logging,
42+
tracing, and metrics. It follows the [OpenTelemetry
43+
specification](https://github.com/open-telemetry/opentelemetry-specification).
44+
Here's a breakdown of its components:
45+
46+
- **[Propagators
47+
Implementation](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/context/api-propagators.md):**
48+
While the `opentelemetry` crate contained the API, this crate contains the actual implementation.
49+
- **[Logs SDK](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/sdk.md):**
50+
Implements the Logs SDK specification.
51+
- **[Tracing
52+
SDK](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md):**
53+
Implements the Tracing SDK specification.
54+
- **[Metrics
55+
SDK](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md):**
56+
Implements the Metrics SDK specification.
3157

32-
From the root directory, run the following command:
58+
This crate lights up the telemetry, by replacing the facade or no-op
59+
implementation from `opentelemetry` crate. In many ways, one can think of
60+
`opentelemetry` as the crate containing the "traits" along with a no-op
61+
implementation, and this (`opentelemetry-sdk`) crate containing a real
62+
implementation to replace the default no-ops.
3363

34-
```sh
35-
cargo bench
36-
```
64+
This crate defines the telemetry pipeline, and makes telemetry available for
65+
processors etc., but the actual exporting of telemetry requires additional
66+
crates, such as
67+
[opentelemetry-stdout](https://crates.io/crates/opentelemetry-stdout),
68+
[opentelemetry-otlp](https://crates.io/crates/opentelemetry-otlp) etc.
69+
70+
### Related crates
71+
72+
Unless you are a plugin (custom Samplers, Processors etc.) author, you will almost always need to use additional
73+
crates along with this. Given this crate has no exporting capability, an
74+
OpenTelemetry Exporter is almost always required. OpenTelemetry provides the following exporters:
75+
76+
- **[opentelemetry-stdout](https://crates.io/crates/opentelemetry-stdout):**
77+
Prints telemetry to stdout, primarily used for learning/debugging purposes.
78+
- **[opentelemetry-otlp](https://crates.io/crates/opentelemetry-otlp):** Exports
79+
telemetry (logs, metrics and traces) in the [OTLP
80+
format](https://github.com/open-telemetry/opentelemetry-specification/tree/main/specification/protocol)
81+
to an endpoint accepting OTLP. This could be the [OTel
82+
Collector](https://github.com/open-telemetry/opentelemetry-collector),
83+
telemetry backends like [Jaeger](https://www.jaegertracing.io/),
84+
[Prometheus](https://prometheus.io/docs/prometheus/latest/feature_flags/#otlp-receiver)
85+
or [vendor specific endpoints](https://opentelemetry.io/ecosystem/vendors/).
86+
- **[opentelemetry-zipkin](https://crates.io/crates/opentelemetry-zipkin):**
87+
Exports telemetry (traces only) to Zipkin following [OpenTelemetry to Zipkin
88+
specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk_exporters/zipkin.md).
89+
- **[opentelemetry-prometheus](https://crates.io/crates/opentelemetry-prometheus):**
90+
Exports telemetry (metrics only) to Prometheus following [OpenTelemetry to
91+
Prometheus
92+
specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk_exporters/prometheus.md).
93+
94+
OpenTelemetry Rust also has a [contrib
95+
repo](https://github.com/open-telemetry/opentelemetry-rust-contrib), where
96+
additional exporters could be found. Check [OpenTelemetry
97+
Registry](https://opentelemetry.io/ecosystem/registry/?language=rust) for
98+
additional exporters and other related components as well.
99+
100+
## Getting started
101+
102+
See [docs](https://docs.rs/opentelemetry-sdk).
37103

38104
## Supported Rust Versions
39-
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.
40105

41-
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.
106+
OpenTelemetry is built against the latest stable release. The minimum supported
107+
version is 1.64. The current OpenTelemetry version is not guaranteed to build
108+
on Rust versions earlier than the minimum supported version.
109+
110+
The current stable Rust compiler and the three most recent minor versions
111+
before it will always be supported. For example, if the current stable compiler
112+
version is 1.49, the minimum supported version will not be increased past 1.46,
113+
three minor versions prior. Increasing the minimum supported compiler version
114+
is not considered a semver breaking change as long as doing so complies with
115+
this policy.

‎opentelemetry-stdout/README.md

+30-50
Original file line numberDiff line numberDiff line change
@@ -1,71 +1,51 @@
1+
# OpenTelemetry Stdout Exporter
2+
13
![OpenTelemetry — An observability framework for cloud-native software.][splash]
24

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

5-
# OpenTelemetry Stdout
6-
7-
Exporters for applications instrumented with [`OpenTelemetry`].
7+
This crate contains an [OpenTelemetry](https://opentelemetry.io/) exporter that
8+
prints telemetry (logs, metrics and traces) to the standard output.
89

910
[![Crates.io: opentelemetry-stdout](https://img.shields.io/crates/v/opentelemetry-stdout.svg)](https://crates.io/crates/opentelemetry-stdout)
1011
[![Documentation](https://docs.rs/opentelemetry-stdout/badge.svg)](https://docs.rs/opentelemetry-stdout)
1112
[![LICENSE](https://img.shields.io/crates/l/opentelemetry-stdout)](./LICENSE)
1213
[![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)
14+
[![codecov](https://codecov.io/gh/open-telemetry/opentelemetry-rust/branch/main/graph/badge.svg)](https://codecov.io/gh/open-telemetry/opentelemetry-rust)
1315
[![Slack](https://img.shields.io/badge/slack-@cncf/otel/rust-brightgreen.svg?logo=slack)](https://cloud-native.slack.com/archives/C03GDP0H023)
1416

1517
## Overview
1618

17-
[`OpenTelemetry`] is a collection of tools, APIs, and SDKs used to instrument,
18-
generate, collect, and export telemetry data (metrics, logs, and traces) for
19-
analysis in order to understand your software's performance and behavior. This
20-
crate provides exporters that export to stdout or any implementation of
21-
[`std::io::Write`].
19+
OpenTelemetry is an Observability framework and toolkit designed to create and
20+
manage telemetry data such as traces, metrics, and logs. OpenTelemetry is
21+
vendor- and tool-agnostic, meaning that it can be used with a broad variety of
22+
Observability backends, including open source tools like [Jaeger] and
23+
[Prometheus], as well as commercial offerings.
24+
25+
OpenTelemetry is *not* an observability backend like Jaeger, Prometheus, or other
26+
commercial vendors. OpenTelemetry is focused on the generation, collection,
27+
management, and export of telemetry. A major goal of OpenTelemetry is that you
28+
can easily instrument your applications or systems, no matter their language,
29+
infrastructure, or runtime environment. Crucially, the storage and visualization
30+
of telemetry is intentionally left to other tools.
2231

2332
*Compiler support: [requires `rustc` 1.64+][msrv]*
2433

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

29-
### Quickstart
30-
31-
Export telemetry signals to stdout.
32-
33-
```rust
34-
use opentelemetry::{
35-
metrics::MeterProvider as _,
36-
trace::{Span, Tracer, TracerProvider as _},
37-
Context, KeyValue,
38-
};
39-
use opentelemetry_sdk::{
40-
metrics::{MeterProvider, PeriodicReader},
41-
runtime,
42-
trace::{BatchSpanProcessor, TracerProvider},
43-
};
44-
45-
fn init_trace() -> TracerProvider {
46-
let exporter = opentelemetry_stdout::SpanExporter::default();
47-
let processor = BatchSpanProcessor::builder(exporter, runtime::Tokio).build();
48-
TracerProvider::builder()
49-
.with_span_processor(processor)
50-
.build()
51-
}
52-
53-
fn init_metrics() -> MeterProvider {
54-
let exporter = opentelemetry_stdout::MetricsExporter::default();
55-
let reader = PeriodicReader::builder(exporter, runtime::Tokio).build();
56-
MeterProvider::builder().with_reader(reader).build()
57-
}
58-
59-
let tracer_provider = init_trace();
60-
let meter_provider = init_metrics();
61-
```
62-
63-
Recorded traces and metrics will now be sent to stdout:
64-
65-
```
66-
{"resourceMetrics":{"resource":{"attributes":[{"key":"service.name","value":{"str..
67-
{"resourceSpans":[{"resource":{"attributes":[{"key":"service.name","value":{"stri..
68-
```
38+
### What does this crate contain?
39+
40+
This crate includes exporters that support all three signals - Logs, Metrics,
41+
and Traces — to standard output. It is intended solely for educational and
42+
debugging purposes. Please note, this crate is not optimized for performance,
43+
and the format of the output may change, making it unsuitable for production
44+
environments
45+
46+
## Getting started
47+
48+
See [docs](https://docs.rs/opentelemetry-stdout).
6949

7050
## Supported Rust Versions
7151

‎opentelemetry/README.md

+5-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,8 @@
1-
# OpenTelemetry Rust
1+
# OpenTelemetry Rust API
2+
3+
![OpenTelemetry — An observability framework for cloud-native software.][splash]
4+
5+
[splash]: https://raw.githubusercontent.com/open-telemetry/opentelemetry-rust/main/assets/logo-text.png
26

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

0 commit comments

Comments
 (0)