Maintaining dependencies

In general, several places in the code base need to be adjusted when upgrading a dependency to a new version.

This documentation contains notes about which place to fix, to make maintenance easier and less error prone.

This doc is only useful when up to date, so make sure to add details about missing parts if any.

Also, another good place to start when upgrading something to N+1 is to find the commit that upgraded to version N (use git blame), and inspect the commit for the last upgrade.

Overview

Dependency	Type
opentelemetry-proto	git submodule
prometheus-cpp	git submodule

opentelemetry-proto

Comments (opentelemetry-proto)

Unlike other opentelemetry SIGs, opentelemetry-cpp generates code from opentelemetry-proto as part of the opentelemetry-cpp build.

Only the source code of opentelemetry-proto is required, which is why this repository is used as a git submodule under third_party.

Code is generated by the protobuf compiler during the build, so that generated code is never checked in.

This allows more flexibility, should the compiler (protobuf) be upgraded even when the source code (opentelemetry-proto) is unchanged.

Origin (opentelemetry-proto)

The repository for opentelemetry-proto is:

repository

Check release notes at:

release-notes

Upgrade (opentelemetry-proto)

When upgrading opentelemetry-proto to a newer release, a few places in the code need adjustment.

In this example, we upgrade from 1.3.1 to 1.3.2

directory third_party/opentelemetry-proto

You need to update the git submodule third_party/opentelemetry-proto, check Upgrade a git submodule for more details.

file third_party_release

Update the line pointing to the opentelemetry-proto tag.

opentelemetry-proto=v1.3.2

Typical change:

[malff@malff-desktop opentelemetry-cpp]$ git diff third_party_release
diff --git a/third_party_release b/third_party_release
index 0bbf67f3..7362473f 100644
--- a/third_party_release
+++ b/third_party_release
@@ -19,7 +19,7 @@ benchmark=v1.8.3
 googletest=1.14.0
 ms-gsl=v3.1.0-67-g6f45293
 nlohmann-json=v3.11.3
-opentelemetry-proto=v1.3.1
+opentelemetry-proto=v1.3.2
 opentracing-cpp=v1.6.0
 prometheus-cpp=v1.2.4
 vcpkg=2024.02.14

file cmake/opentelemetry-proto.cmake

Update the tag in the CMake logic:

        set(opentelemetry-proto "v1.3.2")

Typical change:

[malff@malff-desktop opentelemetry-cpp]$ git diff cmake/opentelemetry-proto.cmake
diff --git a/cmake/opentelemetry-proto.cmake b/cmake/opentelemetry-proto.cmake
index 19516c3b..dd6213c1 100644
--- a/cmake/opentelemetry-proto.cmake
+++ b/cmake/opentelemetry-proto.cmake
@@ -49,7 +49,7 @@ else()
          "opentelemetry-proto=[ \\t]*([A-Za-z0-9_\\.\\-]+)")
         set(opentelemetry-proto "${CMAKE_MATCH_1}")
       else()
-        set(opentelemetry-proto "v1.3.1")
+        set(opentelemetry-proto "v1.3.2")
       endif()
       unset(OTELCPP_THIRD_PARTY_RELEASE_CONTENT)
     endif()

If opentelemetry-proto contains new files, the makefile needs to be adjusted to build the new code.

Depending on the actual changes in the opentelemetry-proto files, the C++ code in opentelemetry-cpp may need adjustments.

Typically, when opentelemetry-proto:

defines a new message (for example, for profiling)
adds new optional fields to an existing message (for example, trace flags)

the existing C++ code should work as is with the new opentelemetry-proto format.

In this case, it is better to:

upgrade the opentelemetry-proto version independently with one PR.
upgrade the C++ code later (to use the new message, of provide new fields) in a different PR.

When the C++ code requires a newer minimum version of opentelemetry-proto, make sure to document this, including in the release notes.

semantic-conventions and weaver

Comments (semantic-conventions)

Some code in opentelemetry-cpp is generated automatically, namely files in:

api/include/opentelemetry/semconv/

The semantic conventions C++ declarations are generated using:

data represented in yaml ("semantic-conventions")
a code generator ("weaver")

This generation is not done as part of the build, it is done once by maintainers, and the generated code is added (checked in) in the opentelemetry-cpp repository.

Origin (semantic-conventions)

The repository for semantic-conventions is:

repository

Check release notes at:

release-notes

The repository for weaver is:

repository

Check release notes at:

release-notes

Semantic conventions and weaver works together, make sure to use the proper version of weaver that is required to use a given version of semantic-conventions.

Upgrade (semantic-conventions)

