[SDK] Better control of threads executed by opentelemetry-cpp (#3175)

CHANGELOG.md

@@ -27,6 +27,66 @@ Increment the:
 * [EXPORTER] Fix throw in OtlpGrpcMetricExporter with shared grpc client
   [#3243](https://github.com/open-telemetry/opentelemetry-cpp/pull/3243)
 
+* [SDK] Better control of threads executed by opentelemetry-cpp
+  [#3175](https://github.com/open-telemetry/opentelemetry-cpp/pull/3175)
+
+New features:
+
+* [SDK] Better control of threads executed by opentelemetry-cpp
+  [#3175](https://github.com/open-telemetry/opentelemetry-cpp/pull/3175)
+
+  * This feature provides a way for applications,
+    when configuring the SDK and exporters,
+    to participate in the execution path
+    of internal opentelemetry-cpp threads.
+
+  * The opentelemetry-cpp library provides the following:
+
+    * a new ThreadInstrumentation interface,
+    * new runtime options structures, to optionally configure the SDK:
+      * BatchSpanProcessorRuntimeOptions
+      * PeriodicExportingMetricReaderRuntimeOptions
+      * BatchLogRecordProcessorRuntimeOptions
+    * new runtime options structures,
+      to optionally configure the OTLP HTTP exporters:
+      * OtlpHttpExporterRuntimeOptions
+      * OtlpHttpMetricExporterRuntimeOptions
+      * OtlpHttpLogRecordExporterRuntimeOptions
+    * new ThreadInstrumentation parameters,
+      to optionally configure the CURL HttpClient
+    * new runtime options structures,
+      to optionally configure the OTLP FILE exporters:
+      * OtlpFileExporterRuntimeOptions
+      * OtlpFileMetricExporterRuntimeOptions
+      * OtlpFileLogRecordExporterRuntimeOptions
+    * new runtime options structure,
+      to optionally configure the OTLP FILE client:
+      * OtlpFileClientRuntimeOptions
+
+  * Using the optional runtime options structures,
+    an application can subclass the ThreadInstrumentation interface,
+    and be notified of specific events of interest during the execution
+    of an internal opentelemetry-cpp thread.
+
+  * This allows an application to call, for example:
+
+    * pthread_setaffinity_np(), for better performances,
+    * setns(), to control the network namespace used by HTTP CURL connections
+    * pthread_setname_np(), for better observability from the operating system
+    * many more specific apis, as needed
+
+  * See the documentation for ThreadInstrumentation for details.
+
+  * A new example program, example_otlp_instrumented_http,
+    shows how to use the feature,
+    and add application logic in the thread execution code path.
+
+  * Note that this feature is experimental,
+    protected by a WITH_THREAD_INSTRUMENTATION_PREVIEW
+    flag in CMake. Various runtime options structures,
+    as well as the thread instrumentation interface,
+    may change without notice before this feature is declared stable.
+
 ## [1.18 2024-11-25]
 
 * [EXPORTER] Fix crash in ElasticsearchLogRecordExporter

CMakeLists.txt

@@ -300,6 +300,10 @@ option(WITH_ASYNC_EXPORT_PREVIEW "Whether to enable async export" OFF)
 option(WITH_METRICS_EXEMPLAR_PREVIEW
        "Whether to enable exemplar within metrics" OFF)
 
+# Experimental, so behind feature flag by default
+option(WITH_THREAD_INSTRUMENTATION_PREVIEW
+       "Whether to enable thread instrumentation" OFF)
+
 option(OPENTELEMETRY_SKIP_DYNAMIC_LOADING_TESTS
        "Whether to build test libraries that are always linked as shared libs"
        OFF)

api/CMakeLists.txt

@@ -126,6 +126,11 @@ if(WITH_METRICS_EXEMPLAR_PREVIEW)
                              INTERFACE ENABLE_METRICS_EXEMPLAR_PREVIEW)
 endif()
 
+if(WITH_THREAD_INSTRUMENTATION_PREVIEW)
+  target_compile_definitions(opentelemetry_api
+                             INTERFACE ENABLE_THREAD_INSTRUMENTATION_PREVIEW)
+endif()
+
 if(WITH_OTLP_HTTP_COMPRESSION)
   target_compile_definitions(opentelemetry_api
                              INTERFACE ENABLE_OTLP_COMPRESSION_PREVIEW)

ci/do_ci.sh

@@ -131,6 +131,7 @@ elif [[ "$1" == "cmake.maintainer.sync.test" ]]; then
         -DOTELCPP_MAINTAINER_MODE=ON \
         -DWITH_NO_DEPRECATED_CODE=ON \
         -DWITH_OTLP_HTTP_COMPRESSION=ON \
+        -DWITH_THREAD_INSTRUMENTATION_PREVIEW=ON \
         ${IWYU} \
         "${SRC_DIR}"
   eval "$MAKE_COMMAND"
@@ -153,6 +154,7 @@ elif [[ "$1" == "cmake.maintainer.async.test" ]]; then
         -DOTELCPP_MAINTAINER_MODE=ON \
         -DWITH_NO_DEPRECATED_CODE=ON \
         -DWITH_OTLP_HTTP_COMPRESSION=ON \
+        -DWITH_THREAD_INSTRUMENTATION_PREVIEW=ON \
         ${IWYU} \
         "${SRC_DIR}"
   eval "$MAKE_COMMAND"
@@ -176,6 +178,7 @@ elif [[ "$1" == "cmake.maintainer.cpp11.async.test" ]]; then
         -DOTELCPP_MAINTAINER_MODE=ON \
         -DWITH_NO_DEPRECATED_CODE=ON \
         -DWITH_OTLP_HTTP_COMPRESSION=ON \
+        -DWITH_THREAD_INSTRUMENTATION_PREVIEW=ON \
         "${SRC_DIR}"
   make -k -j $(nproc)
   make test
@@ -199,6 +202,7 @@ elif [[ "$1" == "cmake.maintainer.abiv2.test" ]]; then
         -DWITH_ABI_VERSION_1=OFF \
         -DWITH_ABI_VERSION_2=ON \
         -DWITH_OTLP_HTTP_COMPRESSION=ON \
+        -DWITH_THREAD_INSTRUMENTATION_PREVIEW=ON \
         ${IWYU} \
         "${SRC_DIR}"
   eval "$MAKE_COMMAND"

examples/otlp/BUILD

@@ -168,3 +168,25 @@ cc_binary(
         "//sdk/src/metrics",
     ],
 )
+
+cc_binary(
+    name = "example_otlp_instrumented_http",
+    srcs = [
+        "http_instrumented_main.cc",
+    ],
+    tags = [
+        "examples",
+        "otlp",
+        "otlp_http",
+    ],
+    deps = [
+        "//api",
+        "//examples/common/logs_foo_library:common_logs_foo_library",
+        "//examples/common/metrics_foo_library:common_metrics_foo_library",
+        "//exporters/otlp:otlp_http_exporter",
+        "//exporters/otlp:otlp_http_log_record_exporter",
+        "//exporters/otlp:otlp_http_metric_exporter",
+        "//sdk/src/metrics",
+        "//sdk/src/trace",
+    ],
+)

examples/otlp/CMakeLists.txt

@@ -99,6 +99,29 @@ if(WITH_OTLP_HTTP)
       opentelemetry_exporter_otlp_http_log)
   endif()
 
+  # ALL, instrumented
+
+  add_executable(example_otlp_instrumented_http http_instrumented_main.cc)
+
+  # Note: common_logs_foo_library provide traces and logs
+  target_link_libraries(
+    example_otlp_instrumented_http ${CMAKE_THREAD_LIBS_INIT}
+    common_metrics_foo_library common_logs_foo_library)
+
+  if(DEFINED OPENTELEMETRY_BUILD_DLL)
+    target_link_libraries(example_otlp_instrumented_http opentelemetry_cpp
+                          opentelemetry_common)
+  else()
+    target_link_libraries(
+      example_otlp_instrumented_http
+      opentelemetry_trace
+      opentelemetry_metrics
+      opentelemetry_logs
+      opentelemetry_exporter_otlp_http
+      opentelemetry_exporter_otlp_http_metric
+      opentelemetry_exporter_otlp_http_log)
+  endif()
+
 endif()
 
 if(WITH_OTLP_FILE)