docs: Improve metrics-basic and tracing-grpc getting started READMEs (#3477)

Author: cijothomas

examples/metrics-basic/README.md

@@ -1,13 +1,65 @@
-# Metric Instrument Usage Example
+# Getting started with OpenTelemetry Rust Metrics
 
-This example shows how to use the various metric instruments to report metrics. The
-example setups a MeterProvider with stdout exporter, so metrics can be seen on
-the stdout.
+This example demonstrates the basics of recording metrics with OpenTelemetry in
+Rust. If you're new to OpenTelemetry metrics, this is a great place to start!
+
+## Understanding OpenTelemetry Metrics
+
+OpenTelemetry provides an end-user facing Metrics API. Application and library
+authors use this API directly (via the
+[`opentelemetry`](https://docs.rs/opentelemetry/latest/opentelemetry/) crate)
+to create instruments and record measurements. The
+[`opentelemetry-sdk`](https://docs.rs/opentelemetry_sdk/latest/opentelemetry_sdk/)
+crate provides the implementation that aggregates those measurements and
+forwards them to one or more exporters.
+
+The Metrics API offers several instrument types, each suited to a particular
+kind of measurement:
+
+- **Counter** - monotonically increasing values (e.g. number of requests
+  served).
+- **UpDownCounter** - values that can increase or decrease (e.g. number of
+  active connections).
+- **Histogram** - distribution of values (e.g. request latency).
+- **Gauge** - the current value of something at the time of measurement (e.g.
+  current CPU temperature).
+- **Observable Counter / UpDownCounter / Gauge** - asynchronous variants where a
+  user-supplied callback is invoked at collection time to report the current
+  value.
+
+## What This Example Does
+
+This example:
+
+1. Sets up an OpenTelemetry `SdkMeterProvider` with resource attributes (like
+   service name)
+2. Configures a **stdout exporter** to output metrics to the console (for
+   simplicity)
+3. Creates one of every instrument type (`Counter`, `UpDownCounter`,
+   `Histogram`, `Gauge`, and their observable counterparts) and records sample
+   measurements
+4. Properly shuts down the metrics pipeline so all buffered measurements are
+   flushed
+
+**Note on Exporters**: This example uses the stdout exporter for demonstration
+purposes. In production scenarios, you would typically use other exporters such
+as:
+
+- **OTLP exporter** (`opentelemetry-otlp`) to send metrics to an OpenTelemetry
+  Collector or compatible backend. See the [OTLP
+  example](../../opentelemetry-otlp/examples/basic-otlp/README.md) for details.
+- **Prometheus exporter** (`opentelemetry-prometheus`) to expose metrics in a
+  Prometheus-scrapeable format.
+- Other vendor-specific exporters for your observability platform.
 
 ## Usage
 
-Run the following, and the Metrics will be written out to stdout.
+Run the example to see metrics being recorded through the OpenTelemetry Metrics
+API and output via the stdout exporter:
 
 ```shell
-$ cargo run
+cargo run
 ```
+
+You'll see the metric output in your console, demonstrating how OpenTelemetry
+collects, aggregates, and exports measurements from each instrument type.

examples/tracing-grpc/README.md

@@ -1,11 +1,66 @@
-# GRPC example
+# Getting started with OpenTelemetry Rust Tracing - gRPC Example
 
-Example showing [Tonic] client and server interaction with OpenTelemetry context
-propagation. Traces are exported to stdout.
+This example demonstrates the basics of distributed tracing with OpenTelemetry
+in Rust, using a [Tonic](https://github.com/hyperium/tonic) gRPC client and
+server. While not the absolute simplest tracing example, it shows a realistic,
+end-to-end scenario: a single trace that spans two processes.
 
-[Tonic]: https://github.com/hyperium/tonic
+## Understanding OpenTelemetry Tracing
 
-## Running the example
+OpenTelemetry provides an end-user facing Tracing API. Application and library
+authors use this API directly (via the
+[`opentelemetry`](https://docs.rs/opentelemetry/latest/opentelemetry/) crate)
+to create **spans** that represent units of work. The
+[`opentelemetry-sdk`](https://docs.rs/opentelemetry_sdk/latest/opentelemetry_sdk/)
+crate provides the implementation that processes those spans and forwards them
+to one or more exporters.
+
+A few key concepts:
+
+- **Span** - a single, named, timed operation (e.g. "handle HTTP request",
+  "query database"). Spans can carry attributes and events.
+- **Trace** - a tree of related spans, sharing a single `TraceId`, that
+  together represent the lifecycle of one logical request or operation.
+- **Context Propagation** - the mechanism that carries trace identifiers
+  across process boundaries (e.g. via HTTP headers or gRPC metadata) so that
+  spans created in different processes are stitched together into one trace.
+
+## What This Example Does
+
+This example consists of two binaries - a gRPC client and a gRPC server -
+sharing a simple "Greeter" service definition:
+
+1. Both client and server set up an OpenTelemetry `SdkTracerProvider` with a
+   **stdout exporter** (for simplicity) and register the W3C
+   `TraceContextPropagator` as the global propagator. This propagator defines
+   *how* trace context is serialized into and deserialized from carrier
+   formats (HTTP headers, gRPC metadata, etc.) using the
+   [W3C Trace Context](https://www.w3.org/TR/trace-context/) standard - it is
+   the piece that makes steps 2 and 3 below possible.
+2. The **client** creates a root span (`Greeter/client`) for the outgoing
+   call, then uses the globally-registered propagator to **inject** the
+   current trace context into the gRPC request metadata before sending it.
+3. The **server** uses the same globally-registered propagator to **extract**
+   the trace context from the incoming gRPC metadata and creates its own
+   span (`Greeter/server`) as a child of the client's span.
+4. Both spans are exported to stdout. Because they share the same `TraceId`
+   and the server span references the client span as its parent, the two
+   pieces are correlated into a single distributed trace.
+
+Without the propagator setup in step 1, the inject/extract calls would have
+nothing to do and the server would create an unrelated root span instead of a
+child of the client - giving you two disconnected traces rather than one.
+
+**Note on Exporters**: This example uses the stdout exporter for demonstration
+purposes. In production scenarios, you would typically use other exporters such
+as:
+
+- **OTLP exporter** (`opentelemetry-otlp`) to send traces to an OpenTelemetry
+  Collector or compatible backend. See the [OTLP
+  example](../../opentelemetry-otlp/examples/basic-otlp/README.md) for details.
+- Other vendor-specific exporters for your observability platform.
+
+## Usage
 
 ```shell
 # Run the server first
@@ -15,11 +70,6 @@ $ cargo run --bin grpc-server
 $ cargo run --bin grpc-client
 ```
 
-Observe that the traces are exported to stdout, and that they share the same
-TraceId. Also, the server span would be parented to the client span. The example
-demonstrates how to propagate and restore OpenTelemetry context when making
-out-of-process calls, so as to ensure the same trace is continued in the next
-process. The client here initiates the trace by creating the root client span,
-and it propagates its context to the server. The server, extracts the context,
-and creates its own server span using the extracted context, ensuring both spans
-are correlated.
+Observe in the stdout output that both spans share the same `TraceId`, and
+that the server span is parented to the client span - confirming that the
+trace was successfully propagated across the process boundary.