@stainlessdev/xray-express 0.6.0 → 0.7.0-dev.588fa57
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +72 -0
- package/package.json +3 -3
package/README.md
ADDED
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
# @stainlessdev/xray-express
|
|
2
|
+
|
|
3
|
+
Express integration for Stainless X-ray request logging. Provides a middleware that wraps Express requests and responses.
|
|
4
|
+
|
|
5
|
+
## Install
|
|
6
|
+
|
|
7
|
+
```sh
|
|
8
|
+
pnpm add @stainlessdev/xray-express
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## Basic usage
|
|
12
|
+
|
|
13
|
+
```ts
|
|
14
|
+
import express from 'express';
|
|
15
|
+
import { createEmitter } from '@stainlessdev/xray-express';
|
|
16
|
+
import { getXrayContext } from '@stainlessdev/xray-node';
|
|
17
|
+
|
|
18
|
+
const app = express();
|
|
19
|
+
|
|
20
|
+
const xray = createEmitter({
|
|
21
|
+
serviceName: 'my-service',
|
|
22
|
+
endpointUrl: 'http://localhost:4318',
|
|
23
|
+
});
|
|
24
|
+
|
|
25
|
+
app.use(xray);
|
|
26
|
+
|
|
27
|
+
app.use((req, _res, next) => {
|
|
28
|
+
const ctx = getXrayContext(req);
|
|
29
|
+
ctx?.setUserId('user-123');
|
|
30
|
+
next();
|
|
31
|
+
});
|
|
32
|
+
|
|
33
|
+
app.get('/', (_req, res) => {
|
|
34
|
+
res.send('ok');
|
|
35
|
+
});
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
The middleware also attaches the context to `req.xray` and `res.locals.xray` for convenience.
|
|
39
|
+
|
|
40
|
+
## Request IDs and response headers
|
|
41
|
+
|
|
42
|
+
X-ray will **auto-generate a request ID and inject it into your response headers** under the configured name (`requestId.header`, default `request-id`, emitted as `Request-Id`) if the header is missing. If you set your own request ID first (via `options.requestId` or by setting the response header yourself), X-ray preserves it and does not overwrite the header.
|
|
43
|
+
|
|
44
|
+
## Configuration
|
|
45
|
+
|
|
46
|
+
`createEmitter(config, options?)` accepts `XrayRuntimeConfig` (config) and `WrapOptions` (per-request defaults):
|
|
47
|
+
|
|
48
|
+
- `serviceName` (required)
|
|
49
|
+
- `endpointUrl` (required; falls back to `STAINLESS_XRAY_ENDPOINT_URL` when omitted; explicit `endpointUrl` wins)
|
|
50
|
+
- `environment`, `version`, `logger`, `logLevel`
|
|
51
|
+
- `exporter`: `endpointUrl`, `headers`, `timeoutMs`, `spanProcessor`, `instance` (custom SpanExporter)
|
|
52
|
+
- `capture`: request/response headers and bodies
|
|
53
|
+
- `redaction`: headers/query/body JSON-path redaction
|
|
54
|
+
- `requestId`: header name to read/write
|
|
55
|
+
- `route`: normalization options
|
|
56
|
+
|
|
57
|
+
## Adapter options (WrapOptions)
|
|
58
|
+
|
|
59
|
+
- `route`: override the route name for the request
|
|
60
|
+
- `requestId`: explicit request ID to use (prevents auto-generation)
|
|
61
|
+
- `capture`: per-request capture overrides
|
|
62
|
+
- `redaction`: per-request redaction overrides
|
|
63
|
+
- `onRequest(ctx)`, `onResponse(ctx, log)`, `onError(ctx, err)` hooks
|
|
64
|
+
|
|
65
|
+
## Advanced usage
|
|
66
|
+
|
|
67
|
+
If you already have an `XrayEmitter` instance, use `createExpressMiddleware(xray, options)` to create middleware.
|
|
68
|
+
|
|
69
|
+
## Notes
|
|
70
|
+
|
|
71
|
+
- This package depends on OpenTelemetry packages as peer dependencies.
|
|
72
|
+
- Node.js >= 20 is required.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@stainlessdev/xray-express",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.7.0-dev.588fa57",
|
|
4
4
|
"description": "Express integration for Stainless X-ray request logging",
|
|
5
5
|
"files": [
|
|
6
6
|
"dist"
|
|
@@ -20,8 +20,8 @@
|
|
|
20
20
|
"access": "public"
|
|
21
21
|
},
|
|
22
22
|
"dependencies": {
|
|
23
|
-
"@stainlessdev/xray-core": "0.
|
|
24
|
-
"@stainlessdev/xray-node": "0.
|
|
23
|
+
"@stainlessdev/xray-core": "0.7.0-dev.588fa57",
|
|
24
|
+
"@stainlessdev/xray-node": "0.7.0-dev.588fa57"
|
|
25
25
|
},
|
|
26
26
|
"devDependencies": {
|
|
27
27
|
"@opentelemetry/api": "^1.9.0",
|