« 设置代理 Flask 支持 »
Elastic 文档 › ›设置代理

Django 支持

编辑

Django 支持编辑

为您的 Django 项目设置 Elastic APM 很容易，并且您可以通过多种方式进行调整以满足您的需求。

安装编辑

使用 pip 安装 Elastic APM 代理

$ pip install elastic-apm

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

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

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

设置编辑

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

  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 服务器。

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

如果您的设置中 DEBUG = False，代理才会捕获并发送数据。要强制代理在 Django 调试模式下捕获数据，请设置debug配置选项，例如

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

性能指标编辑

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

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

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

检测自定义 Python 代码编辑

要进一步了解代码的性能，请参阅检测自定义代码。

忽略特定视图编辑

您可以使用 TRANSACTIONS_IGNORE_PATTERNS 配置选项来忽略特定视图。给定的列表应为正则表达式列表，这些正则表达式与 Elastic APM 用户界面中显示的事务名称匹配

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

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

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

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

ELASTIC_APM['DJANGO_TRANSACTION_NAME_FROM_ROUTE'] = True

在 Django 2.2 之前的版本中，更改此设置将不会产生任何影响。

与 RUM 代理集成编辑

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

要启用此功能，首先将 rum_tracing 上下文处理器添加到您的 TEMPLATES 设置中。您很可能已经有一个 context_processors 列表，在这种情况下，您只需将我们的处理器追加到列表中即可。

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

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

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

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

启用和禁用代理编辑

禁用代理的最简单方法是在开发配置中将 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 的数据中。如果没有它，只会发送消息。

额外数据编辑

如果您想发送比代理默认情况下提供的更多数据，则可以按如下方式执行日志记录

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设置。

在测试期间禁用代理编辑

要阻止代理在测试期间将任何数据发送到 APM 服务器，请将 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版本的列表。

« 设置代理 Flask 支持 »