feat: pass HTTP headers to evlog:drain hook (#31)

Author: HugoRCD

apps/docs/content/1.getting-started/2.installation.md

@@ -166,6 +166,40 @@ export default defineNitroPlugin((nitroApp) => {
 The hook receives a `DrainContext` with:
 - `event`: The complete `WideEvent` (timestamp, level, service, and all accumulated context)
 - `request`: Optional request metadata (`method`, `path`, `requestId`)
+- `headers`: HTTP headers from the original request (useful for correlation with external services)
+
+::callout{icon="i-lucide-shield-check" color="success"}
+**Security:** Sensitive headers (`authorization`, `cookie`, `set-cookie`, `x-api-key`, `x-auth-token`, `proxy-authorization`) are automatically filtered out and never passed to the drain hook.
+::
+
+#### Using Headers for External Service Correlation
+
+The `headers` field allows you to correlate logs with external services like PostHog, Sentry, or custom analytics:
+
+```typescript [server/plugins/evlog-posthog.ts]
+export default defineNitroPlugin((nitroApp) => {
+  const posthog = usePostHog()
+
+  nitroApp.hooks.hook('evlog:drain', (ctx) => {
+    if (!posthog) return
+
+    // Extract correlation headers sent from the client
+    const sessionId = ctx.headers?.['x-posthog-session-id']
+    const distinctId = ctx.headers?.['x-posthog-distinct-id']
+
+    if (!distinctId) return
+
+    posthog.capture({
+      distinctId,
+      event: 'server_log',
+      properties: {
+        ...ctx.event,
+        $session_id: sessionId,
+      },
+    })
+  })
+})
+```
 
 ### Client Transport
 

apps/playground/server/plugins/evlog-drain.ts

@@ -1,14 +1,25 @@
 // Example drain hook - demonstrates evlog:drain usage
 export default defineNitroPlugin((nitroApp) => {
   nitroApp.hooks.hook('evlog:drain', (ctx) => {
-    // Example: log the event to console (replace with your external service)
-    console.log('[DRAIN]', JSON.stringify(ctx.event, null, 2))
+    // Example: log the event and headers to console (replace with your external service)
+    console.log('[DRAIN]', JSON.stringify({
+      event: ctx.event,
+      request: ctx.request,
+      headers: ctx.headers,
+    }, null, 2))
 
     // Example: send to Axiom (uncomment and configure)
     // await fetch('https://api.axiom.co/v1/datasets/logs/ingest', {
     //   method: 'POST',
     //   headers: { Authorization: `Bearer ${process.env.AXIOM_TOKEN}` },
     //   body: JSON.stringify([ctx.event])
     // })
+
+    // Example: correlate with PostHog using headers (uncomment and configure)
+    // const sessionId = ctx.headers?.['x-posthog-session-id']
+    // const distinctId = ctx.headers?.['x-posthog-distinct-id']
+    // if (distinctId) {
+    //   posthog.capture({ distinctId, event: 'server_log', properties: { ...ctx.event, $session_id: sessionId } })
+    // }
   })
 })

packages/evlog/src/nitro/plugin.ts

@@ -1,5 +1,6 @@
 import type { NitroApp } from 'nitropack/types'
 import { defineNitroPlugin, useRuntimeConfig } from 'nitropack/runtime'
+import { getHeaders } from 'h3'
 import { createRequestLogger, initLogger } from '../logger'
 import type { RequestLogger, SamplingConfig, ServerEvent, TailSamplingContext, WideEvent } from '../types'
 import { matchesPattern } from '../utils'
@@ -29,6 +30,29 @@ function shouldLog(path: string, include?: string[], exclude?: string[]): boolea
   return include.some(pattern => matchesPattern(path, pattern))
 }
 
+/** Headers that should never be passed to the drain hook for security */
+const SENSITIVE_HEADERS = [
+  'authorization',
+  'cookie',
+  'set-cookie',
+  'x-api-key',
+  'x-auth-token',
+  'proxy-authorization',
+]
+
+function getSafeHeaders(event: ServerEvent): Record<string, string> {
+  const allHeaders = getHeaders(event as Parameters<typeof getHeaders>[0])
+  const safeHeaders: Record<string, string> = {}
+
+  for (const [key, value] of Object.entries(allHeaders)) {
+    if (!SENSITIVE_HEADERS.includes(key.toLowerCase())) {
+      safeHeaders[key] = value
+    }
+  }
+
+  return safeHeaders
+}
+
 function getResponseStatus(event: ServerEvent): number {
   // Node.js style
   if (event.node?.res?.statusCode) {
@@ -53,6 +77,7 @@ function callDrainHook(nitroApp: NitroApp, emittedEvent: WideEvent | null, event
     nitroApp.hooks.callHook('evlog:drain', {
       event: emittedEvent,
       request: { method: event.method, path: event.path, requestId: event.context.requestId as string | undefined },
+      headers: getSafeHeaders(event),
     }).catch((err) => {
       console.error('[evlog] drain failed:', err)
     })

packages/evlog/src/types.ts

@@ -125,6 +125,8 @@ export interface DrainContext {
     path?: string
     requestId?: string
   }
+  /** HTTP headers from the original request (useful for correlation with external services) */
+  headers?: Record<string, string>
 }
 
 /**