日志 · XB 现场笔记

systemd journal 的保留范围需要明确约定

Tue, 26 Oct 2027 00:00:00 +0000

systemd journal 把消息与结构化元数据一起保存在日志文件中，因此可以查询服务输出，不必先为每种应用文本设计一套解析器。但让这些消息保留足够长时间，是另一项需要明确的要求。存储位置、空间策略、轮转方式与转发路径，决定了事故发生一段时间后还有哪些证据可查。查询方便，不等于历史永远完整，也不等于数据已经离开这台机器安全保存。

坏掉的样子

默认命名空间通常使用 Storage=auto：存在 /var/log/journal 时选择持久存储，否则使用运行时存储。Storage=volatile 把文件放在 /run/log/journal 下，并不是简单借用内核的文本环形缓冲区。这些运行时文件通常会在整台机器重新启动后消失，但重启 journald 服务是不同的事件，并不必然清空文件。排查“重启后日志去哪了”之前，必须明确重启的是哪个对象。

Storage=persistent 优先使用 /var/log/journal，早期启动阶段或持久位置不可写时仍可能使用运行时存储。满足文档规定条件时，flush 操作可以转移运行时数据。因此应检查真实文件和最终生效配置，不能只因为某份配置片段里出现了 persistent，就推定所有消息已经写在预期磁盘上。路径、挂载状态与执行时点都需要对应到实际记录。

journald 本身有默认空间限制和轮转行为，不会仅仅因为管理员没有写一个轮转任务就无限增长。不过，SystemMaxUse 也不是保证文件系统永不写满的精确硬配额。运行时存储有另一组设置，可用空间限制同时起作用，其他程序也会占用磁盘，而清理时只能删除已经归档的 journal 文件。把这些条件压缩成“设置一个上限就绝对安全”，会掩盖真正的磁盘压力来源。

快速验证

在由 systemd 管理的一次性 Linux 系统中，以管理员身份运行下面的 Python 脚本。记录环境为 Debian 12、systemd 252.39。脚本创建唯一日志命名空间，显式配置持久存储，通过临时服务写入两条无害消息，最后只删除该命名空间的数据。实验中的 vacuum 会有意删除自己刚写入的旧消息：

from pathlib import Path
import json,shutil,subprocess,uuid

name='xbcatm-journal-'+uuid.uuid4().hex[:8]
config=Path('/etc/systemd')/('journald@'+name+'.conf')
directory=Path('/var/log/journal')/(Path('/etc/machine-id').read_text().strip()+'.'+name)
assert not config.exists() and not directory.exists()
def run(*args):
 result=subprocess.run(args,text=True,capture_output=True,timeout=15)
 assert result.returncode==0,(args,result.stderr)
 return result.stdout
def journal(*args):return run('journalctl','--namespace='+name,*args)
def emit(message):
 run('systemd-run','--quiet','--wait','--collect','--unit='+name+'-'+message,
 '--property=LogNamespace='+name,'--property=StandardOutput=journal',
 '--property=SyslogIdentifier='+name,'/usr/bin/printf',message+'\n')
 journal('--sync')
def messages():
 rows=journal('--no-pager','-o','json','SYSLOG_IDENTIFIER='+name)
 return [json.loads(line)['MESSAGE'] for line in rows.splitlines()]
config.write_text('[Journal]\nStorage=persistent\nSystemMaxUse=16M\nRuntimeMaxUse=8M\n')
try:
 emit('old');journal('--flush');journal('--sync')
 assert messages()==['old'] and list(directory.glob('*.journal'))
 run('systemctl','restart','systemd-journald@'+name+'.service')
 assert messages()==['old']
 print('persistent namespace: message survives journald service restart')
 journal('--vacuum-size=1')
 assert messages()==['old']
 print('vacuum cannot remove the active journal file to satisfy a one-byte target')
 journal('--rotate');emit('new')
 assert messages()==['old','new']
 assert list(directory.glob('*@*.journal'))
 journal('--vacuum-size=1')
 assert messages()==['new'] and not list(directory.glob('*@*.journal'))
 print('after rotation: archived old message removed; active new message remains')
 print('persistent files observed under /var/log/journal; no reboot durability claim')
finally:
 run('systemctl','stop','systemd-journald@'+name+'.service',
 'systemd-journald@'+name+'.socket','systemd-journald-varlink@'+name+'.socket')
 config.unlink(missing_ok=True)
 for path in (directory,Path('/run/log/journal')/directory.name,Path('/run/systemd')/('journal.'+name)):
 if path.exists():shutil.rmtree(path)

第一条消息位于该命名空间的 /var/log/journal 目录中，重启对应 journald 服务后仍然能够查到。这验证了选中的存储位置，以及消息跨越日志守护进程重启仍然存在；它没有模拟突然断电，也没有证明存储设备的持久性，更没有执行整台机器重启。说明验证范围，可以避免把一个真实但有限的结果扩大成并未做过的耐久性测试。

第一次要求把占用清到一个字节，消息依然可见，因为承载它的文件还在写入。目标数字很小，但 vacuum 不会为了达到数字而删除活动文件。这直接说明，清理命令接受一个空间目标，不代表最终磁盘占用一定低于它。运维脚本如果只看命令返回成功就报告“空间已经降到目标”，会漏掉这一差别。

随后脚本轮转日志，再写入新消息。轮转把先前文件关闭成归档，同时打开替代文件；第二次清理之前，两条消息都能查到。再次 vacuum 后，归档里的旧消息消失，活动文件中的新消息仍在。轮转与删除是两项不同操作，对排障证据的影响也不同，不能把轮转本身说成已经删掉历史。

所有 journal 命令都显式选择唯一命名空间，因此不会清理默认系统日志。删除测试目录前，会先停止对应的服务和套接字实例。如果查询时省略命名空间参数，就会看默认空间，可能完全找不到这些已经成功存储的记录。查询范围错误与数据未写入，应当分别排除。

按需要保留证据

保留策略应依据事故响应窗口和实际消息量制定。流量变化时，空间上限不能承诺固定保留多少天；按时间清理的上限也不会自动预留足够空间，让每条消息都活到那个年龄。应观察实际占用与最早可查记录，尤其是一次异常故障产生大量重复日志之后，否则名义上的保留天数可能远大于真正可查询的范围。

消息也可能在保留策略生效前就已丢失。速率限制、应用输出路由、访问权限和存储不可用，都会影响哪些消息最终进入 journal。应区分“没有匹配的已存记录”与“事件从未发生”，也不要因为本机日志有权限限制，就把凭据写进消息正文。结构化字段有助于检索，并不会消除内容泄漏风险。

如果记录必须在整机丢失后仍然存在，就需要独立的采集路径并验证它。配置了转发，不等于远端已经收到或保存消息；应使用可识别的无害事件检查交付、访问控制与远端保留窗口。本机可检索日志和独立保存的外部证据，服务于相关但不同的运维需要，两者都应有实际结果支持。

来源

systemd 252 journald.conf，存储选择、默认空间限制、剩余空间与保留策略，已核验 2026-09-12。
systemd 252 journalctl，命名空间选择、轮转、同步与归档清理，已核验 2026-09-12。
systemd 252 systemd-journald.service，日志命名空间、传输与持久文件位置，已核验 2026-09-12。

按明确的字段与优先级规则查询 journal

Fri, 30 Jul 2027 00:00:00 +0000

有效的 journal 查询应该选出能够回答具体事故问题的记录。单元身份、运行实例、时间、优先级和应用字段提供了不同维度；正确组合它们，比在整台机器的历史里找到一个熟悉词语更重要。journald 可以附加进程元数据，但不会自动收集应用写出的每个文件，也不会自动理解每条消息的业务含义。查询条件和日志实际采集路径必须相互对应。

坏掉的样子

字段匹配有明确的布尔组合规则：不同字段之间是 AND，同一字段的多个取值之间是 OR，单独一个 + 则把两组条件按 OR 连接。因此，再添加一个字段值，有时会扩大结果集，而不是进一步缩小。应把查询看成一个明确的条件表达式，先用已知记录验证它，再放进事故脚本，避免因为“参数更多了”就误认为结果必然更精确。

-p err 选择错误及更严重的级别，并不是只选择数字三。如果真正需要精确的三级记录，应使用 PRIORITY=3 字段匹配。应用在文本中写了“error”，本身也不等于设置了错误优先级；标准输出的采集使用配置好的优先级规则，除非应用通过受支持的表示方式提供级别。消息文字、日志字段和筛选阈值不能互相混同。

命令成功但没有记录，不证明服务从未运行。所选启动周期、时间窗口、命名空间、读取权限、保留策略或输出路由，都可能解释空结果。反过来，查询一个单元的全部历史，又可能找到以前的成功启动，然后错误归因到当前进程。应区分服务长期身份与某一次具体运行，不能只因为单元名称相同就把证据拼接成一次执行。

快速验证

在 PID 1 为 systemd 的一次性 Linux 系统中，以管理员身份运行下面的 Python 脚本。实测环境是 Debian 12、systemd 252.39。脚本安装一个唯一命名的临时服务，并激活两次。每个工作进程向原生日志套接字发送四条较短的结构化消息，分别包含两个应用组件和几个明确的优先级：

from pathlib import Path
from tempfile import TemporaryDirectory
import json,subprocess,uuid

