Skip to content

Commit 54a2d71

Browse files
jtescherTommyCpp
jtescher
and
TommyCpp
authored
Add feature flag documentation to crates (open-telemetry#335)
Co-authored-by: Zhongyang Wu <zhongyang.wu@outlook.com>
1 parent 9eee7e1 commit 54a2d71

File tree

7 files changed

+172
-2
lines changed

7 files changed

+172
-2
lines changed

‎CODEOWNERS

+1-2
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
1-
21
# Code owners file.
32
# This file controls who is tagged for review for any given pull request.
43

54
# For anything not explicitly taken by someone else:
6-
* @open-telemetry/rust-approvers
5+
* @open-telemetry/rust-approvers

‎opentelemetry-contrib/src/lib.rs

+10
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,16 @@
44
//! some users.
55
//!
66
//! Typically, those include vendor specific propagators.
7+
//!
8+
//! ## Crate Feature Flags
9+
//!
10+
//! The following crate feature flags are available:
11+
//!
12+
//! * `datadog`: Adds a Datadog trace exporter.
13+
//! * `reqwest-blocking-client`: Export spans using the reqwest blocking http
14+
//! client.
15+
//! * `reqwest-client`: Export spans using the reqwest non-blocking http client.
16+
//! * `surf-client`: Export spans using the surf non-blocking http client.
717
#![warn(
818
future_incompatible,
919
missing_debug_implementations,

‎opentelemetry-jaeger/src/lib.rs

+7
Original file line numberDiff line numberDiff line change
@@ -144,6 +144,13 @@
144144
//! }
145145
//! ```
146146
//!
147+
//! ## Crate Feature Flags
148+
//!
149+
//! The following crate feature flags are available:
150+
//!
151+
//! * `collector_client`: Export span data directly to a Jaeger collector using
152+
//! isahc http client.
153+
//!
147154
//! ## Supported Rust Versions
148155
//!
149156
//! OpenTelemetry is built against the latest stable release. The minimum

‎opentelemetry-zipkin/src/lib.rs

+9
Original file line numberDiff line numberDiff line change
@@ -125,6 +125,15 @@
125125
//! }
126126
//! ```
127127
//!
128+
//! ## Crate Feature Flags
129+
//!
130+
//! The following crate feature flags are available:
131+
//!
132+
//! * `reqwest-blocking-client`: Export spans using the reqwest blocking http
133+
//! client (enabled by default).
134+
//! * `reqwest-client`: Export spans using the reqwest non-blocking http client.
135+
//! * `surf-client`: Export spans using the surf non-blocking http client.
136+
//!
128137
//! ## Supported Rust Versions
129138
//!
130139
//! OpenTelemetry is built against the latest stable release. The minimum

‎opentelemetry/CODEOWNERS

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Code owners file.
2+
# This file controls who is tagged for review for any given pull request.
3+
4+
# For anything not explicitly taken by someone else:
5+
* @open-telemetry/rust-approvers

‎opentelemetry/README.md

+128
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
![OpenTelemetry — An observability framework for cloud-native software.][splash]
2+
3+
[splash]: https://raw.githubusercontent.com/open-telemetry/opentelemetry-rust/master/assets/logo-text.png
4+
5+
# OpenTelemetry Rust
6+
7+
The Rust [OpenTelemetry](https://opentelemetry.io/) implementation.
8+
9+
[![Crates.io: opentelemetry](https://img.shields.io/crates/v/opentelemetry.svg)](https://crates.io/crates/opentelemetry)
10+
[![Documentation](https://docs.rs/opentelemetry/badge.svg)](https://docs.rs/opentelemetry)
11+
[![LICENSE](https://img.shields.io/crates/l/opentelemetry)](./LICENSE)
12+
[![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%3Amaster)
13+
[![Gitter chat](https://img.shields.io/badge/gitter-join%20chat%20%E2%86%92-brightgreen.svg)](https://gitter.im/open-telemetry/opentelemetry-rust)
14+
15+
[Website](https://opentelemetry.io/) |
16+
[Chat](https://gitter.im/open-telemetry/opentelemetry-rust) |
17+
[Documentation](https://docs.rs/opentelemetry)
18+
19+
## Overview
20+
21+
OpenTelemetry is a collection of tools, APIs, and SDKs used to instrument,
22+
generate, collect, and export telemetry data (metrics, logs, and traces) for
23+
analysis in order to understand your software's performance and behavior. You
24+
can export and analyze them using [Prometheus], [Jaeger], and other
25+
observability tools.
26+
27+
*Compiler support: [requires `rustc` 1.42+][msrv]*
28+
29+
[Prometheus]: https://prometheus.io
30+
[Jaeger]: https://www.jaegertracing.io
31+
[msrv]: #supported-rust-versions
32+
33+
## Getting Started
34+
35+
```rust
36+
use opentelemetry::{exporter::trace::stdout, trace::Tracer};
37+
38+
fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync + 'static>> {
39+
// Create a new instrumentation pipeline
40+
let (tracer, _uninstall) = stdout::new_pipeline().install();
41+
42+
tracer.in_span("doing_work", |cx| {
43+
// Traced app logic here...
44+
});
45+
46+
Ok(())
47+
}
48+
```
49+
50+
See the [examples](./examples) directory for different integration patterns.
51+
52+
## Ecosystem
53+
54+
### Related Crates
55+
56+
In addition to `opentelemetry`, the [`open-telemetry/opentelemetry-rust`]
57+
repository contains several additional crates designed to be used with the
58+
`opentelemetry` ecosystem. This includes a collection of trace `SpanExporter`
59+
and metrics pull and push controller implementations, as well as utility and
60+
adapter crates to assist in propagating state and instrumenting applications.
61+
62+
In particular, the following crates are likely to be of interest:
63+
64+
- [`opentelemetry-jaeger`] provides a pipeline and exporter for sending trace
65+
information to [`Jaeger`].
66+
- [`opentelemetry-otlp`] exporter for sending trace and metric data in the OTLP
67+
format to the OpenTelemetry collector.
68+
- [`opentelemetry-prometheus`] provides a pipeline and exporter for sending
69+
metrics information to [`Prometheus`].
70+
- [`opentelemetry-zipkin`] provides a pipeline and exporter for sending trace
71+
information to [`Zipkin`].
72+
- [`opentelemetry-contrib`] provides additional exporters to vendors like
73+
[`Datadog`].
74+
- [`opentelemetry-semantic-conventions`] provides standard names and semantic
75+
otel conventions.
76+
77+
Additionally, there are also several third-party crates which are not
78+
maintained by the `opentelemetry` project. These include:
79+
80+
- [`tracing-opentelemetry`] provides integration for applications instrumented
81+
using the [`tracing`] API and ecosystem.
82+
- [`actix-web-opentelemetry`] provides integration for the [`actix-web`] web
83+
server and ecosystem.
84+
- [`opentelemetry-application-insights`] provides an unofficial [Azure
85+
Application Insights] exporter.
86+
- [`opentelemetry-tide`] provides integration for the [`Tide`] web server and
87+
ecosystem.
88+
89+
If you're the maintainer of an `opentelemetry` ecosystem crate not listed
90+
above, please let us know! We'd love to add your project to the list!
91+
92+
[`open-telemetry/opentelemetry-rust`]: https://github.com/open-telemetry/opentelemetry-rust
93+
[`opentelemetry-jaeger`]: https://crates.io/crates/opentelemetry-jaeger
94+
[`Jaeger`]: https://www.jaegertracing.io
95+
[`opentelemetry-otlp`]: https://crates.io/crates/opentelemetry-otlp
96+
[`opentelemetry-prometheus`]: https://crates.io/crates/opentelemetry-prometheus
97+
[`Prometheus`]: https://prometheus.io
98+
[`opentelemetry-zipkin`]: https://crates.io/crates/opentelemetry-zipkin
99+
[`Zipkin`]: https://zipkin.io
100+
[`opentelemetry-contrib`]: https://crates.io/crates/opentelemetry-contrib
101+
[`Datadog`]: https://www.datadoghq.com
102+
[`opentelemetry-semantic-conventions`]: https://crates.io/crates/opentelemetry-semantic-conventions
103+
104+
[`tracing-opentelemetry`]: https://crates.io/crates/tracing-opentelemetry
105+
[`tracing`]: https://crates.io/crates/tracing
106+
[`actix-web-opentelemetry`]: https://crates.io/crates/actix-web-opentelemetry
107+
[`actix-web`]: https://crates.io/crates/actix-web
108+
[`opentelemetry-application-insights`]: https://crates.io/crates/opentelemetry-application-insights
109+
[Azure Application Insights]: https://docs.microsoft.com/en-us/azure/azure-monitor/app/app-insights-overview
110+
[`opentelemetry-tide`]: https://crates.io/crates/opentelemetry-tide
111+
[`Tide`]: https://crates.io/crates/tide
112+
113+
## Supported Rust Versions
114+
115+
OpenTelemetry is built against the latest stable release. The minimum supported
116+
version is 1.42. The current OpenTelemetry version is not guaranteed to build
117+
on Rust versions earlier than the minimum supported version.
118+
119+
The current stable Rust compiler and the three most recent minor versions
120+
before it will always be supported. For example, if the current stable compiler
121+
version is 1.45, the minimum supported version will not be increased past 1.42,
122+
three minor versions prior. Increasing the minimum supported compiler version
123+
is not considered a semver breaking change as long as doing so complies with
124+
this policy.
125+
126+
## Contributing
127+
128+
See the [contributing file](CONTRIBUTING.md).

‎opentelemetry/src/lib.rs

+12
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,18 @@
3030
//! See the [examples](https://github.com/open-telemetry/opentelemetry-rust/tree/master/examples)
3131
//! directory for different integration patterns.
3232
//!
33+
//! ## Crate Feature Flags
34+
//!
35+
//! The following crate feature flags are available:
36+
//!
37+
//! * `trace`: Includes the trace API and SDK (enabled by default).
38+
//! * `metrics`: Includes the unstable metrics API and SDK.
39+
//! * `base64_format`: Adds experimental support for encoding span context
40+
//! information in base64.
41+
//! * `serialize`: Adds serde serializers for common types.
42+
//! * `binary_propagator`: Adds experimental support for the trace binary
43+
//! propagator.
44+
//!
3345
//! ## Related Crates
3446
//!
3547
//! In addition to `opentelemetry`, the [`open-telemetry/opentelemetry-rust`]

0 commit comments

Comments
 (0)