什么是结构化日志？为什么应该使用 JSONL？

结构化日志意味着将日志条目作为带有命名字段的数据输出，而不是自由格式的文本字符串。JSONL 是理想的格式，因为每行都是一个独立的 JSON 对象，日志平台无需正则表达式即可解析。这为您提供可靠的字段提取、类型保留，以及与所有主流日志聚合工具的兼容性，包括 ELK、Fluentd、CloudWatch 和 GCP Logging。

如何将 JSONL 日志发送到 ELK Stack？

最简单的方式是使用 Filebeat 并将 json.keys_under_root 设为 true。Filebeat 监视您的 JSONL 日志文件，将每行解析为 JSON，并将结构化字段转发到 Elasticsearch。如果需要转换或丰富，在 Filebeat 和 Elasticsearch 之间添加使用 json 编解码器的 Logstash。然后 Kibana 可以搜索、可视化和对任何字段设置告警。

Fluentd 和 Fluent Bit 有什么区别？

Fluent Bit 是为资源受限环境（如 Kubernetes 边车和 IoT 设备）设计的轻量级日志处理器。它使用大约 450KB 内存，专注于收集和转发。Fluentd 是功能完整的版本，拥有超过 500 个插件，支持复杂的路由、缓冲和转换。使用 Fluent Bit 进行收集，使用 Fluentd 进行聚合，或对简单管道单独使用 Fluent Bit。

云日志服务会自动解析 JSONL 吗？

是的。AWS CloudWatch、GCP Cloud Logging 和 Azure Monitor 都自动将 JSON 日志行解析为结构化字段。在 AWS 上，CloudWatch Logs Insights 可以直接查询任何 JSON 字段。在 GCP 上，在 Cloud Run 或 GKE 上将 JSONL 写入 stdout 会创建结构化 LogEntry 对象。在 Azure 上，Application Insights 解析 JSON 跟踪并使字段在 KQL 查询中可用。

JSONL 输出应该使用哪个日志库？

Python 推荐使用 structlog，因为它有处理器管道和简洁的 API。Node.js 推荐使用 pino，因为它速度快且原生输出 JSONL。Go 推荐使用 zerolog，因为它零内存分配的高性能。三者默认都输出每行一个 JSON 对象，支持添加自定义字段、用于请求上下文的子日志器和可配置的日志级别。

如何避免结构化日志的性能问题？

使用异步日志器如 pino 或 zerolog，在主线程之外序列化 JSON。避免在 INFO 级别记录大型载荷。对高频事件进行采样而不是记录每次发生。将日志写入本地文件并使用 Filebeat 或 Fluent Bit 等边车异步传输。设置最大行大小以防止过大的条目影响管道。

JSONL 结构化日志

使用 JSONL（JSON Lines）格式进行结构化日志的综合指南。学习与 ELK Stack、Fluentd、CloudWatch、GCP Logging 和 Azure Monitor 的集成，附生产级代码示例。

最后更新：2026年2月

为什么使用 JSONL 做结构化日志？

传统的纯文本日志人类可读，但机器几乎无法可靠解析。一行像 '2024-01-15 ERROR User login failed for admin' 这样的日志将严重级别、事件类型和用户名埋在非结构化字符串中。每个日志聚合工具都不得不依赖脆弱的正则表达式来提取信息，任何日志格式的变更都会破坏管道。

结构化日志通过将每条日志条目作为具有明确字段的 JSON 对象输出来解决这个问题。JSONL（JSON Lines）更进一步：每行一个 JSON 对象，没有包裹数组，没有尾随逗号。这使得 JSONL 日志易于追加、可流式传输，并且所有主流日志平台都能轻松解析。在本指南中，您将学习如何从 Python、Node.js 和 Go 生成 JSONL 日志，以及如何将它们发送到 ELK、Fluentd 和三大主要云平台。

与 CSV 或 XML 等其他结构化格式相比，JSONL 在灵活性、工具支持和人类可读性之间提供了最佳平衡。字段可以嵌套，类型得以保留，而且您永远不需要预先定义固定的 Schema。这就是为什么 JSONL 已成为现代基础设施中结构化日志的事实标准。

各语言日志库

大多数现代日志库原生支持结构化 JSON 输出，或通过简单的配置变更即可实现。以下是 Python、Node.js 和 Go 的推荐库，每个都能生成兼容 JSONL 的输出。

Python: structlog

Node.js: pino

最快

pino 是最快的 Node.js 日志库，默认零配置输出 JSONL。它通过异步写入和最小化的序列化路径实现低开销。配套的 pino-pretty 包为本地开发提供人类可读的输出。

