Request Scope
Every server source adapts its platform's request into one normalized shape, the
scope, before handing it to the collector. A config.ingest mapping resolves
against that shape, so a mapping written once resolves the same on Express, on
Cloud Functions, on Lambda and on any Fetch runtime.
Paths have no prefix: write headers.user-agent, not req.headers.user-agent.
Fields
| Field | Type | Description |
|---|---|---|
method | string | Uppercase HTTP method. |
url | string | Absolute request URL when the platform knows it, otherwise ''. Never a partial URL. |
path | string | Pathname only, no query string, leading slash. |
query | Record<string, string> | Query parameters. Repeated keys joined with ,. |
headers | Record<string, string> | Header bag. Keys lowercased. Repeated values joined with , . |
body | unknown | The parsed body when it parses as JSON, the raw string when it does not, undefined when there is none. |
ip | string | undefined | Client IP as the platform reports it. Absent when the platform reports none. |
raw | unknown | The untouched platform object. |
A value a platform does not supply is never guessed
The required fields are always present: when a platform cannot form one, it
carries the documented empty value rather than a guess (url is '' without a
host header). ip is the one optional field, and it is absent where the
platform reports none. A bare Fetch Request carries no client IP, so
scope.ip is undefined there rather than being derived from
x-forwarded-for. That header is still in headers, so deriving an IP from it
is a choice you make visibly in your configuration.
The body is parsed once, at the boundary. A navigator.sendBeacon payload
arrives as text/plain on several platforms and an API Gateway body can be
base64 encoded; both are resolved before the scope exists, so config.ingest
mappings and the event pipeline read the same normalized value rather than one
seeing the raw string and the other the parsed object.
A body that does not parse to an object is kept as-is and yields one empty
event, so a source.before transformer can decode it from ingest.body, once
config.ingest maps it there (body: { key: 'body' }). That case is the one
where the two deliberately differ; see the
event envelope.
Escape hatch: raw
raw holds the platform object itself: the Express Request, the Lambda event,
the WHATWG Request. Use it for anything the contract deliberately does not
cover.
ingest: {
map: {
// Contract fields, identical on every source
userAgent: { key: 'headers.user-agent' },
path: { key: 'path' },
// Platform specific, only where you know the platform
stage: { key: 'raw.requestContext.stage' },
},
}
A mapping that reads raw works only on that platform. When you need it, the
dependency is at least visible in the config.
Web and queue sources have no scope
Browser and dataLayer sources have no inbound request to adapt, so
config.ingest does not apply to them. Queue sources (Pub/Sub, SQS) push per
message rather than per request and likewise carry no scope.