›

API 参考

编辑

API 参考

编辑

Elastic APM Python 代理有几个公共 API。当使用我们支持的框架时，大多数公共 API 功能是不需要的，但它们允许自定义使用。

客户端 API

编辑

公共客户端 API 由 Client 类上的几个方法组成。此 API 可用于跟踪异常和日志消息，以及标记事务的开始和结束。

实例化

编辑

在 v1.0.0 中添加。

要创建 Client 实例，请导入它并调用其构造函数

from elasticapm import Client

client = Client({'SERVICE_NAME': 'example'}, **defaults)

config: 一个字典，包含键/值配置。有关可能的配置键，请参阅配置。
**defaults: 配置的默认值。在大多数情况下可以省略这些值，并且优先级最低。

像Django和Flask这样的框架集成会自动实例化客户端。

`elasticapm.get_client()`

编辑

[小]#在 v6.1.0 中添加。

检索 Client 单例。这对于许多框架集成非常有用，在这些集成中，客户端会自动实例化。

client = elasticapm.get_client()
client.capture_message('foo')

错误

编辑

`Client.capture_exception()`

编辑

在 v1.0.0 中添加。handled 在 v2.0.0 中添加。

捕获异常对象

try:
    x = int("five")
except ValueError:
    client.capture_exception()

exc_info: 由 sys.exc_info() 返回的 (type, value, traceback) 元组。如果未提供，则会自动捕获。
date: 表示错误发生时间的 datetime.datetime 对象。如果留空，则默认为 datetime.datetime.utcnow()。
context: 包含上下文信息的字典。此字典必须遵循 Context 模式定义。
custom: 您想要附加到事件的自定义数据字典。
handled: 一个布尔值，指示此异常是否已处理。

以字符串形式返回错误的 ID。

`Client.capture_message()`

编辑

在 v1.0.0 中添加。

捕获带有可选添加上下文数据的消息。示例

client.capture_message('Billing process succeeded.')

message: 字符串形式的消息。
param_message: 或者，作为字典的参数化消息。该字典包含两个值：message 和 params。这允许 APM 服务器将共享相同参数化消息的消息组合在一起。示例
```
client.capture_message(param_message={
    'message': 'Billing process for %s succeeded. Amount: %s',
    'params': (customer.id, order.total_amount),
})
```
stack: 如果设置为 True（默认值），将捕获调用站点的堆栈跟踪。
exc_info: 由 sys.exc_info() 返回的 (type, value, traceback) 元组。如果未提供，则会在 except 块中调用 capture_message() 时自动捕获。
date: 表示错误发生时间的 datetime.datetime 对象。如果留空，则默认为 datetime.datetime.utcnow()。
context: 包含上下文信息的字典。此字典必须遵循 Context 模式定义。
custom: 您想要附加到事件的自定义数据字典。

以字符串形式返回消息的 ID。

需要 message 或 param_message 参数之一。

事务

编辑

`Client.begin_transaction()`

编辑

在 v1.0.0 中添加。在 v5.6.0 中添加了 trace_parent 支持。

开始跟踪事务。应在请求开始时或启动后台任务时调用。示例

client.begin_transaction('processors')

transaction_type:（必需）描述事务类型的字符串，例如 'request' 或 'celery'。
trace_parent:（可选）TraceParent 对象。请参阅TraceParent 生成。
links:（可选）此事务因果关联的 TraceParent 对象列表。

`Client.end_transaction()`

编辑

在 v1.0.0 中添加。

结束跟踪事务。应在请求结束时或结束后台任务时调用。示例

client.end_transaction('myapp.billing_process', processor.status)

name:（可选）描述事务名称的字符串，例如 process_order。这通常是处理请求的视图/控制器的名称或路由名称。
result:（可选）描述事务结果的字符串。这通常是 HTTP 状态代码，或者例如后台任务的 'success'。

如果在 end_transaction() 调用中未设置 name 和 result，则必须在事务期间通过调用 elasticapm.set_transaction_name() 和 elasticapm.set_transaction_result() 预先设置它们。

`TraceParent`

编辑

事务可以使用 TraceParent 对象启动。这将创建一个作为 TraceParent 子级的事务，这对于分布式跟踪至关重要。

`elasticapm.trace_parent_from_string()`

编辑

在 v5.6.0 中添加。

从 TraceParent.to_string() 生成的字符串表示形式创建 TraceParent 对象

parent = elasticapm.trace_parent_from_string('00-03d67dcdd62b7c0f7a675424347eee3a-5f0e87be26015733-01')
client.begin_transaction('processors', trace_parent=parent)

traceparent_string:（必需）TraceParent 对象的字符串表示形式。

`elasticapm.trace_parent_from_headers()`

