获取更多动态,关注公众号:黑客下午茶

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 文件。

也就是说,如果你的文件类似于:

Copied
// -- 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)。

或者,如果你的文件类似于:

Copied
//-- 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 )。

最后,如果你的文件类似于:

Copied
//-- 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 注释类似于:

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

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

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

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

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

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

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

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

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

Using the API

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

Copied
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.jshttp://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(托管) 源: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 模块全局安装:

Copied
npm install -g source-map

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

Copied
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 是否可以从同一个磁盘读/写文件。

You can edit this page on GitHub.