« 简介
Elastic 文档 ›

安装

编辑

安装编辑

$ python -m pip install ecs-logging

入门编辑

ecs-logging-python 为标准库 logging 模块和 structlog 包提供格式化程序。

标准库 logging 模块编辑

import logging
import ecs_logging

# Get the Logger
logger = logging.getLogger("app")
logger.setLevel(logging.DEBUG)

# Add an ECS formatter to the Handler
handler = logging.StreamHandler()
handler.setFormatter(ecs_logging.StdlibFormatter())
logger.addHandler(handler)

# Emit a log!
logger.debug("Example message!", extra={"http.request.method": "get"})
{
    "@timestamp": "2020-03-20T18:11:37.895Z",
    "log.level": "debug",
    "message": "Example message!",
    "ecs": {
        "version": "1.6.0"
    },
    "http": {
      "request": {
        "method": "get"
      }
    },
    "log": {
        "logger": "app",
        "origin": {
            "file": {
                "line": 14,
                "name": "test.py"
            },
            "function": "func"
        },
        "original": "Example message!"
    }
}

排除字段编辑

您可以使用 StdlibFormatter 构造函数中的 exclude_fields 选项来排除收集的字段。

from ecs_logging import StdlibFormatter

formatter = StdlibFormatter(
    exclude_fields=[
        # You can specify individual fields to ignore:
        "log.original",
        # or you can also use prefixes to ignore
        # whole categories of fields:
        "process",
        "log.origin",
    ]
)

限制堆栈跟踪编辑

StdlibLogger 会自动将 exc_info 收集到 ECS error.* 字段中。如果您希望控制 error.stack_trace 中包含的堆栈帧数，可以使用 stack_trace_limit 参数（默认情况下会收集所有帧）。

from ecs_logging import StdlibFormatter

formatter = StdlibFormatter(
    # Only collects 3 stack frames
    stack_trace_limit=3,
)
formatter = StdlibFormatter(
    # Disable stack trace collection
    stack_trace_limit=0,
)

Structlog 示例编辑

请注意，structlog 处理器应为列表中的最后一个处理器，因为它会处理转换为 JSON 以及 ECS 字段丰富。

import structlog
import ecs_logging

# Configure Structlog
structlog.configure(
    processors=[ecs_logging.StructlogFormatter()],
    wrapper_class=structlog.BoundLogger,
    context_class=dict,
    logger_factory=structlog.PrintLoggerFactory(),
)

# Get the Logger
logger = structlog.get_logger("app")

# Add additional context
logger = logger.bind(**{
    "http": {
        "version": "2",
        "request": {
            "method": "get",
            "bytes": 1337,
        },
    },
    "url": {
        "domain": "example.com",
        "path": "/",
        "port": 443,
        "scheme": "https",
        "registered_domain": "example.com",
        "top_level_domain": "com",
        "original": "https://example.com",
    }
})

# Emit a log!
logger.debug("Example message!")
{
  "@timestamp": "2020-03-26T13:08:11.728Z",
  "ecs": {
    "version": "1.6.0"
  },
  "http": {
    "request": {
      "bytes": 1337,
      "method": "get"
    },
    "version": "2"
  },
  "log": {
    "level": "debug"
  },
  "message": "Example message!",
  "url": {
    "domain": "example.com",
    "original": "https://example.com",
    "path": "/",
    "port": 443,
    "registered_domain": "example.com",
    "scheme": "https",
    "top_level_domain": "com"
  }
}

Elastic APM 日志关联编辑

ecs-logging-python 支持从 Elastic APM Python 代理 自动收集 ECS 跟踪字段，以便将日志 与 Elastic APM 中的跨度、事务和跟踪相关联。

您也可以通过在 Elastic APM Python 代理中设置 LOG_ECS_REFORMATTING=override 来快速在您的 Python 应用程序中启用 ECS 格式的日志。

安装 Filebeat编辑

将日志格式化为 ECS 后，最好使用 Filebeat 收集日志。

  1. 请按照 Filebeat 快速入门 指南操作。
  2. 将以下配置添加到您的 filebeat.yaml 文件中。

对于 Filebeat 7.16+

filebeat.yaml。

filebeat.inputs:
- type: filestream 
  paths: /path/to/logs.json
  parsers:
    - ndjson:
      overwrite_keys: true 
      add_error_key: true 
      expand_keys: true 

processors: 
  - add_host_metadata: ~
  - add_cloud_metadata: ~
  - add_docker_metadata: ~
  - add_kubernetes_metadata: ~

使用 filestream 输入从活动日志文件中读取行。

解码后的 JSON 对象中的值会覆盖 Filebeat 通常添加的字段（类型、源、偏移量等），以防发生冲突。

如果出现 JSON 反序列化错误，Filebeat 会添加 “error.message” 和 “error.type: json” 密钥。

Filebeat 会递归地解除解码后的 JSON 中的点分隔符密钥，并将它们扩展到分层对象结构中。

处理器可以增强您的数据。请参阅 处理器 了解更多信息。

对于 Filebeat < 7.16

filebeat.yaml。

filebeat.inputs:
- type: log
  paths: /path/to/logs.json
  json.keys_under_root: true
  json.overwrite_keys: true
  json.add_error_key: true
  json.expand_keys: true

processors:
- add_host_metadata: ~
- add_cloud_metadata: ~
- add_docker_metadata: ~
- add_kubernetes_metadata: ~

有关更多信息，请参阅 Filebeat 参考。

« 简介