PostgREST 可观测性完全指南日志、指标与请求追踪的实践与原理【免费下载链接】postgrestREST API for any Postgres database项目地址: https://gitcode.com/GitHub_Trending/po/postgrestPostgREST 将 PostgreSQL 数据库自动转换为 REST API而可观测性正是运维这类无状态 API 服务的关键。本文以docs/references/observability.rst为核心骨架系统讲解 PostgREST 的三类可观测性能力——stdout/stderr日志、Prometheus 指标端点、以及 Server-Timing / Trace Header / EXPLAIN 执行计划等请求追踪手段并结合仓库源码Logger.hs、Metrics.hs、Apache.hs剖析其底层实现。读完本文你将掌握如何配置log-level/log-query、如何采集连接池与 JWT 缓存指标、如何开启 GHC RTS 指标、以及如何用执行计划定位慢查询。Logs两类日志流的区分与配置PostgREST 的日志分为两个截然不同的输出流这与 Logger.hs 模块的模块注释一致Access logs get sent to stdout and server diagnostic get sent to stderr访问日志发往 stdout服务端诊断日志发往 stderr。理解这一区分是正确收集日志的第一步。访问日志stdoutPostgREST 将基本请求信息以 Apache Combined Log 格式写入stdout包括经过认证的用户若可用、请求方 IP 地址、User-Agent、请求的 URL、HTTP 响应状态码、以及响应体大小字节若可用。当log-level设置为info时可以看到类似下面的输出127.0.0.1 - user [26/Jul/2021:01:56:38 -0500] GET /clients HTTP/1.1 200 56 curl/7.64.0 127.0.0.1 - anonymous [26/Jul/2021:01:56:48 -0500] GET /unexistent HTTP/1.1 404 162 curl/7.64.0从源码看这一格式由 Logger/Apache.hs 中的apacheFormat/apacheLogStr函数生成依次拼接来源 socket 地址、认证角色无则输出-、格式化时间、请求方法与路径含查询串、HTTP 版本、状态码、响应字节数无则-、Referer 与 User-Agent。该实现直接 vendored 自wai-logger库的 Apache 日志格式保证与标准 Web 服务器日志格式兼容可直接接入 Logstash、Filebeat 等采集管道。访问日志的具体输出行为由 Logger.hs 中的shouldLogResponse决定它按log-level过滤响应状态码log-level访问日志记录范围crit不记录任何请求error仅记录5xx状态码statusCode 500warn记录4xx及以上statusCode 400info记录所有请求debug记录所有请求服务端诊断日志stderr关于服务器自身的诊断信息则写入stderr主要包括所连接 PostgreSQL 数据库的完整版本schema cache 统计信息见 schema_cache.rstlistener 收到的数据库通知消息见 listener.rst。启动阶段与运行阶段的典型输出如下06/May/2024:08:16:11 -0500: Starting PostgREST 12.1... 06/May/2024:08:16:11 -0500: Successfully connected to PostgreSQL 14.10 (Ubuntu 14.10-0ubuntu0.22.04.1) on x86_64-pc-linux-gnu, compiled by gcc (Ubuntu 11.4.0-1ubuntu1~22.04) 11.4.0, 64-bit 06/May/2024:08:16:11 -0500: Connection Pool initialized with a maximum size of 10 connections 06/May/2024:08:16:11 -0500: API server listening on port 3000 06/May/2024:08:16:11 -0500: Listening for database notifications on the pgrst channel 06/May/2024:08:16:11 -0500: Config reloaded 06/May/2024:08:16:11 -0500: Schema cache queried in 3.8 milliseconds 06/May/2024:08:16:11 -0500: Schema cache loaded 15 Relations, 8 Relationships, 8 RPCs, 0 Domain Representations, 4 Media Type Handlers 06/May/2024:14:11:27 -0500: Received a config reload message on the pgrst channel 06/May/2024:14:11:27 -0500: Config reloaded这些诊断消息全部来自 Logger.hs 的observationMessages函数它对 PostgREST 内部的各种观察事件Observation进行文本化AppStartObs启动版本、DBConnectedObs数据库版本、PoolInit连接池大小、AppServerAddressObs监听端口、DBListenStart监听通道、SchemaCacheLoadedObs缓存加载统计、DBListenerGotConfigMsg/ConfigSucceededObs配置热加载等。注意日志行统一带%d/%b/%Y:%T %z格式的时间前缀例如06/May/2024:08:16:11 -0500。值得强调的是log-level是可以热加载的见下文配置小节Logger.hs 中observationLogger每次处理事件时都会实时读取配置因此修改配置后无需重启即可调整日志详略。log-level 与 log-query 配置详解所有日志行为都受log-level控制configuration.rst类型String默认值error可热加载是环境变量PGRST_LOG_LEVEL。各取值含义官方文档原话逐级递进# 仅记录启动与数据库连接恢复消息 log-level crit # 在 crit 基础上增加服务器错误5xx 状态码记录 log-level error # 在 error 基础上增加请求错误4xx 状态码记录 log-level warn # 在 warn 基础上记录所有请求所有状态码 log-level info # 在 info 基础上增加开发调试事件连接池事件、schema cache 解析耗时等 log-level debug从源码角度parseLogLevel在 Config.hs 中完成字符串到LogLevel数据类型的解析非法值会直接报错Invalid logging level. Check your configuration.。debug级别会额外输出连接池借还事件PoolRequest/PoolRequestFullfilled、连接建立与终止原因、JWT 缓存查找与驱逐、Warp 服务器内部消息等见 Logger.hs。官方文档特别提示由于目前日志没有缓冲crit/error这类最小化日志级别可以提升吞吐量。对高流量生产环境这值得在配置时权衡。记录 SQL 查询log-query要记录每个请求实际执行的 SQL 查询将log-query设为true配合当前的log-level生效configuration.rst 中默认值为falselog-level warn log-query trueSQL 查询只在 HTTP 状态码为 400 及以上时才会被记录。例如用户请求一个无权限的资源curl localhost:3000/protected_tablePostgREST 会输出如下日志——第一行是翻译后的 SQL含完整的 CTE 包装第二行是标准的 Apache 访问日志17/Feb/2025:17:28:15 -0500: WITH pgrst_source AS ( SELECT public.protected_table.* FROM public.protected_table ) SELECT null::bigint AS total_result_set, pg_catalog.count(_postgrest_t) AS page_total, coalesce(json_agg(_postgrest_t), []) AS body, nullif(current_setting(response.headers, true), ) AS response_headers, nullif(current_setting(response.status, true), ) AS response_status, AS response_inserted FROM ( SELECT * FROM pgrst_source ) _postgrest_t 127.0.0.1 - web_anon [17/Feb/2025:17:28:15 -0500] GET /protected_table HTTP/1.1 401 99 curl/8.7.1其实现机制在 Logger.hs当事件为QueryObs MainQuery{..} status时若shouldLogResponse判定当前状态码需要记录warn对应 400就把主查询的各个 SQL 片段事务变量、db-pre-request钩子、主查询、OpenAPI 查询、EXPLAIN 片段等通过renderSnippet渲染并合并为单行输出。数据库端日志从 PostgreSQL 侧观察 SQLPostgREST 的log-query只记录出错的查询。若要观察所有SQL 操作可以开启 PostgreSQL 自身的语句日志。默认情况下 PostgreSQL 不保留这些日志需要修改配置。在你的 PostgreSQL 数据目录中找到postgresql.conf可用show data_directory;命令定位将以下配置项改为对应值或直接追加到配置末尾# 将日志发送到采集器可访问的位置 log_destination stderr # 将 stderr 输出收集到日志文件 logging_collector on # 将日志保存到 pg 数据目录下的 pg_log/ log_directory pg_log # 可选每天新建一个日志文件 log_filename postgresql-%Y-%m-%d.log # 记录所有类型的 SQL 语句 log_statement all重启数据库后实时跟踪日志文件即可观察 HTTP 请求如何被翻译为 SQL 命令。Docker 场景可以通过自定义init.sh启用日志#!/bin/sh echo log_statement all /var/lib/postgresql/data/postgresql.conf然后启动容器并跟踪日志docker run -v $(pwd)/init.sh:/docker-entrypoint-initdb.d/init.sh -d postgres docker logs -f container-idMetricsPrometheus 格式指标端点PostgREST 的管理服务器admin server见 admin_server.rst上提供了metrics端点以 Prometheus 文本格式暴露指标curl http://localhost:3001/metrics响应示例HTTP/1.1 200 OK Content-Type: text/plain; charsetutf-8 # HELP pgrst_schema_cache_query_time_seconds The query time in seconds of the last schema cache load # TYPE pgrst_schema_cache_query_time_seconds gauge pgrst_schema_cache_query_time_seconds 1.5937927e-2 # HELP pgrst_schema_cache_loads_total The total number of times the schema cache was loaded # TYPE pgrst_schema_cache_loads_total counter pgrst_schema_cache_loads_total 1.0 ...这些指标的定义集中在 Metrics.hs 的init函数中底层基于 Haskellprometheus库注册与导出metricsToText通过exportMetricsAsText输出。指标来源是 PostgREST 内部的观察事件流——observationMetrics函数把PoolAcqTimeoutObs、SchemaCacheLoadedObs、JwtCacheLookup等事件分别映射为对应计数器的增减Metrics.hs。这也解释了为什么这些指标与日志能共享同一套内部事件体系。Schema Cache 指标与 schema cache见 schema_cache.rst相关的指标pgrst_schema_cache_query_time_seconds类型Gauge上次 schema cache 加载的查询耗时秒。对应源码中SchemaCacheLoadedObs事件触发时setGauge schemaCacheQueryTime resTime。pgrst_schema_cache_loads_total类型Counter标签statusSUCCESS | FAILschema cache 加载的总次数按成功/失败打标签。源码中成功时withLabel schemaCacheLoads SUCCESS incCounter失败时withLabel schemaCacheLoads FAIL incCounter。Connection Pool 指标与连接池见 connection_pool.rst相关的指标pgrst_db_pool_timeouts_total类型Counter连接池获取连接超时的总次数。对应PoolAcqTimeoutObs事件触发的incCounter poolTimeouts。pgrst_db_pool_available类型Gauge连接池中可用连接数。该值的计算并不简单hasql-pool对连接建立成功和连接建立失败都会发出TerminatedConnectionStatus事件仅凭池事件无法无状态地维护准确的 in-use 连接数因此 Metrics.hs 用ConnTrack哈希表显式跟踪每条连接connTrackConnected/connTrackInUsecalcAvailable connected - inUse计算可用数。pgrst_db_pool_waiting类型Gauge等待获取连接池连接的请求数。PoolRequest事件时incGauge poolWaitingPoolRequestFullfilled事件时decGauge poolWaiting。pgrst_db_pool_max类型Gauge连接池最大连接数。初始化时由configDbPoolSize通过setGauge (poolMaxSize metricState)设置。JWT Cache 指标与 JWT 缓存相关的指标见 auth 文档中的 JWT 缓存章节pgrst_jwt_cache_requests_total类型CounterJWT 缓存查找总次数。源码中JwtCacheLookup事件无论命中与否都会incCounter jwtCacheRequests。pgrst_jwt_cache_hits_total类型CounterJWT 缓存命中总次数。命中时同时递增jwtCacheRequests与jwtCacheHits。pgrst_jwt_cache_evictions_total类型CounterJWT 缓存驱逐总次数。对应JwtCacheEviction事件。提示JWT 缓存命中率直接影响认证阶段耗时见下文 Server-Timing 的jwt阶段说明这两组指标可以联动分析。GHC Runtime 指标进程健康与内存诊断PostgREST 还能暴露 GHC 运行时系统指标使用ghc_*前缀包含 GHC RTS 统计信息运行时分配、垃圾回收、内存、CPU/墙钟时间。这些指标对监控 PostgREST 进程健康、诊断内存压力或 GC 行为非常有价值。要启用它们需要以开启 GHC RTS 统计的方式启动 PostgRESTpostgrest RTS -T -RTS启用后admin 的/metrics端点会包含类似采样# HELP ghc_gcs_total Total number of GCs # TYPE ghc_gcs_total counter ghc_gcs_total 1 # HELP ghc_allocated_bytes_total Total bytes allocated # TYPE ghc_allocated_bytes_total counter ghc_allocated_bytes_total 12345678其他可用的 GHC 运行时指标包括ghc_gcs_totalghc_major_gcs_totalghc_allocated_bytes_totalghc_max_live_bytesghc_max_mem_in_use_bytesghc_mutator_cpu_seconds_totalghc_gc_cpu_seconds_totalghc_elapsed_seconds_total实现上Metrics.hs 在初始化时通过getRTSStatsEnabled检测 RTS 统计是否开启开启时才注册Prometheus.Metric.GHC的ghcMetrics因此不带RTS -T -RTS启动时ghc_*指标不会出现。Traces请求链路追踪与性能定位追踪维度覆盖 HTTP 层面的版本头、请求 ID 透传、分阶段耗时头以及 SQL 执行计划获取用于在请求级定位问题。Server 版本响应头排查问题时首先需要确认正在运行的 PostgREST 版本。每个响应都带有ServerHTTP 响应头HEAD /users HTTP/1.1 Server: postgrest/11.0.1Trace Header请求 ID 透传通过设置server-trace-header见 configuration.rst可以启用 HTTP 请求追踪在请求中携带指定头服务器会将其原样包含在响应中便于跨组件串联日志server-trace-header X-Request-Idcurl http://localhost:3000/users \ -H X-Request-Id: 123响应HTTP/1.1 200 OK X-Request-Id: 123其实现是 App.hs 中的traceHeaderMiddleware中间件从配置读取configServerTraceHeader从请求头中查找同名字段将其缺失时为空附加到响应头中。配置解析在 Config.hsoptString server-trace-header并支持配置转储。Proxy-Status Header反向代理状态头Proxy-Status的相关说明见 proxy_status_header位于 api.rst 文档。它用于携带反向代理如 Nginx、CDN对请求的处理状态信息。Server-Timing Header请求-响应各阶段耗时开启server-timing-enabled见 configuration.rst后PostgREST 会返回Server-Timing响应头携带请求-响应周期内各阶段的耗时指标curl http://localhost:3000/users -iHTTP/1.1 200 OK Server-Timing: jwt;dur14.9, parse;dur71.1, plan;dur109.0, transaction;dur353.2, response;dur4.4所有dur单位均为毫秒jwt执行 JWT 认证的阶段见 auth.rst。该耗时可通过 JWT 缓存降低jwt-cache相关配置parse解析 URL 语法阶段见 url_grammar.rstplan利用 schema cache 生成事务主查询的阶段见 main_query 相关章节transaction数据库事务执行阶段见 transactions.rstresponse计算响应状态与响应头的阶段。官方文档同时指出项目正致力于降低parse与plan阶段的耗时。实现上serverTimingHeader位于 Response/Performance.hs按jwt, parse, plan, transaction, response顺序渲染App.hs 的withTiming通过timeItT对各阶段计时configServerTimingEnabled为真时把结果头附加到响应App.hs。此外相关测试位于 ServerTimingSpec.hs可作为行为参考。Content-Length Header响应体大小验证可以通过Content-Length响应头验证响应体大小字节curl -i localhost:3000/usersHTTP/1.1 200 OK Content-Length: 104注意出于优化目的HEAD请求不会返回该头见 head_req 相关说明这与 RFC 9110 的规定一致。响应体大小同样出现在 PostgREST 的访问日志中即 Apache 日志格式里的字节数字段。Execution plan获取 EXPLAIN 执行计划为请求添加Accept: application/vnd.pgrst.plan头即可获取其 EXPLAIN 执行计划。此功能由db-plan-enabled开启默认false见 configuration.rstcurl http://localhost:3000/users?selectnameorderid \ -H Accept: application/vnd.pgrst.plan输出text 格式Aggregate (cost73.65..73.68 rows1 width112) - Index Scan using users_pkey on users (cost0.15..60.90 rows850 width36)计划默认以text格式生成可通过json后缀改为 JSONcurl http://localhost:3000/users?selectnameorderid \ -H Accept: application/vnd.pgrst.planjson[ { Plan: { Node Type: Aggregate, Strategy: Plain, Partial Mode: Simple, Parallel Aware: false, Async Capable: false, Startup Cost: 73.65, Total Cost: 73.68, Plan Rows: 1, Plan Width: 112, Plans: [ { Node Type: Index Scan, Parent Relationship: Outer, Parallel Aware: false, Async Capable: false, Scan Direction: Forward, Index Name: users_pkey, Relation Name: users, Alias: users, Startup Cost: 0.15, Total Cost: 60.90, Plan Rows: 850, Plan Width: 36 } ] } } ]for参数默认计划假设资源以 JSON 表示application/json但可以通过for参数获取 PostgREST 支持的不同表示见 res_format的计划。例如获取text/xml表示的计划Accept: application/vnd.pgrst.plan; fortext/xmloptions参数其他可用参数为analyze、verbose、settings、buffers、wal与 EXPLAIN 命令选项一一对应。例如同时使用analyze与walAccept: application/vnd.pgrst.plan; optionsanalyze|wal工作流参考如需从 verbose 计划中提取Query Identifier并在pg_stat_statements中检查同一条查询可参考 debugging-performance-with-pg-stat-statements.rst。重要注意事项与 EXPLAIN 命令类似使用analyze选项时变更会被提交。要避免提交可以配合db-tx-end配置与Prefer: txrollback头使用见 transactions.rst。保护执行计划功能官方强烈建议仅在测试环境启用db-plan-enabled因为它会泄露数据库内部细节。若确需在生产环境使用可以通过db-pre-request见 configuration.rst限制可使用该功能的请求。例如仅允许特定 IP 获取执行计划-- 假设反向代理(Nginx、Cloudflare 等)传递 X-Forwarded-For 头 create or replace function filter_plan_requests() returns void as $$ declare headers json : current_setting(request.headers, true)::json; client_ip text : coalesce(headers-x-forwarded-for, ); accept text : coalesce(headers-accept, ); begin if accept like application/vnd.pgrst.plan% and client_ip ! 144.96.121.73 then raise insufficient_privilege using message Not allowed to use application/vnd.pgrst.plan; end if; end; $$ language plpgsql; -- 在 postgrest.conf 中配置 -- db-pre-request filter_plan_requests该函数读取request.headersGUC 头机制见 guc_header 相关章节中的accept与x-forwarded-for对非白名单 IP 的 plan 请求抛出insufficient_privilege从而在不关闭功能的前提下收紧访问。结语如何组合使用三层可观测性PostgREST 的可观测性设计遵循经典的 logs / metrics / traces 三支柱模型且全部围绕同一套内部观察事件体系PostgREST.Observation实现源码中 Logger.hs 与 Metrics.hs 分别消费这些事件产出日志与指标架构清晰、易于扩展。实际运维时可参考以下组合策略日常监控开启 admin server 的/metrics端点配合 Prometheus Grafana 采集pgrst_db_pool_*、pgrst_schema_cache_*、pgrst_jwt_cache_*并在启动命令中加上RTS -T -RTS以获得ghc_*运行时指标故障定位设置server-trace-header透传X-Request-Id开启server-timing-enabled观察各阶段耗时分布jwt/parse/plan/transaction/response再结合log-level warnlog-query true捕获 4xx/5xx 对应的 SQL性能调优在测试环境开启db-plan-enabled用Accept: application/vnd.pgrst.planjson获取 JSON 执行计划结合pg_stat_statements做深入分析生产环境务必用db-pre-request做访问控制。相关配置项速查详见 configuration.rst配置项默认值作用log-levelerror日志详细程度crit/error/warn/info/debug可热加载log-queryfalse是否在 4xx/5xx 时记录对应 SQLserver-trace-header空透传的请求追踪头名server-timing-enabledfalse是否输出 Server-Timing 分阶段耗时db-plan-enabledfalse是否允许通过 Accept 头获取 EXPLAIN 计划db-pre-request空请求前置函数可限制 plan 等功能的使用相关源码与测试入口日志格式 Logger/Apache.hs、日志实现 Logger.hs、指标实现 Metrics.hs、Server-Timing 渲染 Response/Performance.hs、Trace Header 中间件 App.hs、配置解析 Config.hs、行为测试 ServerTimingSpec.hs。【免费下载链接】postgrestREST API for any Postgres database项目地址: https://gitcode.com/GitHub_Trending/po/postgrest创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考