-
Notifications
You must be signed in to change notification settings - Fork 459
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Make readme for api,sdk,stdout,otlp consistent (#1760)
Co-authored-by: Zhongyang Wu <[email protected]>
- Loading branch information
1 parent
d34de1a
commit a4d9211
Showing
4 changed files
with
157 additions
and
138 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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). | ||
|
|
||
| [](https://crates.io/crates/opentelemetry-otlp) | ||
| [](https://docs.rs/opentelemetry-otlp) | ||
| [](./LICENSE) | ||
| [](https://github.com/open-telemetry/opentelemetry-rust/actions?query=workflow%3ACI+branch%3Amain) | ||
| [](https://codecov.io/gh/open-telemetry/opentelemetry-rust) | ||
| [](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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters