Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Rewrite readme page for opentelemetry crate #1586

Merged
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion opentelemetry/Cargo.toml
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
[package]
name = "opentelemetry"
version = "0.22.0"
description = "A metrics collection and distributed tracing framework"
description = "OpenTelemetry API for Rust"
homepage = "https://github.com/open-telemetry/opentelemetry-rust"
repository = "https://github.com/open-telemetry/opentelemetry-rust"
readme = "README.md"
Expand Down
192 changes: 72 additions & 120 deletions opentelemetry/README.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,6 @@
![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

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

[![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)
Expand All @@ -15,124 +11,84 @@ 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
cijothomas marked this conversation as resolved.
Show resolved Hide resolved
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

## Getting Started

```rust
use opentelemetry::{
global,
sdk::trace::TracerProvider,
trace::{Tracer, TracerProvider as _},
};

fn main() {
// Create a new trace pipeline that prints to stdout
let provider = TracerProvider::builder()
.with_simple_exporter(opentelemetry_stdout::SpanExporter::default())
.build();
let tracer = provider.tracer("readme_example");

tracer.in_span("doing_work", |cx| {
// Traced app logic here...
});

// Shutdown trace pipeline
global::shutdown_tracer_provider();
}
```

See the [examples](../examples) directory for different integration patterns.

## Ecosystem

### Related Crates

In addition to `opentelemetry`, which only carries the API, the
[`open-telemetry/opentelemetry-rust`] repository contains several additional
crates designed to be used with the `opentelemetry` ecosystem. This includes a
collection of trace `SpanExporter` and metrics pull and push controller
implementations, as well as utility and adapter crates to assist in propagating
state and instrumenting applications.

In particular, the following crates are likely to be of interest:

- [`opentelemetry-aws`] provides unofficial propagators for AWS X-ray.
- [`opentelemetry-contrib`] provides additional exporters and propagators that
are experimental.
- [`opentelemetry-datadog`] provides additional exporters to [`Datadog`].
- [`opentelemetry-dynatrace`] *Deprecated, last release 0.4.0* provides additional exporters to [`Dynatrace`]. See [README][`opentelemetry-dynatrace-readme`]
- [`opentelemetry-http`] provides an interface for injecting and extracting
trace information from [`http`] headers.
- [`opentelemetry-jaeger`] provides a pipeline and exporter for sending trace
information to [`Jaeger`].
- [`opentelemetry-otlp`] exporter for sending trace and metric data in the OTLP
format to the OpenTelemetry collector.
- [`opentelemetry-prometheus`] provides a pipeline and exporter for sending
metrics information to [`Prometheus`].
- [`opentelemetry_sdk`] provides the standard reference implementation of
opentelemetry.
- [`opentelemetry-semantic-conventions`] provides standard names and semantic
otel conventions.
- [`opentelemetry-stackdriver`] provides an exporter for Google's [Cloud Trace]
(which used to be called StackDriver).
- [`opentelemetry-zipkin`] provides a pipeline and exporter for sending trace
information to [`Zipkin`].

Additionally, there are also several third-party crates which are not
maintained by the `opentelemetry` project. These include:

- [`tracing-opentelemetry`] provides integration for applications instrumented
using the [`tracing`] API and ecosystem.
- [`actix-web-opentelemetry`] provides integration for the [`actix-web`] web
server and ecosystem.
- [`opentelemetry-application-insights`] provides an unofficial [Azure
Application Insights] exporter.
- [`opentelemetry-tide`] provides integration for the [`Tide`] web server and
ecosystem.

If you're the maintainer of an `opentelemetry` ecosystem crate not listed
above, please let us know! We'd love to add your project to the list!

[`open-telemetry/opentelemetry-rust`]: https://github.com/open-telemetry/opentelemetry-rust
[`opentelemetry-jaeger`]: https://crates.io/crates/opentelemetry-jaeger
[`Jaeger`]: https://www.jaegertracing.io
[`opentelemetry-otlp`]: https://crates.io/crates/opentelemetry-otlp
[`opentelemetry-http`]: https://crates.io/crates/opentelemetry-http
[`opentelemetry-prometheus`]: https://crates.io/crates/opentelemetry-prometheus
[`opentelemetry-aws`]: https://crates.io/crates/opentelemetry-aws
[`Prometheus`]: https://prometheus.io
[`opentelemetry-zipkin`]: https://crates.io/crates/opentelemetry-zipkin
[`Zipkin`]: https://zipkin.io
[`opentelemetry-contrib`]: https://crates.io/crates/opentelemetry-contrib
[`Datadog`]: https://www.datadoghq.com
[`Dynatrace`]: https://www.dynatrace.com
[`opentelemetry-datadog`]: https://crates.io/crates/opentelemetry-datadog
[`opentelemetry-dynatrace`]: https://crates.io/crates/opentelemetry-dynatrace
[`opentelemetry-dynatrace-readme`]: https://github.com/open-telemetry/opentelemetry-rust-contrib/blob/main/opentelemetry-dynatrace/README.md
[`opentelemetry-semantic-conventions`]: https://crates.io/crates/opentelemetry-semantic-conventions
[`http`]: https://crates.io/crates/http

[`tracing-opentelemetry`]: https://crates.io/crates/tracing-opentelemetry
[`tracing`]: https://crates.io/crates/tracing
[`actix-web-opentelemetry`]: https://crates.io/crates/actix-web-opentelemetry
[`actix-web`]: https://crates.io/crates/actix-web
[`opentelemetry-application-insights`]: https://crates.io/crates/opentelemetry-application-insights
[Azure Application Insights]: https://docs.microsoft.com/en-us/azure/azure-monitor/app/app-insights-overview
[`opentelemetry-tide`]: https://crates.io/crates/opentelemetry-tide
[`Tide`]: https://crates.io/crates/tide
[`opentelemetry-stackdriver`]: https://crates.io/crates/opentelemetry-stackdriver
[Cloud Trace]: https://cloud.google.com/trace/
### What does this crate contain?

This crate is basic foundation for integrating OpenTelemetry into libraries and
applications, encompassing several aspects of OpenTelemetry, such as context
management and propagation, baggage, logging, tracing, and metrics. It follows
the [OpenTelemetry
specification](https://github.com/open-telemetry/opentelemetry-specification).
Here's a breakdown of its components:

- **[Context
API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/context/README.md):**
Provides a way to manage and propagate context, which is essential for keeping
track of trace execution across asynchronous tasks.
- **[Propagators
API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/context/api-propagators.md):**
Defines how context can be shared across process boundaries, ensuring
continuity across microservices or distributed systems.
- **[Baggage
API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/baggage/api.md):**
Allows for the attachment of metadata (baggage) to telemetry, which can be
used for sharing application-specific information across service boundaries.
- **[Logs Bridge
API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/bridge-api.md):**
Allows to bridge existing logging mechanisms with OpenTelemetry logging. This
is **NOT** meant for end users to call, instead it is meant to enable writing
bridges/appenders for existing logging mechanisms such as
[log](https://crates.io/crates/log) or
[tracing](https://crates.io/crates/tracing).
- **[Tracing
API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md):**
Offers a set of primitives to produce distributed traces to understand the
flow of a request across system boundaries.
- **[Metrics
API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md):**
Offers a set of primitives to produce measurements of operational metrics like
latency, throughput, or error rates.

This crate serves as a facade or no-op implementation, meaning it defines the
traits for instrumentation but does not itself implement the processing or
exporting of telemetry data. This separation of concerns allows library authors
to depend on the API crate without tying themselves to a specific
implementation.

Actual implementation and the heavy lifting of telemetry data collection,
processing, and exporting are delegated to the
[opentelemetry-sdk](https://crates.io/crates/opentelemetry-sdk) crate and
various exporter crates such as
[opentelemetry-otlp](https://crates.io/crates/opentelemetry-otlp). This
architecture ensures that the final application can light up the instrumentation
by integrating an SDK implementation.

Library authors are recommended to depend on this crate *only*. This approach is
also aligned with the design philosophy of existing telemetry solutions in the
Rust ecosystem, like `tracing` or `log`, where these crates only offer a facade
and the actual functionality is enabled through additional crates.

## Getting started
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It would be good to add a reference to the registry https://opentelemetry.io/ecosystem/registry/?language=rust for Exporters, Propagator, Instrumentation, and more.
I took the liberty to add the missing elements this morning open-telemetry/opentelemetry.io#4062

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks!
I am going to skip that suggestion in this PR, and add it next. I am still thinking what is the best way to ensure success - simply linking to registry won't necessarily help much unless the user is already familiar with OTel space.
Will come back to this.


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

## Supported Rust Versions

Expand All @@ -146,7 +102,3 @@ 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.

## Contributing

See the [contributing file](../CONTRIBUTING.md).
Loading