« 简介
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 中将日志与 spans、事务和跟踪关联起来。

您还可以通过在 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 参考。

« 简介