When upgrading semantic-conventions to a newer release, a few places in the code need adjustment.

In this example, we upgrade from semantic-conventions 1.32.0 to 1.33.0

In this case, semantic-conventions 1.33.0 also require a new version of weaver, because the yaml format for the data changed.

In this example, we upgrade from weaver 0.13.2 to 0.15.0

file buildscripts/semantic-convention/generate.sh

Update the line pointing to the semantic-conventions tag.

SEMCONV_VERSION=1.33.0

Update the line pointing to the weaver tag.

WEAVER_VERSION=0.15.0

Typical change:

[malff@malff-desktop opentelemetry-cpp]$ git diff buildscripts/semantic-convention/generate.sh
diff --git a/buildscripts/semantic-convention/generate.sh b/buildscripts/semantic-convention/generate.sh
index fc04a11f..6d03b747 100755
--- a/buildscripts/semantic-convention/generate.sh
+++ b/buildscripts/semantic-convention/generate.sh
@@ -16,10 +16,10 @@ ROOT_DIR="${SCRIPT_DIR}/../../"
 # freeze the spec & generator tools versions to make the generation reproducible

 # repository: https://github.com/open-telemetry/semantic-conventions
-SEMCONV_VERSION=1.32.0
+SEMCONV_VERSION=1.33.0

 # repository: https://github.com/open-telemetry/weaver
-WEAVER_VERSION=0.13.2
+WEAVER_VERSION=0.15.0

 SEMCONV_VERSION_TAG=v$SEMCONV_VERSION
 WEAVER_VERSION_TAG=v$WEAVER_VERSION

This change alone does nothing, the next step is to execute the generate.sh script.

If generation is successful, the generated code contains the new schema URL:

[malff@malff-desktop opentelemetry-cpp]$ grep kSchemaUrl ./api/include/opentelemetry/semconv/schema_url.h
static constexpr const char *kSchemaUrl = "https://opentelemetry.io/schemas/1.34.0";

Apply clang-format on the generated code, and check-in changes.

Known issues (semantic-conventions)

Depending on tooling changes, the generate.sh script may need adjustments.

Depending on changes in code generation, the template used to generate code may need adjustments.

This templates are implemented in directory buildscripts/semantic-convention/templates/registry.

See templates and file weaver.yaml for details.

prometheus-cpp

Comments (prometheus-cpp)

The prometheus-cpp library provides a C++ client for Prometheus, facilitating the creation and registration of metrics that Prometheus scrapes. prometheus-cpp is used as a git submodule under the third_party directory for ease of inclusion in build system.

Origin (prometheus-cpp)

The repository for prometheus-cpp can be found here:

repository

Check release notes at:

release-notes

Upgrade (prometheus-cpp)

When upgrading prometheus-cpp to a newer release, you’ll need to update a few key files in the codebase to reflect the new version.

In this example, we upgrade from v1.2.3 to v1.2.4.

Directory `third_party/prometheus-cpp`

prometheus-cpp is a git submodule, so it needs to be pointed to the new release tag.

cd third_party/prometheus-cpp
git log -1

The current submodule should show something like:

commit abcdef1234567890abcdef1234567890abcdef12 (HEAD, tag: v1.2.3)
Author: John Doe <johndoe@example.com>
Date:   Fri Apr 25 17:55:35 2024 +0200

    Minor fixes for performance and compatibility

Pull new tags:

git pull --tag origin

Upgrade to the new tag:

git pull origin v1.2.4

Verify the new commit:

git log -1
commit 1234567890abcdef1234567890abcdef12345678 (HEAD, tag: v1.2.4)
Author: Jane Doe <janedoe@example.com>
Date:   Thu Jun 28 08:19:11 2024 -0500

    Improved metrics handling for high concurrency

Return to the root directory:

cd ../..
git status

The status should display:

On branch upgrade_prometheus_1.2.4
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   third_party/prometheus-cpp (new commits)

Add the upgraded submodule:

git add third_party/prometheus-cpp

File third_party_release Update the line referencing the prometheus-cpp version.

prometheus-cpp=v1.2.4

Example change:

$ git diff third_party_release
diff --git a/third_party_release b/third_party_release
index abc1234..def5678 100644
--- a/third_party_release
+++ b/third_party_release
@@ -19,7 +19,7 @@ some-dependency=v0.8.3
 another-dependency=1.14.0
 prometheus-cpp=v1.2.3
+prometheus-cpp=v1.2.4

In file MODULE.bazel locate the entry for prometheus-cpp and update it to the new version:

bazel_dep(name = "prometheus-cpp", version = "1.3.0", repo_name = "com_github_jupp0r_prometheus_cpp")

