Sentry(v20.12.1) K8S 云原生架构探索，SENTRY FOR JAVASCRIPT Source Maps详解（二）

Troubleshooting

Source maps 有时可能很难上手。如果您遇到问题：

Verify a release is configured in your SDK

要定位和应用已上传的 source maps，需要通过 CLI 或 API 创建 release(以及上传的正确 artifacts)，并且需要在 SDK 配置中指定新创建的 release 的名称。

要验证这一点，请从 Sentry UI 打开 issue 并检查是否配置了 release。如果屏幕右侧的 Release 旁边显示 "not configured" 或 "N/A"（或如果你没有看到一个 release 标签在标签列表），则需要返回并 tag your errors。如果设置正确，您将看到 "Release: my_example_release"。

Verify artifacts are uploaded

一旦您的 release 被正确配置并且问题被标记，您可以通过导航到 [Project] » Project Settings » Source Maps 来找到上传到 Sentry 的工件（artifacts）。

此外，请确保所有必要的文件都可用。为了让 Sentry 去 de-minify 你的堆栈跟踪，您必须同时提供两个压缩的文件（例如，app.min.js)以及相应的 source maps。如果 source map 文件不包含原始 source code（sourcesContent），则必须另外提供原始 source code。或者，sentry-cli 会自动将源代码（如果缺少）嵌入到 source maps 中。

Verify sourceMappingURL is present

一些 CDN 自动从静态文件(包括 JavaScript 文件)中删除注释。这可能会导致 JavaScript 文件中没有 sourceMappingURL 指令，因为它被视为注释。例如，CloudFlare 有一个名为 Auto-Minify 的功能，如果它被启用，它将剥离 sourceMappingURL。

仔细检查部署的最终 JavaScript 文件是否有 sourceMappingURL。

或者，您可以在压缩的文件上设置 SourceMap HTTP header，而不是 sourceMappingURL。如果存在此标头，Sentry 将使用它来发现 source map 的位置。

Verify artifact names match sourceMappingURL value

bundled 或 minified 的 JavaScript 文件的最后一行的 sourceMappingURL 注释告诉Sentry（或浏览器）在哪里找到相应的 source map。这可以是绝对的 URL，相对路径或文件名本身。将工件（artifacts）上传到 Sentry 时，必须使用文件解析到的值来命名 source map 文件。

也就是说，如果你的文件类似于：

// -- end script.min.js
//# sourceMappingURL=script.min.js.map

并托管在 http://example.com/js/script.min.js 上，然后 Sentry 将在 http://example.com/js/script.min.js.map 上查找 source map 文件。因此，您上传的工件（artifact）必须命名为 http://example.com/js/script.min.js.map (或 ~/js/script.min.js.map)。

或者，如果你的文件类似于：

//-- end script.min.js
//# sourceMappingURL=https://example.com/dist/js/script.min.js.map

然后你上传的工件（artifact）也应该命名为 https://example.com/dist/js/script.min.js.map (或者 ~/dist/js/script.min.js.map )。

最后，如果你的文件类似于：

//-- end script.min.js
//# sourceMappingURL=../maps/script.min.js.map

然后你上传的工件应该命名为 https://example.com/dist/maps/script.min.js.map (或者 ~/dist/maps/script.min.js.map)。

Verify artifact names match stack trace frames

如果您上传了 source maps，但它们没有应用到 Sentry 中的某个 issue 中的代码中，请查看事件的 JSON 并查找 abs_path，以查看我们试图解析文件的确切位置 — 例如，http://localhost:8000/scripts/script.js（对于堆栈跟踪中的每一帧，abs_path 将出现一次 - 将其与未被非 deminified 的文件匹配。）。在事件发生日期旁边的 issue 页面顶部可以找到一个指向 JSON 视图的链接。上载的工件名称（uploaded artifact names）必须与这些值匹配。