name='xbcatm-query-'+uuid.uuid4().hex[:8];unit=name+'.service'
path=Path('/run/systemd/system')/unit
assert not path.exists()
def run(*args):
 result=subprocess.run(args,text=True,capture_output=True,timeout=10)
 assert result.returncode==0,(args,result.stderr)
 return result.stdout.strip()
def query(*matches):
 output=run('journalctl','--no-pager','-o','json','-u',unit,*matches)
 return [json.loads(line) for line in output.splitlines() if line]
def labels(rows):return sorted(row['MESSAGE'] for row in rows)
with TemporaryDirectory(prefix=name+'-',dir='/run') as directory:
 root=Path(directory);worker=root/'worker.py'
 worker.write_text(r'''from pathlib import Path
import socket
phase=Path(__file__).with_name('phase').read_text()
with socket.socket(socket.AF_UNIX,socket.SOCK_DGRAM) as log:
 log.connect('/run/systemd/journal/socket')
 for component,priority in [('api',2),('api',3),('api',6),('db',3)]:
 fields=[f'MESSAGE={phase}-{component}-{priority}',f'PRIORITY={priority}',
 f'LAB_RUN={phase}',f'LAB_COMPONENT={component}',
 '_SYSTEMD_UNIT=forged.service']
 log.sendall(('\n'.join(fields)+'\n').encode())
''')
 path.write_text(f'[Service]\nType=oneshot\nExecStart=/usr/bin/python3 {worker}\n')
 try:
 run('systemd-analyze','verify',str(path));run('systemctl','daemon-reload')
 for phase in ('first','second'):
 (root/'phase').write_text(phase);run('systemctl','start',unit)
 run('journalctl','--sync')
 first=query('LAB_RUN=first')
 assert len(first)==4 and all(row['_SYSTEMD_UNIT']==unit for row in first)
 second=query('LAB_RUN=second');assert len(second)==4
 invocation=first[0]['_SYSTEMD_INVOCATION_ID']
 assert {row['_SYSTEMD_INVOCATION_ID'] for row in first}=={invocation}
 assert {row['_SYSTEMD_INVOCATION_ID'] for row in second}!={invocation}
 assert labels(query('LAB_RUN=first','LAB_COMPONENT=api','-p','err'))==['first-api-2','first-api-3']
 print('different fields AND; -p err includes critical priority 2 and error priority 3')
 assert labels(query('LAB_RUN=first','LAB_COMPONENT=api','PRIORITY=3'))==['first-api-3']
 assert labels(query('LAB_RUN=first','LAB_COMPONENT=api','LAB_COMPONENT=db','PRIORITY=3'))==['first-api-3','first-db-3']
 print('exact PRIORITY=3 differs from threshold; repeated component fields OR')
 union=query('LAB_RUN=first','LAB_COMPONENT=db','+','LAB_RUN=second','LAB_COMPONENT=db')
 assert labels(union)==['first-db-3','second-db-3']
 assert labels(query('_SYSTEMD_INVOCATION_ID='+invocation,'LAB_COMPONENT=db'))==['first-db-3']
 print('explicit + joins match groups; invocation filter separates repeated starts')
 assert query('LAB_RUN=absent')==[]
 print('empty query still succeeds; underscore unit field comes from journal metadata')
 finally:
 run('systemctl','stop',unit)
 if run('systemctl','show',unit,'-p','ActiveState','--value')=='failed':run('systemctl','reset-failed',unit)
 path.unlink();run('systemctl','daemon-reload')

第一次激活生成 API 严重消息、API 错误消息、API 普通信息和数据库错误消息；第二次生成相同类别，但带另一个应用运行标签。按第一次运行、API 组件和 -p err 过滤，会返回两条记录，优先级分别为二和三。改成精确匹配三级，只剩 API 错误。这组对照直接展示阈值与精确值的区别，而不是仅解释命令名称。

同一个组件字段同时写 API 与数据库取值，会返回第一次运行中两个组件的错误记录，并不要求一条记录同时具有两个值。随后使用显式 +，选出前后两次运行各自的数据库消息。断言比较的是完整预期消息列表，因此过滤条件意外过宽时，不能仅靠结果里包含某句想找的话就通过检查；多出来的记录同样会使验证失败。

两次激活具有不同的 journal 运行实例标识。使用第一次的标识过滤，只会选出那次激活的数据库消息，尽管单元名称没有变化。这对崩溃循环和反复手动启动很有价值：单元名称组织服务长期历史，运行实例则标识一次执行生命周期。排障时把两者都保留下来，能减少把上次成功误认为本次恢复的判断错误。

工作程序还尝试提交一个伪造的、下划线开头的单元字段，但返回记录仍然携带真实服务单元。这类可信字段由 journal 根据进程上下文提供，不会像普通应用标签一样接受程序自报。与之不同，组件和运行标签是应用自身的声明；实验能够控制它们，但生产解析器不能仅因为字段名称看起来正式，就把它们当成独立身份认证机制。

最后，匹配一个不存在的运行标签，查询成功返回空列表，脚本专门断言这一情况。完成后会移除临时单元和工作文件；八条无害日志继续遵循主机正常保留策略，不会为了抹掉少量实验记录而删除无关系统历史。空结果、命令失败与后续历史清理，分别属于不同层面的行为。

导出时保留上下文

当另一个程序消费查询结果时，应使用结构化输出。本例解析 JSON，并有意使用短小文本字段；通用 journal JSON 对重复取值或二进制数据可能使用不同表示，所以消费方应明确接受的数据结构，不能假定任意字段永远是一条简单字符串。导出证据时保留时间戳与归属字段，后续才能对照执行顺序和实例，而不是只剩无法定位来源的消息正文。

按时间窗口查询时，应记录对应启动周期或运行实例，并明确时区假设。读取身份和所选命名空间也是观察条件，不是无关细节。在认定某个应用事件缺失前，先确认同一路径产生的一条已知无害事件确实可见。一个范围明确、能够复现的查询，应让选择规则和证据边界都清楚可查，而不是只给出一行看似有结果的命令。

来源

systemd 252 journalctl，字段布尔组合、优先级筛选与 JSON 输出，已核验 2026-09-12。
systemd 252 systemd.journal-fields，可信元数据、应用字段与运行实例标识，已核验 2026-09-12。
systemd 252 systemd-journald.service，原生日志传输、命名空间区分与采集范围，已核验 2026-09-12。

结构化 nginx 日志需要同时约定转义和字段类型

Thu, 15 Jul 2027 00:00:00 +0000

看起来像 JSON 的 log_format，不一定能可靠地产生结构化事件。nginx 把变量值代入文本，而变量可能包含引号、反斜杠、控制字符，也可能完全没有数据。正确字符串转义与正确字段类型是两个独立要求。用真实解析器检查输出，能发现肉眼查看配置或 nginx -t 成功无法证明的问题，避免上线后才发现部分日志无法进入查询系统。

坏掉的样子

把 User-Agent 原样插入带引号的 JSON 字段，遇到请求头中的引号就会失败。关闭转义不会更安全，只会让请求字符改变外层记录语法。nginx 默认日志转义则有另一种问题：它可能使用十六进制 \xXX 序列，而这不是合法 JSON 字符串转义。日志适合人阅读，不代表它符合另一种数据格式的语法。

加入 escape=json 可以处理 JSON 字符串转义，但不会自动添加引号、提供 null，或把变量转换成数字。对于本地生成的响应，上游耗时可能根本不存在。如果没有定义可选值的表示方式，就直接不加引号输出，字段可能在语法上缺值；即使实际存在的字符全部转义正确，整个 JSON 仍然无效。

缺失值表示也取决于实测版本的转义路径。nginx 1.28.0 默认转义会为找不到的变量写入短横线，JSON 转义则不写变量文本，所以外面的双引号最终成为空字符串。解析器还必须把这种情况与变量本身确实包含短横线、或包含多次上游尝试列表的情况区分开，不能把所有形式都硬当成同一个数字。

快速验证

下文集成实验的结果保留自历史运行记录；本次修订没有重新执行该实验，不能将这些记录当成本次环境的新实测。

使用宿主 Python、Docker 和固定 nginx 镜像运行脚本。实测为 Linux arm64 上的 nginx 1.28.0、Docker 29.3.1。它构建包含四种日志格式的临时配置，验证语法，发送两次真实 HTTP 请求，解析生成文件，最后清理自己的容器、镜像标签和网络。请求头都是公开测试字符串，不读取真实凭据或业务日志：

from contextlib import contextmanager
from pathlib import Path
from tempfile import TemporaryDirectory
import http.client,json,socket,subprocess,time,uuid

NGINX='nginx@sha256:552e7481ca93ffccd046aa658dbbed22caefbc09c66fa7cd247cbb90b8a5c609'
PYTHON='python@sha256:528257d48c1da0dcecc2e725d1ae34498d60c965f1241e39cd6a85a8859bdf84'
def docker(*args,check=True):
 result=subprocess.run(['docker',*args],capture_output=True,text=True,timeout=120)
 if check:assert result.returncode==0,result.stderr
 return result
def wait(predicate):
 deadline=time.monotonic()+15
 while time.monotonic()<deadline:
 try:
 if predicate():return
 except OSError:pass
 time.sleep(.1)
 raise AssertionError('fixture did not become ready')

