Merge branch 'fix/doc_comment_api' of https://github.com/zurex/opentelemetry-cpp into fix/doc_comment_api

Author: zurex

.github/workflows/ci.yml

@@ -57,6 +57,33 @@ jobs:
       run: |
         ./ci/do_ci.sh cmake.test
 
+  cmake_fetch_content_test:
+    name: CMake FetchContent usage with opentelemetry-cpp
+    runs-on: ubuntu-24.04
+    env:
+      CXX_STANDARD: '17'
+      BUILD_TYPE: 'Debug'
+    steps:
+    - name: Harden the runner (Audit all outbound calls)
+      uses: step-security/harden-runner@0634a2670c59f64b4a01f0f96f84700a4088b9f0 # v2.12.0
+      with:
+        egress-policy: audit
+    - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      with:
+        submodules: 'recursive'
+    - name: setup
+      run: |
+        sudo -E ./ci/setup_ci_environment.sh
+        sudo -E ./ci/setup_cmake.sh
+        sudo -E ./ci/setup_googletest.sh
+    - name: Install abseil, protobuf, and grpc with apt
+      run: |
+        sudo -E apt-get update
+        sudo -E apt-get install -y libabsl-dev libprotobuf-dev libgrpc++-dev protobuf-compiler protobuf-compiler-grpc
+    - name: run fetch content cmake test
+      run: |
+        ./ci/do_ci.sh cmake.fetch_content.test
+
   cmake_gcc_maintainer_sync_test:
     name: CMake gcc 14 (maintainer mode, sync)
     runs-on: ubuntu-24.04
@@ -1104,7 +1131,7 @@ jobs:
         CXX: /usr/bin/g++-10
       run: ./ci/do_ci.sh code.coverage
     - name: upload report
-      uses: codecov/codecov-action@ad3126e916f78f00edff4ed0317cf185271ccc2d # v5.4.2
+      uses: codecov/codecov-action@18283e04ce6e62d37312384ff67231eb8fd56d24 # v5.4.3
       with:
         files: /home/runner/build/coverage.info
 

.github/workflows/codeql-analysis.yml

@@ -39,10 +39,10 @@ jobs:
         sudo -E ./ci/setup_googletest.sh
         sudo -E ./ci/setup_ci_environment.sh
     - name: Initialize CodeQL
-      uses: github/codeql-action/init@28deaeda66b76a05916b6923827895f2b14ab387 # v3.28.16
+      uses: github/codeql-action/init@ff0a06e83cb2de871e5a09832bc6a81e7276941f # v3.28.18
       with:
        languages: cpp
     - name: Autobuild
-      uses: github/codeql-action/autobuild@28deaeda66b76a05916b6923827895f2b14ab387 # v3.28.16
+      uses: github/codeql-action/autobuild@ff0a06e83cb2de871e5a09832bc6a81e7276941f # v3.28.18
     - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@28deaeda66b76a05916b6923827895f2b14ab387 # v3.28.16
+      uses: github/codeql-action/analyze@ff0a06e83cb2de871e5a09832bc6a81e7276941f # v3.28.18

.github/workflows/dependencies_image.yml

@@ -29,7 +29,7 @@ jobs:
       uses: docker/setup-buildx-action@b5ca514318bd6ebac0fb2aedd5d36ec1b5c232a2 # v3.10.0
     -
       name: Build Image
-      uses: docker/build-push-action@14487ce63c7a62a4a324b0bfb37086795e31c6c1 # v6.16.0
+      uses: docker/build-push-action@1dc73863535b631f98b2378be8619f83b136f4a0 # v6.17.0
       with:
         builder: ${{ steps.buildx.outputs.name }}
         context: ci/

.github/workflows/fossa.yml

@@ -19,7 +19,7 @@ jobs:
 
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
 
-      - uses: fossas/fossa-action@c0a7d013f84c8ee5e910593186598625513cc1e4 # v1.6.0
+      - uses: fossas/fossa-action@3ebcea1862c6ffbd5cf1b4d0bd6b3fe7bd6f2cac # v1.7.0
         with:
           api-key: ${{secrets.FOSSA_API_KEY}}
           team: OpenTelemetry

.github/workflows/ossf-scorecard.yml

@@ -47,6 +47,6 @@ jobs:
       # Upload the results to GitHub's code scanning dashboard (optional).
       # Commenting out will disable upload of results to your repo's Code Scanning dashboard
       - name: "Upload to code-scanning"
-        uses: github/codeql-action/upload-sarif@28deaeda66b76a05916b6923827895f2b14ab387 # v3.28.16
+        uses: github/codeql-action/upload-sarif@ff0a06e83cb2de871e5a09832bc6a81e7276941f # v3.28.18
         with:
           sarif_file: results.sarif

CHANGELOG.md

