基本选项

了解如何配置 SDK。这些选项在 SDK 首次初始化时设置，并作为对象传递给 init 函数。

SDK 可以使用多种选项进行配置。这些选项在大多数 SDK 中是标准化的，但有一些差异以更好地适应平台的特殊性。选项在 SDK 首次初始化时设置。

选项作为可选的关键字参数传递给 init() 函数：

Copied

import sentry_sdk

sentry_sdk.init(
    dsn="https://examplePublicKey@o0.ingest.sentry.io/0",
    max_breadcrumbs=50,
    debug=True,
    enable_tracing=True,

    # By default the SDK will try to use the SENTRY_RELEASE
    # environment variable, or infer a git commit
    # SHA as release, however you may want to set
    # something more human-readable.
    # release="myapp@1.0.0",
)

跨 SDK 的常用选项列表。这些选项在大多数 SDK 中的工作方式大致相同，但为了更好地支持平台，可能存在一些细微的差异。可以从环境变量中读取的选项（如 SENTRY_DSN、SENTRY_ENVIRONMENT、SENTRY_RELEASE）会自动读取。

`dsn`

环境变量: SENTRY_DSN

DSN 告诉 SDK 将事件发送到哪里。如果未设置此选项，SDK 将不会发送任何数据。

dsn 配置选项优先于环境变量。

了解更多关于 DSN 利用。

`debug`

环境变量: SENTRY_DEBUG

启用或禁用调试模式。当设置为 True 时，SDK 将尝试打印调试信息。这在事件发送出现问题时很有用。默认值始终为 False。通常不建议在生产环境中启用，因为会增加日志输出。

debug 配置选项优先于环境变量。

`release`

环境变量: SENTRY_RELEASE

设置发布版本。如果未设置，SDK 将尝试自动配置一个发布版本，但最好手动设置以确保发布版本与部署集成同步。发布版本名称是字符串，但 Sentry 会检测某些格式并可能以不同的方式呈现。有关 SDK 如何自动配置发布版本的详细信息，请参阅发布版本文档。

release 配置选项优先于环境变量。

了解更多关于如何发送发布数据，以便 Sentry 可以告诉您不同发布版本之间的回归并识别潜在来源的信息，请参阅产品文档或沙箱。

`environment`

环境变量: SENTRY_ENVIRONMENT

设置环境。这是一个自由格式的字符串，默认值为 production。一个发布版本可以关联到多个环境，以便在 UI 中将它们分开（例如 staging 与 production 或类似环境）。

environment 配置选项优先于环境变量。

`dist`

应用程序的分发版本。分发版本用于区分同一应用程序发布版本的不同构建或部署变体。分发版本可以是例如构建号。

`sample_rate`

配置错误事件的采样率，范围为 0.0 到 1.0。默认值为 1.0，表示将发送 100% 的错误事件。如果设置为 0.1，则只发送 10% 的错误事件。事件是随机选择的。

`error_sampler`

动态配置每个事件的错误事件采样率。此配置选项接受一个函数，该函数接受两个参数（event 和 hint），并返回一个布尔值（指示是否将事件发送到 Sentry）或一个介于 0.0 和 1.0 之间的浮点数（包括 0.0 和 1.0，表示事件发送到 Sentry 的概率；SDK 将根据给定的概率随机决定是否发送事件）。

如果指定了此配置选项，则忽略 sample_rate 选项。

`max_breadcrumbs`

默认值为 100，但您可以将其设置为任何数字。然而，您应该注意 Sentry 有一个最大有效负载大小，任何超过该有效负载大小的事件将被丢弃。

`attach_stacktrace`

跟踪信息总是附加到异常；但是，当设置此选项时，堆栈跟踪也会与消息一起发送。例如，这意味着堆栈跟踪会出现在所有日志消息旁边。

此选项默认关闭。

Sentry 中带有堆栈跟踪和不带堆栈跟踪的事件分组方式不同。因此，当您为某些事件启用或禁用此标志时，会生成新的分组。

`send_default_pii`

活动集成的数据。默认情况下，不发送此类数据。

如果您在移动应用中使用 Sentry，请阅读我们的移动数据隐私常见问题，以协助处理 Apple App Store 和 Google Play 应用的隐私详情。

此选项默认关闭。

如果您启用此选项，请确保使用我们的敏感数据管理功能手动移除不想发送的数据。

`event_scrubber`

从事件负载中清除敏感信息（如 cookie、会话和密码）中的 denylist。如果 send_default_pii 被禁用，还可以从另一个 pii_denylist 中清除。请参阅如何配置清除器。

`include_source_context`

