diff options
Diffstat (limited to 'src/jaegertracing/opentelemetry-cpp/examples/metrics_simple/README.md')
-rw-r--r-- | src/jaegertracing/opentelemetry-cpp/examples/metrics_simple/README.md | 86 |
1 files changed, 86 insertions, 0 deletions
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) |