Merge pull request #7134 from NomicFoundation/refactor-sentry-reporter

Refactor sentry reporter

Author: kanej

v-next/hardhat/src/cli.ts

@@ -23,6 +23,5 @@ function isTsxRequired(): boolean {
   return true;
 }
 
-main(process.argv.slice(2), { registerTsx: isTsxRequired() }).catch(() => {
-  process.exitCode = 1;
-});
+// eslint-disable-next-line no-restricted-syntax -- We do want TLA here
+await main(process.argv.slice(2), { registerTsx: isTsxRequired() });

v-next/hardhat/src/internal/cli/main.ts

@@ -37,7 +37,11 @@ import { printErrorMessages } from "./error-handler.js";
 import { getGlobalHelpString } from "./help/get-global-help-string.js";
 import { getHelpString } from "./help/get-help-string.js";
 import { sendTaskAnalytics } from "./telemetry/analytics/analytics.js";
-import { sendErrorTelemetry } from "./telemetry/sentry/reporter.js";
+import {
+  sendErrorTelemetry,
+  setCliHardhatConfigPath,
+  setupErrorTelemetryIfEnabled,
+} from "./telemetry/sentry/reporter.js";
 import { printVersionMessage } from "./version.js";
 
 export interface MainOptions {
@@ -50,6 +54,7 @@ export async function main(
   rawArguments: string[],
   options: MainOptions = {},
 ): Promise<void> {
+  await setupErrorTelemetryIfEnabled();
   const print = options.print ?? console.log;
 
   const log = debug("hardhat:core:cli:main");
@@ -86,6 +91,8 @@ export async function main(
       builtinGlobalOptions.configPath,
     );
 
+    setCliHardhatConfigPath(configPath);
+
     const projectRoot = await resolveProjectRoot(configPath);
 
     const esmErrorPrinted = await printEsmErrorMessageIfNecessary(
@@ -198,7 +205,7 @@ export async function main(
 
     if (error instanceof Error) {
       try {
-        await sendErrorTelemetry(error, configPath);
+        await sendErrorTelemetry(error);
       } catch (e) {
         log("Couldn't report error to sentry: %O", e);
       }

v-next/hardhat/src/internal/cli/telemetry/sentry/anonymizer.ts

@@ -1,4 +1,11 @@
-import type { Event, Exception, StackFrame, Stacktrace } from "@sentry/core";
+import type {
+  Envelope,
+  Event,
+  EventItem,
+  Exception,
+  StackFrame,
+  Stacktrace,
+} from "@sentry/core";
 
 import * as path from "node:path";
 
@@ -18,12 +25,18 @@ import * as simplifiedChinese from "ethereum-cryptography/bip39/wordlists/simpli
 import * as SPANISH from "ethereum-cryptography/bip39/wordlists/spanish.js";
 import * as traditionalChinese from "ethereum-cryptography/bip39/wordlists/traditional-chinese.js";
 
+import { GENERIC_SERVER_NAME } from "./constants.js";
+
 interface WordMatch {
   index: number;
   word: string;
 }
 
-export type AnonymizeResult =
+export type AnonymizeEnvelopeResult =
+  | { success: true; envelope: Envelope }
+  | { success: false; error: string };
+
+export type AnonymizeEventResult =
   | { success: true; event: Event }
   | { success: false; error: string };
 
@@ -39,25 +52,47 @@ export class Anonymizer {
     this.#configPath = configPath;
   }
 
+  /**
+   * Anonymizes the events in the envelope in place, modifying the envelope.
+   */
+  public async anonymizeEventsFromEnvelope(
+    envelope: Envelope,
+  ): Promise<AnonymizeEnvelopeResult> {
+    for (const item of envelope[1]) {
+      if (item[0].type === "event") {
+        /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions 
+          -- We know that the item is an event item */
+        const eventItem = item as EventItem;
+
+        const anonymizedEvent = await this.anonymizeEvent(eventItem[1]);
+        if (anonymizedEvent.success) {
+          eventItem[1] = anonymizedEvent.event;
+        } else {
+          return { success: false, error: anonymizedEvent.error };
+        }
+      }
+    }
+
+    return { success: true, envelope };
+  }
+
   /**
    * Given a sentry serialized exception
    * (https://develop.sentry.dev/sdk/event-payloads/exception/), return an
    * anonymized version of the event.
    */
-  public async anonymize(event: any): Promise<AnonymizeResult> {
-    if (event === null || event === undefined) {
-      return { success: false, error: "event is null or undefined" };
-    }
-    if (typeof event !== "object") {
-      return { success: false, error: "event is not an object" };
-    }
-
+  public async anonymizeEvent(event: Event): Promise<AnonymizeEventResult> {
     const result: Event = {
       event_id: event.event_id,
       platform: event.platform,
-      release: event.release,
       timestamp: event.timestamp,
       extra: event.extra,
+      release: event.release,
+      contexts: event.contexts,
+      sdk: event.sdk,
+      level: event.level,
+      server_name: GENERIC_SERVER_NAME,
+      environment: event.environment,
     };
 
     if (event.exception !== undefined && event.exception.values !== undefined) {
@@ -244,6 +279,7 @@ export class Anonymizer {
   async #anonymizeException(value: Exception): Promise<Exception> {
     const result: Exception = {
       type: value.type,
+      mechanism: value.mechanism,
     };
 
     if (value.value !== undefined) {

v-next/hardhat/src/internal/cli/telemetry/sentry/constants.ts

@@ -0,0 +1 @@
+export const GENERIC_SERVER_NAME = "<server-name>";

v-next/hardhat/src/internal/cli/telemetry/sentry/init.ts

@@ -1,118 +1,146 @@
 /* This file is inspired by https://github.com/getsentry/sentry-javascript/blob/9.4.0/packages/node/src/sdk/index.ts */
 
 import type {
-  BaseTransportOptions,
-  Integration,
+  Client,
   ServerRuntimeClientOptions,
   Transport,
 } from "@sentry/core";
 
+import os from "node:os";
+import path from "node:path";
+
 import {
   createStackParser,
   functionToStringIntegration,
-  getIntegrationsToSetup,
   initAndBind,
   linkedErrorsIntegration,
   nodeStackLineParser,
-  requestDataIntegration,
   ServerRuntimeClient,
   stackParserFromStackParserOptions,
 } from "@sentry/core";
+import debug from "debug";
 
-import { getHardhatVersion } from "../../../utils/package.js";
-
-import { onUncaughtExceptionIntegration } from "./integrations/onuncaughtexception.js";
-import { onUnhandledRejectionIntegration } from "./integrations/onunhandledrejection.js";
+import { GENERIC_SERVER_NAME } from "./constants.js";
 import { nodeContextIntegration } from "./vendor/integrations/context.js";
 import { contextLinesIntegration } from "./vendor/integrations/contextlines.js";
 import { createGetModuleFromFilename } from "./vendor/utils/module.js";
 
-interface InitOptions {
+const log = debug("hardhat:core:sentry:init");
+
+interface GlobalCustomSentryReporterOptions {
+  /**
+   * Sentry's DSN
+   */
   dsn: string;
-  transport: (transportOptions: BaseTransportOptions) => Transport;
-  release?: string;
-  serverName?: string;
-  integrations?: (integrations: Integration[]) => Integration[];
+
+  /**
+   * The environment used to report the events
+   */
+  environment: string;
+
+  /**
+   * The release of Hardhat
+   */
+  release: string;
+
+  /**
+   * A transport that customizes how we send envelopes to Sentry's server.
+   *
+   * See the transport module for the different options.
+   */
+  transport: Transport;
+
+  /**
+   * If `true`, the global unhandled rejection and uncaught exception handlers
+   * will be installed.
+   */
+  installGlobalHandlers?: boolean;
 }
 
 /**
- * Initialize Sentry for Node, without performance instrumentation.
+ * This function initializes a custom global sentry reporter/client.
+ *
+ * There are two reasons why we customize it, instead of using the default one
+ * provided by @sentry/node:
+ *   - @sentry/node has an astronomical amount of dependencies -- See https://github.com/getsentry/sentry-javascript/discussions/13846
+ *   - We customize the transport to avoid blocking the main Hardhat process
+ *     while reporting errors.
+ *
+ * Once you initialize the custom global sentry reporter, you can use the usual
+ * `captureException` and `captureMessage` functions exposed by @sentry/core.
+ *
+ * The reason that this uses the global instance of sentry (by calling
+ * initAndBind), is that using the client directly doesn't work with the linked
+ * errors integration.
+ *
+ * Calling `init` also has an option to set global unhandled rejection and
+ * uncaught exception handlers.
  */
-export async function init(options: InitOptions): Promise<void> {
-  const stackParser = stackParserFromStackParserOptions(
-    createStackParser(nodeStackLineParser(createGetModuleFromFilename())),
+export function init(options: GlobalCustomSentryReporterOptions): void {
+  const client = initAndBind<ServerRuntimeClient, ServerRuntimeClientOptions>(
+    ServerRuntimeClient,
+    {
+      dsn: options.dsn,
+      environment: options.environment,
+      serverName: GENERIC_SERVER_NAME,
+      release: options.release,
+      initialScope: {
+        contexts: {
+          os: {
+            name: os.type(),
+            build: os.release(),
+            version: os.version(),
+          },
+          device: {
+            arch: os.arch(),
+          },
+          runtime: {
+            name: path.basename(process.title),
+            version: process.version,
+          },
+        },
+      },
+      transport: () => options.transport,
+      integrations: [
+        functionToStringIntegration(),
+        contextLinesIntegration(),
+        linkedErrorsIntegration(),
+        nodeContextIntegration(),
+      ],
+      platform: process.platform,
+      stackParser: stackParserFromStackParserOptions(
+        createStackParser(nodeStackLineParser(createGetModuleFromFilename())),
+      ),
+    },
   );
 
-  // NOTE: We do not include most of the default integrations @sentry/node does
-  // because in the main hardhat process, we don't use the default integrations
-  // at all, and they're of limited use in the context of a reporter subprocess.
-  const integrationOptions = {
-    defaultIntegrations: [
-      // Inbound filters integration filters out events (errors and transactions) mainly based on init inputs we never use
-      // Import from @sentry/core if needed
-      // inboundFiltersIntegration(),
-
-      functionToStringIntegration(),
-      linkedErrorsIntegration(),
-      requestDataIntegration(),
-
-      // Native Wrappers
-      // Console integration captures console logs as breadcrumbs
-      // Vendor https://github.com/getsentry/sentry-javascript/blob/9.4.0/packages/node/src/integrations/console.ts if needed
-      // consoleIntegration(),
-
-      // HTTP integration instruments the http(s) modules to capture outgoing requests and attach them as breadcrumbs/spans
-      // Vendor https://github.com/getsentry/sentry-javascript/blob/9.4.0/packages/node/src/integrations/http/index.ts if needed
-      // httpIntegration(),
-
-      // Native Node Fetch integration instruments the native node fetch module to capture outgoing requests and attach them as breadcrumbs/spans
-      // Vendor https://github.com/getsentry/sentry-javascript/blob/9.4.0/packages/node/src/integrations/node-fetch/index.ts if needed
-      // nativeNodeFetchIntegration(),
-
-      // Global Handlers
-      onUncaughtExceptionIntegration(),
-      onUnhandledRejectionIntegration(),
-
-      // Event Info
-      contextLinesIntegration(),
-      nodeContextIntegration(),
-
-      // Local variables integrations adds local variables to exception frames
-      // Vendor https://github.com/getsentry/sentry-javascript/blob/9.4.0/packages/node/src/integrations/local-variables/local-variables-async.ts if needed
-      // localVariablesIntegration(),
-
-      // Child process integration captures child process/worker thread events as breadcrumbs
-      // Vendor https://github.com/getsentry/sentry-javascript/blob/9.4.0/packages/node/src/integrations/childProcess.ts if needed
-      // childProcessIntegration(),
-
-      // Records a session for the current process to track release health
-      // Vendor https://github.com/getsentry/sentry-javascript/blob/9.4.0/packages/node/src/integrations/processSession.ts if needed
-      // processSessionIntegration(),
-
-      // CommonJS Only
-      // Vendor https://github.com/getsentry/sentry-javascript/blob/9.4.0/packages/node/src/integrations/modules.ts if needed
-      // modulesIntegration(),
-    ],
-    integrations: options.integrations,
-  };
-
-  const clientOptions: ServerRuntimeClientOptions = {
-    sendClientReports: true,
-    ...options,
-    platform: "node",
-    runtime: {
-      name: "node",
-      version: process.version,
-    },
-    stackParser,
-    integrations: getIntegrationsToSetup(integrationOptions),
-    _metadata: {
-      sdk: {
-        name: "hardhat",
-        version: await getHardhatVersion(),
+  setupGlobalUnhandledErrorHandlers(client);
+}
+
+function setupGlobalUnhandledErrorHandlers(client: Client) {
+  log("Setting up global unhandled error handlers");
+
+  async function listener(error: Error | unknown) {
+    log("Uncaught exception", error);
+
+    client.captureException(error, {
+      captureContext: {
+        level: "fatal",
       },
-    },
-  };
+      mechanism: {
+        handled: false,
+        type: "onuncaughtexception",
+      },
+    });
+
+    await client.flush(100);
+    await client.close(100);
+
+    console.error("Unexpected error encountered:\n");
+    console.error(error);
+    process.exit(1);
+  }
 
-  initAndBind(ServerRuntimeClient, clientOptions);
+  process.on("uncaughtException", listener);
+  process.on("unhandledRejection", listener);
 }