如果您的 dynamic values in your path（路径中有动态值）（例如：https://www.site.com/{some_value}/scripts/script.js），则可能需要使用 rewriteFrames integration 来更改 abs_path 值。

Using sentry-cli

如果您的 sourceMappingURL 注释类似于：

// -- end script.min.js (located at http://localhost:8000/scripts/script.min.js)
//# sourceMappingURL=script.min.js.map

正确上传这些文件的示例，sentry-cli 命令如下所示（假设您位于 /scripts 目录中，并从一个更高的目录运行 Web 服务器，这就是为什么我们使用 --url-prefix 选项）：

sentry-cli releases files VERSION upload-sourcemaps . --url-prefix '~/scripts'

此命令上传当前目录中的所有 JavaScript 文件。Sentry 中的 Artifacts 页面现在应如下所示：

~/scripts/script.js
~/scripts/script.min.js
~/scripts/script.min.js.map

或者，您可以指定要上传的文件。例如：

sentry-cli releases files VERSION upload-sourcemaps script.min.js script.min.js.map --url-prefix '~/scripts'

您也可以使用绝对 URL 上传它。例如：

sentry-cli releases files VERSION upload-sourcemaps . --url-prefix 'http://localhost:8000/scripts'

Using the API

您也可以使用我们的API 来上传工件，遵循这里解释的相同命名约定。

curl -X POST \
  https://sentry.io/api/0/organizations/ORG_SLUG/releases/VERSION/files/ \
  -H 'Authorization: Bearer AUTH_TOKEN' \
  -H 'content-type: multipart/form-data' \
  -F file=@script.min.js.map \
  -F 'name=~/scripts/script.min.js.map'

Using the ~

~ 在 Sentry 中用于替换 scheme 和 domain。这不是一个问题！

http://example.com/dist/js/script.js 将匹配 ~/dist/js/script.js 或 http://example.com/dist/js/script.js

但是将不匹配 ~/script.js。

Verify artifacts are uploaded before errors occur

Sentry 希望在某个 release 中出现错误之前，将 source code 和 source maps 上传到 Sentry。

如果您在 Sentry 捕获错误之后上传工件，Sentry 将不会返回并追溯地对这些错误应用任何源注释。只有在工件上传后触发的新错误才会受到影响。

Verify your source maps are built correctly

我们维护了一个在线验证工具，可以用来测试您的 source maps 与 hosted（托管） 源：https://sourcemaps.io。

另外，如果你正在使用 Sentry CLI 上传 source maps 到 Sentry，你可以使用 --validate 命令行选项来验证你的 source maps 是否正确。

Verify your source maps work locally

如果发现 Sentry 没有正确映射文件名，行或列映射，则应验证 source maps 是否在本地运行。为此，您可以将 Node.js 与Mozilla 的 source-map library 一起使用。

首先，将 source-map 作为 npm 模块全局安装：

npm install -g source-map

然后，编写一个脚本，该脚本读取您的 source map 文件并测试映射。这是一个例子：

var fs = require("fs"),
  path = require("path"),
  sourceMap = require("source-map");
// file output by Webpack, Uglify, and so forth
var GENERATED_FILE = path.join(".", "app.min.js.map");
// line and column located in your generated file (for example, the source of your error
// from your minified file)
var GENERATED_LINE_AND_COLUMN = { line: 1, column: 1000 };
var rawSourceMap = fs.readFileSync(GENERATED_FILE).toString();
new sourceMap.SourceMapConsumer(rawSourceMap).then(function(smc) {
  var pos = smc.originalPositionFor(GENERATED_LINE_AND_COLUMN);
  // should see something like:
  // { source: 'original.js', line: 57, column: 9, name: 'myfunc' }
  console.log(pos);
});

如果您通过 Sentry 在本地获得相同（不正确）的结果，请仔细检查您的 source map 生成配置。

Verify your source files are not too large

对于单个 artifact，Sentry 接受的最大文件大小为 40 MB。

