[SDK] Better control of threads executed by opentelemetry-cpp

CHANGELOG.md

@@ -24,6 +24,60 @@ Increment the:
 * [EXPORTER] Fix scope attributes missing from otlp traces metrics
   [#3185](https://github.com/open-telemetry/opentelemetry-cpp/pull/3185)
 
+* [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.
+
 ## [1.18 2024-11-25]
 
 * [EXPORTER] Fix crash in ElasticsearchLogRecordExporter

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)