@contextmanager
def lab(configuration,files=None,backend=None):
 name='xbcatm-nginx-'+uuid.uuid4().hex[:10];tags=[name+':proxy',name+':backend'];containers=[name+'-proxy',name+'-backend']
 try:
 with TemporaryDirectory(prefix=name+'-') as directory:
 root=Path(directory);(root/'files').mkdir();(root/'nginx.conf').write_text(configuration)
 for path,content in (files or {}).items():
 target=root/'files'/path;target.parent.mkdir(parents=True,exist_ok=True);target.write_text(content)
 docker('network','create',name)
 if backend is not None:
 (root/'backend.py').write_text(backend)
 (root/'backend.Dockerfile').write_text(f'FROM {PYTHON}\nCOPY backend.py /backend.py\nCMD ["python", "/backend.py"]\n')
 docker('build','--network','none','-f',str(root/'backend.Dockerfile'),'-t',tags[1],str(root))
 docker('run','-d','--name',containers[1],'--network',name,'--network-alias','backend',tags[1])
 wait(lambda:docker('exec',containers[1],'python','-c','import socket;s=socket.create_connection(("127.0.0.1",8081),timeout=.5);s.close()',check=False).returncode==0)
 (root/'Dockerfile').write_text(f'FROM {NGINX}\nCOPY nginx.conf /etc/nginx/nginx.conf\nCOPY files /srv\n')
 docker('build','--network','none','-t',tags[0],str(root))
 docker('run','--rm','--network',name,tags[0],'nginx','-t')
 docker('run','-d','--name',containers[0],'--network',name,'-p','127.0.0.1::8080',tags[0])
 details=json.loads(docker('inspect',containers[0]).stdout)[0]
 binding=details['NetworkSettings']['Ports']['8080/tcp'][0];assert binding['HostIp']=='127.0.0.1';port=int(binding['HostPort'])
 def ready():
 connection=socket.create_connection(('127.0.0.1',port),timeout=.5);connection.close();return True
 wait(ready)
 def request(path,method='GET',headers=None,body=None):
 connection=http.client.HTTPConnection('127.0.0.1',port,timeout=5)
 try:
 connection.request(method,path,body=body,headers=headers or {})
 response=connection.getresponse();return response.status,{k.lower():v for k,v in response.getheaders()},response.read()
 finally:connection.close()
 yield containers[0],request
 finally:
 docker('rm','-f',*containers,check=False);docker('image','rm',*tags,check=False);docker('network','rm',name,check=False)

def config(locations,extra=''):
 return 'worker_processes 1;\nerror_log /tmp/error.log notice;\nevents {}\nhttp {\naccess_log off;\n'+extra+'\nserver { listen 8080; root /srv;\n'+locations+'\n}\n}\n'

extra=r'''
log_format default_escape '{"agent":"$http_user_agent","upstream_time":"$upstream_response_time"}';
log_format raw escape=none '{"agent":"$http_user_agent"}';
log_format numeric escape=json '{"upstream_time":$upstream_response_time}';
log_format structured escape=json '{"agent":"$http_user_agent","upstream_time":"$upstream_response_time","status":$status,"request_id":"$request_id"}';
'''
locations=r'''
access_log /tmp/default.json default_escape;
access_log /tmp/raw.json raw;
access_log /tmp/numeric.json numeric;
access_log /tmp/structured.json structured;
location / { return 204; }
'''
with lab(config(locations,extra)) as (container,request):
 agent='reader "quoted" '+chr(92)+' path'+chr(9)+'tab'
 assert request('/local',headers={'User-Agent':agent})[0]==204
 assert request('/local',headers={'User-Agent':'plain'})[0]==204
 def lines(path):return docker('exec',container,'cat',path).stdout.splitlines()
 wait(lambda:len(lines('/tmp/structured.json'))==2)
 default=lines('/tmp/default.json');raw=lines('/tmp/raw.json');numeric=lines('/tmp/numeric.json');structured=list(map(json.loads,lines('/tmp/structured.json')))
 for line in [default[0],raw[0]]:
 try:json.loads(line)
 except json.JSONDecodeError:pass
 else:raise AssertionError('non-JSON escaping unexpectedly formed valid JSON')
 assert r'\x22' in default[0]
 assert json.loads(default[1])=={'agent':'plain','upstream_time':'-'}
 assert json.loads(raw[1])=={'agent':'plain'}
 for line in numeric:
 try:json.loads(line)
 except json.JSONDecodeError:pass
 else:raise AssertionError('unquoted missing timing unexpectedly formed valid JSON')
 assert [row['agent'] for row in structured]==[agent,'plain']
 assert all(row['status']==204 and row['upstream_time']=='' for row in structured)
 identifiers=[row['request_id'] for row in structured]
 assert len(set(identifiers))==2 and all(len(value)==32 and int(value,16)>=0 for value in identifiers)
 print('escape=json preserves quotes, backslashes and tabs as valid JSON strings; both default and no escaping break JSON on the same public header')
 print('default escaping writes a dash for the absent timing, while JSON escaping writes an empty string in the quoted field')
 print('an unavailable upstream timing is empty under JSON escaping, so emitting it unquoted still creates invalid JSON')
 print('structured records parse with a numeric status, explicit empty timing string and distinct nginx-generated request IDs')

第一个请求的 User-Agent 包含引号、一个反斜杠和制表符，第二个只包含 plain。两者都得到本地 204 响应，不发生上游请求。这有意把特殊字符串与缺失耗时组合起来，分别检验转义和可选值处理，不只依赖普通字母数字头部。测试输入需要能触及格式边界，才能暴露看起来正常的配置缺陷。

第一个请求的默认转义记录包含 \x22，无法通过 JSON 解析；不转义记录也因原始引号破坏外层字符串而失败。普通请求头对照说明，一个格式可以在常见输入下看似正确，却对另一个有效头部值失败。因此，少量肉眼可读日志不是充分验证，尤其无法覆盖客户端能够控制的字符串内容。

默认格式的普通记录，可以解析出带引号的短横线耗时；JSON 转义的结构化格式则得到空耗时字符串。这些实际观察与指定版本日志源码一致。区别对于采集器很重要：如果它假定 nginx 无论使用哪种格式选项，都用同一个缺失值标记，就可能错误解析或丢弃合法记录。版本与格式属于解析契约的一部分。

故意不给耗时加引号的格式，对两个请求都无效。JSON 转义无法把不存在的变量变成数字，所以冒号后面缺少值。结构化格式给可选耗时加引号，保持记录有效，同时不把缺少测量伪装成耗时零秒。缺失与零具有不同含义，不能为了让图表好看而在采集时悄悄合并。

两条结构化记录都成功解析，解码后的 User-Agent 与输入完全相同，status 是数值 204，可选耗时为空字符串。两个 nginx 生成的请求 ID 是不同的三十二位十六进制字符串。实验核对解析后的含义，而不是只检查一行有没有花括号；这样才能证明转义既保留内容，又没有破坏字段结构。

定义采集器应该接受什么

选择稳定字段名和类型，并说明缺失值。上游测量可能包含多个尝试值，保留字符串有时比强行写成单个数字更准确。如果采集器要转换成结构化尝试列表，应为转换定义明确语法和错误处理，不要把异常记录静默归零。原始记录与转换结果都需要足以定位解析差异的证据。

在采集边界同时验证文本编码与 JSON 转义。本实验覆盖包含特殊 ASCII 字符的普通文本，不声称任意无效字节序列都会变成合法 Unicode JSON。解析失败应可观测，避免事故期间有问题的记录悄悄消失，导致查询结果看似完整，实际已经漏掉最需要分析的一批请求。

只记录必要请求数据，并设置合理保留期和访问权限。正确转义的字段仍可能包含敏感信息或不可信身份声明。日志传送和查询全链路需要单独验证：本地 JSON 有效建立了有用契约，却不证明轮转、采集、传输和保留能够保存每一条事件。格式正确只是可靠日志处理的一部分。

来源

nginx HTTP log module，日志格式、转义模式与请求完成记录，已核验 2026-10-15。
nginx 1.28.0 log implementation，默认与 JSON 转义对缺失变量的不同处理，已核验 2026-10-15。
nginx core variables，请求标识与 HTTP 请求变量，已核验 2026-10-15。

结构化日志让查询约定明确可见

Tue, 09 Mar 2027 00:00:00 +0000

结构化日志为字段赋予稳定含义，使查询不必每次都从说明文字中推断全部信息。一条记录可以包含事件名称、请求编号、数值时长、严重级别，以及供人阅读的消息。自由文本仍然有价值，也可以被搜索或解析。结构化的实际收益，是让常用问题依赖一份明确的数据约定，即使说明措辞改变，字段的语义仍然保持稳定，而不是简单地给原来的一段话套上花括号。

这份约定必须涉及类型和单位。作为数字保存的时长可以直接进行数值比较，作为字符串保存时，索引和比较方式却可能不同。毫秒与秒不能共用一个含义模糊的字段名称，事件名称也应跨版本稳定描述所发生的动作。模式版本能够标识有意进行的格式变化，但它不会自动转换旧记录，也不会自动保证全部查询消费者继续兼容。字段设计需要围绕真实查询，而不是追求看起来丰富的输出。

把上下文放到正确的记录上

请求编号只有属于当前发出日志的操作时才有帮助。多个请求并发执行时，使用一个进程级可变全局变量保存当前编号并不合适。Python 上下文变量可以在异步任务范围内保持局部状态，但前提是在正确作用域设置并恢复值。这并不意味着所有线程或自定义执行机制都采用同一种继承方式；经过真正的并发边界时，仍需验证上下文怎样到达执行位置。