Node.js: pino

import pino from 'pino';

// pino outputs JSONL by default
const log = pino({
  level: 'info',
  timestamp: pino.stdTimeFunctions.isoTime,
});

// Each call produces one JSONL line
log.info({ userId: 'u-42', ip: '10.0.0.1' }, 'user.login');
// {"level":30,"time":"2026-02-15T08:30:00.000Z","userId":"u-42","ip":"10.0.0.1","msg":"user.login"}

log.error({ host: 'db-primary', retries: 3 }, 'db.connection_failed');
// {"level":50,"time":"2026-02-15T08:30:01.000Z","host":"db-primary","retries":3,"msg":"db.connection_failed"}

// Child loggers inherit context
const reqLog = log.child({ requestId: 'req-abc-123' });
reqLog.info({ path: '/api/users' }, 'request.start');

Go: zerolog

零内存分配

zerolog 是 Go 的零内存分配 JSON 日志库，专为高吞吐量服务中的最大性能而设计。它直接写入 io.Writer 而无需中间分配，非常适合延迟敏感的应用。其链式 API 既优雅又高效。

Go: zerolog

package main

import (
    "os"
    "github.com/rs/zerolog"
    "github.com/rs/zerolog/log"
)

func main() {
    // Configure JSONL output to stdout
    zerolog.TimeFieldFormat = zerolog.TimeFormatUnix
    log.Logger = zerolog.New(os.Stdout).With().Timestamp().Logger()

    // Each call produces one JSONL line
    log.Info().
        Str("user_id", "u-42").
        Str("ip", "10.0.0.1").
        Msg("user.login")
    // {"level":"info","user_id":"u-42","ip":"10.0.0.1","time":1739608200,"message":"user.login"}

    log.Error().
        Str("host", "db-primary").
        Int("retries", 3).
        Msg("db.connection_failed")
}

ELK Stack 集成

ELK Stack（Elasticsearch、Logstash、Kibana）是部署最广泛的开源日志管理平台。JSONL 日志无缝集成，因为 Logstash 和 Filebeat 可以原生解析 JSON，无需复杂的 grok 模式。

Filebeat 是轻量级日志收集器，它监视您的 JSONL 日志文件并将其转发到 Logstash 或 Elasticsearch。将 json.keys_under_root 设为 true 可将 JSON 字段提升为 Elasticsearch 的顶层字段，使其可直接在 Kibana 中搜索。

Filebeat 配置

