Stability for the `WITH_OTLP_RETRY_PREVIEW` flag

[tusharg1993]

Hello, we are using opentelemetry-cpp sdk internally, and were seeing issues due to network communication issues with grpc exporter.

I came across the compile time flag WITH_OTLP_RETRY_PREVIEW which should allow the grpc retries to alleviate some of the temporary retries and the associated #3481 about enabling it by default. I see that support was added a while ago but cmake sets it to false by default [cite]. Are there any plans to enable it?

The issue with the compile time flag is that it can not be dynamically enabled/disabled in the production for the compile binary if there are associated issues with the same.

[marcalff]

WITH_OTLP_RETRY_PREVIEW is a PREVIEW flag, meaning that the feature behind it is opt-in.

Typically, the process for some new feature to mature is as follows.

Step 1, WITH_OTLP_RETRY_PREVIEW is OFF by default

This is a compile time flag in CMake, default is Off.

Users not changing anything in their build do not see the feature, to use it the CMake command must enable it explicitly.

Step 2, WITH_OTLP_RETRY_PREVIEW is ON by default

This is the next step, where the feature is available by default, with a compile time option to not use it.

Users not changing anything in their build do see the feature, to not use it the CMake command must disable it explicitly.

Once the feature is compiled in, depending on what the feature is, there might be runtime settings associated with it.

In this case:

OtlpGrpcClientOptions contains members like:

• OtlpGrpcClientOptions::retry_policy_max_attempts
• OtlpGrpcClientOptions::retry_policy_initial_backoff
• OtlpGrpcClientOptions::retry_policy_max_backoff
• OtlpGrpcClientOptions::retry_policy_backoff_multiplier

When initializing a OTLP GRPC exporter:

• providing retry_policy_max_attempts = 0 will disable the retry feature,
• providing retry_policy_max_attempts != 0, as well as related retry_policy_* attributes, will enable the retry feature.

so the application can decide whether to use this or not, at sdk configuration time.

Step 3, WITH_OTLP_RETRY_PREVIEW is removed

The PREVIEW option is no longer a compile flag, the feature is always available in the binary.

Whether the retry is done depends on the retry options provided at sdk initialization time.

---

Currently, WITH_OTLP_RETRY_PREVIEW stands at the first step, with issue #3481 to resolve to progress to step 2 (compiled in by default), to be followed by another change later to drop the preview flag and reach step 3, where the code is mature and no longer optional.

The progression path is on purpose slow and cautious, to avoid introducing instability.

Nothing prevents an application today to build with WITH_OTLP_RETRY_PREVIEW=ON and use the feature at runtime or not, depending on the grpc exporter options provided.

[marcalff]

The original retry implementation was introduced in:

• [EXPORTER] Support handling retry-able errors for OTLP/gRPC #3219 for OTLP GRPC
• [EXPORTER] Support handling retry-able errors for OTLP/HTTP #3223 for OTLP HTTP

both implemented in December 2024, with no known issues reported, so it seems the time has come to enable this by default and consider the feature mature.

[tusharg1993]

Thanks for the detailed response @marcalff!

When initializing a OTLP GRPC exporter:

• providing retry_policy_max_attempts = 0 will disable the retry feature,
• providing retry_policy_max_attempts != 0, as well as related retry_policy_* attributes, will enable the retry feature.

This is exactly what I was looking for. To begin with, for our internal usecases, we will start compiling with WITH_OTLP_RETRY_PREVIEW and start using the retry_policy_max_attempts to do a slow rollout.

both implemented in December 2024, with no known issues reported, so it seems the time has come to enable this by default and consider the feature mature.

+1. I would agree with this. In general, that increases the robustness and reliability of metric emission via gRPC/HTTP.

[svrnm]

Would it make sense to call this out in documentation? Most end users need to compile the c++ sdk and can not rely on prebuilt packages so having that 3 steps mentioned somewhere could be a helpful addition? Or if that already exists point from docs to the respective doc in the c++ repo

[marcalff]

Would it make sense to call this out in documentation? Most end users need to compile the c++ sdk and can not rely on prebuilt packages so having that 3 steps mentioned somewhere could be a helpful addition? Or if that already exists point from docs to the respective doc in the c++ repo

These "3 steps" are just how internally a feature matures, what we need to do is mark this feature as stable to reduce complexity and combinations, not document why there are so many combinations.

[svrnm]

Would it make sense to call this out in documentation? Most end users need to compile the c++ sdk and can not rely on prebuilt packages so having that 3 steps mentioned somewhere could be a helpful addition? Or if that already exists point from docs to the respective doc in the c++ repo

These "3 steps" are just how internally a feature matures, what we need to do is mark this feature as stable to reduce complexity and combinations, not document why there are so many combinations.

I was not suggesting this for this or any particular feature, but call out somewhere that WITH__PREVIEW follows this pattern, and people are encouraged to use them and report back?

[marcalff]

Closing, duplicate of #3953