Elastic Stack Logstash 数据管道与 ELFK 项目实践
Elastic Stack Logstash 数据管道与 ELFK 项目
1. Logstash Pipeline 架构
一个 Pipeline 固定由三部分组成:
| 阶段 | 作用 | 常见插件 |
|---|---|---|
| Input | 数据从哪里来 | stdin、file、beats、tcp、kafka、redis |
| Filter | 数据如何处理 | mutate、date、grok、geoip、useragent、json |
| Output | 数据向哪里去 | stdout、elasticsearch、kafka |
ELFK 的基本链路:
Nginx → Filebeat → Logstash → Elasticsearch → Kibana
职责建议:
- Filebeat 部署在日志产生端,负责轻量采集。
- Logstash 集中完成复杂解析、字段转换、地理分析和条件路由。
- Elasticsearch 负责索引、存储、搜索和聚合。
- Kibana 负责查询和可视化。
2. Input 插件概览
| 插件 | 用途 | 注意事项 |
|---|---|---|
stdin | 标准输入测试 | 仅适合验证配置 |
file | 读取文本文件 | 依赖 sincedb 记录读取位置 |
beats | 接收 Filebeat 数据 | 默认端口常用 5044 或自定义端口 |
tcp | 接收原始 TCP 文本 | 生产环境应启用 TLS 和访问控制 |
kafka | 从 Kafka 消费消息 | 适合削峰、解耦和多消费者 |
redis | 从 Redis 列表或频道读取 | 适合简单缓冲,需处理持久化与高可用 |
3. file input 的读取位置
3.1 sincedb
file 输入插件把已读取文件的位置记录在 sincedb 中。默认位置可能位于:
/usr/share/logstash/data/plugins/inputs/file/.sincedb_*
下一次启动时,Logstash 会依据记录继续读取,而不是从头开始。
建议显式指定独立状态文件:
input {
file {
path => ["/tmp/demo-app.log"]
start_position => "beginning"
sincedb_path => "/var/lib/logstash/sincedb-demo-app"
}
}
3.2 start_position
beginning:首次发现文件时从头读取。end:首次发现文件时从末尾读取,是默认值。- 文件已有
sincedb记录时,start_position不会覆盖原读取位置。
3.3 受控重放旧数据
测试环境需要重新读取旧数据时:
- 停止对应 Logstash 实例。
- 备份原
sincedb。 - 创建新的状态文件路径。
- 使用新的
sincedb_path启动。
sudo install -d -o logstash -g logstash /var/lib/logstash
sudo cp -a \
/var/lib/logstash/sincedb-demo-app \
/var/backups/sincedb-demo-app.$(date +%Y%m%d%H%M%S)
新配置:
sincedb_path => "/var/lib/logstash/demo-replay/sincedb-app"
不要直接在共享目录中删除未知的 .sincedb_* 文件,这可能导致其他采集任务重复写入大量数据。
4. mutate filter 处理业务日志
假定业务日志格式固定:
INFO 2026-07-16 10:34:39,123 [com.example.main] - DAU|1001|pay|1|299.00
目标字段:
| 字段 | 类型 | 含义 |
|---|---|---|
user_id | integer | 用户编号 |
action | keyword | 用户行为 |
vip | integer | VIP 标记 |
price | float | 金额 |
datetime | string | 日志中的业务时间 |
4.1 按分隔符拆分
filter {
mutate {
split => {
"message" => "|"
}
add_field => {
"prefix" => "%{[message][0]}"
"user_id" => "%{[message][1]}"
"action" => "%{[message][2]}"
"vip" => "%{[message][3]}"
"price" => "%{[message][4]}"
}
}
mutate {
split => {
"prefix" => " "
}
add_field => {
"datetime" => "%{[prefix][1]} %{[prefix][2]}"
}
remove_field => ["message", "prefix", "@version"]
}
mutate {
convert => {
"price" => "float"
"user_id" => "integer"
"vip" => "integer"
}
}
}
说明:
split适合稳定的分隔符格式。add_field会先把值作为字符串加入事件,再通过convert转换为数字。- 字段名应与目标类型一致,例如数字使用
user_id,文本使用action。 - 处理失败时可检查
@timestamp、原始message和 Logstash 日志。
4.2 更适合生产的方式
对于严格固定的格式,dissect 比复杂正则更高效;对于半结构化日志,再使用 grok。
dissect {
mapping => {
"message" => "%{level} %{date} %{time},%{millis} [com.example.%{module}] - DAU|%{user_id}|%{action}|%{vip}|%{price}"
}
}
之后仍需使用 date 和 mutate 转换时间与数值类型。
5. date filter 与时间戳
5.1 替换 @timestamp
日志里的业务时间需要转换成 Elasticsearch 日期类型,并用于 Kibana 时间筛选。
date {
match => ["datetime", "yyyy-MM-dd HH:mm:ss"]
target => "@timestamp"
}
如果日志时间没有时区信息,应明确指定时区:
date {
match => ["datetime", "yyyy-MM-dd HH:mm:ss"]
timezone => "Asia/Shanghai"
target => "@timestamp"
}
5.2 保留原时间字段
若希望同时保留原始业务时间:
date {
match => ["datetime", "yyyy-MM-dd HH:mm:ss"]
timezone => "Asia/Shanghai"
target => "event.created"
}
5.3 没有指定 target 时
date 插件默认把解析结果写入 @timestamp。显式写出 target => "@timestamp" 更容易审阅,也能避免团队成员误解。
6. 写入 Elasticsearch 自定义索引
完整配置示例:/etc/logstash/config/04-business-to-es.conf
input {
file {
path => ["/tmp/demo-app.log"]
start_position => "beginning"
sincedb_path => "/var/lib/logstash/sincedb-demo-business"
}
}
filter {
mutate {
split => {
"message" => "|"
}
add_field => {
"prefix" => "%{[message][0]}"
"user_id" => "%{[message][1]}"
"action" => "%{[message][2]}"
"vip" => "%{[message][3]}"
"price" => "%{[message][4]}"
}
}
mutate {
split => {
"prefix" => " "
}
add_field => {
"datetime" => "%{[prefix][1]} %{[prefix][2]}"
}
remove_field => ["message", "prefix", "@version"]
}
mutate {
convert => {
"price" => "float"
"user_id" => "integer"
"vip" => "integer"
}
}
date {
match => ["datetime", "yyyy-MM-dd HH:mm:ss"]
timezone => "Asia/Shanghai"
target => "@timestamp"
}
}
output {
elasticsearch {
hosts => [
"http://192.0.2.11:9200",
"http://192.0.2.12:9200",
"http://192.0.2.13:9200"
]
index => "demo-business-%{+yyyy.MM.dd}"
}
}
索引命名要求:
- 只能使用小写字母。
- 可以使用数字、点、下划线和连字符。
- 不要使用空格、反斜杠、斜杠、星号、问号、引号、尖括号、竖线、逗号或井号。
%{+yyyy.MM.dd}使用事件的@timestamp生成日期后缀。
验证:
GET http://192.0.2.11:9200/_cat/indices/demo-business-*?v
GET http://192.0.2.11:9200/demo-business-*/_search?pretty&size=3
7. ELFK 解析 Nginx 访问日志
7.1 避免重复解析
有两条常见路线:
- Filebeat Nginx 模块 + Elasticsearch Ingest Pipeline:模块的字段解析通常依赖 Elasticsearch Ingest Pipeline,Filebeat 负责采集并携带相关元数据。若中间经过 Logstash,应确认 Pipeline 元数据能被正确传递,或者由 Logstash 完成相应解析。
- Logstash Grok 解析:Filebeat 只发送原始日志,由 Logstash 统一完成解析。
不建议在没有明确数据处理边界的情况下同时启用模块解析和 Logstash Grok,再对相同内容重复处理。这会导致字段覆盖、重复计算和排错困难。
7.2 原始 Nginx 日志格式
以下日志使用 Nginx 常见格式:
192.0.2.10 - - [15/Jul/2026:14:32:55 +0800] "GET /pc HTTP/1.1" 200 263 "-" "Mozilla/5.0"
%{HTTPD_COMMONLOG} 可提取:
clientip
ident
auth
verb
request
rawrequest
response
bytes
referrer
agent
timestamp
7.3 Logstash Beats 输入
input {
beats {
port => 9999
}
}
filter {
grok {
match => {
"message" => "%{HTTPD_COMMONLOG}"
}
tag_on_failure => ["_nginx_parse_failure"]
}
geoip {
source => "clientip"
target => "geoip"
}
useragent {
source => "agent"
target => "user_agent"
}
date {
match => ["timestamp", "dd/MMM/yyyy:HH:mm:ss Z"]
target => "@timestamp"
}
mutate {
remove_field => ["message", "@version"]
}
}
output {
elasticsearch {
hosts => [
"http://192.0.2.11:9200",
"http://192.0.2.12:9200",
"http://192.0.2.13:9200"
]
index => "demo-nginx-%{+yyyy.MM.dd}"
}
}
要点:
useragent.source应使用 Grok 解析出的agent,不要对整个message再次解析。geoip.source必须是可查询的 IP 地址。geoip.target的坐标字段需要在 Elasticsearch 中映射为geo_point。- 日期格式包含
+0800时,不需要再强制指定相同偏移;没有时区时要明确时区。 _nginx_parse_failure标签可用于查找解析失败的文档。
8. Filebeat 输出到 Logstash
Filebeat 仅采集原始日志的配置:
filebeat.inputs:
- type: filestream
id: demo-nginx-raw
paths:
- /var/log/nginx/access.log
output.logstash:
hosts:
- "192.0.2.13:9999"
使用 Filebeat 模块并交给 Logstash 补充处理时:
filebeat.config.modules:
path: ${path.config}/modules.d/*.yml
reload.enabled: true
reload.period: 5s
output.logstash:
hosts:
- "192.0.2.13:9999"
示例只使用明文传输,仅适合隔离的实验网络。生产环境应为 Filebeat 到 Logstash 的链路配置 TLS 和访问控制。
为避免旧采集状态影响实验,可以指定新的独立数据目录:
sudo install -d -o filebeat -g filebeat /var/lib/filebeat-elk-demo
sudo filebeat -e \
-c /etc/filebeat/config/15-nginx-to-logstash.yml \
--path.data /var/lib/filebeat-elk-demo
建议先用 output.console 检查 Filebeat 发出的事件,再切换到 Logstash。
9. 自定义 Grok Pattern
9.1 pattern 文件
例如创建 /etc/logstash/patterns/demo.pattern:
DEMO_SCHOOL [A-Za-z][A-Za-z0-9_-]*
DEMO_CLASS [A-Za-z0-9_-]+
DEMO_YEAR \d{4}
9.2 在 Grok 中引用
grok {
patterns_dir => ["/etc/logstash/patterns"]
match => {
"message" => "%{DEMO_YEAR:year} %{DEMO_SCHOOL:school} %{DEMO_CLASS:class_name} %{IPV4:client_ip}"
}
tag_on_failure => ["_custom_parse_failure"]
}
对应测试日志:
2026 demo-school class-a 192.0.2.20
注意:
- 自定义 Pattern 名通常使用大写字母和数字。
- Pattern 必须写入独立的
.pattern文件或正确配置的 patterns 目录。 - 字段名使用小写、数字和下划线更便于查询。
- 不要从用户输入中直接构造正则,避免性能和注入风险。
10. geoip 与 useragent
10.1 geoip
geoip {
source => "client_ip"
target => "geoip"
}
可用字段通常包括:
geoip.location
geoip.country_name
geoip.city_name
geoip.timezone
Kibana Maps 使用坐标字段,因此 Elasticsearch 中必须将 geoip.location 映射为 geo_point。
注意:
- 私网 IP 通常无法得到可靠地理位置。
- IP 地理定位只能作为近似结果。
- 第三方 IP 数据的使用应遵守许可证和隐私要求。
- 真实日志在共享或展示前应脱敏。
10.2 useragent
useragent {
source => "agent"
target => "user_agent"
}
可得到浏览器、操作系统、版本和设备类型等信息。常见字段:
user_agent.original
user_agent.name
user_agent.version
user_agent.device.name
user_agent.os.name
在 Kibana 中可对操作系统或设备名称做 Terms 聚合,制作设备类型分布图。
11. 多分支处理
11.1 使用输入类型分支
input {
file {
path => ["/tmp/demo-web.log"]
start_position => "beginning"
sincedb_path => "/var/lib/logstash/sincedb-demo-web"
type => "web"
}
beats {
port => 9999
type => "beats"
}
tcp {
port => 8888
type => "tcp"
}
}
filter {
if [type] == "web" {
grok {
match => {
"message" => "%{HTTPD_COMMONLOG}"
}
tag_on_failure => ["_web_parse_failure"]
}
date {
match => ["timestamp", "dd/MMM/yyyy:HH:mm:ss Z"]
target => "@timestamp"
}
} else if [type] == "beats" {
mutate {
remove_field => ["@version"]
}
} else {
grok {
patterns_dir => ["/etc/logstash/patterns"]
match => {
"message" => "%{DEMO_YEAR:year} %{DEMO_SCHOOL:school} %{DEMO_CLASS:class_name} %{IPV4:client_ip}"
}
}
}
}
11.2 输出条件路由
output {
if [type] == "web" {
elasticsearch {
hosts => ["http://192.0.2.11:9200"]
index => "demo-web-%{+yyyy.MM.dd}"
}
} else if [type] == "beats" {
elasticsearch {
hosts => ["http://192.0.2.11:9200"]
index => "demo-beats-%{+yyyy.MM.dd}"
}
} else {
elasticsearch {
hosts => ["http://192.0.2.11:9200"]
index => "demo-tcp-%{+yyyy.MM.dd}"
}
}
}
建议:
- 新设计优先使用明确的业务字段或
tags,减少对旧type字段的依赖。 - 输入、过滤和输出条件应相互对应。
- 每个事件只能进入预期的唯一索引。
- 对解析失败的数据增加失败标签和独立处理路径,而不是静默丢弃。
12. Logstash 多实例
多实例表示启动多个独立 Logstash 进程。
每个实例应具有:
- 独立配置文件。
- 独立
--path.data。 - 互不冲突的监听端口。
- 独立的服务单元或进程管理方式。
示例:
sudo install -d -o logstash -g logstash /var/lib/logstash-file-a
sudo install -d -o logstash -g logstash /var/lib/logstash-file-b
logstash -r -f /etc/logstash/config/demo-a.conf \
--path.data /var/lib/logstash-file-a
logstash -r -f /etc/logstash/config/demo-b.conf \
--path.data /var/lib/logstash-file-b
不要用 /tmp/logstash-* 保存长期状态,因为临时目录可能被清理。
需要避免:
- 两个实例监听相同 TCP/Beats 端口。
- 两个实例读取相同文件却使用不同状态,造成重复数据。
- 多个实例写入相同索引但字段结构不一致。
- 误把
--path.data当成输出数据目录,它主要保存内部状态和持久化数据。
13. 单进程多 Pipeline
13.1 pipelines.yml
Logstash 软件包通常使用:
/etc/logstash/pipelines.yml
示例:
- pipeline.id: demo_file
path.config: "/etc/logstash/conf.d/02-file.conf"
- pipeline.id: demo_beats
path.config: "/etc/logstash/conf.d/03-beats.conf"
启动:
sudo systemctl restart logstash
sudo journalctl -u logstash -f
注意:
pipeline.id在同一进程内必须唯一。path.config必须指向对应配置文件。- 如果启动命令使用
-f,Logstash 会忽略pipelines.yml。 - 不同 Pipeline 的输入端口、输出索引和条件路由应清晰隔离。
13.2 Pipeline、分支和多实例的区别
| 概念 | 本质 | 示例 |
|---|---|---|
| Pipeline | 一个完整的 input → filter → output 数据流 | Nginx 日志管道 |
| 多分支 | 在同一 Pipeline 内使用 if/else | 按 type 或 tags 路由 |
| 单进程多 Pipeline | 一个 Logstash 进程加载多个 Pipeline | pipelines.yml |
| 多实例 | 多个独立 Logstash 进程 | 不同配置、端口和数据目录 |
一个 Pipeline 内可以包含多分支;一个进程可以运行多个 Pipeline;多实例则是多个进程。
14. Kibana 时区问题
14.1 时间的处理链路
正确的时间链路:
原始日志时间 → date filter → @timestamp → Elasticsearch 日期字段 → Kibana 时区显示
常见问题:
- 原始日志没有时区,却被默认按 UTC 解析。
- 业务时间和
@timestamp不一致。 - Kibana 时间范围与用户预期时区不一致。
- 浏览器仍使用旧的时区设置。
14.2 设置 date filter 时区
日志时间没有偏移量时:
date {
match => ["datetime", "yyyy-MM-dd HH:mm:ss"]
timezone => "Asia/Shanghai"
target => "@timestamp"
}
带偏移量的 Nginx 日志:
15/Jul/2026:14:32:55 +0800
可使用:
date {
match => ["timestamp", "dd/MMM/yyyy:HH:mm:ss Z"]
target => "@timestamp"
}
14.3 Kibana 显示时区
在 Kibana 的用户设置中选择:
Time zone for date formatting → Asia/Shanghai
或者选择浏览器时区。保存后刷新页面,并重新检查 Discover 的时间范围。
15. 完整 ELFK 配置示例
15.1 Filebeat
filebeat.inputs:
- type: filestream
id: demo-nginx-elk
paths:
- /var/log/nginx/access.log
output.logstash:
hosts:
- "192.0.2.13:9999"
15.2 Logstash
input {
beats {
port => 9999
}
}
filter {
grok {
match => {
"message" => "%{HTTPD_COMMONLOG}"
}
tag_on_failure => ["_nginx_parse_failure"]
}
geoip {
source => "clientip"
target => "geoip"
}
useragent {
source => "agent"
target => "user_agent"
}
date {
match => ["timestamp", "dd/MMM/yyyy:HH:mm:ss Z"]
target => "@timestamp"
}
}
output {
elasticsearch {
hosts => [
"http://192.0.2.11:9200",
"http://192.0.2.12:9200",
"http://192.0.2.13:9200"
]
index => "demo-nginx-%{+yyyy.MM.dd}"
}
}
15.3 验证链路
# 1. 检查 Logstash 是否监听 Beats 端口
sudo ss -ntlp | grep ':9999'
# 2. 测试 Logstash 配置
logstash -f /etc/logstash/config/15-nginx-elk.conf \
--config.test_and_exit
# 3. 启动 Filebeat
sudo filebeat test config -c /etc/filebeat/config/15-nginx-to-logstash.yml
sudo filebeat test output -c /etc/filebeat/config/15-nginx-to-logstash.yml
sudo filebeat -e -c /etc/filebeat/config/15-nginx-to-logstash.yml
# 4. 追加请求
curl -s -o /dev/null http://192.0.2.11/
# 5. 查看索引
curl -s "http://192.0.2.11:9200/_cat/indices/demo-nginx-*?v"
16. 常见故障排查
16.1 Logstash 配置
logstash -f /etc/logstash/config/demo.conf \
--config.test_and_exit
sudo journalctl -u logstash -f
重点检查:
- 配置文件语法。
- 插件是否已安装。
- 输入端口是否被占用。
- 输出 Elasticsearch 是否可达。
- Pattern 文件路径和语法。
- 字段引用是否使用正确格式,例如
[user_id]。
16.2 文件没有被重新读取
排查:
filebeat --version
sudo ls -la /var/lib/logstash/
sudo find /usr/share/logstash/data/plugins/inputs/file \
-maxdepth 1 -name '.sincedb_*' -ls
处理:
- 检查是否已有
sincedb。 - 给测试任务使用新的
sincedb_path。 - 保留原状态备份,不要在未知任务上直接删除。
16.3 Grok 解析失败
在 Kibana 中搜索:
tags: "_nginx_parse_failure" or tags: "_custom_parse_failure"
比较:
- 原始
message。 - 实际日志格式。
- Pattern 对空格、方括号和引号的要求。
- Grok Debugger 的测试结果。
16.4 地图没有坐标
检查:
GET http://192.0.2.11:9200/demo-nginx-*/_mapping
确认:
geoip.location是否存在。- 字段类型是否为
geo_point。 - IP 是否为可定位的公网地址。
- Kibana 是否选择了坐标字段。
16.5 时间显示相差 8 小时
依次检查:
- 原始日志是否带时区。
datefilter 是否指定timezone。@timestamp是否被正确覆盖。- Kibana 用户时区是否为
Asia/Shanghai。 - 浏览器是否刷新了新设置。
16.6 多条日志重复
可能原因:
- Filebeat 多实例共用数据目录。
- Logstash 多实例读取同一文件。
sincedb被清理或更换。- 同时启用 Filebeat 模块和手工输入。
17. ELFK 可视化项目练习
17.1 目标
部署一个实验业务站点,使用 ELFK 分析访问日志:
- 可选 WordPress 或 Kodcloud。
- Web 服务产生访问日志。
- Filebeat 采集日志。
- Logstash 完成解析、时间和 User-Agent 处理。
- Elasticsearch 存储结构化数据。
- Kibana 制作 Dashboard。
17.2 Dashboard 指标
| 指标 | 字段与聚合 |
|---|---|
| 真实客户端 IP | clientip 或 source.ip 的 Cardinality |
| PV | 文档 Count |
| 带宽 | bytes 或 send_bytes 的 Sum |
| VIP 用户 | 对 vip 做 Terms,统计 0/1 分布 |
| 设备类型 | user_agent.device.name 的 Terms |
| 城市分布 | geoip.city_name 的 Terms |
| 地理分布 | geoip.location 的 Maps 图层 |
| 状态码 | response 或 status 的 Terms |
| 热门 URI | request 或 uri 的 Terms |
| 访问趋势 | 基于 @timestamp 的 Date Histogram |
17.3 Grafana 扩展
可通过 Elasticsearch 数据源在 Grafana 中展示:
- IP 数。
- 带宽。
- VIP 用户分布。
- PV。
- 设备类型。
- 城市分布。
- 状态码和访问趋势。
安全建议:
- 使用只读且权限范围受限的 Elasticsearch 账号。
- 不要在 Grafana 面板中公开真实用户 IP。
- 查询大范围数据时设置合理时间范围、过滤条件和缓存。
18. 总结
fileinput 的start_position只在首次读取新文件时生效。sincedb保存读取位置,重放旧数据应使用独立状态路径。mutate适合拆分和转换已知结构的字段。- 固定格式优先考虑
dissect,复杂文本再使用grok。 date负责把业务时间写入@timestamp或指定日期字段。- 无时区时间必须明确指定
timezone。 geoip和useragent应使用已经解析出的 IP、User-Agent 字段。- Filebeat 模块解析和 Logstash Grok 不应重复处理同一日志。
- 多分支使用
if/else条件控制 Filter 和 Output。 - 单进程可运行多个 Pipeline,多实例是多个独立进程。
- 多实例必须隔离配置、端口和
path.data。 - Kibana 时区问题要同时检查原始时间、
datefilter 和显示设置。