@@ -15,6 +15,12 @@ Increment the:
 
 ## [Unreleased]
 
+* [BUILD] Error out when building DLL without MSVC
+  [#3438](https://github.com/open-telemetry/opentelemetry-cpp/pull/3438)
+
+* [Metrics SDK] Use nostd::function_ref in AttributesHashMap
+  [#3393](https://github.com/open-telemetry/opentelemetry-cpp/pull/3393)
+
 * [SDK] Base2 exponential histogram aggregation
   [#3175](https://github.com/open-telemetry/opentelemetry-cpp/pull/3346)
 
@@ -33,6 +39,56 @@ Increment the:
 * [API] Add Enabled method to Tracer
   [#3357](https://github.com/open-telemetry/opentelemetry-cpp/pull/3357)
 
+* [SDK] Optimize PeriodicExportingMetricReader thread usage
+  [#3383](https://github.com/open-telemetry/opentelemetry-cpp/pull/3383)
+
+* [SDK] Aggregate identical metrics instruments and detect duplicates
+  [#3358](https://github.com/open-telemetry/opentelemetry-cpp/pull/3358)
+
+* [INSTALL] Add CMake components to the opentelemetry-cpp package
+  [#3320](https://github.com/open-telemetry/opentelemetry-cpp/pull/3220)
+  [#3368](https://github.com/open-telemetry/opentelemetry-cpp/pull/3368)
+
+* [BUILD] Upgrade opentelemetry-proto to 1.6.0
+  [#3407](https://github.com/open-telemetry/opentelemetry-cpp/pull/3407)
+
+* [BUILD] Upgrade nlohmann_json to 3.12.0
+  [#3406](https://github.com/open-telemetry/opentelemetry-cpp/pull/3406)
+
+* [CMAKE] Add generated protobuf headers to the opentelemetry_proto target
+  [#3400](https://github.com/open-telemetry/opentelemetry-cpp/pull/3400)
+
+* [CMAKE] Remove include_directories usage and rely on target properties
+  [#3426](https://github.com/open-telemetry/opentelemetry-cpp/pull/3426)
+
+* [SEMANTIC CONVENTIONS] Upgrade to semantic conventions 1.34.0
+  [#3428](https://github.com/open-telemetry/opentelemetry-cpp/pull/3428)
+
+* [EXPORTER] ostream log exporter, fixed memory ownership issues
+  [#3417](https://github.com/open-telemetry/opentelemetry-cpp/pull/3417)
+
+* [TEST] Test all components in a CMake super build
+  [#3433](https://github.com/open-telemetry/opentelemetry-cpp/pull/3433)
+
+Important changes:
+
+* [EXPORTER] ostream log exporter, fixed memory ownership issues
+  [#3417](https://github.com/open-telemetry/opentelemetry-cpp/pull/3417)
+
+  * In the SDK, the following classes implementation has changed:
+
+    * opentelemetry::sdk::logs::ReadableLogRecord
+    * opentelemetry::sdk::logs::ReadWriteLogRecord
+
+  * An application implementing a custom log record exporter,
+    that reuses these classes from the opentelemetry-cpp SDK,
+    will need code adjustments, in particular for methods:
+
+    * GetBody()
+    * GetAttributes()
+
+  * Applications not using these SDK classes directly are not affected.
+
 ## [1.20 2025-04-01]
 
 * [BUILD] Update opentelemetry-proto version

CMakeLists.txt

@@ -849,6 +849,8 @@ if(prometheus-cpp_FOUND)
 endif()
 message(STATUS "---------------------------------------------")
 
+include("${PROJECT_SOURCE_DIR}/cmake/otel-install-functions.cmake")
+
 include(CMakePackageConfigHelpers)
 
 if(DEFINED OPENTELEMETRY_BUILD_DLL)
@@ -865,8 +867,6 @@ if(DEFINED OPENTELEMETRY_BUILD_DLL)
   add_definitions(-DOPENTELEMETRY_BUILD_EXPORT_DLL)
 endif()
 
-include_directories(api/include)
-
 add_subdirectory(api)
 
 if(WITH_OPENTRACING)
@@ -899,9 +899,6 @@ endif()
 
 if(NOT WITH_API_ONLY)
   set(BUILD_TESTING ${BUILD_TESTING})
-  include_directories(sdk/include)
-  include_directories(sdk)
-  include_directories(ext/include)
 
   add_subdirectory(sdk)
   add_subdirectory(ext)
@@ -922,39 +919,14 @@ include(cmake/opentelemetry-build-external-component.cmake)
 include(cmake/patch-imported-config.cmake)
 
 if(OPENTELEMETRY_INSTALL)
-  # Export cmake config and support find_packages(opentelemetry-cpp CONFIG)
-  # Write config file for find_packages(opentelemetry-cpp CONFIG)
-  set(INCLUDE_INSTALL_DIR "${CMAKE_INSTALL_INCLUDEDIR}")
-  configure_package_config_file(
-    "${CMAKE_CURRENT_LIST_DIR}/cmake/templates/opentelemetry-cpp-config.cmake.in"
-    "${CMAKE_CURRENT_BINARY_DIR}/cmake/${PROJECT_NAME}/${PROJECT_NAME}-config.cmake"
-    INSTALL_DESTINATION "${CMAKE_INSTALL_LIBDIR}/cmake/${PROJECT_NAME}"
-    PATH_VARS OPENTELEMETRY_ABI_VERSION_NO OPENTELEMETRY_VERSION PROJECT_NAME
-              INCLUDE_INSTALL_DIR CMAKE_INSTALL_LIBDIR)
-
-  # Write version file for find_packages(opentelemetry-cpp CONFIG)
-  write_basic_package_version_file(
-    "${CMAKE_CURRENT_BINARY_DIR}/cmake/${PROJECT_NAME}/${PROJECT_NAME}-config-version.cmake"
-    VERSION ${OPENTELEMETRY_VERSION}
-    COMPATIBILITY ExactVersion)
-
-  # Write the "BUILT_WITH_<dependency" flags for use in the
-  # opentelemetry-cpp-config.cmake
-  configure_file(
-    "${CMAKE_CURRENT_SOURCE_DIR}/cmake/templates/thirdparty-built-with-flags.cmake.in"
-    "${CMAKE_CURRENT_BINARY_DIR}/thirdparty-built-with-flags.cmake"
-    @ONLY)
-
-  install(
-    FILES
-      "${CMAKE_CURRENT_BINARY_DIR}/cmake/${PROJECT_NAME}/${PROJECT_NAME}-config.cmake"
-      "${CMAKE_CURRENT_BINARY_DIR}/cmake/${PROJECT_NAME}/${PROJECT_NAME}-config-version.cmake"
-      "${CMAKE_CURRENT_BINARY_DIR}/thirdparty-built-with-flags.cmake"
-      "${CMAKE_CURRENT_LIST_DIR}/cmake/component-definitions.cmake"
-      "${CMAKE_CURRENT_LIST_DIR}/cmake/thirdparty-dependency-definitions.cmake"
-      "${CMAKE_CURRENT_LIST_DIR}/cmake/find-package-support-functions.cmake"
-    DESTINATION "${CMAKE_INSTALL_LIBDIR}/cmake/${PROJECT_NAME}"
-    COMPONENT cmake-config)
+  # Install the cmake config and version files
+  otel_install_cmake_config()
+
+  # Install the components and associated files
+  otel_install_components()
+
+  # Install the thirdparty dependency definition file
+  otel_install_thirdparty_definitions()
 
   if(BUILD_PACKAGE)
     include(cmake/package.cmake)

INSTALL.md

@@ -151,21 +151,55 @@ If building and installing Protobuf and gRPC manually with cmake the
    $
    ```
 
-### Incorporating into an existing CMake Project
+### Incorporating into an external CMake Project
 
-To use the library from a CMake project, you can locate it directly with
- `find_package` and use the imported targets from generated package
- configurations. As of now, this will import targets for both API and SDK. In
- future, there may be separate packages for API and SDK which can be installed
- and imported separately according to need.
+There are two approaches to incoporate `opentelemetry-cpp` into
+ an external CMake project:
 
-```cmake
-# CMakeLists.txt
-find_package(opentelemetry-cpp CONFIG REQUIRED)
-...
-target_include_directories(foo PRIVATE ${OPENTELEMETRY_CPP_INCLUDE_DIRS})
-target_link_libraries(foo PRIVATE ${OPENTELEMETRY_CPP_LIBRARIES})
-```
+1. Build and install `opentelemetry-cpp` then use `find_package`
+ to import its targets
+
+   ```cmake
+   # Find all installed components and link all imported targets
+   find_package(opentelemetry-cpp CONFIG REQUIRED)
+   ...
+   target_include_directories(foo PRIVATE ${OPENTELEMETRY_CPP_INCLUDE_DIRS})
+   target_link_libraries(foo PRIVATE ${OPENTELEMETRY_CPP_LIBRARIES})
+   ```
+
+   ```cmake
+   # Find a specific component and link its imported target(s)
+   find_package(opentelemetry-cpp CONFIG REQUIRED COMPONENTS api)
+   ...
+   target_link_libraries(foo PRIVATE opentelemetry-cpp::api)
+   ```
+
+2. Use CMake's [FetchContent](https://cmake.org/cmake/help/latest/module/FetchContent.html)
+ module to fetch and build `opentelemetry-cpp` then make its targets available
+
+   ```cmake
+   # Fetch from an existing clone and build
+   include(FetchContent)
+   FetchContent_Declare(opentelemetry-cpp SOURCE_DIR "<path/to/opentelemetry-cpp>")
+   FetchContent_MakeAvailable(opentelemetry-cpp)
+   ...
+   target_link_libraries(foo PRIVATE opentelemetry-cpp::api)
+   ```
+
+   ```cmake
+   # Clone and build opentelemetry-cpp from a git tag
+   include(FetchContent)
+   FetchContent_Declare(
+   opentelemetry-cpp
+   GIT_REPOSITORY https://github.com/open-telemetry/opentelemetry-cpp.git
+   GIT_TAG        v1.20.0)
+   FetchContent_MakeAvailable(opentelemetry-cpp)
+   ...
+   target_link_libraries(foo PRIVATE opentelemetry-cpp::api)
+   ```
+
+In both cases the project's built or imported CMake targets will be
+ available in the `opentelemetry-cpp` namespace (ie: `opentelemetry-cpp::api`)
 
 #### Using opentelemetry-cpp package components
 
@@ -187,13 +221,17 @@ target_link_libraries(foo_lib PRIVATE opentelemetry-cpp::api)
 # foo_app/CMakeLists.txt
 find_package(opentelemetry-cpp CONFIG REQUIRED COMPONENTS api sdk exporters_otlp_grpc)
 add_executable(foo_app main.cpp)
-target_link_libraries(foo_app PRIVATE foo_lib opentelemetry-cpp::api opentelemetry-cpp::sdk opentelemetry-cpp::otlp_grpc_exporter )
+target_link_libraries(foo_app PRIVATE foo_lib opentelemetry-cpp::api opentelemetry-cpp::trace opentelemetry-cpp::otlp_grpc_exporter )
 ```
 
 The following table provides the mapping between components and targets. Components
 and targets available in the installation depends on the opentelemetry-cpp package
 build configuration.
 
+> **Note:** components `exporters_elasticsearch` and `exporters_etw`
+ may be moved out of the core package and to `opentelemetry-cpp-contrib`
+  in a future release
+
 | Component                  | Targets                                                                                          |
 |----------------------------|--------------------------------------------------------------------------------------------------|
 | **api**                    | opentelemetry-cpp::api                                                                           |

MODULE.bazel

@@ -12,8 +12,8 @@ bazel_dep(name = "abseil-cpp", version = "20240116.1", repo_name = "com_google_a
 bazel_dep(name = "bazel_skylib", version = "1.5.0")
 bazel_dep(name = "curl", version = "8.8.0")
 bazel_dep(name = "grpc", version = "1.63.1.bcr.1", repo_name = "com_github_grpc_grpc")
-bazel_dep(name = "nlohmann_json", version = "3.11.3", repo_name = "github_nlohmann_json")
-bazel_dep(name = "opentelemetry-proto", version = "1.5.0", repo_name = "com_github_opentelemetry_proto")
+bazel_dep(name = "nlohmann_json", version = "3.12.0", repo_name = "github_nlohmann_json")
+bazel_dep(name = "opentelemetry-proto", version = "1.6.0", repo_name = "com_github_opentelemetry_proto")
 bazel_dep(name = "opentracing-cpp", version = "1.6.0", repo_name = "com_github_opentracing")
 bazel_dep(name = "platforms", version = "0.0.8")
 bazel_dep(name = "prometheus-cpp", version = "1.3.0", repo_name = "com_github_jupp0r_prometheus_cpp")

api/CMakeLists.txt

@@ -9,28 +9,20 @@ target_include_directories(
 
 set_target_properties(opentelemetry_api PROPERTIES EXPORT_NAME api)
 
-if(OPENTELEMETRY_INSTALL)
-  install(
-    TARGETS opentelemetry_api
-    EXPORT "${PROJECT_NAME}-api-target"
-    RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
-    LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
-    ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR} COMPONENT api)
-
-  install(
-    DIRECTORY include/opentelemetry
-    DESTINATION include
-    COMPONENT api
-    FILES_MATCHING
-    PATTERN "*.h")
-
-  install(
-    EXPORT "${PROJECT_NAME}-api-target"
-    FILE "${PROJECT_NAME}-api-target.cmake"
-    NAMESPACE "${PROJECT_NAME}::"
-    DESTINATION "${CMAKE_INSTALL_LIBDIR}/cmake/${PROJECT_NAME}"
-    COMPONENT api)
+otel_add_component(
+  COMPONENT
+  api
+  TARGETS
+  opentelemetry_api
+  FILES_DIRECTORY
+  "include/opentelemetry"
+  FILES_DESTINATION
+  "include"
+  FILES_MATCHING
+  PATTERN
+  "*.h")
 
+if(OPENTELEMETRY_INSTALL)
   unset(TARGET_DEPS)
 endif()