[public-api] improve request exception logging

Author: akosyakov

components/dashboard/src/service/metrics.ts

@@ -71,6 +71,10 @@ export function reportError(...args: any[]) {
         }
     }
 
+    if (!err) {
+        return;
+    }
+
     let data = {};
     if (details && typeof details === "object") {
         data = Object.assign(
@@ -90,8 +94,9 @@ export function reportError(...args: any[]) {
             ),
         );
     }
-
-    if (err) {
-        metricsReporter.reportError(err, data);
+    if ("requestContext" in err && typeof err["requestContext"] === "object") {
+        data = Object.assign(data, err["requestContext"]);
     }
+
+    metricsReporter.reportError(err, data);
 }

components/dashboard/src/service/public-api.ts

@@ -197,15 +197,24 @@ function createServiceClient<T extends ServiceType>(
              * The original application error is retained using gRPC metadata to ensure that existing error handling remains intact.
              */
             function handleError(e: any): unknown {
+                let requestId = undefined;
                 if (e instanceof ConnectError) {
-                    throw converter.fromError(e);
+                    requestId = e.metadata.get("x-request-id") || undefined;
+                    e = converter.fromError(e);
                 }
+
+                Object.assign(e, {
+                    requestContext: {
+                        requestId,
+                        requestMethod: `${type.typeName}/${prop as string}`,
+                    },
+                });
                 throw e;
             }
             return (...args: any[]) => {
                 const method = type.methods[prop as string];
                 if (!method) {
-                    throw new ConnectError("unimplemented", Code.Unimplemented);
+                    handleError(new ConnectError("unimplemented", Code.Unimplemented));
                 }
 
                 // TODO(ak) default timeouts

components/public-api/typescript-common/README.md

@@ -1,5 +1,13 @@
 # Public API TypeScript Common
 
+## Overview
+
+This package serves as a bridge for code conversion between two distinct Gitpod packages: @gitpod/gitpod-protocol and @gitpod/public-api. Its primary responsibility is to ensure seamless translation of application data structures from the gitpod-protocol format to the public-api gRPC format, and vice versa.
+
+## Allowed Usage
+
+Use this package exclusively for tasks that require data structure from @gitpod/gitpod-protocol and @gitpod/public-api. It's important not to introduce dependencies on this package from gitpod-protocol or public-api to ensure changes in one package don't trigger rebuilds of unrelated components such as ws-manager-bridge and supervisor-frontend.
+
 ## Golden tests
 
 Golden tests are used to test the output of a function against a known good output. The output is stored in a file with the same name as the test file but with a `.golden` extension. The test will fail if the output does not match the golden file.

components/public-api/typescript-common/src/public-api-converter.spec.ts

@@ -481,14 +481,15 @@ describe("PublicAPIConverter", () => {
         });
 
         it("Any other error is internal", () => {
-            const error = new Error("unknown");
-            const connectError = converter.toError(error);
+            const reason = new Error("unknown");
+            const connectError = converter.toError(reason);
             expect(connectError.code).to.equal(Code.Internal);
-            expect(connectError.rawMessage).to.equal("unknown");
+            expect(connectError.rawMessage).to.equal("Oops! Something went wrong.");
+            expect(connectError.cause).to.equal(reason);
 
             const appError = converter.fromError(connectError);
             expect(appError.code).to.equal(ErrorCodes.INTERNAL_SERVER_ERROR);
-            expect(appError.message).to.equal("unknown");
+            expect(appError.message).to.equal("Oops! Something went wrong.");
         });
     });
 });

components/public-api/typescript-common/src/public-api-converter.ts

@@ -386,7 +386,7 @@ export class PublicAPIConverter {
             }
             return new ConnectError(reason.message, Code.Unknown, undefined, undefined, reason);
         }
-        return ConnectError.from(reason, Code.Internal);
+        return new ConnectError(`Oops! Something went wrong.`, Code.Internal, undefined, undefined, reason);
     }
 
     fromError(reason: ConnectError): ApplicationError {

components/server/src/api/server.ts

@@ -159,8 +159,10 @@ export class API {
             get(target, prop) {
                 return (...args: any[]) => {
                     const connectContext = args[1] as HandlerContext;
+                    const requestId = connectContext.requestHeader.get("x-request-id") || v4();
+                    connectContext.responseHeader.set("x-request-id", requestId);
                     const requestContext: RequestContextSeed = {
-                        requestId: v4(),
+                        requestId,
                         requestKind: "public-api",
                         requestMethod: `${grpc_service}/${prop as string}`,
                         startTime: performance.now(),
@@ -192,6 +194,9 @@ export class API {
                         grpc_type = "bidi_stream";
                     }
 
+                    const isException = (err: ConnectError) =>
+                        err.code === Code.Internal || err.code === Code.Unknown || err.code === Code.DataLoss;
+
                     grpcServerStarted.labels(grpc_service, grpc_method, grpc_type).inc();
                     const stopTimer = grpcServerHandling.startTimer({ grpc_service, grpc_method, grpc_type });
                     const done = (err?: ConnectError) => {
@@ -201,15 +206,9 @@ export class API {
                         log.debug("public api: done", { grpc_code });
                     };
                     const handleError = (reason: unknown) => {
-                        let err = self.apiConverter.toError(reason);
-                        if (reason != err && err.code === Code.Internal) {
-                            log.error("public api: unexpected internal error", reason);
-                            err = new ConnectError(
-                                `Oops! Something went wrong.`,
-                                Code.Internal,
-                                // pass metadata to preserve the application error
-                                err.metadata,
-                            );
+                        const err = self.apiConverter.toError(reason);
+                        if (isException(err)) {
+                            log.error("public api exception reason:", reason);
                         }
                         done(err);
                         throw err;