›

简介

编辑

简介

编辑

使用 Elastic Stack 轻松实现集中式应用程序日志记录。

62682932 9cac3600 b9bd 11e9 9cc3 39e907280f8e

什么是 ECS？

编辑

Elastic Common Schema (ECS) 定义了一组用于将数据摄取到 Elasticsearch 中的通用字段。有关 ECS 的更多信息，请访问 ECS 参考文档。

什么是 ECS 日志记录？

编辑

ECS 日志记录器是您喜欢的日志记录库的插件。它们可以轻松地将您的日志格式化为 ECS 兼容的 JSON。例如

{"@timestamp":"2019-08-06T12:09:12.375Z", "log.level": "INFO", "message":"Tomcat started on port(s): 8080 (http) with context path ''", "service.name":"spring-petclinic","process.thread.name":"restartedMain","log.logger":"org.springframework.boot.web.embedded.tomcat.TomcatWebServer"}
{"@timestamp":"2019-08-06T12:09:12.379Z", "log.level": "INFO", "message":"Started PetClinicApplication in 7.095 seconds (JVM running for 9.082)", "service.name":"spring-petclinic","process.thread.name":"restartedMain","log.logger":"org.springframework.samples.petclinic.PetClinicApplication"}
{"@timestamp":"2019-08-06T14:08:40.199Z", "log.level":"DEBUG", "message":"init find form", "service.name":"spring-petclinic","process.thread.name":"http-nio-8080-exec-8","log.logger":"org.springframework.samples.petclinic.owner.OwnerController","transaction.id":"28b7fb8d5aba51f1","trace.id":"2869b25b5469590610fea49ac04af7da"}

开始使用

编辑

请参阅各个日志记录器的安装说明

.NET
Go：zap，logrus，zerolog
Java
Node.js：morgan，pino，winston
PHP
Python
Ruby

为什么选择 ECS 日志记录？

编辑

简单性：无需手动解析

日志以预先格式化、预先丰富的方式到达，并可以立即发挥作用，从而更快、更轻松地识别问题。不再需要为每个应用程序自定义繁琐的 grok 解析。

易于阅读的 JSON 结构

前三个字段是 @timestamp、log.level 和 message。这使您可以在终端中轻松读取日志，而无需使用将日志转换为纯文本的工具。

享受通用模式的好处

无需额外配置即可使用 Kibana 日志应用程序。

在不同的服务和团队中使用通用模式可以创建可重用的仪表板，并避免映射爆炸。

APM 日志关联

如果您正在使用 Elastic APM 代理，则可以利用日志关联功能，而无需任何额外的配置。这使您可以从 APM UI 中的 Span 时间线跳转到日志应用程序，仅显示属于相应请求的日志。反之亦然，您也可以从日志 UI 中的日志行跳转到 APM UI 的 Span 时间线。

与 Filebeat 结合使用时的其他优势

编辑

我们建议使用 Filebeat 传输日志。根据应用程序的部署方式，您可以将日志记录到日志文件或 stdout（例如，在 Kubernetes 中）。

与直接从应用程序将日志发送到 Elasticsearch 相比，这样做有以下好处

在中断时具有弹性: 保证至少一次传递，而无需在应用程序中进行缓冲，因此不会出现内存不足错误或事件丢失的风险。也可以选择使用 JSON 日志或纯文本日志作为后备方案。
松散耦合: 应用程序无需知道日志记录后端（URI、凭据等）的详细信息。您还可以利用其他 Filebeat 输出，例如 Logstash、Kafka 或 Redis。
索引生命周期管理: 利用 Filebeat 的默认索引生命周期管理设置。这比使用每日索引更有效。
高效的 Elasticsearch 映射: 利用 Filebeat 的默认 ECS 兼容索引模板。

字段映射

编辑

默认字段

编辑

默认情况下，ECS 日志记录器会填充这些字段。其中一些字段，例如 log.origin.* 字段，可能需要显式启用。其他字段，例如 process.thread.name，并非适用于所有语言。有关更多信息，请参阅各个日志记录器的文档。

ECS 字段	描述	示例
`@timestamp`	日志事件的时间戳。	`"2019-08-06T12:09:12.375Z"`
`log.level`	日志事件的级别或严重性。	`"INFO"`
`log.logger`	应用程序内部的日志记录器名称。	`"org.example.MyClass"`
`log.origin.file.name`	包含发起日志事件的源代码的文件的名称。	`"App.java"`
`log.origin.file.line`	包含发起日志事件的源代码的文件的行号。	`42`
`log.origin.function`	发起日志事件的函数或方法的名称。	`"methodName"`
`message`	日志消息。	`"Hello World!"`
`error.type`	仅当日志包含异常或错误时才出现。如果此日志事件包含异常，则为错误的类型或类。	`"java.lang.NullPointerException"`
`error.message`	仅当日志包含异常或错误时才出现。异常或错误的消息。	`"参数不能为空"`
`error.stack_trace`	仅当日志包含异常或错误时才出现。异常或错误的完整堆栈跟踪，以原始字符串形式表示。	`"线程“main”中的异常 java.lang.NullPointerException\n\tat org.example.App.methodName(App.java:42)"`
`process.thread.name`	记录事件的线程的名称。	`"main"`

可配置字段

编辑

有关如何设置这些字段，请参阅各个日志记录器的文档。

ECS 字段	描述	示例
`service.name`	帮助按服务筛选日志。	`"my-service"`
`service.version`	帮助按服务版本筛选日志。	`"1.0"`
`service.environment`	帮助按环境筛选日志。	`"production"`
`service.node.name`	允许区分同一主机上同一服务的两个节点。	`"instance-0000000016"`
`event.dataset`	启用日志速率异常检测。	`"my-service"`

自定义字段

编辑

大多数日志记录器允许您添加其他自定义字段。这包括静态字段和动态字段。动态字段的示例包括记录结构化对象或来自线程局部上下文（例如 MDC 或 ThreadContext）的字段。

添加自定义字段时，我们建议对这些自定义值使用现有的 ECS 字段。如果没有合适的 ECS 字段，请考虑使用 labels. 作为字段的前缀，例如 labels.foo，表示简单的键/值对。对于嵌套结构，请考虑使用 custom. 作为前缀。这种方法可以防止在 ECS 以后添加相同字段但使用不同映射时发生冲突。