需要在上下文尚可取得的位置捕获它。本例在发出日志的任务中同步格式化记录，因此格式化器能够读取该任务的上下文变量。如果改成通过队列交给另一线程或进程处理，就应在交接前把所需字段附加到记录上。让监听线程临时读取它自己的当前请求上下文，并不能可靠恢复原发出者的身份。数据最终都进入同一个日志文件，不代表它们在跨线程之后仍然拥有正确的关联关系。

坏掉的样子

手工拼接 JSON 时，消息中的引号或换行可能破坏格式。按行读取的采集器随后可能把一个应用事件拆成多个看似独立的事件。应使用 JSON 序列化器，并保证每个物理行包含一个完整对象。消息的逻辑字符串可以保留换行，但在线上表示中它会被转义，不会产生新的记录边界。后续界面展示解码后的消息时，也应继续清楚区分记录，避免展示方式重新造成误读。

结构化输出不会自动建立索引、降低查询账单或保证投递成功。不受约束的字段、意外变化的类型、缺失的编号和不该记录的敏感内容，都可能使一份合法 JSON 流难以使用。需要依据实际问题选择字段，保持模式稳定，并核对采集器的解析规则和数据保留方式。可查询的结构是生产者与消费者之间的约定，不是文件扩展名或者一次序列化成功就能单方面建立的能力。

快速验证

将脚本保存为 structured-logging.py 并用 Python 执行；本次实际版本为 Python 3.12.14，只使用标准库。两个异步请求各自写入开始事件，在共同的放行点等待，再写入包含刻意构造消息的完成事件。这会让两个请求的存活区间重叠，便于检查编号是否混淆。时长是用于检查 JSON 类型的固定合成值，并不是测得的请求性能，输出也只保存在内存里供断言读取。

import asyncio
import io
import json
import logging
from collections import Counter
from contextvars import ContextVar

request_id = ContextVar("request_id", default=None)
stream = io.StringIO()


class JsonFormatter(logging.Formatter):
 def format(self, record):
 return json.dumps({"schema_version": 1, "event": record.event,
 "request_id": request_id.get(), "worker": record.worker,
 "duration_ms": record.duration_ms,
 "level": record.levelname, "message": record.getMessage()},
 ensure_ascii=False, separators=(",", ":"))


logger = logging.getLogger("structured-log-lab")
logger.setLevel(logging.INFO)
logger.propagate = False
handler = logging.StreamHandler(stream)
handler.setFormatter(JsonFormatter())
logger.addHandler(handler)


async def request(name, ready, release):
 token = request_id.set(name)
 try:
 logger.info("starting %s", name, extra={"event": "request.started",
 "worker": name, "duration_ms": 0})
 ready.set()
 await release.wait()
 await asyncio.sleep(0)
 logger.info('untrusted line\n{"event":"forged"}',
 extra={"event": "request.completed", "worker": name, "duration_ms": 4})
 finally:
 request_id.reset(token)


async def main():
 ready = [asyncio.Event(), asyncio.Event()]
 release = asyncio.Event()
 tasks = [asyncio.create_task(request(name, signal, release))
 for name, signal in zip(("req-a", "req-b"), ready)]
 await asyncio.gather(*(signal.wait() for signal in ready))
 release.set()
 await asyncio.gather(*tasks)
 assert request_id.get() is None


try:
 asyncio.run(main())
finally:
 logger.removeHandler(handler)
 handler.close()
lines = stream.getvalue().splitlines()
records = [json.loads(line) for line in lines]
assert len(lines) == 4
assert Counter(record["request_id"] for record in records) == {"req-a": 2, "req-b": 2}
assert all(record["request_id"] == record["worker"] for record in records)
assert all(type(record["duration_ms"]) is int for record in records)
completed = [record for record in records if record["event"] == "request.completed"]
assert len(completed) == 2 and all("\n" in record["message"] for record in completed)
assert not any(record["event"] == "forged" for record in records)
print(json.dumps({"physical_lines": len(lines), "parsed_records": len(records),
 "requests": 2, "context_mixing": False,
 "numeric_duration_preserved": True, "forged_records": 0}, indent=2))

断言要求最终恰好有四个物理行、四条可解析记录，每个请求编号对应两条记录。即使请求并发，记录中的编号也必须与实际发出日志的工作任务一致。时长在解析后仍然是数字，完成消息中的换行保留在字符串内部，却不会多出一个名为 forged 的伪造事件。每个任务最后恢复自己的上下文令牌，外层上下文仍然没有请求编号，从而验证本例的设置和清理作用域。

这些结果验证的是任务隔离、同步格式化以及按行安全的序列化，没有执行后台队列、采集器重试、存储索引或敏感信息脱敏。接入实际系统时，应采用有代表性的字段和真实并发模型检查完整路径，观察后台解析后究竟保存了哪些值，并执行最初促使团队加入这些字段的查询。生产端格式正确是一个必要的边界证据，但可靠的日志系统还需要证明记录携带完整含义到达消费者，不能把这一环节的通过当成全部链路已经验证。

来源

Python logging cookbook，携带上下文的记录及并发执行中的日志处理，已核验 2026-10-15。
Python contextvars，任务局部上下文与令牌恢复语义，已核验 2026-10-15。
Python json，序列化、字符转义和 JSON 值类型，已核验 2026-10-15。
JSON Lines，每个物理行对应一个完整 JSON 值，已核验 2026-10-15。

访问日志应区分客户端结果与上游尝试

Mon, 01 Mar 2027 00:00:00 +0000

nginx 访问日志在请求处理末尾执行记录。选择合适字段，可以区分客户端请求了什么、最终由哪个 URI 处理、发送了什么响应，以及上游尝试期间发生了什么。这些是不同观察。有用格式会保留区别，而不是假定一个状态、耗时或路径就能独立解释整个请求。字段越准确地对应事件，事故期间越容易沿实际处理链定位问题。

坏掉的样子

最终客户端状态可以隐藏较早上游失败。如果 nginx 成功重试其他服务器，客户端可能得到 200，但尝试列表仍记录第一次连接失败。反过来，本地生成的响应没有上游操作可计时。把每个请求都当成恰好一次后端响应，会丢失解释重试和本地处理所需的信息，也可能把成功率与上游健康情况混在一起。

内部跳转后，原始和当前 URI 字段也不同。$request 保留请求行，$request_uri 保留原 URI 和查询，$uri 则可能反映后来的规范化或重写路径。只记录最终 URI，调查者可能不知道哪个公共地址触发它；只记录原始路径，又可能看不到最终处理器上下文。两类字段需要按各自含义使用。

时间字段不是总能直接相减并得到精确诊断的独立延迟组件。请求时间覆盖到 nginx 日志采用的客户端侧完成点，上游时间字段则描述自己的阶段，还可能包含多次尝试。分辨率、缺失值和边界都重要；毫秒显示看起来为零，不证明没有执行工作。粗粒度测量与真实无耗时不能混为一谈。

快速验证

下文集成实验的结果保留自历史运行记录；本次修订没有重新执行该实验，不能将这些记录当成本次环境的新实测。

使用宿主 Python、Docker，以及固定 nginx 和 Python 镜像运行脚本。实测为 Linux arm64 上的 nginx 1.28.0、Python 3.11.16、Docker 29.3.1。它配置真实后端，以及代理容器内一个没有监听者的端口，检查 nginx 配置，只发布宿主回环代理端口，读取日志后清理自身资源，不向外部未知服务发送探测：

from contextlib import contextmanager
from pathlib import Path
from tempfile import TemporaryDirectory
import http.client,json,socket,subprocess,time,uuid

NGINX='nginx@sha256:552e7481ca93ffccd046aa658dbbed22caefbc09c66fa7cd247cbb90b8a5c609'
PYTHON='python@sha256:528257d48c1da0dcecc2e725d1ae34498d60c965f1241e39cd6a85a8859bdf84'
def docker(*args,check=True):
 result=subprocess.run(['docker',*args],capture_output=True,text=True,timeout=120)
 if check:assert result.returncode==0,result.stderr
 return result
def wait(predicate):
 deadline=time.monotonic()+15
 while time.monotonic()<deadline:
 try:
 if predicate():return
 except OSError:pass
 time.sleep(.1)
 raise AssertionError('fixture did not become ready')