用户通常会达到此限制，因为他们在临时构建阶段传输源文件。例如，在 Webpack/Browserify 合并所有源文件之后，但在压缩之前。如果可能，请发送原始源文件。

Verify artifacts are not gzipped

Sentry API 当前仅适用于以纯文本（UTF-8 编码）上传的 source maps 和 source files。如果文件以压缩格式（例如 gzip）上传，则将无法正确解释它们。

这种情况有时会发生在生成预压缩小文件的构建脚本和插件中。例如，Webpack 的压缩插件。您需要禁用这些插件，并在将生成的 source maps/source files 上传到 Sentry 后执行压缩。

Verify workers are sharing the same volume as web (if running as docker on premise)

Sentry 在其 workers 中进行 source map 计算。这意味着 workers 需要访问通过前端上传的文件。仔细检查 cron workers 和 web workers 是否可以从同一个磁盘读/写文件。

Uploading Source Maps

我们建议将上传 source maps 作为构建过程的一部分，但您也可以将它们与源文件一起公开提供。

建议的上传 source maps 的方法是使用 sentry-cli。如果您使用 Sentry Wizard 来设置项目，则它已经创建了所有必要的配置以上传 source maps。否则，请遵循 CLI 配置文档来设置您的项目。

您需要设置构建系统以创建 release 并附加各种源文件。为了使 Sentry 缩小堆栈跟踪的大小，必须同时提供缩小的文件（例如app.min.js）和相应的源映射。如果源映射文件不包含原始源代码（sourcesContent），则还必须提供原始源文件。另外，sentry-cli 将自动将源（如果缺少）嵌入到 source maps 中。

Sentry 使用 Releases 将正确的 source maps 与您的事件进行匹配。要创建新 release，请运行以下命令（例如，在发布期间）：

sentry-cli releases new <release_name>

release 名称必须是在您的组织内唯一的，并且与 SDK 初始化代码中的 release 选项匹配。然后，使用 upload-sourcemaps 命令扫描文件夹中的 source maps，进行处理并将其上传到 Sentry。

sentry-cli releases files <release_name> upload-sourcemaps /path/to/files

您可以通过导航找到上传到 Sentry 的工件：[Project] » Project Settings » Source Maps。

此命令会将所有以 .js 和 .map 结尾的文件上传到指定的 release。如果您想更改这些扩展名（例如，上传 typescript 源），请使用 --ext 选项：

sentry-cli releases files <release_name> upload-sourcemaps --ext ts --ext map /path/to/files

到目前为止，版本处于草稿状态（(“unreleased”)。一旦所有 source maps 都已上传，并且您的应用已成功发布，请使用以下命令完成 release：

sentry-cli releases finalize <release_name>

为了方便起见，您也可以将 --finalize flag 传递给 new 命令，该命令将立即完成 release。

你不必一定上传源文件(由 source maps 引用)，但是没有它们，分组算法就不会那么强大，UI 也不会显示任何上下文相关的源文件。

有关更多信息，请参阅我们 Releases API documentation。

web 应用程序可以从多个来源访问并不少见。请参阅我们关于如何处理此问题的多个来源的文档。

Validating Files

要确保 source maps 本身是有效的，并且正确上传，这可能是一个相当具有挑战性的问题。为了帮助实现这一点，我们维护了一个在线验证工具，可用于根据托管源测试源映射：https://sourcemaps.io。

此外，当使用 sentry-cli 上传源映射时，可以在中使用 --validate 标志，这将尝试本地解析源映射并查找引用。请注意，在某些已知情况下，当设置正确时，validate 标志将指示失败（如果您有对外部源映射的引用，则验证工具将指示失败）。

除了验证步骤之外，您还可以检查以下内容：

• 确保您的文件的 URL 前缀正确。这很容易出错。
  
• 为 minimized 的文件上传匹配的源映射。
  
• 确保服务器上的 minified 文件确实引用了您的文件。