编辑

在 v5.6.0 中添加。

从 HTTP 标头创建 TraceParent 对象（通常由另一个 Elastic APM 代理生成）

parent = elasticapm.trace_parent_from_headers(headers_dict)
client.begin_transaction('processors', trace_parent=parent)

headers:（必需）作为字典形式的 HTTP 标头。

`elasticapm.get_trace_parent_header()`

编辑

在 v5.10.0 中添加。

返回当前事务 TraceParent 对象的字符串表示形式

elasticapm.get_trace_parent_header()

其他 API

编辑

`elasticapm.instrument()`

编辑

在 v1.0.0 中添加。

自动检测库。这包括各种标准库和第三方模块。可在 elasticapm.instrumentation.register 中找到已检测模块的列表。此函数应在应用程序启动时尽早调用。对于支持的框架，会自动调用此函数。示例

import elasticapm

elasticapm.instrument()

`elasticapm.set_transaction_name()`

编辑

在 v1.0.0 中添加。

设置当前事务的名称。对于支持的框架，会自动确定事务名称，并且可以使用此函数覆盖它。示例

import elasticapm

elasticapm.set_transaction_name('myapp.billing_process')

name:（必需）描述事务名称的字符串
override: 如果 True（默认值），则覆盖任何先前设置的事务名称。如果 False，则仅在尚未设置事务名称时设置名称。

`elasticapm.set_transaction_result()`

编辑

在 v2.2.0 中添加。

设置当前事务的结果。对于支持的框架，会自动确定事务结果，并且可以使用此函数覆盖它。示例

import elasticapm

elasticapm.set_transaction_result('SUCCESS')

result:（必需）描述事务结果的字符串，例如 HTTP 2xx 或 SUCCESS
override: 如果 True（默认值），则覆盖任何先前设置的结果。如果 False，则仅在尚未设置结果时设置结果。

`elasticapm.set_transaction_outcome()`

编辑

在 v5.9.0 中添加。

设置事务的结果。该值可以是 "success"、"failure" 或 "unknown"。这应仅在确定结果后在事务结束时调用。

outcome 用于错误率计算。success 表示事务已成功完成，而 failure 表示事务未能成功完成。如果将 outcome 设置为 unknown，则事务将不包含在错误率计算中。

对于支持的 Web 框架，如果尚未设置事务结果，则会根据 HTTP 状态代码自动设置事务结果。低于 500 的状态代码被视为 success，而任何 500 或更高的值都算作 failure。

如果您的事务导致 HTTP 响应，您可以选择提供 HTTP 状态代码。

尽管 outcome 和 result 字段看起来非常相似，但它们的用途不同。除了可以包含任意字符串值的 result 字段外，outcome 仅限于三个不同的值："success"、"failure" 和 "unknown"。这允许 APM 应用程序对这些值执行错误率计算。

示例

import elasticapm

elasticapm.set_transaction_outcome("success")

# Using an HTTP status code
elasticapm.set_transaction_outcome(http_status_code=200)

# Using predefined constants:

from elasticapm.conf.constants import OUTCOME

elasticapm.set_transaction_outcome(OUTCOME.SUCCESS)
elasticapm.set_transaction_outcome(OUTCOME.FAILURE)
elasticapm.set_transaction_outcome(OUTCOME.UNKNOWN)

outcome: "success"、"failure" 或 "unknown" 之一。如果提供了 http_status_code，则可以省略。
http_status_code: 如果事务表示 HTTP 响应，则可以提供其状态代码以自动确定 outcome。
override: 如果为 True (默认值)，则会覆盖任何先前设置的 outcome。如果为 False，则仅在之前未设置时才设置 outcome。

`elasticapm.get_transaction_id()`

编辑

在 v5.2.0 中添加。

获取当前事务的 ID。示例

import elasticapm

transaction_id = elasticapm.get_transaction_id()

`elasticapm.get_trace_id()`

编辑

在 v5.2.0 中添加。

获取当前事务的跟踪 trace_id。示例

import elasticapm

trace_id = elasticapm.get_trace_id()

`elasticapm.get_span_id()`

编辑

在 v5.2.0 中添加。

获取当前 Span 的 ID。示例

import elasticapm

span_id = elasticapm.get_span_id()

`elasticapm.set_custom_context()`

编辑

在 v2.0.0 中添加。

将自定义上下文数据附加到当前事务和错误。支持的框架会自动附加有关 HTTP 请求和已登录用户的信息。您可以使用此函数附加更多数据。

在使用自定义上下文之前，请确保您了解可用的不同类型的元数据。

示例

import elasticapm

elasticapm.set_custom_context({'billing_amount': product.price * item_count})