@contextmanager
def lab(configuration,files=None,backend=None):
 name='xbcatm-nginx-'+uuid.uuid4().hex[:10];tags=[name+':proxy',name+':backend'];containers=[name+'-proxy',name+'-backend']
 try:
 with TemporaryDirectory(prefix=name+'-') as directory:
 root=Path(directory);(root/'files').mkdir();(root/'nginx.conf').write_text(configuration)
 for path,content in (files or {}).items():
 target=root/'files'/path;target.parent.mkdir(parents=True,exist_ok=True);target.write_text(content)
 docker('network','create',name)
 if backend is not None:
 (root/'backend.py').write_text(backend)
 (root/'backend.Dockerfile').write_text(f'FROM {PYTHON}\nCOPY backend.py /backend.py\nCMD ["python", "/backend.py"]\n')
 docker('build','--network','none','-f',str(root/'backend.Dockerfile'),'-t',tags[1],str(root))
 docker('run','-d','--name',containers[1],'--network',name,'--network-alias','backend',tags[1])
 wait(lambda:docker('exec',containers[1],'python','-c','import socket;s=socket.create_connection(("127.0.0.1",8081),timeout=.5);s.close()',check=False).returncode==0)
 (root/'Dockerfile').write_text(f'FROM {NGINX}\nCOPY nginx.conf /etc/nginx/nginx.conf\nCOPY files /srv\n')
 docker('build','--network','none','-t',tags[0],str(root))
 docker('run','--rm','--network',name,tags[0],'nginx','-t')
 docker('run','-d','--name',containers[0],'--network',name,'-p','127.0.0.1::8080',tags[0])
 details=json.loads(docker('inspect',containers[0]).stdout)[0]
 binding=details['NetworkSettings']['Ports']['8080/tcp'][0];assert binding['HostIp']=='127.0.0.1';port=int(binding['HostPort'])
 def ready():
 connection=socket.create_connection(('127.0.0.1',port),timeout=.5);connection.close();return True
 wait(ready)
 def request(path,method='GET',headers=None,body=None):
 connection=http.client.HTTPConnection('127.0.0.1',port,timeout=5)
 try:
 connection.request(method,path,body=body,headers=headers or {})
 response=connection.getresponse();return response.status,{k.lower():v for k,v in response.getheaders()},response.read()
 finally:connection.close()
 yield containers[0],request
 finally:
 docker('rm','-f',*containers,check=False);docker('image','rm',*tags,check=False);docker('network','rm',name,check=False)

def config(locations,extra=''):
 return 'worker_processes 1;\nerror_log /tmp/error.log notice;\nevents {}\nhttp {\naccess_log off;\n'+extra+'\nserver { listen 8080; root /srv;\n'+locations+'\n}\n}\n'

backend=r'''from http.server import BaseHTTPRequestHandler,HTTPServer
import json
class Handler(BaseHTTPRequestHandler):
 def do_GET(self):
 body=self.rfile.read(int(self.headers.get('Content-Length','0')))
 document={'path':self.path,'method':self.command,'body':body.decode(),'headers':{key:self.headers.get(key) for key in ['Host','X-Forwarded-For','X-Real-IP','X-Forwarded-Proto','X-Forwarded-Host']}}
 data=json.dumps(document).encode()
 self.send_response(200);self.send_header('Content-Type','application/json');self.send_header('Content-Length',str(len(data)));self.send_header('X-Backend-Info','fixture-node');self.end_headers();self.wfile.write(data)
 do_POST=do_GET
 def log_message(self,*args):pass
HTTPServer(('0.0.0.0',8081),Handler).serve_forever()
'''

fields={'request':'$request','request_uri':'$request_uri','uri':'$uri','status':'$status','upstream_status':'$upstream_status','upstream_addr':'$upstream_addr','request_time':'$request_time','upstream_connect_time':'$upstream_connect_time','upstream_header_time':'$upstream_header_time','upstream_response_time':'$upstream_response_time','body_bytes_sent':'$body_bytes_sent','bytes_sent':'$bytes_sent'}
extra="log_format details escape=json '"+json.dumps(fields,separators=(',',':'))+"';\nupstream service_pool { server 127.0.0.1:1 max_fails=1; server backend:8081 backup; }"
locations=r'''
access_log /tmp/access.json details;
location = /local { return 204; }
location = /rewrite { rewrite ^ /normalized last; }
location = /normalized { return 200 "normalized"; }
location /proxy {
 proxy_next_upstream error timeout;
 proxy_next_upstream_tries 2;
 proxy_pass http://service_pool;
}
'''
with lab(config(locations,extra),backend=backend) as (container,request):
 assert request('/local')[0]==204
 assert request('/rewrite?x=1')[2]==b'normalized'
 status,headers,body=request('/proxy?x=1');assert status==200
 def lines():return docker('exec',container,'cat','/tmp/access.json').stdout.splitlines()
 wait(lambda:len(lines())>=3)
 records={record['request_uri']:record for record in map(json.loads,lines())}
 print(json.dumps(records,indent=2),flush=True)
 local=records['/local'];assert local['status']=='204' and local['upstream_status']=='' and local['upstream_response_time']==''
 assert local['body_bytes_sent']=='0' and int(local['bytes_sent'])>0
 changed=records['/rewrite?x=1'];assert changed['request']=='GET /rewrite?x=1 HTTP/1.1' and changed['uri']=='/normalized'
 proxy=records['/proxy?x=1'];assert proxy['status']=='200' and proxy['upstream_status']=='502, 200'
 assert len(proxy['upstream_addr'].split(', '))==2 and int(proxy['body_bytes_sent'])==len(body)
 assert float(proxy['request_time'])>=0 and len(proxy['upstream_response_time'].split(', '))==2
 print('a local 204 has no upstream and no body bytes, but still sends response-header bytes')
 print('the final uri reflects the internal redirect while request and request_uri retain the original request')
 print('one client-visible 200 records upstream attempts 502, 200 and separate attempt-address/timing lists')

/local 不访问上游，直接返回 204。日志正文计数为零，bytes_sent 却为正，因为发送了响应头。在本例 JSON 转义格式中，缺失上游字段是空字符串。这不同于实际测得零秒的上游操作，也不同于实测版本默认转义路径使用的短横线。正确解析需要知道字段是否有测量，而不是仅看它能否转成数字。

/rewrite?x=1 内部变成 /normalized。日志请求行仍为 GET /rewrite?x=1 HTTP/1.1，原 URI 仍带查询，而 uri 字段记录 /normalized。这在真实日志写入点验证了区别，不是只根据 rewrite 声明或响应正文推测。最终字段值能够帮助判断处理过程中是否发生了内部路由变化。

代理请求先尝试回环端口一，实验代理容器中该端口没有监听者。nginx 把失败尝试记录为 502，再请求配置的备用服务器。客户端最终收到 200，上游状态字符串却为 502, 200。第一项是 nginx 记录的失败结果，不证明某个后端真的发送过 HTTP 502 响应；连接根本未建立时，状态也可能由代理生成。

同一事件包含两个上游地址和两个响应耗时。对于没有进入连接完成或响应头阶段的尝试，相应时间列表可能含短横线，即使整个变量确实存在。这与完全不存在的上游变量不同。解析时应保留这些关系，不能把每个异常形状都替换成无法区分的数值零，否则失败阶段和尝试次数都会丢失。

在这个未压缩实验中，日志正文计数等于客户端实际读取的响应正文长度。bytes_sent 包含更多 HTTP 响应字节，但两者都不是对以太网、TCP 或 TLS 开销的完整统计。这里用计数器区分内容与响应头流量，不把它们冒充物理网络计费测量。指标用途应与其真实计数边界一致。

脚本等到三条事件出现后才解析。日志位于请求处理之后，配置写入缓冲还可能继续延迟可见性。HTTP 成功响应不保证远程日志采集器已经收到或保留对应事件。排查日志延迟时，需要继续检查缓冲、轮转和采集链路，不能只因为请求完成就认定记录应该立即出现在中央查询系统。

在模式中保留诊断含义

按具体运维问题选择字段：原始目标、最终路由、客户端状态、上游尝试结果和相关耗时。在遵循文档语法的解析器处理之前，保留尝试列表原貌。多上游组或内部转换还可能引入比这里两次尝试更复杂的结构，不能把本例逗号拆分直接扩展成所有部署通用解析器。

不要把客户端可控制的转发头当成已经验证的调用者身份。保留查询或其他请求字段前，也要考虑其中是否存在敏感值。更丰富的日志只有在信息用途清楚、访问和保留控制合适时才有价值；收集越多不自动意味着诊断越可靠，反而可能增加隐私和容量负担。

修改格式时，生成有代表性的本地响应、重试、重写和失败，再解析真实记录。轮转与采集另行验证。可靠访问日志把每个字段连接到它测量的事件，并保留缺失或多次尝试信息，而不是压缩成误导性的单一摘要。这样，日志才能支持根因分析，而不只是证明曾经有请求经过。

来源

nginx HTTP log module，请求完成时间、字节计数与日志格式字段，已核验 2026-10-15。
nginx upstream variables，逐次尝试的地址、状态及时间列表，已核验 2026-10-15。
nginx core request variables，原始请求文本与当前规范化 URI，已核验 2026-10-15。
nginx 1.28.0 log implementation，JSON 转义下缺失变量的表示，已核验 2026-10-15。

时间戳需要明确的时间语义

Sun, 29 Nov 2026 00:00:00 +0000

像 2026-11-01 01:30 这样的钟表标签，单独存在时不能确定唯一瞬间。解释它需要知道所在时区，在时钟回拨期间还可能需要说明是哪一次出现。反过来，已经明确纪元和单位的 Unix 时间戳，即使没有显示时区名称，也可以具有完整的瞬间语义。选择字符串格式之前，应先明确系统保存的究竟是哪一种时间值。

偏移不是完整时区规则

带数值偏移的时间戳说明本地字段如何对应 UTC。同一天的 12:00Z 和 20:00+08:00 可以表示同一瞬间。IANA 命名时区还包含历史及未来的民用时间规则，包括夏令时切换。安排下个月的洛杉矶本地约会时，固定的负七小时偏移不能替代 America/Los_Angeles，因为到时可能适用不同偏移。