# filebeat.yml
filebeat.inputs:
  - type: log
    enabled: true
    paths:
      - /var/log/app/*.jsonl
    json.keys_under_root: true
    json.add_error_key: true
    json.message_key: message
    json.overwrite_keys: true

output.elasticsearch:
  hosts: ["http://elasticsearch:9200"]
  index: "app-logs-%{+yyyy.MM.dd}"

# Optional: send to Logstash instead
# output.logstash:
#   hosts: ["logstash:5044"]

如果您需要在索引之前转换或丰富日志，Logstash 位于 Filebeat 和 Elasticsearch 之间。json 编解码器自动解析每行 JSONL。使用 mutate 过滤器重命名字段、添加标签或在存储前移除敏感数据。

Logstash 管道

# logstash.conf
input {
  beats {
    port => 5044
    codec => json
  }
}

filter {
  # Parse timestamp from the JSON field
  date {
    match => ["timestamp", "ISO8601"]
    target => "@timestamp"
  }

  # Add environment tag
  mutate {
    add_field => { "environment" => "production" }
    remove_field => ["agent", "ecs", "host"]
  }

  # Route by log level
  if [level] == "error" or [level] == "fatal" {
    mutate { add_tag => ["alert"] }
  }
}

output {
  elasticsearch {
    hosts => ["http://elasticsearch:9200"]
    index => "app-logs-%{+YYYY.MM.dd}"
  }
}

Fluentd 与 Fluent Bit

Fluentd 及其轻量级兄弟 Fluent Bit 是 CNCF 毕业项目，在 Kubernetes 环境中广泛使用。两者都原生处理 JSONL 日志，可以将其转发到几乎任何目标，从 Elasticsearch 到 S3 再到云原生日志服务。

Fluent Bit 是 Kubernetes 和资源受限环境中首选的日志收集器。它仅消耗约 450KB 内存，每秒可处理数十万条记录。json 解析器无需任何自定义配置即可处理 JSONL 输入。

Fluent Bit 配置

[SERVICE]
    Flush        5
    Daemon       Off
    Log_Level    info
    Parsers_File parsers.conf

[INPUT]
    Name         tail
    Path         /var/log/app/*.jsonl
    Parser       json
    Tag          app.*
    Refresh_Interval 5

[FILTER]
    Name         modify
    Match        app.*
    Add          cluster production-us-east-1
    Add          service my-api

[OUTPUT]
    Name         es
    Match        app.*
    Host         elasticsearch
    Port         9200
    Index        app-logs
    Type         _doc
    Logstash_Format On

Fluentd 与 Fluent Bit 相比提供了更丰富的插件生态系统，拥有超过 500 个社区插件。当您需要高级路由、缓冲或转换时使用它。in_tail 插件配合 format json 原生读取 JSONL 文件。

Fluentd 配置

# fluentd.conf
<source>
  @type tail
  path /var/log/app/*.jsonl
  pos_file /var/log/fluentd/app.pos
  tag app.logs
  <parse>
    @type json
    time_key timestamp
    time_format %Y-%m-%dT%H:%M:%S%z
  </parse>
</source>

<filter app.logs>
  @type record_transformer
  <record>
    hostname "#{Socket.gethostname}"
    environment production
  </record>
</filter>

<match app.logs>
  @type elasticsearch
  host elasticsearch
  port 9200
  index_name app-logs
  logstash_format true
  <buffer>
    @type memory
    flush_interval 5s
    chunk_limit_size 5m
  </buffer>
</match>

云日志平台

三大主要云平台都接受 JSONL 格式的日志，并自动将 JSON 字段解析为可搜索、可过滤的属性。这消除了运行自己的日志基础设施的需要，同时提供相同的结构化查询能力。

AWS CloudWatch Logs

AWS

CloudWatch Logs 自动解析 JSON 日志条目，使每个字段都可通过 CloudWatch Logs Insights 查询。当您的应用在 ECS、Lambda 或配有 CloudWatch 代理的 EC2 上运行时，JSONL 输出无需额外配置即可作为结构化数据被索引。使用 Logs Insights 类 SQL 语法可在数秒内查询数百万条日志。

AWS CloudWatch Logs

# CloudWatch Logs Insights query examples
# Find all errors in the last hour
fields @timestamp, level, event, user_id
| filter level = "error"
| sort @timestamp desc
| limit 100

# Aggregate error counts by event type
fields event
| filter level = "error"
| stats count(*) as error_count by event
| sort error_count desc

# P99 latency by endpoint
fields path, duration_ms
| filter ispresent(duration_ms)
| stats pct(duration_ms, 99) as p99 by path
| sort p99 desc

GCP Cloud Logging

GCP

Google Cloud Logging（前身为 Stackdriver）将 JSON 负载视为具有一流支持的结构化日志条目。当您在 Cloud Run、GKE 或 Cloud Functions 上将 JSONL 写入 stdout 时，日志代理将每行解析为结构化 LogEntry。severity 字段直接映射到 Cloud Logging 的严重级别，jsonPayload 字段变为可索引和可搜索的。

GCP Cloud Logging

# Python example for Cloud Run / Cloud Functions
import json
import sys

def log(severity: str, message: str, **fields):
    """Write a JSONL log entry compatible with GCP Cloud Logging."""
    entry = {
        "severity": severity.upper(),  # Maps to Cloud Logging severity
        "message": message,
        **fields,
    }
    print(json.dumps(entry), file=sys.stdout, flush=True)

# GCP automatically parses these as structured logs
log("INFO", "user.login", user_id="u-42", ip="10.0.0.1")
log("ERROR", "db.timeout", host="db-primary", latency_ms=5200)

# Query in Cloud Logging:
# jsonPayload.user_id = "u-42"
# severity >= ERROR

Azure Monitor Logs

Azure

Azure Monitor 通过 Azure Monitor Agent 或直接 API 导入接收 JSONL 日志。Application Insights 自动解析 JSON 跟踪和自定义事件。KQL（Kusto 查询语言）提供了强大的结构化日志数据查询能力，支持聚合、时间序列分析和异常检测。

Azure Monitor Logs

// KQL queries for JSONL logs in Azure Monitor
// Find recent errors
AppTraces
| where SeverityLevel >= 3
| extend parsed = parse_json(Message)
| project TimeGenerated, parsed.event, parsed.user_id,
          parsed.error_message
| order by TimeGenerated desc
| take 100

// Error rate over time (5-minute buckets)
AppTraces
| where SeverityLevel >= 3
| summarize ErrorCount = count() by bin(TimeGenerated, 5m)
| render timechart

// Top error events
AppTraces
| where SeverityLevel >= 3
| extend parsed = parse_json(Message)
| summarize Count = count() by tostring(parsed.event)
| top 10 by Count

JSONL 日志最佳实践

在所有服务中遵循一致的规范使 JSONL 日志更易于查询、关联和告警。这些最佳实践来自每天处理数十亿条日志的生产系统。

使用一致的日志级别

采用标准的严重级别并在所有服务中一致使用。最常见的约定使用五个级别：DEBUG 用于开发诊断，INFO 用于正常操作，WARN 用于可恢复的问题，ERROR 用于需要关注的故障，FATAL 用于不可恢复的崩溃。在导入时将数字级别（如 pino 的 10-60 刻度）映射为这些字符串名称，以实现统一查询。

使用一致的日志级别

{"level":"debug","event":"cache.miss","key":"user:42","timestamp":"2026-02-15T08:30:00Z"}
{"level":"info","event":"request.completed","method":"GET","path":"/api/users","status":200,"duration_ms":45,"timestamp":"2026-02-15T08:30:01Z"}
{"level":"warn","event":"rate_limit.approaching","client_id":"c-99","current":950,"limit":1000,"timestamp":"2026-02-15T08:30:02Z"}
{"level":"error","event":"payment.failed","order_id":"ord-123","error":"card_declined","timestamp":"2026-02-15T08:30:03Z"}
{"level":"fatal","event":"startup.failed","reason":"missing DATABASE_URL","timestamp":"2026-02-15T08:30:04Z"}

标准化字段名称

为所有服务的通用字段定义共享 Schema。字段名使用 snake_case，时间戳使用 ISO 8601，关联标识符使用一致的命名。至少每条日志条目应包含：timestamp、level、event（机器可读的事件名称）和 service。请求范围的条目应包含 request_id 和 user_id 以便追踪。

标准化字段名称

// Recommended field schema
{
  "timestamp": "2026-02-15T08:30:00.000Z",  // ISO 8601, always UTC
  "level": "info",                            // debug|info|warn|error|fatal
  "event": "order.created",                    // dot-notation event name
  "service": "order-api",                      // emitting service
  "version": "1.4.2",                          // service version
  "request_id": "req-abc-123",                 // correlation ID
  "trace_id": "4bf92f3577b34da6",              // distributed trace ID
  "user_id": "u-42",                           // authenticated user
  "duration_ms": 120,                          // numeric, not string
  "order_id": "ord-789",                       // domain-specific context
  "items_count": 3                             // domain-specific context
}

性能注意事项

结构化日志为每次日志调用增加了序列化开销。在高吞吐量服务中，这可能变得显著。使用异步日志（pino、zerolog）将序列化从热路径移开。避免在 INFO 级别记录大型对象或请求/响应正文。对高频调试日志使用采样。写入本地文件并让边车（Filebeat、Fluent Bit）处理传输，而不是在日志路径中同步发送网络请求。

使用异步日志库（pino、zerolog），避免在 JSON 序列化期间阻塞主线程。

永远不要在 INFO 级别记录完整的请求或响应正文。使用 DEBUG 级别，仅在排查问题时启用。

对高频事件进行采样。每 100 个健康检查请求记录 1 个，而非全部记录。

将日志写入本地文件，使用 Filebeat 或 Fluent Bit 异步传输。避免在日志路径中进行同步网络调用。

设置最大日志行大小（如 16KB），防止过大的条目堵塞管道。

使用 logrotate 或内置的库轮转功能进行日志文件轮转，防止磁盘耗尽。

在线验证您的 JSONL 日志

使用我们免费的浏览器工具检查、验证和转换 JSONL 日志文件。无需上传，所有处理在本地完成。

JSONL streaming

large JSONL files

JSONL validator

在浏览器中检查 JSONL 日志

查看、搜索和验证最大 1GB 的 JSONL 日志文件。即时加载，客户端处理，100% 私密。

JSONL 结构化日志

为什么使用 JSONL 做结构化日志？

各语言日志库

Python: structlog

Node.js: pino

Go: zerolog

ELK Stack 集成

Fluentd 与 Fluent Bit

云日志平台

AWS CloudWatch Logs

GCP Cloud Logging

Azure Monitor Logs

JSONL 日志最佳实践

使用一致的日志级别

标准化字段名称

性能注意事项

在线验证您的 JSONL 日志

在浏览器中检查 JSONL 日志

常见问题

什么是结构化日志？为什么应该使用 JSONL？

如何将 JSONL 日志发送到 ELK Stack？

Fluentd 和 Fluent Bit 有什么区别？

云日志服务会自动解析 JSONL 吗？

JSONL 输出应该使用哪个日志库？

如何避免结构化日志的性能问题？