Upgrade a git submodule

All the git submodule are under the folder third_party. We will use opentelemetry-propto as example in this case. This is a git submodule, it needs to point to the new tag.

Get current tag

cd third_party/opentelemetry-proto
git log -1

The current submodule show something like:

commit b3060d2104df364136d75a35779e6bd48bac449a (HEAD, tag: v1.3.1)
Author: Damien Mathieu <42@dmathieu.com>
Date:   Thu Apr 25 17:55:35 2024 +0200

    generate profiles proto for CI (#552)

In this case we can see the current tag is v.1.3.1.

Upgrade to new tag

Pull new tags:

git pull --tag origin

Upgrade to a new tag:

git pull origin v1.3.2

Check the new state:

git log -1

commit 40b3c1b746767cbc13c2e39da3eaf1a23e54ffdd (HEAD, tag: v1.3.2)
Author: jack-berg <34418638+jack-berg@users.noreply.github.com>
Date:   Fri Jun 28 08:19:11 2024 -0500

    Prepare changelog for 1.3.2 release (#563)

    Co-authored-by: Armin Ruech <7052238+arminru@users.noreply.github.com>

Add changes

Go back to the root of opentelemetry-cpp

cd ../..
git status

On branch upgrade_proto_1.3.2
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   third_party/opentelemetry-proto (new commits)

Add the upgraded submodule:

git add third_party/opentelemetry-proto

Upgrade a bazel dependency

Update MODULE.bazel

Remember, the link is different in your case. Replace opentelemetry-proto to correct target.

Make sure the new tag is available in bazel central:

opentelemetry-proto bazel-central

If missing, file a PR to add it, or contact the maintainer:

opentelemetry-proto repository

Update the opentelemetry-proto version to the new tag:

bazel_dep(name = "opentelemetry-proto", version = "1.3.2", repo_name = "com_github_opentelemetry_proto")

File MODULE.bazel is used in the github CI for repository opentelemetry-cpp, so using a tag that does not exist (yet) in bazel central will break the CI build.

See the known issues section.

Typical change:

[malff@malff-desktop opentelemetry-cpp]$ git diff MODULE.bazel
diff --git a/MODULE.bazel b/MODULE.bazel
index 7b84c2b7..3161ffb1 100644
--- a/MODULE.bazel
+++ b/MODULE.bazel
@@ -13,7 +13,7 @@ bazel_dep(name = "bazel_skylib", version = "1.5.0")
 bazel_dep(name = "curl", version = "8.4.0")
 bazel_dep(name = "grpc", version = "1.62.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.3.1", repo_name = "com_github_opentelemetry_proto")
+bazel_dep(name = "opentelemetry-proto", version = "1.3.2", 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.2.4", repo_name = "com_github_jupp0r_prometheus_cpp")

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Maintaining dependencies

Overview

opentelemetry-proto

Comments (opentelemetry-proto)

Origin (opentelemetry-proto)

Upgrade (opentelemetry-proto)

directory third_party/opentelemetry-proto

file third_party_release

file cmake/opentelemetry-proto.cmake

semantic-conventions and weaver

Comments (semantic-conventions)

Origin (semantic-conventions)

Upgrade (semantic-conventions)

file buildscripts/semantic-convention/generate.sh

Known issues (semantic-conventions)

prometheus-cpp

Comments (prometheus-cpp)

Origin (prometheus-cpp)

Upgrade (prometheus-cpp)

Directory `third_party/prometheus-cpp`

Upgrade a git submodule

Get current tag

Upgrade to new tag

Add changes

Upgrade a bazel dependency

Update MODULE.bazel

FilesExpand file tree

maintaining-dependencies.md

Latest commit

History

maintaining-dependencies.md

File metadata and controls

Maintaining dependencies

Overview

opentelemetry-proto

Comments (opentelemetry-proto)

Origin (opentelemetry-proto)

Upgrade (opentelemetry-proto)

directory third_party/opentelemetry-proto

file third_party_release

file cmake/opentelemetry-proto.cmake

semantic-conventions and weaver

Comments (semantic-conventions)

Origin (semantic-conventions)

Upgrade (semantic-conventions)

file buildscripts/semantic-convention/generate.sh

Known issues (semantic-conventions)

prometheus-cpp

Comments (prometheus-cpp)

Origin (prometheus-cpp)

Upgrade (prometheus-cpp)

Directory third_party/prometheus-cpp

Upgrade a git submodule

Get current tag

Upgrade to new tag

Add changes

Upgrade a bazel dependency

Update MODULE.bazel

Directory `third_party/prometheus-cpp`