« 使用 Winston 进行 ECS 日志记录
Elastic 文档 ›

使用 Morgan 进行 ECS 日志记录

编辑

使用 Morgan 进行 ECS 日志记录

编辑

这个 Node.js 包为 morgan 日志中间件提供了一个格式化器，该中间件通常与 Express 一起使用，并且与 Elastic Common Schema (ECS) 日志兼容。结合 Filebeat shipper，你可以在 Elastic Stack 中在一个地方监控所有日志。

设置

编辑

步骤 1：安装

编辑
$ npm install @elastic/ecs-morgan-format

步骤 2：配置

编辑
const app = require('express')();
const morgan = require('morgan');
const { ecsFormat } = require('@elastic/ecs-morgan-format');

app.use(morgan(ecsFormat(/* options */))); 

// ...
app.get('/', function (req, res) {
  res.send('hello, world!');
})
app.listen(3000);

将 ECS 格式化器传递给 morgan()。

步骤 3：配置 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 参考。

用法

编辑
const app = require('express')();
const morgan = require('morgan');
const { ecsFormat } = require('@elastic/ecs-morgan-format');

app.use(morgan(ecsFormat(/* options */))); 

app.get('/', function (req, res) {
  res.send('hello, world!');
})
app.get('/error', function (req, res, next) {
  next(new Error('boom'));
})

app.listen(3000)

请查看下方的可用选项。

运行此脚本（完整的示例在此处），并发出请求（通过 curl -i localhost:3000/），将生成类似于以下的日志输出

% node examples/express.js | jq .  # piping to jq for pretty-printing
{
  "@timestamp": "2021-01-16T00:03:23.279Z",
  "log.level": "info",
  "message": "::1 - - [16/Jan/2021:00:03:23 +0000] \"GET / HTTP/1.1\" 200 13 \"-\" \"curl/7.64.1\"",
  "ecs.version": "8.10.0",
  "http": {
    "version": "1.1",
    "request": {
      "method": "GET",
      "headers": {
        "host": "localhost:3000",
        "accept": "*/*"
      }
    },
    "response": {
      "status_code": 200,
      "headers": {
        "x-powered-by": "Express",
        "content-type": "text/html; charset=utf-8",
        "etag": "W/\"d-HwnTDHB9U/PRbFMN1z1wps51lqk\""
      },
      "body": {
        "bytes": 13
      }
    }
  },
  "url": {
    "path": "/",
    "domain": "localhost",
    "full": "https://127.0.0.1:3000/"
  },
  "user_agent": {
    "original": "curl/7.64.1"
  }
}

格式选项

编辑

你可以传递任何你通常传递给 morgan() 的 format 参数，并且日志 "message" 字段将使用指定的格式。默认值为 combined。

const app = require('express')();
const morgan = require('morgan');
const { ecsFormat } = require('@elastic/ecs-morgan-format');

app.use(morgan(ecsFormat({ format: 'tiny' }))); 
// ...

如果 "format" 是你正在使用的唯一选项，则可以将其作为 ecsFormat('tiny') 传递。

log.level

编辑

对于响应代码 >= 500，log.level 字段将为 "error"，否则为 "info"。例如，再次运行 examples/express.js，curl -i localhost:3000/error 将产生

% node examples/express.js | jq .
{
  "@timestamp": "2021-01-18T17:52:12.810Z",
  "log.level": "error",
  "message": "::1 - - [18/Jan/2021:17:52:12 +0000] \"GET /error HTTP/1.1\" 500 1416 \"-\" \"curl/7.64.1\"",
  "http": {
    "response": {
      "status_code": 500,
  ...

与 APM 的日志关联

编辑

此 ECS 日志格式化器与 Elastic APM 集成。如果你的 Node 应用程序正在使用 Node.js Elastic APM Agent，则会向日志记录添加许多字段，以在 APM 服务或跟踪和日志记录数据之间进行关联

  • 当存在当前跟踪跨度时调用的日志语句（例如 logger.info(...)）将包括跟踪字段 — trace.id, transaction.id。
  • 由 APM Agent 确定或配置的许多服务标识符字段允许在 Kibana 中跨服务和日志进行交叉链接 — service.name、service.version、service.environment、service.node.name。
  • event.dataset 启用 Elastic Observability 应用程序中的日志速率异常检测。

例如，运行 examples/express-with-apm.js 和 curl -i localhost:3000/ 会产生以下日志记录

% node examples/express-with-apm.js | jq .
{
  // The same fields as before, plus:
  "service.name": "express-with-elastic-apm",
  "service.version": "1.1.0",
  "service.environment": "development",
  "event.dataset": "express-with-elastic-apm",
  "trace.id": "116d46f667a7600deed9c41fa015f7de",
  "transaction.id": "b84fb72d7bf42866"
}

这些 ID 与 APM Agent 报告的跟踪数据匹配。

可以通过 apmIntegration: false 选项显式禁用与 Elastic APM 的集成，例如

app.use(morgan(ecsFormat({ apmIntegration: false })));

参考

编辑

ecsFormat([options])

编辑

  • options {type-object} 支持以下选项

    • format {type-string} 格式名称（例如，combined）、格式函数（例如，morgan.combined）或格式字符串（例如，:method :url :status）。这用于格式化 “message” 字段。默认为 morgan.combined。
    • convertErr {type-boolean} 是否将记录的 err 字段转换为 ECS 错误字段。默认值：true。
    • apmIntegration {type-boolean} 是否启用 APM Agent 集成。默认值：true。
    • serviceName {type-string} “service.name” 值。如果指定，则会覆盖任何来自活动的 APM Agent 的值。
    • serviceVersion {type-string} “service.version” 值。如果指定，则会覆盖任何来自活动的 APM Agent 的值。
    • serviceEnvironment {type-string} “service.environment” 值。如果指定，则会覆盖任何来自活动的 APM Agent 的值。
    • serviceNodeName {type-string} “service.node.name” 值。如果指定，则会覆盖任何来自活动的 APM Agent 的值。
    • eventDataset {type-string} “event.dataset” 值。如果指定，则会覆盖默认的 ${serviceVersion}。

为 morgan 创建一个以 ECS 日志格式输出的格式化器。

« 使用 Winston 进行 ECS 日志记录