对于已经发生的事件，可以保留无歧义瞬间，再按照读者需要的时区显示。但“每个工作日早上九点”是重复的民用时间意图，还需要保留本地日程及其适用时区。政策变化可能改变未来规则，需要可复现性时也应记录所用时区数据库版本。把今天的偏移固化成永远使用的日程，会悄悄改变原始业务含义。

UTC 格式并不证明时钟准确，也不证明因果顺序。两台机器都能打印 Z 后缀，但各自系统时钟仍可能有偏差；有限精度还会让多个事件得到相同时间戳。需要排序依据时，应保留事件标识及适当的因果上下文。本机经过时长则应选用合适的单调时钟，不能期待时区转换修复最初就测错的瞬间。

数值接口还必须注明采用秒还是毫秒，以及从哪个纪元开始计数。一个较大的整数本身不能完整说明单位；接收方把单位解释错了，之后再切换显示时区也无法恢复正确含义。单位应属于接口契约，而不是靠字段长度临时猜测。

坏掉的样子

任意时间戳字符串直接排序，可能得到与时间先后相反的结果。RFC 3339 对适合文字排序的条件有明确说明，包括统一的时区表示和小数精度。面对混合偏移，应先解析并归一化到瞬间，再进行比较。视觉上本地小时较晚的记录，换算到 UTC 之后可能反而更早，因此字符串字符比较不能替代时间语义解释。

秋季回拨可能让同一个本地小时出现两次，Python 的 ZoneInfo 通过 fold 区分这两个实例。春季前拨则可能让某个本地时刻根本不存在。仅仅把时区对象附到日期上，并不会自动拒绝缺失时间。接受本地约会输入的程序必须定义拒绝或解决歧义的策略，不能悄悄替用户猜测他想选择哪一个瞬间。

日期运算也要与目标一致。两个 datetime 共享同一个 tzinfo 时，相关运算可能使用钟表字段语义，忽略 fold 所表达的瞬间区别。如果需要比较实际经过时间，应先分别转换到 UTC。这个选择需要明确，因为跨越时钟切换时，本地表盘读数之差可能与真正经过的秒数不同，二者都不能无条件替代另一种含义。

快速验证

将下面程序保存为 timezone.py，使用 Python 3.11 或更新版本执行 python3 timezone.py，并确保环境中有 IANA 时区数据。实测环境是 Python 3.11.2 和 Debian tzdata 2026b。程序全部使用固定日期，不会修改机器的时钟，也不会更改系统时区；不同数据库版本需要重新检查相应规则。

from datetime import datetime, timezone
from zoneinfo import ZoneInfo
import json


def instant(text):
 value = datetime.fromisoformat(text)
 if value.tzinfo is None:
 raise ValueError('an instant requires an explicit offset')
 return value.astimezone(timezone.utc)


same = ['2026-09-13T12:00:00Z', '2026-09-13T20:00:00+08:00']
assert instant(same[0]) == instant(same[1])
values = ['2026-01-01T10:00:00+02:00', '2026-01-01T09:30:00+00:00']
assert sorted(values) != sorted(values, key=instant)
try:
 instant('2026-09-13T12:00:00')
except ValueError as error:
 rejection = str(error)
else:
 raise AssertionError('ambiguous instant accepted')

zone = ZoneInfo('America/Los_Angeles')
first = datetime(2026, 11, 1, 1, 30, tzinfo=zone, fold=0)
second = first.replace(fold=1)
first_utc, second_utc = first.astimezone(timezone.utc), second.astimezone(timezone.utc)
assert (second_utc - first_utc).total_seconds() == 3600
missing = datetime(2026, 3, 8, 2, 30)
round_trips = []
for fold in (0, 1):
 candidate = missing.replace(tzinfo=zone, fold=fold)
 returned = candidate.astimezone(timezone.utc).astimezone(zone)
 assert returned.replace(tzinfo=None) != missing
 round_trips.append(returned.isoformat())
print(json.dumps({'same_instant': True, 'lexical_order': sorted(values),
 'instant_order': sorted(values, key=instant), 'naive_rejected': rejection,
 'repeated_wall_time': [first.isoformat(), second.isoformat()],
 'actual_separation_seconds': 3600, 'nonexistent_time_round_trips': round_trips}))

第一项断言确认两个不同偏移的表示指向同一瞬间。随后，文字排序把 09:30+00:00 放在 10:00+02:00 前面，而按瞬间排序会正确地反过来。辅助函数还会拒绝没有偏移的值，不会借用运行机器的当前时区来补足信息。这只是用于示例的小型瞬间解析函数，并不是完整的 RFC 3339 格式验证器。

对于洛杉矶 2026 年十一月一日，两次 01:30 分别带有负七小时和负八小时偏移。转成 UTC 后，实际间隔为三千六百秒。对于三月八日 02:30，两个 fold 候选经 UTC 往返转换都不能保留原本的本地字段，结果分别落在 03:30 和 01:30，说明这个本地标签在当天没有对应的有效瞬间。

全部断言已运行通过。这些案例验证的是已安装数据库中的特定转换规则，并不承诺所有地区永远保持今天的制度。数据契约应分别保留瞬间含义、本地日程意图以及解析政策，避免在显示、存储和调度之间无意丢失决定时间意义的信息。

来源

RFC 3339: Date and Time on the Internet，带偏移的时间戳及字符串排序条件，已核验 2026-09-13。
Python: datetime，带时区值、UTC 转换与日期运算，已核验 2026-09-13。
Python: zoneinfo，IANA 规则、重复时间与 fold，已核验 2026-09-13。

Logrotate 在执行时应用轮转策略

Sat, 21 Nov 2026 00:00:00 +0000

Logrotate 在被调用时读取配置，轮转符合条件的日志，并执行选定的保留与压缩动作。何时检查由定时器或其他调度器决定，它不会持续限制文件大小，改名也不会自动重定向应用的打开描述符。完整设置需要把检查频率、文件策略和写者实际重开行为结合起来，才能判断日志确实按预期流转。

坏掉的样子

两次执行之间可能超过 size 阈值，突发写入或调度停止时尤其明显。rotate 限制的是保留代数，不是历史时间，也不覆盖全部临时磁盘使用。因此，阈值乘代数不是硬容量保证；活动文件、检查间隔内增长，以及压缩或复制工作，都需要空间。只看到配置里有两个有限数字，不能证明磁盘不会耗尽。

create 指定替代文件的模式和所有权，不会向应用发送信号。postrotate 可以调用受支持的重开机制，但 HUP 并不普遍表示重载。delaycompress 只把压缩推迟一个轮转周期，无法修复从不放弃旧 inode 的写者。每项指令负责不同动作，需要核对它们是否共同完成实际交接。

脚本可能在文件操作已经成功后失败。Logrotate 返回非零，不会回滚全部改名和创建；未检查文件及写者状态就反复强制轮转，可能再次切分或删除需要的代数。应诊断已经发生的部分结果，而不是把失败理解成没有变化。错误恢复也必须依据当前事实，而不能只看最后退出码。

快速验证

历史上的 root 所有文件示例保持原样，本次没有重跑；当前没有 logrotate 及所需特权实验环境。

把脚本保存为 logrotate-cli.py，在装有 Python、logrotate 和 gzip 的一次性 Linux 容器中，以 root 运行 python3 logrotate-cli.py。实测使用 Linux 6.12.76、Python 3.11.2、logrotate 3.21.0 和 ext4。样本使用私有配置与状态文件，只有一个日志子进程，其 HUP 处理函数明确重开自己的临时日志：

from pathlib import Path
from tempfile import TemporaryDirectory
import gzip,os,stat,subprocess,sys

