From fcd65b23dadae87b358c3b03c1d163843922d630 Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Mon, 27 May 2024 16:23:35 +0200 Subject: [PATCH] Add note on OTel C++ and automatic instrumentation (#4542) Co-authored-by: Phillip Carter --- .../en/docs/languages/cpp/getting-started.md | 4 +- .../en/docs/languages/cpp/instrumentation.md | 63 ++++++++++--------- 2 files changed, 37 insertions(+), 30 deletions(-) diff --git a/content/en/docs/languages/cpp/getting-started.md b/content/en/docs/languages/cpp/getting-started.md index f51ed335a1c9..d499e7762445 100644 --- a/content/en/docs/languages/cpp/getting-started.md +++ b/content/en/docs/languages/cpp/getting-started.md @@ -19,7 +19,7 @@ Ensure that you have the following installed locally: - Make - CMake version >= 3.25 -## Example Application +## Example application The following example uses a basic [Oat++](https://oatpp.io/) application. If you are not using Oat++, that's OK - you can use OpenTelemetry C++ with any @@ -396,7 +396,7 @@ will see a span being emitted to the terminal. } ``` -## Next Steps +## Next steps For more information about instrumenting your code, refer the [instrumentation](/docs/languages/cpp/instrumentation) documentation. diff --git a/content/en/docs/languages/cpp/instrumentation.md b/content/en/docs/languages/cpp/instrumentation.md index 4b88b067809e..829b317558be 100644 --- a/content/en/docs/languages/cpp/instrumentation.md +++ b/content/en/docs/languages/cpp/instrumentation.md @@ -11,6 +11,13 @@ cSpell:ignore: decltype labelkv nostd nullptr {{% docs/languages/instrumentation-intro %}} +{{% alert title="Note" color="primary" %}} + +OpenTelemetry C++ doesn't support automatic instrumentation when the source code +of the library you want to instrument isn't available. + +{{% /alert %}} + ## Setup Follow the instructions in the @@ -19,7 +26,7 @@ OpenTelemetry C++. ## Traces -### Initializing tracing +### Initialize tracing ```cpp auto provider = opentelemetry::trace::Provider::GetTracerProvider(); @@ -57,7 +64,7 @@ The concept of an active span is important, as any span that is created without explicitly specifying a parent is parented to the currently active span. A span without a parent is called root span. -### Create nested Spans +### Create nested spans ```cpp auto outer_span = tracer->StartSpan("Outer operation"); @@ -76,7 +83,7 @@ Spans can be nested, and have a parent-child relationship with other spans. When a given span is active, the newly created span inherits the active span’s trace ID, and other context attributes. -### Context Propagation +### Context propagation ```cpp // set global propagator @@ -105,7 +112,7 @@ distributed tracing to transfer this Context across service boundary often through HTTP headers. OpenTelemetry provides a text-based approach to propagate context to remote services using the W3C Trace Context HTTP headers. -### Further Reading +### Further reading - [Traces API](https://opentelemetry-cpp.readthedocs.io/en/latest/otel_docs/namespace_opentelemetry__trace.html) - [Traces SDK](https://opentelemetry-cpp.readthedocs.io/en/latest/otel_docs/namespace_opentelemetry__sdk__trace.html) @@ -113,10 +120,10 @@ context to remote services using the W3C Trace Context HTTP headers. ## Metrics -### Initialize Exporter and Reader +### Initialize exporter and reader -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 +Initialize an exporter and a reader. In this case, you initialize an OStream +Exporter which prints to stdout by default. The reader periodically collects metrics from the Aggregation Store and exports them. ```cpp @@ -125,10 +132,10 @@ std::unique_ptr reader{ new opentelemetry::sdk::metrics::PeriodicExportingMetricReader(std::move(exporter), options)}; ``` -### Initialize Meter Provider +### Initialize a meter provider -Initialize a MeterProvider and add the reader. We will use this to obtain Meter -objects in the future. +Initialize a MeterProvider and add the reader. Use this to obtain Meter objects +in the future. ```cpp auto provider = std::shared_ptr(new opentelemetry::sdk::metrics::MeterProvider()); @@ -136,12 +143,12 @@ auto p = std::static_pointer_cast(pr p->AddMetricReader(std::move(reader)); ``` -### Create a Counter +### Create a counter Create a Counter instrument from the Meter, and record the measurement. 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. +that the Meter can combine metrics captured from different functions without +having to constantly pass the Meter around the library. ```cpp auto meter = provider->GetMeter(name, "1.2.0"); @@ -152,9 +159,9 @@ auto labelkv = common::KeyValueIterableView{labels}; double_counter->Add(val, labelkv); ``` -### Create a Histogram +### Create a histogram -Create a Histogram instrument from the Meter, and record the measurement. +Create a histogram instrument from the meter, and record the measurement. ```cpp auto meter = provider->GetMeter(name, "1.2.0"); @@ -162,11 +169,11 @@ auto histogram_counter = meter->CreateDoubleHistogram("histogram_name"); histogram_counter->Record(val, labelkv); ``` -### Create Observable Counter +### Create an observable counter -Create a Observable Counter Instrument from the Meter, and add a callback. The -callback would be used to record the measurement during metrics collection. -Ensure to keep the Instrument object active for the lifetime of collection. +Create an observable counter instrument from the meter, and add a callback. The +callback is used to record the measurement during metrics collection. Ensure to +keep the Instrument object active for the lifetime of collection. ```cpp auto meter = provider->GetMeter(name, "1.2.0"); @@ -174,14 +181,14 @@ auto counter = meter->CreateDoubleObservableCounter(counter_name); counter->AddCallback(MeasurementFetcher::Fetcher, nullptr); ``` -### Create Views +### Create views -#### Map the Counter Instrument to Sum Aggregation +#### Map the counter instrument to sum aggregation Create a view to map the Counter Instrument to Sum Aggregation. Add this view to -provider. View creation is optional unless we want to add custom aggregation -config, and attribute processor. Metrics SDK will implicitly create a missing -view with default mapping between Instrument and Aggregation. +provider. View creation is optional unless you want to add custom aggregation +config, and attribute processor. Metrics SDK creates a missing view with default +mapping between Instrument and Aggregation. ```cpp std::unique_ptr instrument_selector{ @@ -193,7 +200,7 @@ std::unique_ptr sum_view{ p->AddView(std::move(instrument_selector), std::move(meter_selector), std::move(sum_view)); ``` -#### Map the Histogram Instrument to Histogram Aggregation +#### Map the histogram instrument to histogram aggregation ```cpp std::unique_ptr histogram_instrument_selector{ @@ -206,7 +213,7 @@ p->AddView(std::move(histogram_instrument_selector), std::move(histogram_meter_s std::move(histogram_view)); ``` -#### Map the Observable Counter Instrument to Sum Aggregation +#### Map the observable counter instrument to sum aggregation ```cpp std::unique_ptr observable_instrument_selector{ @@ -220,7 +227,7 @@ p->AddView(std::move(observable_instrument_selector), std::move(observable_meter std::move(observable_sum_view)); ``` -### Further Reading +### Further reading - [Metrics API](https://opentelemetry-cpp.readthedocs.io/en/latest/otel_docs/namespace_opentelemetry__metrics.html#) - [Metrics SDK](https://opentelemetry-cpp.readthedocs.io/en/latest/otel_docs/namespace_opentelemetry__sdk__metrics.html) @@ -232,7 +239,7 @@ The documentation for the logs API & SDK is missing, you can help make it available by [editing this page](https://github.com/open-telemetry/opentelemetry.io/edit/main/content/en/docs/languages/cpp/instrumentation.md). -## Next Steps +## Next steps You’ll also want to configure an appropriate exporter to [export your telemetry data](/docs/languages/cpp/exporters) to one or more