Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[GcpObservability C++] Backport: De-experimentalize API (#32715) #32813

Merged
merged 1 commit into from
Apr 5, 2023

Conversation

yashykt
Copy link
Member

@yashykt yashykt commented Apr 5, 2023

This PR aims to de-experimentalize the APIs for GCP Observability.

We would have ideally wanted public feedback before declaring the APIs stable, but we need stable APIs for GA.

Changes made after API review with @markdroth @veblush, @ctiller and the entire Core/C++ team -

  • The old experimental APIs grpc::experimental::GcpObservabilityInit and grpc::experimental::GcpObservabilityClose are now deprecated and will be deleted after v.1.55 release.
  • The new API gets rid of the Close method and follows the RAII idiom with a single grpc::GcpObservability::Init() call that returns an GcpObservability object, the lifetime of which controls when observability data is flushed.
  • The GcpObservability class could in the future add more methods. For example, a debug method that shows the current configuration.
  • Document that GcpObservability initialization and flushing (on GcpObservability destruction) are blocking calls.
  • Document that gRPC is still usable if GcpObservability initialization failed. (Added a test to prove the same).
  • Since we don't have a good way to flush stats and tracing with OpenCensus, the examples required users to sleep for 25 seconds. This sleep is now part of GcpObservability destruction.

Additional Implementation details -

  • GcpObservability::Init is now marked with GRPC_MUST_USE_RESULT to make sure that the results are used. We ideally want users to store it, but this is better than nothing.
  • Added a note on GCP Observability lifetime guarantees.

This PR aims to de-experimentalize the APIs for GCP Observability. 

We would have ideally wanted public feedback before declaring the APIs
stable, but we need stable APIs for GA.

Changes made after API review with @markdroth @veblush, @ctiller and the
entire Core/C++ team -
* The old experimental APIs `grpc::experimental::GcpObservabilityInit`
and `grpc::experimental::GcpObservabilityClose` are now deprecated and
will be deleted after v.1.55 release.
* The new API gets rid of the Close method and follows the RAII idiom
with a single `grpc::GcpObservability::Init()` call that returns an
`GcpObservability` object, the lifetime of which controls when
observability data is flushed.
* The `GcpObservability` class could in the future add more methods. For
example, a debug method that shows the current configuration.
* Document that GcpObservability initialization and flushing (on
`GcpObservability` destruction) are blocking calls.
* Document that gRPC is still usable if GcpObservability initialization
failed. (Added a test to prove the same).
* Since we don't have a good way to flush stats and tracing with
OpenCensus, the examples required users to sleep for 25 seconds. This
sleep is now part of `GcpObservability` destruction.

Additional Implementation details -
* `GcpObservability::Init` is now marked with `GRPC_MUST_USE_RESULT` to
make sure that the results are used. We ideally want users to store it,
but this is better than nothing.
* Added a note on GCP Observability lifetime guarantees.

<!--

If you know who should review your pull request, please assign it to
that
person, otherwise the pull request would get assigned randomly.

If your pull request is for a specific language, please add the
appropriate
lang label.

-->
@yashykt yashykt changed the title Backport: [GcpObservability C++] De-experimentalize API (#32715) [GcpObservability C++] Backport: De-experimentalize API (#32715) Apr 5, 2023
@yashykt yashykt added the release notes: yes Indicates if PR needs to be in release notes label Apr 5, 2023
@yashykt yashykt merged commit 4bf3c5d into grpc:v1.54.x Apr 5, 2023
11 of 12 checks passed
@yashykt yashykt deleted the Backport32715To154 branch May 18, 2023 20:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

2 participants