Skip to content

Commit

Permalink
Few doc updates for opentelemetry (#2353)
Browse files Browse the repository at this point in the history
  • Loading branch information
@cijothomas
cijothomas authored Nov 27, 2024
1 parent ab332b0 commit 195dea8
Show file tree
Hide file tree
Showing 2 changed files with 98 additions and 47 deletions.
5 changes: 1 addition & 4 deletions examples/metrics-basic/Cargo.toml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,12 +6,9 @@ license = "Apache-2.0"
publish = false

[dependencies]
opentelemetry = { path = "../../opentelemetry", features = ["metrics", "otel_unstable"] }
opentelemetry = { path = "../../opentelemetry", features = ["metrics"] }
opentelemetry_sdk = { path = "../../opentelemetry-sdk", features = ["metrics", "rt-tokio"] }
opentelemetry-stdout = { path = "../../opentelemetry-stdout", features = ["metrics"]}
tokio = { workspace = true, features = ["full"] }
serde_json = { workspace = true }

[features]
default = ["otel_unstable"]
otel_unstable = ["opentelemetry/otel_unstable"]
140 changes: 97 additions & 43 deletions opentelemetry/src/lib.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,35 +5,14 @@
//! [`API`]: https://opentelemetry.io/docs/specs/otel/overview/#api
//! [OpenTelemetry]: https://opentelemetry.io/docs/what-is-opentelemetry/
//!
//! # Getting Started
//!
//! ```no_run
//! # #[cfg(feature = "trace")]
//! # {
//! use opentelemetry::{global, trace::{TraceContextExt, Tracer}, Context };
//!
//! fn do_something() {
//! let tracer = global::tracer("my_component");
//! let _guard = Context::current_with_span(tracer.start("my_span")).attach();
//! // do work tracked by the now current span
//! }
//! # }
//! ```
//!
//! See the [examples] directory for different integration patterns.
//!
//! [examples]: https://github.com/open-telemetry/opentelemetry-rust/tree/main/examples
//!
//! # Traces
//! # Getting Started with Traces
//!
//! The [`trace`] module includes types for tracking the progression of a single
//! request while it is handled by services that make up an application. A trace
//! is a tree of [`Span`]s which are objects that represent the work being done
//! by individual services or components involved in a request as it flows
//! through a system.
//!
//! ### Creating and exporting spans
//!
//! ```
//! # #[cfg(feature = "trace")]
//! # {
Expand All @@ -55,40 +34,111 @@
//! # }
//! ```
//!
//! See the [examples](https://github.com/open-telemetry/opentelemetry-rust/tree/main/examples) directory for different integration patterns.
//!
//! See the [`trace`] module docs for more information on creating and managing
//! spans.
//!
//! [`Span`]: crate::trace::Span
//!
//! # Metrics
//!
//!
//! The [`metrics`] module includes types for recording measurements about a
//! service at runtime.
//!
//! ### Creating instruments and recording measurements
//!
//! # Getting Started with Metrics
//!
//! The [`metrics`] module provides types for recording measurements about a
//! service at runtime. Below are the key steps to report measurements using
//! OpenTelemetry Metrics:
//!
//! 1. **Obtain a Meter:** Get a `Meter` from a `MeterProvider`.
//! 2. **Create Instruments:** Use the `Meter` to create one or more instruments
//! (e.g., counters, histograms).
//! 3. **Record Measurements:** Use the instruments to record measurement values
//! along with optional attributes.
//!
//! ## How Metrics work in OpenTelemetry
//! In OpenTelemetry, raw measurements recorded using instruments are
//! **aggregated in memory** to form metrics. These aggregated metrics are
//! periodically exported by the [`opentelemetry_sdk`] at fixed intervals (e.g.,
//! every 60 seconds) via exporters such as [`opentelemetry-stdout`] or
//! [`opentelemetry-otlp`]. This reduces reporting overhead while ensuring
//! up-to-date data. The aggregation strategy and export interval can be
//! customized in the [`opentelemetry_sdk`] based on your use case.
//!
//! ## Choosing the Right Instrument
//! Selecting the correct instrument is critical for accurately representing
//! your metrics data:
//!
//! - Use **Counters** for values that only increase, such as the number of
//! requests served or errors encountered.
//! - Use **UpDownCounters** for values that can increase or decrease, such as
//! the number of active connections, number of items in a queue etc.
//! - **Gauges:** Use for values that can go up or down and represent the
//! current state, such as CPU usage, temperature etc.
//! - Use **Histograms** for measuring the distribution of a value, such as
//! response times or payload sizes.
//!
//! ### Observable Instruments
//!
//! Counters, UpDownCounters, and Gauges have Observable variants that allow
//! values to be reported through a callback function. Observable instruments
//! are ideal when the metric value is managed elsewhere and needs to be
//! observed by OpenTelemetry instrumentation. The callbacks are automatically
//! invoked by the OpenTelemetry SDK before every export (e.g., every 60
//! seconds).
//!
//! For example:
//! - An **ObservableCounter** can monitor the number of page faults in a
//! process as reported by the operating system.
//! - An **ObservableUpDownCounter** can monitor the size of an in-memory queue
//! by reporting the size using queue's len() method within the callback
//! function.
//! - An **ObservableGauge** can monitor the CPU temperature by using
//! temperature sensor APIs within the callback function.
//!
//! For detailed guidance, refer to [OpenTelemetry Metrics API - Instrumentation
//! Guidance](https://opentelemetry.io/docs/specs/otel/metrics/supplementary-guidelines/#instrument-selection).
//!
//! ## Best Practices
//! - **Re-use Instruments:** Instruments are designed for
//! reuse. Avoid creating new instruments repeatedly.
//! - **Clone for Sharing:** If the same instrument needs to be used across
//! multiple parts of your code, you can safely clone it to share.
//!
//! ## Example Usage
//! ```
//! # #[cfg(feature = "metrics")]
//! # {
//! use opentelemetry::{global, KeyValue};
//!
//! // get a meter from a provider
//! // Get a meter from a provider.
//! let meter = global::meter("my_service");
//!
//! // create an instrument
//! let counter = meter.u64_counter("my_counter").build();
//! // Create an instrument (in this case, a Counter).
//! let counter = meter.u64_counter("request.count").build();
//!
//! // record a measurement
//! // Record a measurement by passing the value and a set of attributes.
//! counter.add(1, &[KeyValue::new("http.client_ip", "83.164.160.102")]);
//! # }
//!
//! // Create an ObservableCounter and register a callback that reports the measurement.
//! let _observable_counter = meter
//! .u64_observable_counter("bytes_received")
//! .with_callback(|observer| {
//! observer.observe(
//! 100,
//! &[
//! KeyValue::new("protocol", "udp"),
//! ],
//! )
//! })
//! .build();
//! ```
//!
//! See the
//! [examples](https://github.com/open-telemetry/opentelemetry-rust/tree/main/examples/metrics-basic)
//! directory that show a runnable example with all type of instruments.
//!
//!
//! See the [`metrics`] module docs for more information on creating and
//! managing instruments.
//!
//!
//! # Logs
//! # Getting Started with Logs
//!
//! The [`logs`] module contains the Logs Bridge API. It is not intended to be
//! called by application developers directly. It is provided for logging
Expand All @@ -102,23 +152,24 @@
//! [`opentelemetry-appender-tracing`](https://crates.io/crates/opentelemetry-appender-tracing)
//! crates.
//!
//! ## Crate Feature Flags
//! # Crate Feature Flags
//!
//! The following core crate feature flags are available:
//!
//! * `trace`: Includes the trace API.
//! * `metrics`: Includes the metrics API.
//! * `logs`: Includes the logs bridge API.
//! * `internal-logs`: Includes internal logging for the OpenTelemetry library via `tracing`.
//!
//! The default feature flags are ["trace", "metrics", "logs"]
//! The default feature flags are ["trace", "metrics", "logs", "internal-logs"].
//!
//! The following feature flags provides additional configuration for `logs`:
//! * `spec_unstable_logs_enabled`: Allow users to control the log level
//!
//! The following feature flags enable APIs defined in OpenTelemetry specification that is in experimental phase:
//! * `otel_unstable`: Includes unstable APIs.
//! * `otel_unstable`: Includes unstable APIs. There are no features behind this flag at the moment.
//!
//! ## Related Crates
//! # Related Crates
//!
//! In addition to `opentelemetry`, the [`open-telemetry/opentelemetry-rust`]
//! repository contains several additional crates designed to be used with the
Expand All @@ -133,6 +184,8 @@
//! trace information from [`http`] headers.
//! - [`opentelemetry-otlp`] exporter for sending telemetry in the
//! OTLP format.
//! - [`opentelemetry-stdout`] provides ability to output telemetry to stdout,
//! primarily used for learning/debugging purposes.
//! - [`opentelemetry-prometheus`] provides a pipeline and exporter for sending
//! metrics information to [`Prometheus`].
//! - [`opentelemetry-zipkin`] provides a pipeline and exporter for sending
Expand All @@ -148,14 +201,15 @@
//! [`http`]: https://crates.io/crates/http
//! [`open-telemetry/opentelemetry-rust`]: https://github.com/open-telemetry/opentelemetry-rust
//! [`opentelemetry_sdk`]: https://crates.io/crates/opentelemetry_sdk
//! [`opentelemetry-stdout`]: https://crates.io/crates/opentelemetry_stdout
//! [`opentelemetry-http`]: https://crates.io/crates/opentelemetry-http
//! [`opentelemetry-otlp`]: https://crates.io/crates/opentelemetry-otlp
//! [`opentelemetry-prometheus`]: https://crates.io/crates/opentelemetry-prometheus
//! [`opentelemetry-zipkin`]: https://crates.io/crates/opentelemetry-zipkin
//! [`Prometheus`]: https://prometheus.io
//! [`Zipkin`]: https://zipkin.io
//!
//! ## Supported Rust Versions
//! # Supported Rust Versions
//!
//! OpenTelemetry is built against the latest stable release. The minimum
//! supported version is 1.70. The current OpenTelemetry version is not
Expand Down

0 comments on commit 195dea8

Please sign in to comment.