Generate a Client Trace ID to Troubleshoot Non-Pub/Sub API Errors

To help with troubleshooting errors that don’t originate from Pub/Sub API and don’t include the RPC ID, add the x-client-trace-id metadata to every RPC request that the client makes to Pub/Sub API as part of the authorization headers.

Some gRPC exception errors that Pub/Sub API returns don’t originate from the Pub/Sub API service, such as network errors or errors returned from the data center infrastructure. These gRPC exceptions don’t have an RPC ID value in the error message or the rpc-id field in the exception trailer because Pub/Sub API adds the RPC ID only to errors it generates. It doesn’t add the RPC ID to errors that an external source returns. The RPC ID helps Salesforce Customer Support with tracing a request and troubleshooting the error. To help with troubleshooting errors that don’t contain an RPC ID, the client can add the x-client-trace-id metadata with a generated unique ID.

Here are some examples of gRPC exceptions that don’t contain an RPC ID. These errors aren’t listed in Error Codes because they aren’t generated by Pub/Sub API.

gRPC Status CodeError Message
UNAVAILABLEHttp2StreamException: The HTTP/2 server reset the stream. HTTP/2 error code
UNAVAILABLEThis application is down for maintenance

With the x-client-trace-id metadata value present in every request, it’s possible to trace the request from the client to the Pub/Sub API service without the RPC ID value. When an error occurs, you can contact Salesforce Customer Support and provide the x-client-trace-id and timestamp for the failed request. Salesforce can use this information for debugging purposes.

Here are the steps to add the x-client-trace-id metadata header to each RPC request.

  1. Create a client interceptor that adds a unique x-client-trace-id to the metadata headers. The client interceptor also logs the start and end of the request. Clients can use this information to trace the x-client-trace-id for each request and provide this information to Salesforce Customer Support when needed. To learn more about interceptors, see Interceptors in the gRPC Docs. For an example implementation in the sample pub-sub-api Java client, see XClientTraceIdClientInterceptor.java in GitHub.
  2. Configure the gRPC channel to go through the client interceptor that you created so that each request has a unique x-client-trace-id. For an example implementation in the sample pub-sub-api Java client, see CommonContext() in CommonContext.java in GitHub.

The types of errors that originate from an external source are typically transient. When a client catches these errors, we recommend that it retries the RPC method with exponential backoff.

See Also