« 设置 Agent Flask 支持 »
Elastic 文档 › ›设置 Agent

Django 支持

编辑

Django 支持

编辑

为你的 Django 项目设置 Elastic APM 非常简单，并且你可以通过多种方式进行调整以满足你的需求。

安装

编辑

使用 pip 安装 Elastic APM Agent

$ pip install elastic-apm

或者将其添加到你项目的 requirements.txt 文件中。

对于 apm-server 6.2+，请确保你使用 elastic-apm 的 2.0 或更高版本。

如果你将 Django 与 uwsgi 一起使用，请确保启用线程。

设置

编辑

通过以下两个步骤在 Django 中设置 Elastic APM Agent

  1. 将 elasticapm.contrib.django 添加到你设置中的 INSTALLED_APPS
INSTALLED_APPS = (
   # ...
   'elasticapm.contrib.django',
)
  1. 选择一个服务名称，并在需要时设置密钥令牌。
ELASTIC_APM = {
   'SERVICE_NAME': '<SERVICE-NAME>',
   'SECRET_TOKEN': '<SECRET-TOKEN>',
}

或者作为环境变量

ELASTIC_APM_SERVICE_NAME=<SERVICE-NAME>
ELASTIC_APM_SECRET_TOKEN=<SECRET-TOKEN>

你现在已经设置了基本的错误日志记录，并且所有导致 500 HTTP 状态代码的内容都将报告给 APM Server。

你可以在配置页面中找到所有可用设置的列表。

仅当你的设置中 DEBUG = False 时，Agent 才会捕获并发送数据。 要强制 Agent 在 Django 调试模式下捕获数据，请设置 debug 配置选项，例如

ELASTIC_APM = {
   'SERVICE_NAME': '<SERVICE-NAME>',
   'DEBUG': True,
}

性能指标

编辑

为了收集性能指标，Agent 会自动在你中间件列表的顶部插入一个中间件（在当前版本的 Django 中为 settings.MIDDLEWARE，在某些旧版本中为 settings.MIDDLEWARE_CLASSES）。要禁用中间件的自动插入，请参阅 django_autoinsert_middleware。

为了使自动插入工作，你的中间件列表（settings.MIDDLEWARE 或 settings.MIDDLEWARE_CLASSES）必须是 list 或 tuple 类型。

除了广泛的请求指标（将在 APM 应用程序中显示为事务）外，Agent 还收集关于模板渲染、数据库查询、HTTP 请求等方面的细粒度指标。你可以在自动检测部分找到关于我们检测内容的更多信息。

检测自定义 Python 代码
编辑

要深入了解你代码的性能，请参阅检测自定义代码。

忽略特定视图
编辑

你可以使用 TRANSACTIONS_IGNORE_PATTERNS 配置选项来忽略特定的视图。给定的列表应该是一个正则表达式列表，这些正则表达式将与 Elastic APM 用户界面中看到的事务名称进行匹配

ELASTIC_APM['TRANSACTIONS_IGNORE_PATTERNS'] = ['^OPTIONS ', 'views.api.v2']

此示例忽略使用 OPTIONS 方法的任何请求以及包含 views.api.v2 的任何请求。

使用路由作为事务名称
编辑

默认情况下，我们使用视图的函数或类名称作为事务名称。从 Django 2.2 开始，Django 使路由（例如 users/<int:user_id>/）在 request.resolver_match 对象上可用。如果你想使用路由而不是视图名称作为事务名称，你可以将 django_transaction_name_from_route 配置选项设置为 true。

ELASTIC_APM['DJANGO_TRANSACTION_NAME_FROM_ROUTE'] = True

在 Django 2.2 之前的版本中，更改此设置将不起作用。

与 RUM Agent 集成
编辑

为了将浏览器中的性能测量结果与你的 Django 应用程序中的测量结果相关联，你可以通过使用后端请求的跟踪 ID 和 Span ID 配置 RUM（真实用户监控）Agent 来帮助它。我们提供了一个方便的模板上下文处理器，它将所有必需的内容添加到你的模板上下文中。

要启用此功能，请首先将 rum_tracing 上下文处理器添加到你的 TEMPLATES 设置中。你很可能已经有了一个 context_processors 列表，在这种情况下，你可以简单地将我们的处理器附加到该列表中。

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'OPTIONS': {
            'context_processors': [
                # ...
                'elasticapm.contrib.django.context_processors.rum_tracing',
            ],
        },
    },
]

然后，更新对初始化 RUM Agent 的调用（这可能发生在你的基本模板中），如下所示

elasticApm.init({
    serviceName: "my-frontend-service",
    pageLoadTraceId: "{{ apm.trace_id }}",
    pageLoadSpanId: "{{ apm.span_id }}",
    pageLoadSampled: {{ apm.is_sampled_js }}
})

有关更多信息，请参阅 JavaScript RUM Agent 文档。

