›

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()`编辑

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

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

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

错误编辑

`Client.capture_exception()`编辑

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

捕获异常对象

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

exc_info: 由 sys.exc_info() 返回的 (type, value, traceback) 元组。如果未提供，它将被自动捕获。
date: 一个 datetime.datetime 对象，表示错误发生的时刻。如果留空，它默认为 datetime.datetime.utcnow()。
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) 元组。如果未提供，它将被自动捕获，如果 capture_message() 在 except 块中被调用。
date: 一个 datetime.datetime 对象，表示错误发生的时刻。如果留空，它默认为 datetime.datetime.utcnow()。
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 标头（通常由另一个 Elastic APM 代理生成）创建 TraceParent 对象

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，则仅在之前未设置结果的情况下设置结果。

`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 中添加。

获取当前跨度的 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 中添加。

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

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_type: (可选) 跨度的类型，通常是 type、subtype 和 action 的点分隔层次结构，例如 db.mysql.query。或者，类型、子类型和操作可以作为三个单独的参数提供，请参阅 span_subtype 和 span_action。
skip_frames: (可选) 收集堆栈跟踪时要跳过的堆栈帧数。默认为 0。
leaf: (可选) 如果为 True，则将忽略此跨度下方嵌套的所有跨度。默认为 False。
labels: (可选) 标签字典。键必须是字符串，值可以是字符串、布尔值或数值 (int、float、decimal.Decimal)。默认为 None。
span_subtype: (可选) 跨度的子类型，例如数据库的名称。默认为 None。
span_action: (可选) 跨度的操作，例如 query。默认为 None。
links: (可选) 与此跨度因果相关的 TraceParent 对象列表。

`elasticapm.async_capture_span`编辑

在 v5.4.0 中添加。

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

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_type: (可选) 跨度的类型，通常是 type、subtype 和 action 的点分隔层次结构，例如 db.mysql.query。或者，类型、子类型和操作可以作为三个单独的参数提供，请参阅 span_subtype 和 span_action。
skip_frames: (可选) 收集堆栈跟踪时要跳过的堆栈帧数。默认为 0。
leaf: (可选) 如果为 True，则将忽略此跨度下方嵌套的所有跨度。默认为 False。
labels: (可选) 标签字典。键必须是字符串，值可以是字符串、布尔值或数值 (int、float、decimal.Decimal)。默认为 None。
span_subtype: (可选) 跨度的子类型，例如数据库的名称。默认为 None。
span_action: (可选) 跨度的操作，例如 query。默认为 None。
links: (可选) 与此跨度因果相关的 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) .、* 和 " 是标签名的无效字符，将被替换为 _。

避免定义太多用户指定的标签。在索引中定义太多唯一字段会导致映射爆炸。

« 在本地运行测试指标 »

API 参考

API 参考编辑

客户端 API编辑

实例化编辑

elasticapm.get_client()编辑

错误编辑

Client.capture_exception()编辑

Client.capture_message()编辑

事务编辑

Client.begin_transaction()编辑

Client.end_transaction()编辑

TraceParent编辑

elasticapm.trace_parent_from_string()编辑

elasticapm.trace_parent_from_headers()编辑

elasticapm.get_trace_parent_header()编辑

其他 API编辑

elasticapm.instrument()编辑

elasticapm.set_transaction_name()编辑

elasticapm.set_transaction_result()编辑

elasticapm.set_transaction_outcome()编辑

elasticapm.get_transaction_id()编辑

elasticapm.get_trace_id()编辑

elasticapm.get_span_id()编辑

elasticapm.set_custom_context()编辑

elasticapm.set_user_context()编辑

elasticapm.capture_span编辑

elasticapm.async_capture_span编辑

elasticapm.label()编辑

`elasticapm.get_client()`编辑

`Client.capture_exception()`编辑

`Client.capture_message()`编辑

`Client.begin_transaction()`编辑

`Client.end_transaction()`编辑

`TraceParent`编辑

`elasticapm.trace_parent_from_string()`编辑

`elasticapm.trace_parent_from_headers()`编辑

`elasticapm.get_trace_parent_header()`编辑

`elasticapm.instrument()`编辑

`elasticapm.set_transaction_name()`编辑

`elasticapm.set_transaction_result()`编辑

`elasticapm.set_transaction_outcome()`编辑

`elasticapm.get_transaction_id()`编辑

`elasticapm.get_trace_id()`编辑

`elasticapm.get_span_id()`编辑

`elasticapm.set_custom_context()`编辑

`elasticapm.set_user_context()`编辑

`elasticapm.capture_span`编辑

`elasticapm.async_capture_span`编辑

`elasticapm.label()`编辑