@stainlessdev/xray-core 0.6.0-branch.bg-base48-ids.30aade2 → 0.6.0-dev.43c6594
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 +67 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
# @stainlessdev/xray-core
|
|
2
|
+
|
|
3
|
+
Core instrumentation for Stainless X-ray request logging. This package is runtime-agnostic and only provides the emitter, config, and types. Use it directly if you need a custom runtime or a custom OpenTelemetry exporter; otherwise prefer `@stainlessdev/xray-node` or `@stainlessdev/xray-fetch`.
|
|
4
|
+
|
|
5
|
+
## Install
|
|
6
|
+
|
|
7
|
+
```sh
|
|
8
|
+
pnpm add @stainlessdev/xray-core @opentelemetry/sdk-trace-base @opentelemetry/exporter-trace-otlp-proto
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## Basic usage
|
|
12
|
+
|
|
13
|
+
```ts
|
|
14
|
+
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto';
|
|
15
|
+
import { createEmitter } from '@stainlessdev/xray-core';
|
|
16
|
+
|
|
17
|
+
const endpointUrl = 'http://localhost:4318';
|
|
18
|
+
const exporter = new OTLPTraceExporter({
|
|
19
|
+
url: `${endpointUrl}/v1/traces`,
|
|
20
|
+
});
|
|
21
|
+
|
|
22
|
+
const xray = createEmitter(
|
|
23
|
+
{
|
|
24
|
+
serviceName: 'my-service',
|
|
25
|
+
endpointUrl,
|
|
26
|
+
},
|
|
27
|
+
exporter,
|
|
28
|
+
);
|
|
29
|
+
|
|
30
|
+
const ctx = xray.startRequest({
|
|
31
|
+
method: 'GET',
|
|
32
|
+
url: 'https://example.com/hello',
|
|
33
|
+
headers: { 'user-agent': 'curl/8.0' },
|
|
34
|
+
startTimeMs: Date.now(),
|
|
35
|
+
});
|
|
36
|
+
|
|
37
|
+
const log = xray.endRequest(ctx, {
|
|
38
|
+
statusCode: 200,
|
|
39
|
+
headers: { 'request-id': 'req_123' },
|
|
40
|
+
endTimeMs: Date.now(),
|
|
41
|
+
});
|
|
42
|
+
|
|
43
|
+
await xray.flush();
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
## Request IDs
|
|
47
|
+
|
|
48
|
+
X-ray always produces a request ID for each request. If you do not provide one, it resolves the ID in this order: explicit `requestId`, configured response header name (`requestId.header`, default: `request-id`), then an auto-generated UUIDv7-based ID. Runtime adapters inject the header automatically when missing; if you use `@stainlessdev/xray-core` directly, you are responsible for writing the response header yourself.
|
|
49
|
+
|
|
50
|
+
## Configuration (high-level)
|
|
51
|
+
|
|
52
|
+
`XrayConfig` lives in `packages/core/src/config.ts`. Common knobs:
|
|
53
|
+
|
|
54
|
+
- `serviceName` (required) and `endpointUrl` (falls back to `STAINLESS_XRAY_ENDPOINT_URL`).
|
|
55
|
+
- `exporter` overrides for OTLP headers, timeout, and span processor.
|
|
56
|
+
- `capture` and `redaction` toggles for headers/body logging.
|
|
57
|
+
- `requestId.header` for the response header name.
|
|
58
|
+
- `route` normalization options.
|
|
59
|
+
|
|
60
|
+
Notes:
|
|
61
|
+
|
|
62
|
+
- `endpointUrl` is required; `/v1/traces` is appended if missing. If both are set, `endpointUrl` wins over `STAINLESS_XRAY_ENDPOINT_URL`.
|
|
63
|
+
- If `endpointUrl` includes basic auth credentials, they are moved to the `Authorization` header automatically.
|
|
64
|
+
|
|
65
|
+
## When to use this package
|
|
66
|
+
|
|
67
|
+
Use `@stainlessdev/xray-core` only if you need to integrate with a custom runtime or supply your own `SpanExporter`. For Node and fetch-based runtimes, use `@stainlessdev/xray-node` or `@stainlessdev/xray-fetch` for a ready-to-go emitter and request/response adapters.
|