worker=r'''
import os,signal,sys
path=sys.argv[1];fd=os.open(path,os.O_WRONLY|os.O_CREAT|os.O_APPEND,0o600)
def reopen(signum,frame):
 global fd
 os.close(fd);fd=os.open(path,os.O_WRONLY|os.O_APPEND)
 print('reopened',flush=True)
signal.signal(signal.SIGHUP,reopen)
try:
 print('ready',flush=True)
 for line in sys.stdin:
 if line=='QUIT\n':break
 os.write(fd,line.encode());print('wrote',flush=True)
finally:os.close(fd)
'''
assert os.geteuid()==0,'use a disposable container for the root-owned fixture'
with TemporaryDirectory(prefix='xbcatm-logrotate-') as directory:
 root=Path(directory);active=root/'app.log';configuration=root/'logrotate.conf';state=root/'state'
 process=subprocess.Popen([sys.executable,'-c',worker,str(active)],stdin=subprocess.PIPE,stdout=subprocess.PIPE,stderr=subprocess.PIPE,text=True)
 try:
 assert process.stdout.readline().strip()=='ready'
 configuration.write_text(f'''"{active}" {{
 size 64
 rotate 2
 compress
 delaycompress
 missingok
 notifempty
 create 0600 root root
 postrotate
 /bin/kill -HUP {process.pid}
 endscript
}}
''')
 def append(text):
 process.stdin.write(text+'\n');process.stdin.flush();assert process.stdout.readline().strip()=='wrote'
 def rotate(*options):return subprocess.run(['logrotate',*options,'--state',str(state),str(configuration)],capture_output=True,text=True,timeout=5)
 append('short');initial=active.read_bytes()
 result=rotate('--debug');assert result.returncode==0,result.stderr
 assert active.read_bytes()==initial and not state.exists() and not (root/'app.log.1').exists()
 result=rotate();assert result.returncode==0,result.stderr
 assert state.exists() and not (root/'app.log.1').exists()
 print('debug changes neither logs nor state; a normal below-threshold run records state without rotating')
 first=initial+b'first-'+b'a'*80+b'\n';second=b'second-'+b'b'*80+b'\n';third=b'third-'+b'c'*80+b'\n'
 for number,payload in enumerate([first,second,third],1):
 append((payload[len(initial):] if number==1 else payload).decode().rstrip('\n'))
 result=rotate();assert result.returncode==0,result.stderr
 assert process.stdout.readline().strip()=='reopened'
 assert active.read_bytes()==b'' and stat.S_IMODE(active.stat().st_mode)==0o600
 assert (root/'app.log.1').read_bytes()==payload
 if number>=2:
 with gzip.open(root/'app.log.2.gz','rb') as handle:assert handle.read()==(first if number==2 else second)
 assert not (root/'app.log.3.gz').exists()
 append('new-active');assert active.read_bytes()==b'new-active\n'
 print('three actual rotations reopen the writer, delay compression one generation, retain two archives, and preserve the expected bytes')
 failed=root/'failed.log';failed.write_bytes(b'failure-fixture')
 bad=root/'failed.conf';bad.write_text(f'''"{failed}" {{
 size 1
 rotate 1
 create 0600 root root
 postrotate
 /bin/false
 endscript
}}
''')
 result=subprocess.run(['logrotate','--state',str(root/'failed.state'),str(bad)],capture_output=True,text=True,timeout=5)
 assert result.returncode!=0
 assert (root/'failed.log.1').read_bytes()==b'failure-fixture' and failed.read_bytes()==b''
 print('a failed postrotate command returns failure after rename/create side effects have already happened')
 output,error=process.communicate('QUIT\n',timeout=5);assert process.returncode==0,error
 finally:
 if process.poll() is None:process.kill();process.wait()

配置选择六十四字节阈值、两代保留、延迟一个周期的压缩，以及 root 所有、0600 模式的新文件。钩子只向受控子进程已知 PID 发信号。写者对写入和重开都发出确认，让控制进程验证交接，而不是仅凭发送命令成功就推测新路径已经被使用。

日志较小时，debug 模式不会改变日志，也不会创建私有状态文件。随后正常调用创建状态，但不轮转低于阈值的日志。两项检查区分配置观察与真实修改，并证明一次成功执行可以合理地不发生轮转。不能把工具没有切文件直接当作调度失败，也不能把调试输出当成操作已执行。

脚本接着写入超过阈值的数据，分三次调用 logrotate，每次之前加入已知内容。每轮创建空的 0600 活动文件，子进程确认已重开；最新归档作为第一代保持未压缩，前一代则成为 gzip 压缩的第二代。结果来自实际 CLI 操作与文件检查，没有只根据配置文本推测轮转名称。

样本解压较老归档并比较精确字节。第三次轮转后，第二代包含第二次内容，第一代包含第三次内容，不再保留第三代压缩文件。最后一条记录进入当前活动文件。这同时验证保留、压缩与写入位置，而不只是确认某些看起来正确的文件名已经出现。

第二份私有配置刻意执行失败的 postrotate 命令。Logrotate 返回失败，但旧内容已经位于第一代，新活动文件也已创建且为空。这个受控错误展示退出失败后仍然存在的副作用。最后样本停止并回收日志子进程，删除所有临时文件；它没有修改系统原有轮转配置或其他服务日志。

把策略作为完整流程运行

状态文件应与预期轮转任务一致，并在安排并发执行时考虑锁定行为。不同状态文件不代表共享历史。debug 适合审阅判断，force 会改变是否轮转的条件，不能把强制执行成功当作普通调度会在预期时间触发的证据。需要分别验证配置判定、调用频率和真实文件结果。

指令应按目标触发条件选择。大小和时间策略有具体交互与顺序规则，把几个熟悉词放在一起，不会自动形成逻辑与条件。应针对代表性的小文件、大文件、空文件和缺失文件核对生效策略，还要检查应用身份能否写入新建文件。新文件存在，并不证明其模式和所有权适合真实写者。

运行中应同时观察定时检查和重开是否成功、文件系统余量，以及实际保留的历史窗口。如果必须使用 copytruncate，应明确接受并测试复制到截断之间的丢失窗口。保留契约要求时，还要独立转发或备份日志，并验证代表性旧记录经过压缩、轮转和恢复之后仍然可读，才能确认历史确实可用。

来源

logrotate 3.21.0 manual，size、rotate、create、压缩、状态、调试与脚本失败，已核验 2026-09-12。
rename(2)，重命名路径为何不会重定向存活写者，已核验 2026-09-12。
signal(7)，应用定义的 HUP 行为与默认终止，已核验 2026-09-12。

指标与日志都需要明确统计总体

Fri, 16 Oct 2026 00:00:00 +0000

指标与日志是对已观测行为的不同表示，并不是互相竞争的真相定义。指标通常在一组维度下汇总测量结果，日志记录则描述一个事件，并能够携带更具体的上下文。只要数据覆盖与语义支持，两者都可以回答聚合问题。不能因为某张仪表盘更整齐，就认为它天然更权威；也不能因为日志字段很多，就默认其中包含完整且可直接比较的业务总体。

对于结账服务，一个已完成请求计数器可以把每个最终结果归为成功或错误。路由、结果等少量有界维度，方便持续比较流量与失败比例。诊断日志则可以利用关联编号、错误类型和依赖响应，解释某一次失败请求的具体原因。这两类信息互相帮助，但它们采用的分母仍然需要分别确定。共享服务名称或时间图形，并不足以证明两份数据统计了相同的请求集合。

先决定测量包含什么

累计计数器本身不是每秒请求数。实际速率查询需要跨时间观测，并考虑进程重启等导致的计数重置。不过，一个起点、终点和成员都明确的完整合成批次，可以直接计数。不能悄悄把生产中的时间窗口速率换成两个无关快照的比例，也不能把经过选择的事件流与覆盖全部请求的计数器混为同一个统计总体。计算形式相似，并不代表时间口径已经一致。

日志也不是只能靠人逐条阅读。只要终态事件结构稳定且记录完整，就能聚合出与请求计数器相同的总量。选择时需要考虑事件体积、索引、查询延迟、保留期限和维护复杂度。指标经常适合反复执行的汇总查询，但如果每个请求都生成一个新的标签值，指标存储也可能迅速变得昂贵。究竟哪种方式成本较低，取决于实际维度和使用方式，而不是单凭指标或日志这个名称判断。

坏掉的样子

假设一百个已完成请求里有四个失败。为了排查问题，日志系统或人工查询特意保留其中五个请求，里面包含两个失败。完整总体的失败比例是百分之四，被选日志的失败比例则是百分之四十。两次算术运算都没有错，但把后者宣称为整个服务的失败率就错了，因为这五条记录既不是全部请求，也没有证明是能够代表总体的样本。排障数据的选择目的必须与统计推断分开。

把重试过程中的失败次数当成最终失败请求数，也会造成类似误差：同一个请求的一次尝试可能失败，随后却成功完成。日志缺失、重复投递、时间窗口不同和路由归类不一致，都可能令看起来相关的图表互相矛盾。用于可靠性计算时，应明确每个请求只有一个最终结果，同时保留尝试级证据用于诊断。发现不一致后，不能只改图表标题，或者简单平均两个比例来掩盖口径差异。

快速验证

将代码保存为 metrics-logs.py，使用 Python 3，并把官方 promtool 可执行程序放入 PATH。本次完整运行采用 Python 3.12.14 与 promtool 3.14.0。真实校验器从标准输入读取生成的指标文本，不建立服务器、容器或网络连接。合成请求集合按构造保证完整，诊断日志子集则是刻意选取，并非随机抽样。程序同时输出实际工具版本，避免把历史容器版本误写成这次使用的版本。

import json
import subprocess
from collections import Counter

# A complete synthetic population, with exactly one terminal outcome per request.
requests = [{"request_id": f"r{i}", "route": "/checkout",
 "outcome": "error" if i in {7, 18, 53, 94} else "success"}
 for i in range(1, 101)]
counter = Counter(request["outcome"] for request in requests)
selected_logs = [request for i, request in enumerate(requests, 1)
 if i in {1, 7, 18, 33, 55}]
logged_errors = sum(record["outcome"] == "error" for record in selected_logs)
text = "# HELP demo_requests_total Completed synthetic requests.\n# TYPE demo_requests_total counter\n"
for outcome, count in sorted(counter.items()):
 text += f'demo_requests_total{{route="/checkout",outcome="{outcome}"}} {count}\n'
version = subprocess.run(["promtool", "--version"], capture_output=True, text=True, check=True).stdout.splitlines()[0]
result = subprocess.run(["promtool", "check", "metrics"], input=text,
 text=True, capture_output=True, timeout=30)
assert result.returncode == 0, result.stdout + result.stderr
population_rate = counter["error"] / len(requests)
selected_rate = logged_errors / len(selected_logs)
assert population_rate == 0.04 and selected_rate == 0.4
assert "request_id" not in text and len(counter) == 2
# Full event coverage would recover the same aggregate; these five logs cannot.
assert sum(r["outcome"] == "error" for r in requests) == counter["error"]
print(json.dumps({"requests": len(requests), "errors": counter["error"],
 "population_error_rate": population_rate, "exposed_metric_series": len(counter),
 "selected_logs": len(selected_logs), "selected_log_errors": logged_errors,
 "selected_log_error_rate": selected_rate,
 "exposition_validated_by": version}, indent=2))