启用时，源上下文将包含在发送到 Sentry 的事件中。此源上下文包括错误发生代码行前后各五行代码。

此选项默认启用。

`include_local_variables`

启用时，SDK 将捕获本地变量的快照并随事件一起发送，以帮助调试。

此选项默认启用。

`add_full_stack`

在捕获错误时，Sentry 堆栈跟踪通常仅包含错误发生时的帧。但如果启用了 "add-full-stack" 选项（设置为 True），堆栈跟踪将包含从执行开始的所有帧。默认情况下，此选项设置为 False。

`max_stack_frames`

此选项限制在启用 add_full_stack 时捕获的堆栈帧数量。默认值为 100。

`server_name`

此选项可用于提供“服务器名称”。提供后，服务器名称将随事件一起发送并持久化。对于许多集成，服务器名称实际上对应于设备的主机名，即使该机器实际上不是服务器。

大多数 SDK 将尝试自动发现此值。

`project_root`

应用程序根目录的完整路径。默认值为 os.getcwd()。

project_root 用于标记堆栈跟踪中的帧是属于应用程序还是应用程序之外。

`in_app_include`

属于应用程序的模块名称字符串前缀列表。此选项优先于 in-app-exclude。

Sentry 区分直接与您的应用程序相关的堆栈帧（“在应用程序中”）和其他包（如标准库、框架或其他依赖项）的堆栈帧。应用程序包会自动标记为 inApp。差异在 sentry.io 中可见，默认情况下仅显示“在应用程序中”的帧。

`in_app_exclude`

不属于应用程序而是属于第三方包的模块名称字符串前缀列表。默认情况下，被视为不属于应用程序的模块将从堆栈跟踪中隐藏。

此选项可以使用 in_app_include 覆盖。

`max_request_body_size`

此参数控制集成是否应捕获 HTTP 请求正文。它可以设置为以下值之一：

never: 永不发送请求正文。
small: 仅捕获小请求正文。小请求正文的大小限制取决于 SDK（通常为 4KB）。
medium: 捕获中等和小请求正文（通常为 10KB）。
always: SDK 将始终捕获请求正文，只要 Sentry 能够理解它。

请注意，Sentry 服务器限制 HTTP 请求正文大小。服务器始终强制执行其大小限制，无论您如何配置此选项。

`max_value_length`

事件负载中包含文本的值在多少个字符后会被截断（默认为 1024）。

如果您设置的值非常大，事件可能会超过 1 MiB 并被 Sentry 丢弃。

`ca_certs`

PEM 格式的替代 CA 证书包文件的路径。

`send_client_reports`

将此布尔值设置为 False 以禁用发送客户端报告。客户端报告允许客户端向 Sentry 发送有关自身的状态报告，例如有关在发送之前被丢弃的事件的信息。

`integrations`

要启用的集成列表，除了自动启用的集成。此设置可以用于覆盖特定自动启用集成的默认配置选项，或添加未自动启用的集成。

`disabled_integrations`

要禁用的集成列表。此设置可以用于显式关闭特定的自动启用或默认集成。

`auto_enabling_integrations`

配置是否启用自动启用的集成。默认值为 True。

设置为 False 时，即使检测到相应的框架或库，也不会默认启用任何自动启用的集成。

`default_integrations`

配置是否启用默认集成。默认值为 True。

将 default_integrations 设置为 False 将禁用所有默认集成以及所有自动启用的集成，除非它们在上述 integrations 选项中显式添加。

这些选项可以用于以各种方式钩住 SDK 以自定义事件的报告。

`before_send`

此函数在发送 SDK 特定的消息或错误事件对象之前调用，可以返回一个修改后的事件对象，或返回 null 以跳过报告该事件。例如，可以在发送之前手动剥离 PII。

在执行 before_send 时，所有范围数据已应用于事件。进一步修改范围将不会有任何效果。

`before_send_transaction`

此函数在发送 SDK 特定的事务事件对象之前调用，可以返回一个修改后的事务事件对象，或返回 null 以跳过报告该事件。例如，可以在发送之前手动剥离 PII。

此函数在面包屑添加到范围之前调用，接收 SDK 特定的面包屑对象。如果函数未返回任何内容，则丢弃该面包屑。要传递面包屑，请返回第一个参数，其中包含面包屑对象。回调通常会接收第二个参数（称为“提示”），其中包含创建面包屑的原始对象，以便进一步自定义面包屑的外观。

传输用于将事件发送到 Sentry。传输可以进行一定程度的自定义，以更好地支持特定的部署。

`transport`