启用和禁用 Agent

编辑

禁用 Agent 的最简单方法是在你的开发配置中将 Django 的 DEBUG 选项设置为 True。不会将任何错误或指标记录到 Elastic APM。

但是，如果在调试期间你希望强制将错误日志记录到 Elastic APM，那么你可以在 Elastic APM 配置字典中将 DEBUG 设置为 True，如下所示

ELASTIC_APM = {
   # ...
   'DEBUG': True,
}

与 Python 日志记录集成

编辑

为了轻松地将 Python logging 消息作为“错误”对象发送到 Elasticsearch，我们提供了一个 LoggingHandler，你可以在你的日志记录设置中使用它。日志消息将使用堆栈跟踪、请求中的数据等进行丰富。

此处理程序的预期用例是将高优先级日志消息（例如，级别为 ERROR 的日志消息）发送到 Elasticsearch。对于正常的日志发送，我们建议使用filebeat。

如果你不熟悉 logging 模块如何与 Django 一起工作，请在Django 文档中阅读更多内容。

你的 LOGGING 设置可能如下所示的示例

LOGGING = {
    'version': 1,
    'disable_existing_loggers': True,
    'formatters': {
        'verbose': {
            'format': '%(levelname)s %(asctime)s %(module)s %(process)d %(thread)d %(message)s'
        },
    },
    'handlers': {
        'elasticapm': {
            'level': 'WARNING',
            'class': 'elasticapm.contrib.django.handlers.LoggingHandler',
        },
        'console': {
            'level': 'DEBUG',
            'class': 'logging.StreamHandler',
            'formatter': 'verbose'
        }
    },
    'loggers': {
        'django.db.backends': {
            'level': 'ERROR',
            'handlers': ['console'],
            'propagate': False,
        },
        'mysite': {
            'level': 'WARNING',
            'handlers': ['elasticapm'],
            'propagate': False,
        },
        # Log errors from the Elastic APM module to the console (recommended)
        'elasticapm.errors': {
            'level': 'ERROR',
            'handlers': ['console'],
            'propagate': False,
        },
    },
}

通过此配置，可以在 myapp django 应用程序中的任何模块中执行如下所示的日志记录

你现在可以在 myapp Django 应用程序中的任何模块中使用记录器，例如 myapp/views.py

import logging
logger = logging.getLogger('mysite')

try:
    instance = MyModel.objects.get(pk=42)
except MyModel.DoesNotExist:
    logger.error(
        'Could not find instance, doing something else',
        exc_info=True
    )

请注意，exc_info=True 会将异常信息添加到发送到 Elastic APM 的数据中。如果没有它，只会发送消息。

额外数据
编辑

如果你想发送比默认情况下从 Agent 获取的更多数据，可以按如下方式进行日志记录

import logging
logger = logging.getLogger('mysite')

try:
    instance = MyModel.objects.get(pk=42)
except MyModel.DoesNotExist:
    logger.error(
        'There was some crazy error',
        exc_info=True,
        extra={
            'datetime': str(datetime.now()),
        }
    )

Celery 集成

编辑

有关如何使用 Celery 设置 Django 的一般指南，请转到 Celery 的 Django 文档。

Elastic APM 将自动记录你的 Celery 任务中的错误，记录性能数据，并在从已经启动的 Elastic 事务启动任务时保留 trace.id。

记录 “HTTP 404 未找到” 错误

编辑

默认情况下，Elastic APM 不会记录 HTTP 404 错误。如果你希望记录这些错误，请将 'elasticapm.contrib.django.middleware.Catch404Middleware' 添加到你设置中的 MIDDLEWARE

MIDDLEWARE = (
    # ...
    'elasticapm.contrib.django.middleware.Catch404Middleware',
    # ...
)

请注意，此中间件遵循 Django 的IGNORABLE_404_URLS 设置。

在测试期间禁用 Agent

编辑

为了防止 Agent 在测试期间向 APM Server 发送任何数据，请将 ELASTIC_APM_DISABLE_SEND 环境变量设置为 true，例如

ELASTIC_APM_DISABLE_SEND=true python manage.py test

故障排除

编辑

Elastic APM 提供了一个 Django 命令，可以帮助你排查设置问题。要检查你的配置，请运行

python manage.py elasticapm check

要使用当前设置发送测试异常，请运行

python manage.py elasticapm test

如果该命令成功发送了测试异常，它将打印一条成功消息

python manage.py elasticapm test

Trying to send a test error using these settings:

SERVICE_NAME:      <SERVICE_NAME>
SECRET_TOKEN:      <SECRET_TOKEN>
SERVER:            http://127.0.0.1:8200

Success! We tracked the error successfully! You should be able to see it in a few seconds.

支持的 Django 和 Python 版本

编辑

可以在我们的支持的技术页面上找到支持的Django 和 Python 版本列表。

« 设置 Agent Flask 支持 »