data: (必需) 要附加的数据的字典。这应该是一个扁平的键/值 dict 对象。

.、* 和 " 是键名的无效字符，将被替换为 _。

在此调用之后发生的错误也会附加自定义上下文。您可以多次调用此函数，新的上下文数据将与现有数据合并，遵循 Python 字典的 update() 语义。

`elasticapm.set_user_context()`

编辑

在 v2.0.0 中添加。

将有关当前登录用户的信息附加到当前事务和错误。示例

import elasticapm

elasticapm.set_user_context(username=user.username, email=user.email, user_id=user.id)

username: 已登录用户的用户名
email: 已登录用户的电子邮件
user_id: 已登录用户的唯一标识符，例如主键值

在此调用之后发生的错误也会附加用户上下文。您可以多次调用此函数，新的用户数据将与现有数据合并，遵循 Python 字典的 update() 语义。

`elasticapm.capture_span`

编辑

在 v4.1.0 中添加。

捕获自定义 Span。这可以用作函数装饰器或上下文管理器（在 with 语句中）。当用作装饰器时，Span 的名称将设置为函数的名称。当用作上下文管理器时，必须提供名称。

import elasticapm

@elasticapm.capture_span()
def coffee_maker(strength):
    fetch_water()

    with elasticapm.capture_span('near-to-machine', labels={"type": "arabica"}):
        insert_filter()
        for i in range(strength):
            pour_coffee()

        start_drip()

    fresh_pots()

name: Span 的名称。如果用作装饰器，则默认为函数名称。
span_type: (可选) Span 的类型，通常是 type、subtype 和 action 的点分隔层次结构，例如 db.mysql.query。或者，类型、子类型和操作可以作为三个单独的参数提供，请参阅 span_subtype 和 span_action。
skip_frames: (可选) 收集堆栈跟踪时要跳过的堆栈帧数。默认为 0。
leaf: (可选) 如果为 True，则将忽略此 Span 下的所有嵌套 Span。默认为 False。
labels: (可选) 标签字典。键必须是字符串，值可以是字符串、布尔值或数值 (int、float、decimal.Decimal)。默认为 None。
span_subtype: (可选) Span 的子类型，例如数据库的名称。默认为 None。
span_action: (可选) Span 的操作，例如 query。默认为 None。
links: (可选) 此 Span 在因果上链接到的 TraceParent 对象列表。

`elasticapm.async_capture_span`

编辑

在 v5.4.0 中添加。

捕获自定义异步感知 Span。这可以用作函数装饰器或上下文管理器（在 async with 语句中）。当用作装饰器时，Span 的名称将设置为函数的名称。当用作上下文管理器时，必须提供名称。

import elasticapm

@elasticapm.async_capture_span()
async def coffee_maker(strength):
    await fetch_water()

    async with elasticapm.async_capture_span('near-to-machine', labels={"type": "arabica"}):
        await insert_filter()
        async for i in range(strength):
            await pour_coffee()

        start_drip()

    fresh_pots()

name: Span 的名称。如果用作装饰器，则默认为函数名称。
span_type: (可选) Span 的类型，通常是 type、subtype 和 action 的点分隔层次结构，例如 db.mysql.query。或者，类型、子类型和操作可以作为三个单独的参数提供，请参阅 span_subtype 和 span_action。
skip_frames: (可选) 收集堆栈跟踪时要跳过的堆栈帧数。默认为 0。
leaf: (可选) 如果为 True，则将忽略此 Span 下的所有嵌套 Span。默认为 False。
labels: (可选) 标签字典。键必须是字符串，值可以是字符串、布尔值或数值 (int、float、decimal.Decimal)。默认为 None。
span_subtype: (可选) Span 的子类型，例如数据库的名称。默认为 None。
span_action: (可选) Span 的操作，例如 query。默认为 None。
links: (可选) 此 Span 在因果上链接到的 TraceParent 对象列表。

asyncio 仅支持 Python 3.7+。

`elasticapm.label()`

编辑

在 v5.0.0 中添加。

将标签附加到当前事务和错误。

在使用自定义标签之前，请确保您了解可用的不同类型的元数据。

示例

import elasticapm

elasticapm.label(ecommerce=True, dollar_value=47.12)

在此调用之后发生的错误也会附加标签。您可以多次调用此函数，新的标签将与现有标签合并，遵循 Python 字典的 update() 语义。

键必须是字符串，值可以是字符串、布尔值或数值 (int、float、decimal.Decimal) .、* 和 " 是标签名称的无效字符，将被替换为 _。

避免定义太多用户指定的标签。在一个索引中定义太多唯一的字段是一种可能导致映射爆炸的情况。

« 本地运行测试指标 »