切换用于发送事件的传输。具体实现取决于 SDK。例如，可以用于捕获事件进行单元测试，或通过需要代理身份验证的更复杂设置发送事件。

`http_proxy`

设置时，可以配置一个用于出站请求的代理。这也用于 HTTPS 请求，除非单独配置了 https-proxy。然而，并非所有 SDK 都支持单独的 HTTPS 代理。如果可能，SDK 将尝试使用系统范围配置的代理。例如，在 Unix 系统上，将使用 http_proxy 环境变量。

`https_proxy`

配置用于出站 HTTPS 请求的单独代理。此值可能不受所有 SDK 支持。如果不支持，则 http-proxy 值将始终用于 HTTPS 请求。

`proxy_headers`

包含要转发到 urllib3 的 ProxyManager 的附加代理头（通常用于身份验证）的字典。

`shutdown_timeout`

控制在关闭之前等待的秒数。Sentry SDK 从后台队列发送事件。此队列会等待一段时间以处理待处理事件。默认值因 SDK 而异，但通常约为两秒。将此值设置得太低可能会导致从命令行应用程序发送事件出现问题。将此值设置得太高会导致网络连接问题的用户应用程序长时间阻塞。

`keep_alive`

确定是否在请求之间保持连接。在遇到频繁网络问题（如连接重置）的环境中，这可能很有用。

`cert_file`

要使用的客户端证书的路径。如果设置，将覆盖 CLIENT_CERT_FILE 环境变量。

`key_file`

要使用的密钥文件的路径。如果设置，将覆盖 CLIENT_KEY_FILE 环境变量。

`socket_options`

一个可选的套接字选项列表。这些选项提供对 SDK 连接到 Sentry 方式的细粒度、低级控制。如果提供，这些选项将覆盖默认的 urllib3 套接字选项。

Copied

import socket
from urllib3.connection import HTTPConnection

sentry_sdk.init(
    socket_options=HTTPConnection.default_socket_options + [
        (socket.SOL_SOCKET, socket.SO_KEEPALIVE, 1),
    ],
)

`enable_tracing`

一个布尔值，如果为 true，将生成并捕获事务和跟踪数据。如果未定义 traces-sample-rate，这将将其设置为推荐的默认值 1.0。请注意，traces-sample-rate 和 traces-sampler 优先于此选项。

`traces_sample_rate`

一个介于 0 和 1 之间的数字，控制给定事务发送到 Sentry 的百分比机会。（0 表示 0%，1 表示 100%。）适用于应用程序中创建的所有事务。必须定义此选项或 traces_sampler 以启用跟踪。

如果 traces_sample_rate 为 0，这意味着不会创建新的跟踪。然而，如果您有另一个服务（例如 JS 前端）向您的服务发送包含跟踪信息的请求，这些跟踪将继续，因此事务将发送到 Sentry。

如果您想禁用所有跟踪，需要将 traces_sample_rate 设置为 None 或将 enable_tracing 设置为 False。在这种情况下，不会启动新的跟踪，也不会继续传入的跟踪。

`traces_sampler`

一个负责确定给定事务发送到 Sentry 的百分比机会的函数。它会自动传递有关事务及其创建上下文的信息，并必须返回一个介于 0（0% 的发送机会）和 1（100% 的发送机会）之间的数字。也可以用于过滤事务，通过返回 0 来排除不需要的事务。必须定义此选项或 traces_sample_rate 以启用跟踪。

`trace_propagation_targets`

一个可选属性，用于控制哪些下游服务接收跟踪数据，形式为附加到任何出站 HTTP 请求的 sentry-trace 和 baggage 头。

该选项可以包含一个字符串或正则表达式的列表，用于匹配出站请求的 URL。如果列表中的某个条目与出站请求的 URL 匹配，则跟踪数据将附加到该请求。字符串条目不需要完全匹配，只要请求的 URL 包含通过选项提供的字符串即可。

如果未提供 trace_propagation_targets，则跟踪数据将附加到从仪器化客户端发出的每个出站请求。

`functions_to_trace`

一个可选的函数列表，这些函数应设置为跟踪。对于列表中的每个函数，在执行该函数时将创建一个跨度。列表中的函数表示为包含函数完全限定名称的字符串。

这是一个方便的选项，使您可以在一个中心位置配置要跟踪的函数，而不是在代码库中分散自定义的跟踪。

要了解更多信息，请参阅自定义跟踪文档。

Copied

def custom_repr(obj):
    if isinstance(obj, MyCustomClass):
        return "<MyCustomClass>"
    else
        return None

sentry_sdk.init(custom_repr=custom_repr)

默认值为 None。

配置

环境