From e6918187568dbd01842d8d1d2c808ce16a894239 Mon Sep 17 00:00:00 2001
From: Daniel Baumann <daniel.baumann@progress-linux.org>
Date: Sun, 21 Apr 2024 13:54:28 +0200
Subject: Adding upstream version 18.2.2.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
---
 .../examples/metrics_simple/README.md              | 86 ++++++++++++++++++++++
 1 file changed, 86 insertions(+)
 create mode 100644 src/jaegertracing/opentelemetry-cpp/examples/metrics_simple/README.md

(limited to 'src/jaegertracing/opentelemetry-cpp/examples/metrics_simple/README.md')

diff --git a/src/jaegertracing/opentelemetry-cpp/examples/metrics_simple/README.md b/src/jaegertracing/opentelemetry-cpp/examples/metrics_simple/README.md
new file mode 100644
index 000000000..b2c5dc0a7
--- /dev/null
+++ b/src/jaegertracing/opentelemetry-cpp/examples/metrics_simple/README.md
@@ -0,0 +1,86 @@
+# Simple Metrics Example
+
+This example initializes the metrics pipeline with 2 different instrument types.
+Here are more detailed explanations of each part.
+
+1: Initialize an exporter and a reader. In this case, we initialize an OStream
+Exporter which will print to stdout by default.
+The reader periodically collects metrics from the collector and exports them.
+
+```cpp
+std::unique_ptr<metric_sdk::MetricExporter> exporter{new exportermetrics::OStreamMetricExporter};
+std::unique_ptr<metric_sdk::MetricReader> reader{
+    new metric_sdk::PeriodicExportingMetricReader(std::move(exporter), options)};
+```
+
+2: Initialize a MeterProvider and add the reader.
+We will use this to obtain Meter objects in the future.
+
+```cpp
+auto provider = std::shared_ptr<metrics_api::MeterProvider>(new opentelemetry::metrics::MeterProvider());
+auto p = std::static_pointer_cast<metric_sdk::MeterProvider>(provider);
+p->AddMetricReader(std::move(reader));
+```
+
+3: Create and add a view to the provider.
+
+```cpp
+std::unique_ptr<metric_sdk::InstrumentSelector> instrument_selector{
+    new metric_sdk::InstrumentSelector(metric_sdk::InstrumentType::kCounter, "name_counter")};
+std::unique_ptr<metric_sdk::MeterSelector> meter_selector{
+    new metric_sdk::MeterSelector(name, version, schema)};
+std::unique_ptr<metric_sdk::View> sum_view{
+    new metric_sdk::View{name, "description", metric_sdk::AggregationType::kSum}};
+p->AddView(std::move(instrument_selector), std::move(meter_selector), std::move(sum_view));
+```
+
+4: Then create a
+[Counter](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#counter)
+instrument from it. Every Meter pointer returned by the
+MeterProvider points to the same Meter. This means that the Meter will be able
+to combine metrics captured from different functions without having to
+constantly pass the Meter around the library.
+
+```cpp
+nostd::shared_ptr<metrics_api::Meter> meter = provider->GetMeter(name, "1.2.0");
+auto double_counter = meter->CreateDoubleCounter(counter_name);
+// Create a label set which annotates metric values
+std::map<std::string, std::string> labels = {{"key", "value"}};
+auto labelkv = common::KeyValueIterableView<decltype(labels)>{labels};
+double_counter->Add(val, labelkv);
+```
+
+5: To use histogram instrument, a view with proper `InstrumentType` and `AggregationType`
+has to be added to the provider.
+
+```cpp
+std::unique_ptr<metric_sdk::InstrumentSelector> histogram_instrument_selector{
+    new metric_sdk::InstrumentSelector(metric_sdk::InstrumentType::kHistogram, "histogram_name")};
+std::unique_ptr<metric_sdk::MeterSelector> histogram_meter_selector{
+    new metric_sdk::MeterSelector(name, version, schema)};
+std::unique_ptr<metric_sdk::View> histogram_view{
+    new metric_sdk::View{name, "description", metric_sdk::AggregationType::kHistogram}};
+p->AddView(std::move(histogram_instrument_selector), std::move(histogram_meter_selector),
+            std::move(histogram_view));
+
+auto histogram_counter = meter->CreateDoubleHistogram("histogram_name");
+auto context = opentelemetry::context::Context{};
+histogram_counter->Record(val, labelkv, context);
+```
+
+See [CONTRIBUTING.md](../../CONTRIBUTING.md) for instructions on building and
+running the example.
+
+## Additional Documentation
+
+[API
+Design](https://github.com/open-o11y/docs/blob/master/cpp-metrics/api-design.md)
+
+[SDK
+Design](https://github.com/open-o11y/docs/blob/master/cpp-metrics/sdk-design.md)
+
+[OStreamExporters
+Design](https://github.com/open-o11y/docs/blob/master/cpp-ostream/ostream-exporter-design.md)
+
+[OpenTelemetry C++ Metrics
+Overview](https://github.com/open-o11y/docs/blob/master/cpp-metrics/README.md)
-- 
cgit v1.2.3