Skip to content

Commit 650caeb

Browse files
cijothomascijothomas
committed
Move docs from readme to docs.rs
1 parent 1119549 commit 650caeb

File tree

2 files changed

+121
-159
lines changed

2 files changed

+121
-159
lines changed

‎opentelemetry/README.md

-126
Original file line numberDiff line numberDiff line change
@@ -15,130 +15,4 @@ This crate contains the [OpenTelemetry](https://opentelemetry.io/) API for Rust.
1515

1616
## Overview
1717

18-
OpenTelemetry is an Observability framework and toolkit designed to create and
19-
manage telemetry data such as traces, metrics, and logs. OpenTelemetry is
20-
vendor- and tool-agnostic, meaning that it can be used with a broad variety of
21-
Observability backends, including open source tools like [Jaeger] and
22-
[Prometheus], as well as commercial offerings.
23-
24-
OpenTelemetry is *not* an observability backend like Jaeger, Prometheus, or other
25-
commercial vendors. OpenTelemetry is focused on the generation, collection,
26-
management, and export of telemetry. A major goal of OpenTelemetry is that you
27-
can easily instrument your applications or systems, no matter their language,
28-
infrastructure, or runtime environment. Crucially, the storage and visualization
29-
of telemetry is intentionally left to other tools.
30-
31-
*[Supported Rust Versions](#supported-rust-versions)*
32-
33-
[Prometheus]: https://prometheus.io
34-
[Jaeger]: https://www.jaegertracing.io
35-
[msrv]: #supported-rust-versions
36-
37-
### What does this crate contain?
38-
39-
This crate is basic foundation for integrating OpenTelemetry into libraries and
40-
applications, encompassing several aspects of OpenTelemetry, such as context
41-
management and propagation, baggage, logging, tracing, and metrics. It follows
42-
the [OpenTelemetry
43-
specification](https://github.com/open-telemetry/opentelemetry-specification).
44-
Here's a breakdown of its components:
45-
46-
- **[Context
47-
API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/context/README.md):**
48-
Provides a way to manage and propagate context, which is essential for keeping
49-
track of trace execution across asynchronous tasks.
50-
- **[Propagators
51-
API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/context/api-propagators.md):**
52-
Defines how context can be shared across process boundaries, ensuring
53-
continuity across microservices or distributed systems.
54-
- **[Baggage
55-
API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/baggage/api.md):**
56-
Allows for the attachment of metadata (baggage) to telemetry, which can be
57-
used for sharing application-specific information across service boundaries.
58-
- **[Logs Bridge
59-
API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/api.md):**
60-
Allows to bridge existing logging mechanisms with OpenTelemetry logging. This
61-
is **NOT** meant for end users to call, instead it is meant to enable writing
62-
bridges/appenders for existing logging mechanisms such as
63-
[log](https://crates.io/crates/log) or
64-
[tracing](https://crates.io/crates/tracing).
65-
- **[Tracing
66-
API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md):**
67-
Offers a set of primitives to produce distributed traces to understand the
68-
flow of a request across system boundaries.
69-
- **[Metrics
70-
API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md):**
71-
Offers a set of primitives to produce measurements of operational metrics like
72-
latency, throughput, or error rates.
73-
74-
This crate serves as a facade or no-op implementation, meaning it defines the
75-
traits for instrumentation but does not itself implement the processing or
76-
exporting of telemetry data. This separation of concerns allows library authors
77-
to depend on the API crate without tying themselves to a specific
78-
implementation.
79-
80-
Actual implementation and the heavy lifting of telemetry data collection,
81-
processing, and exporting are delegated to the
82-
[opentelemetry-sdk](https://crates.io/crates/opentelemetry-sdk) crate and
83-
various exporter crates such as
84-
[opentelemetry-otlp](https://crates.io/crates/opentelemetry-otlp). This
85-
architecture ensures that the final application can light up the instrumentation
86-
by integrating an SDK implementation.
87-
88-
Library authors are recommended to depend on this crate *only*. This approach is
89-
also aligned with the design philosophy of existing telemetry solutions in the
90-
Rust ecosystem, like `tracing` or `log`, where these crates only offer a facade
91-
and the actual functionality is enabled through additional crates.
92-
93-
### Related crates
94-
95-
Unless you are a library author, you will almost always need to use additional
96-
crates along with this. Given this crate has no-op implementation only, an
97-
OpenTelemetry SDK is always required.
98-
[opentelemetry-sdk](https://crates.io/crates/opentelemetry-sdk) is the official
99-
SDK implemented by OpenTelemetry itself, though it is possible to use a
100-
different sdk.
101-
102-
Additionally one or more exporters are also required to export telemetry to a
103-
destination. OpenTelemetry provides the following exporters:
104-
105-
- **[opentelemetry-stdout](https://crates.io/crates/opentelemetry-stdout):**
106-
Prints telemetry to stdout, primarily used for learning/debugging purposes.
107-
- **[opentelemetry-otlp](https://crates.io/crates/opentelemetry-otlp):** Exports
108-
telemetry (logs, metrics and traces) in the [OTLP
109-
format](https://github.com/open-telemetry/opentelemetry-specification/tree/main/specification/protocol)
110-
to an endpoint accepting OTLP. This could be the [OTel
111-
Collector](https://github.com/open-telemetry/opentelemetry-collector),
112-
telemetry backends like [Jaeger](https://www.jaegertracing.io/),
113-
[Prometheus](https://prometheus.io/docs/prometheus/latest/feature_flags/#otlp-receiver)
114-
or [vendor specific endpoints](https://opentelemetry.io/ecosystem/vendors/).
115-
- **[opentelemetry-zipkin](https://crates.io/crates/opentelemetry-zipkin):**
116-
Exports telemetry (traces only) to Zipkin following [OpenTelemetry to Zipkin
117-
specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk_exporters/zipkin.md)
118-
- **[opentelemetry-prometheus](https://crates.io/crates/opentelemetry-prometheus):**
119-
Exports telemetry (metrics only) to Prometheus following [OpenTelemetry to
120-
Prometheus
121-
specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk_exporters/prometheus.md)
122-
123-
OpenTelemetry Rust also has a [contrib
124-
repo](https://github.com/open-telemetry/opentelemetry-rust-contrib), where
125-
additional exporters could be found. Check [OpenTelemetry
126-
Registry](https://opentelemetry.io/ecosystem/registry/?language=rust) for
127-
additional exporters and other related components as well.
128-
129-
## Getting started
130-
13118
See [docs](https://docs.rs/opentelemetry).
132-
133-
## Supported Rust Versions
134-
135-
OpenTelemetry is built against the latest stable release. The minimum supported
136-
version is 1.70. The current OpenTelemetry version is not guaranteed to build
137-
on Rust versions earlier than the minimum supported version.
138-
139-
The current stable Rust compiler and the three most recent minor versions
140-
before it will always be supported. For example, if the current stable compiler
141-
version is 1.49, the minimum supported version will not be increased past 1.46,
142-
three minor versions prior. Increasing the minimum supported compiler version
143-
is not considered a semver breaking change as long as doing so complies with
144-
this policy.

‎opentelemetry/src/lib.rs

+121-33
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,116 @@
55
//! [`API`]: https://opentelemetry.io/docs/specs/otel/overview/#api
66
//! [OpenTelemetry]: https://opentelemetry.io/docs/what-is-opentelemetry/
77
//!
8+
//! [Jaeger]: https://www.jaegertracing.io/
9+
//! [Prometheus]: https://www.prometheus.io/
10+
//!
11+
//! # Overview
12+
13+
//! OpenTelemetry is an Observability framework and toolkit designed to create and
14+
//! manage telemetry data such as traces, metrics, and logs. OpenTelemetry is
15+
//! vendor- and tool-agnostic, meaning that it can be used with a broad variety of
16+
//! Observability backends, including open source tools like [Jaeger] and
17+
//! [Prometheus], as well as commercial offerings.
18+
19+
//! OpenTelemetry is *not* an observability backend like Jaeger, Prometheus, or other
20+
//! commercial vendors. OpenTelemetry is focused on the generation, collection,
21+
//! management, and export of telemetry. A major goal of OpenTelemetry is that you
22+
//! can easily instrument your applications or systems, no matter their language,
23+
//! infrastructure, or runtime environment. Crucially, the storage and visualization
24+
//! of telemetry is intentionally left to other tools.
25+
//!
26+
//! ## What does this crate contain?
27+
28+
//! This crate is basic foundation for integrating OpenTelemetry into libraries and
29+
//! applications, encompassing several aspects of OpenTelemetry, such as context
30+
//! management and propagation, baggage, logging, tracing, and metrics. It follows
31+
//! the [OpenTelemetry
32+
//! specification](https://github.com/open-telemetry/opentelemetry-specification).
33+
//! Here's a breakdown of its components:
34+
//!
35+
//! - **[Context
36+
//! API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/context/README.md):**
37+
//! Provides a way to manage and propagate context, which is essential for keeping
38+
//! track of trace execution across asynchronous tasks.
39+
//! - **[Propagators
40+
//! API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/context/api-propagators.md):**
41+
//! Defines how context can be shared across process boundaries, ensuring
42+
//! continuity across microservices or distributed systems.
43+
//! - **[Baggage
44+
//! API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/baggage/api.md):**
45+
//! Allows for the attachment of metadata (baggage) to telemetry, which can be
46+
//! used for sharing application-specific information across service boundaries.
47+
//! - **[Logs Bridge
48+
//! API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/api.md):**
49+
//! Allows to bridge existing logging mechanisms with OpenTelemetry logging. This
50+
//! is **NOT** meant for end users to call, instead it is meant to enable writing
51+
//! bridges/appenders for existing logging mechanisms such as
52+
//! [log](https://crates.io/crates/log) or
53+
//! [tracing](https://crates.io/crates/tracing).
54+
//! - **[Tracing
55+
//! API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md):**
56+
//! Offers a set of primitives to produce distributed traces to understand the
57+
//! flow of a request across system boundaries.
58+
//! - **[Metrics
59+
//! API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md):**
60+
//! Offers a set of primitives to produce measurements of operational metrics like
61+
//! latency, throughput, or error rates.
62+
//!
63+
//! This crate serves as a facade or no-op implementation, meaning it defines the
64+
//! traits for instrumentation but does not itself implement the processing or
65+
//! exporting of telemetry data. This separation of concerns allows library authors
66+
//! to depend on the API crate without tying themselves to a specific
67+
//! implementation.
68+
//!
69+
//! Actual implementation and the heavy lifting of telemetry data collection,
70+
//! processing, and exporting are delegated to the
71+
//! [opentelemetry-sdk](https://crates.io/crates/opentelemetry-sdk) crate and
72+
//! various exporter crates such as
73+
//! [opentelemetry-otlp](https://crates.io/crates/opentelemetry-otlp). This
74+
//! architecture ensures that the final application can light up the instrumentation
75+
//! by integrating an SDK implementation.
76+
//!
77+
//! Library authors are recommended to depend on this crate *only*. This approach is
78+
//! also aligned with the design philosophy of existing telemetry solutions in the
79+
//! Rust ecosystem, like `tracing` or `log`, where these crates only offer a facade
80+
//! and the actual functionality is enabled through additional crates.
81+
//!
82+
//! ## Related crates
83+
84+
//! Unless you are a library author, you will almost always need to use additional
85+
//! crates along with this. Given this crate has no-op implementation only, an
86+
//! OpenTelemetry SDK is always required.
87+
//! [opentelemetry-sdk](https://crates.io/crates/opentelemetry-sdk) is the official
88+
//! SDK implemented by OpenTelemetry itself, though it is possible to use a
89+
//! different sdk.
90+
//!
91+
//! Additionally one or more exporters are also required to export telemetry to a
92+
//! destination. OpenTelemetry provides the following exporters:
93+
//!
94+
//! - **[opentelemetry-stdout](https://crates.io/crates/opentelemetry-stdout):**
95+
//! Prints telemetry to stdout, primarily used for learning/debugging purposes.
96+
//! - **[opentelemetry-otlp](https://crates.io/crates/opentelemetry-otlp):** Exports
97+
//! telemetry (logs, metrics and traces) in the [OTLP
98+
//! format](https://github.com/open-telemetry/opentelemetry-specification/tree/main/specification/protocol)
99+
//! to an endpoint accepting OTLP. This could be the [OTel
100+
//! Collector](https://github.com/open-telemetry/opentelemetry-collector),
101+
//! telemetry backends like [Jaeger](https://www.jaegertracing.io/),
102+
//! [Prometheus](https://prometheus.io/docs/prometheus/latest/feature_flags/#otlp-receiver)
103+
//! or [vendor specific endpoints](https://opentelemetry.io/ecosystem/vendors/).
104+
//! - **[opentelemetry-zipkin](https://crates.io/crates/opentelemetry-zipkin):**
105+
//! Exports telemetry (traces only) to Zipkin following [OpenTelemetry to Zipkin
106+
//! specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk_exporters/zipkin.md)
107+
//! - **[opentelemetry-prometheus](https://crates.io/crates/opentelemetry-prometheus):**
108+
//! Exports telemetry (metrics only) to Prometheus following [OpenTelemetry to
109+
//! Prometheus
110+
//! specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk_exporters/prometheus.md)
111+
//!
112+
//! OpenTelemetry Rust also has a [contrib
113+
//! repo](https://github.com/open-telemetry/opentelemetry-rust-contrib), where
114+
//! additional exporters could be found. Check [OpenTelemetry
115+
//! Registry](https://opentelemetry.io/ecosystem/registry/?language=rust) for
116+
//! additional exporters and other related components as well.
117+
//!
8118
//! # Getting Started
9119
//!
10120
//! ```no_run
@@ -24,15 +134,15 @@
24134
//!
25135
//! [examples]: https://github.com/open-telemetry/opentelemetry-rust/tree/main/examples
26136
//!
27-
//! # Traces
137+
//! ## Traces
28138
//!
29139
//! The [`trace`] module includes types for tracking the progression of a single
30140
//! request while it is handled by services that make up an application. A trace
31141
//! is a tree of [`Span`]s which are objects that represent the work being done
32142
//! by individual services or components involved in a request as it flows
33143
//! through a system.
34144
//!
35-
//! ### Creating and exporting spans
145+
//! ### Creating spans
36146
//!
37147
//! ```
38148
//! # #[cfg(feature = "trace")]
@@ -60,7 +170,7 @@
60170
//!
61171
//! [`Span`]: crate::trace::Span
62172
//!
63-
//! # Metrics
173+
//! ## Metrics
64174
//!
65175
//!
66176
//! The [`metrics`] module includes types for recording measurements about a
@@ -88,7 +198,7 @@
88198
//! managing instruments.
89199
//!
90200
//!
91-
//! # Logs
201+
//! ## Logs
92202
//!
93203
//! The [`logs`] module contains the Logs Bridge API. It is not intended to be
94204
//! called by application developers directly. It is provided for logging
@@ -102,48 +212,23 @@
102212
//! [`opentelemetry-appender-tracing`](https://crates.io/crates/opentelemetry-appender-tracing)
103213
//! crates.
104214
//!
105-
//! ## Crate Feature Flags
215+
//! ## Feature Flags
106216
//!
107217
//! The following core crate feature flags are available:
108218
//!
109219
//! * `trace`: Includes the trace API.
110220
//! * `metrics`: Includes the metrics API.
111221
//! * `logs`: Includes the logs bridge API.
222+
//! * `internal-logs`: Enables internal logging via `tracing`.
112223
//!
113-
//! The default feature flags are ["trace", "metrics", "logs"]
224+
//! The default feature flags are ["trace", "metrics", "logs", "internal-logs"].
114225
//!
115226
//! The following feature flags provides additional configuration for `logs`:
116227
//! * `spec_unstable_logs_enabled`: Allow users to control the log level
117228
//!
118229
//! The following feature flags enable APIs defined in OpenTelemetry specification that is in experimental phase:
119230
//! * `otel_unstable`: Includes unstable APIs.
120231
//!
121-
//! ## Related Crates
122-
//!
123-
//! In addition to `opentelemetry`, the [`open-telemetry/opentelemetry-rust`]
124-
//! repository contains several additional crates designed to be used with the
125-
//! `opentelemetry` ecosystem. This includes exporters, samplers, as well as
126-
//! utility and adapter crates to assist in propagating context and
127-
//! instrumenting applications.
128-
//!
129-
//! In particular, the following crates are likely to be of interest:
130-
//!
131-
//! - [`opentelemetry_sdk`] provides the OpenTelemetry SDK used to configure providers.
132-
//! - [`opentelemetry-http`] provides an interface for injecting and extracting
133-
//! trace information from [`http`] headers.
134-
//! - [`opentelemetry-otlp`] exporter for sending telemetry in the
135-
//! OTLP format.
136-
//! - [`opentelemetry-prometheus`] provides a pipeline and exporter for sending
137-
//! metrics information to [`Prometheus`].
138-
//! - [`opentelemetry-zipkin`] provides a pipeline and exporter for sending
139-
//! trace information to [`Zipkin`].
140-
//!
141-
//! In addition, there are several other useful crates in the [OTel Rust
142-
//! Contrib
143-
//! repo](https://github.com/open-telemetry/opentelemetry-rust-contrib). A lot
144-
//! of crates maintained outside OpenTelemetry owned repos can be found in the
145-
//! [OpenTelemetry
146-
//! Registry](https://opentelemetry.io/ecosystem/registry/?language=rust).
147232
//!
148233
//! [`http`]: https://crates.io/crates/http
149234
//! [`open-telemetry/opentelemetry-rust`]: https://github.com/open-telemetry/opentelemetry-rust
@@ -161,6 +246,9 @@
161246
//! supported version is 1.70. The current OpenTelemetry version is not
162247
//! guaranteed to build on Rust versions earlier than the minimum supported
163248
//! version.
249+
//! This crate is built against the latest stable release. The minimum supported
250+
//! version is 1.70. The current version is not guaranteed to build on Rust
251+
//! versions earlier than the minimum supported version.
164252
//!
165253
//! The current stable Rust compiler and the three most recent minor versions
166254
//! before it will always be supported. For example, if the current stable
@@ -239,4 +327,4 @@ pub mod time {
239327
pub fn now() -> SystemTime {
240328
SystemTime::UNIX_EPOCH + std::time::Duration::from_millis(js_sys::Date::now() as u64)
241329
}
242-
}
330+
}

0 commit comments

Comments
 (0)