输出应包含一百个请求、四个错误及零点零四的总体比例。筛选后的五条日志中有两个错误，得到零点四。导出文本只有两条按结果区分的计数序列，标签中不包含请求编号。Promtool 负责验证格式，Python 断言负责验证算术结果和事先定义的成员关系。这不是实际抓取流程、计数器重置处理或存储费用基准测试，因此不能把格式检查通过扩大为整套监控链路已经验证。

实际排查时，可以先用有界指标维度确定受影响的路由、结果或部署，再沿关联编号进入日志或链路，寻找单个请求的上下文。普通指标标签通常不应加入请求编号，除非已有明确的基数预算；当整套技术栈支持时，也可以通过示例数据关联追踪，而不把每个请求都变成独立序列。最后应把事件完整性、选择规则与派生比例的说明放在一起，让后来阅读图表的人能够重现它的单位、总体和时间口径。

来源

OpenTelemetry metrics，针对总体的测量与聚合，已核验 2026-09-13。
OpenTelemetry logs，事件记录及其与其他遥测信号的关系，已核验 2026-09-13。
Prometheus metric and label naming，有界标签及高基数维度的成本，已核验 2026-09-13。

给日志查询明确的问题与统计分母

Sun, 06 Sep 2026 00:00:00 +0000

有用的日志设计，应当从一个能够准确翻译为查询的问题开始。“找出错误记录”与“统计协调世界时十点到十一点之间最终失败的结账请求数”并不是同一个问题。前者用于定位诊断事件，后者需要明确哪些已完成请求属于总体、什么结果算失败，以及时间如何归属。单纯收集更多文本，并不会自动补齐这些语义；如果问题本身模糊，增加字段和存储量也可能只是让错误计算更快出现。

对于请求结果问题，可以定义每个逻辑请求只产生一次的终态事件。需要排查重试时，另外保留尝试事件，并为每个事件赋予稳定身份，以便识别重复投递。请求编号负责连接一次请求中的多个事件，事件编号负责区分这些事件本身。如果把请求编号用作所有事件的去重键，就会把合法的多次尝试和最终结果一起折叠掉，丢失原本需要解释的处理过程。

让查询约定可以被看见

首先决定窗口依据事件发生时间还是日志到达时间。采集器延迟时，两者会明显不同。采用包含起点、不包含终点的半开区间，可以让相邻窗口首尾连接，而不重复计算恰好落在边界上的事件。比较之前，还要把时间归到明确且无歧义的基准。只有本地时钟文字而没有偏移信息，不足以证明一条记录属于某个 UTC 故障窗口，不能由查询人员临时猜测其含义。

随后定义哪些终态属于失败。服务端错误、客户端取消和输入被拒绝，未必适合放进同一个可靠性指标。还应说明相关请求是否都会产生终态事件，以及采集链路是否可能丢失记录。查询对数据库里现存事件完全正确，也仍然可能无法完整描述服务行为。保留期限和筛选策略应写在结果解释旁边，不能只藏在采集配置里，让图表读者误把部分记录理解成全部业务事实。

坏掉的样子

一个请求第一次尝试失败、重试后成功，会留下真实错误事件，但它不是最终失败请求。把每条错误日志都计入失败请求数，会夸大问题；重复投递又可能把同一错误再计算一次。去重应建立在事件身份不可变的约定上。如果两个不同内容声称拥有相同事件编号，那是数据完整性异常，不能因为去重查询能顺利运行，就认为随便忽略其中一个也不会影响结果。

空窗口会带来另一种误判。零个失败除以零个请求，并不是已经测得零失败率。必须保留没有分母这一事实，否则日志采集停止时，可靠性图表反而可能显得十分健康。当排查需要解释某个具体请求时，应在总体口径确定后，读取该请求按时间排列的事件和依赖细节。单独一个汇总数量无法说明哪次重试恢复了，也无法解释另一个请求为什么最终失败。

快速验证

将代码保存为 log-questions.py，用 Python 执行。本次实际环境为 Python 3.14.4，使用标准库中的 SQLite 模块和内存数据库。输入的八条投递记录里有一条完全相同的重复事件；时间围绕一个固定 UTC 小时构造，并专门包含窗口开始之前的一条记录，以及恰好发生在窗口结束时的一条记录。这里没有连接真实采集器或外部数据库，目的是把查询规则及边界结果精确展示出来。

import json
import sqlite3
from datetime import datetime


def timestamp(value):
 parsed = datetime.fromisoformat(value)
 assert parsed.tzinfo is not None
 return int(parsed.timestamp())


start = timestamp("2026-09-01T10:00:00+00:00")
end = timestamp("2026-09-01T11:00:00+00:00")
rows = [
 ("e0", "r0", "request.completed", start - 1, 503),
 ("e1", "r1", "attempt.failed", start + 600, 503),
 ("e2", "r1", "request.completed", start + 660, 200),
 ("e3", "r2", "attempt.failed", start + 900, 503),
 ("e4", "r2", "request.completed", start + 960, 503),
 ("e4", "r2", "request.completed", start + 960, 503),
 ("e5", "r3", "request.completed", start + 1080, 200),
 ("e6", "r4", "request.completed", end, 503),
]
db = sqlite3.connect(":memory:")
db.execute("""CREATE TABLE events (
 event_id TEXT PRIMARY KEY, request_id TEXT,
 event_type TEXT, occurred_at INTEGER, status INTEGER)""")
db.executemany("""INSERT INTO events VALUES (?, ?, ?, ?, ?)
 ON CONFLICT(event_id) DO NOTHING""", rows)
stored = db.execute("SELECT count(*) FROM events").fetchone()[0]
assert stored == 7
error_events = db.execute("""SELECT count(*) FROM events
 WHERE occurred_at >= ? AND occurred_at < ? AND status >= 500""",
 (start, end)).fetchone()[0]
query = """SELECT count(*), coalesce(sum(status >= 500), 0)
 FROM events WHERE event_type = 'request.completed'
 AND occurred_at >= ? AND occurred_at < ?"""
total, failed = db.execute(query, (start, end)).fetchone()
completed = db.execute("""SELECT request_id, status FROM events
 WHERE event_type = 'request.completed' AND occurred_at >= ? AND occurred_at < ?
 ORDER BY request_id""", (start, end)).fetchall()
assert completed == [("r1", 200), ("r2", 503), ("r3", 200)]
assert (error_events, total, failed) == (3, 3, 1)
empty_total, empty_failed = db.execute(query, (end + 1, end + 3600)).fetchone()
empty_rate = empty_failed / empty_total if empty_total else None
assert (empty_total, empty_failed, empty_rate) == (0, 0, None)
print(json.dumps({"received_events": len(rows), "deduplicated_events": stored,
 "error_events_in_window": error_events, "completed_requests": total,
 "failed_requests": failed, "terminal_failure_rate": failed / total,
 "empty_window_rate": empty_rate}, indent=2))
db.close()

去重之后应剩下七个独立事件。在窗口内，按状态宽泛检索会找到三个错误事件：第一个请求的一次失败尝试、第二个请求的一次失败尝试，以及第二个请求的失败终态。但只统计终态时，结果是三个已完成请求，其中一个失败。第一个请求重试后成功，第三个请求直接成功，位于窗口外和结束边界的事件都被排除。因此请求最终失败比例是三分之一，而不是错误事件数除以某个未经定义的总量。

第二次查询针对更晚的空区间，请求数量为零，错误数量的空求和被规范为零，但派生失败率仍保留为空，因为不存在可计算的分母。断言证明的是完整受控记录上的查询语义。生产使用时，还要检查事件产生与传输覆盖，调查身份冲突，并与独立请求计数进行总量对照。最终交付的应是另一位值班人员能够按同样定义重现的问题与答案，而不是附着在大量日志上的一个无法解释的数字。

来源

OpenTelemetry logs，事件记录及其与其他遥测数据的关联，已核验 2026-09-13。
SQLite aggregate functions，查询中使用的计数、求和与空输入语义，已核验 2026-09-13。

日志 · XB 现场笔记

systemd journal 的保留范围需要明确约定

坏掉的样子

快速验证

按需要保留证据

延伸阅读

来源

按明确的字段与优先级规则查询 journal

坏掉的样子

快速验证

导出时保留上下文

延伸阅读

来源

结构化 nginx 日志需要同时约定转义和字段类型

坏掉的样子

快速验证

定义采集器应该接受什么

延伸阅读

来源

结构化日志让查询约定明确可见

把上下文放到正确的记录上

坏掉的样子

快速验证

延伸阅读

来源

访问日志应区分客户端结果与上游尝试

坏掉的样子

快速验证

在模式中保留诊断含义

来源

时间戳需要明确的时间语义

偏移不是完整时区规则

坏掉的样子

快速验证

延伸阅读

来源

Logrotate 在执行时应用轮转策略

坏掉的样子

快速验证

把策略作为完整流程运行

延伸阅读

来源

指标与日志都需要明确统计总体

先决定测量包含什么

坏掉的样子

快速验证

延伸阅读

来源

给日志查询明确的问题与统计分母

让查询约定可以被看见

坏掉的样子

快速验证

延伸阅读

来源