Request ID

在请求和响应之间生成或透传唯一标识

Elogs 自动生成或读取唯一请求标识(request ID),挂到请求 context、响应头和 access log 上。生产环境调试、按 ID grep 日志、跨服务追踪都用得上。

基本用法

config.requestId: true 开启。默认配置使用 X-Request-Id 头和 crypto.randomUUID() 生成器。

import { Elysia } from 'elysia'
import { createElogs } from '@eastgold15/elogs'

const app = new Elysia().use(
  createElogs({
    config: {
      requestId: true,
    },
  })
)

请求进来时:

读入站 Request 的 X-Request-Id header,有就用它(透传上游 trace key)。
没有就 crypto.randomUUID() 生成一个。
ID 写到请求作用域 context 的 requestId 字段。
响应阶段(afterHandle)回写到响应 header —— 客户端也能拿到。

关闭整个 feature false 或不设。

import { createElogs } from '@eastgold15/elogs'

createElogs({ config: { requestId: false } })

`prod` preset 自动开启

const app = new Elysia().use(
  createElogs({
    preset: 'prod', // 自动 requestId: true
  })
)

自定义配置

传 RequestIdConfig 对象做更细的控制:

import { createElogs } from '@eastgold15/elogs'

createElogs({
  config: {
    requestId: {
      // 自定义 header 名(读入站 + 写回响应都用这个)
      header: 'X-Correlation-Id',
      // 自定义 ID 生成函数
      generator: () => `req-${crypto.randomUUID()}`,
    },
  },
})

选项

字段	类型	默认	描述
`enabled`	`boolean`	`true`	用对象配置时显式开关;设 `false` 等价于整个 feature 关闭
`header`	`string`	`"X-Request-Id"`	入站读、出站写的 header 名
`generator`	`() => string`	`crypto.randomUUID`	生成新 ID 的函数

入站值会用 ^[A-Za-z0-9._-]{1,128}$ 校验 —— 长度合法才会被信任地回显,否则直接替换成 generator() 的新值(防 header 注入 / 超长字符串污染日志)。

在日志格式里引用

customLogFormat 支持 {requestId} 占位符,直接渲染当前请求的 ID:

import { createElogs } from '@eastgold15/elogs'

createElogs({
  config: {
    requestId: true,
    customLogFormat: '[{requestId}] {method} {pathname} {status} {duration}ms',
  },
})

输出形如:

[01HXY...] GET /api/users 200 12.34ms

requestId 没开启或缺失时,token 渲染为空字符串。

跟 redaction 配对

把 request ID 跟 autoRedact: true 配对,让 authorization / cookie 在 access log 里被脱敏,但 request ID 仍能 grep:

import { createElogs } from '@eastgold15/elogs'

createElogs({
  config: {
    requestId: true,
    autoRedact: true,
    customLogFormat: '[{requestId}] {method} {pathname} {status} {duration}ms',
  },
})

跨服务追踪

request ID 是应用层关联键,跟 OpenTelemetry 的 trace ID 是独立的。生产环境通常两层都开:

import { Elysia } from 'elysia'
import { createElogs } from '@eastgold15/elogs'
import { injectTraceContext } from '@eastgold15/elogs/otel' // 可选 peer 依赖,见 OTel 集成文档

const plugin = createElogs({
  config: {
    requestId: true,
  },
})

new Elysia()
  .use(plugin)
  .request(({ request, store }) => {
    injectTraceContext(store.logger, request)
  })

request ID → grep 单服务日志;trace ID → 跨服务 span 关联。详见 OpenTelemetry 集成。

公开 API

resolveRequestIdConfig(raw) 和 getOrCreateRequestId(request, config) 也单独导出,要写自己的中间件 / 测试时用:

import { resolveRequestIdConfig, getOrCreateRequestId } from '@eastgold15/elogs'

const config = resolveRequestIdConfig(true)
// → { enabled: true, generator: <UUID>, header: 'X-Request-Id' }

const id = getOrCreateRequestId(request, config)
// → '01HXY...' 或 入站 header 的值