@apinecka/logs-client 0.0.0-stage → 1.1.0

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.
Files changed (75) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +189 -2
  3. package/dist/client.d.ts +68 -0
  4. package/dist/client.js +372 -0
  5. package/dist/client.js.map +1 -0
  6. package/dist/conform.d.ts +39 -0
  7. package/dist/conform.js +187 -0
  8. package/dist/conform.js.map +1 -0
  9. package/dist/context.d.ts +60 -0
  10. package/dist/context.js +118 -0
  11. package/dist/context.js.map +1 -0
  12. package/dist/error.d.ts +8 -0
  13. package/dist/error.js +58 -0
  14. package/dist/error.js.map +1 -0
  15. package/dist/index.d.ts +5 -0
  16. package/dist/index.js +22 -0
  17. package/dist/index.js.map +1 -0
  18. package/dist/nest/index.d.ts +1 -0
  19. package/dist/nest/index.js +18 -0
  20. package/dist/nest/index.js.map +1 -0
  21. package/dist/nest/logs.logger.d.ts +39 -0
  22. package/dist/nest/logs.logger.js +199 -0
  23. package/dist/nest/logs.logger.js.map +1 -0
  24. package/dist/schema/index.d.ts +7 -0
  25. package/dist/schema/index.js +9 -0
  26. package/dist/schema/index.js.map +1 -0
  27. package/dist/schema/models/createLog.d.ts +53 -0
  28. package/dist/schema/models/createLog.js +3 -0
  29. package/dist/schema/models/createLog.js.map +1 -0
  30. package/dist/schema/models/createLogBatch.d.ts +15 -0
  31. package/dist/schema/models/createLogBatch.js +3 -0
  32. package/dist/schema/models/createLogBatch.js.map +1 -0
  33. package/dist/schema/models/createLogBatchResult.d.ts +13 -0
  34. package/dist/schema/models/createLogBatchResult.js +10 -0
  35. package/dist/schema/models/createLogBatchResult.js.map +1 -0
  36. package/dist/schema/models/createLogMeta.d.ts +13 -0
  37. package/dist/schema/models/createLogMeta.js +10 -0
  38. package/dist/schema/models/createLogMeta.js.map +1 -0
  39. package/dist/schema/models/createLogTags.d.ts +13 -0
  40. package/dist/schema/models/createLogTags.js +10 -0
  41. package/dist/schema/models/createLogTags.js.map +1 -0
  42. package/dist/schema/models/index.d.ts +21 -0
  43. package/dist/schema/models/index.js +38 -0
  44. package/dist/schema/models/index.js.map +1 -0
  45. package/dist/schema/models/logContexts.d.ts +15 -0
  46. package/dist/schema/models/logContexts.js +3 -0
  47. package/dist/schema/models/logContexts.js.map +1 -0
  48. package/dist/schema/models/logError.d.ts +21 -0
  49. package/dist/schema/models/logError.js +3 -0
  50. package/dist/schema/models/logError.js.map +1 -0
  51. package/dist/schema/models/logLevel.d.ts +16 -0
  52. package/dist/schema/models/logLevel.js +19 -0
  53. package/dist/schema/models/logLevel.js.map +1 -0
  54. package/dist/schema/models/logRequestContext.d.ts +28 -0
  55. package/dist/schema/models/logRequestContext.js +3 -0
  56. package/dist/schema/models/logRequestContext.js.map +1 -0
  57. package/dist/schema/models/logRequestContextHeaders.d.ts +13 -0
  58. package/dist/schema/models/logRequestContextHeaders.js +10 -0
  59. package/dist/schema/models/logRequestContextHeaders.js.map +1 -0
  60. package/dist/schema/models/logRequestContextQuery.d.ts +13 -0
  61. package/dist/schema/models/logRequestContextQuery.js +10 -0
  62. package/dist/schema/models/logRequestContextQuery.js.map +1 -0
  63. package/dist/schema/models/logRuntimeContext.d.ts +20 -0
  64. package/dist/schema/models/logRuntimeContext.js +10 -0
  65. package/dist/schema/models/logRuntimeContext.js.map +1 -0
  66. package/dist/schema/models/logStackFrame.d.ts +17 -0
  67. package/dist/schema/models/logStackFrame.js +10 -0
  68. package/dist/schema/models/logStackFrame.js.map +1 -0
  69. package/dist/schema/models/logUser.d.ts +13 -0
  70. package/dist/schema/models/logUser.js +10 -0
  71. package/dist/schema/models/logUser.js.map +1 -0
  72. package/dist/types.d.ts +63 -0
  73. package/dist/types.js +3 -0
  74. package/dist/types.js.map +1 -0
  75. package/package.json +69 -5
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Tomáš Cupák
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,190 @@
1
- # Temporary Holding Version
1
+ # @apinecka/logs-client
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Client for the ingest endpoints (`POST /logs`, `POST /logs/batch`) of Apinecka Logs:
4
+ a framework-free client with batching, retries and request context, and a NestJS logger that ships log lines to logs-api.
5
+
6
+ ## Install
7
+
8
+ ```bash
9
+ npm install @apinecka/logs-client
10
+ # for the NestJS logger (an optional peer dependency):
11
+ npm install @nestjs/common
12
+ ```
13
+
14
+ ## NestJS
15
+
16
+ ```ts
17
+ import { LogsClient } from '@apinecka/logs-client'
18
+ import { LogsApiLogger } from '@apinecka/logs-client/nest'
19
+ import { NestFactory } from '@nestjs/core'
20
+
21
+ const client = new LogsClient({
22
+ baseUrl: 'https://logs.apinecka.com',
23
+ apiKey: process.env.LOGS_API_KEY,
24
+ release: process.env.GIT_SHA,
25
+ })
26
+ const app = await NestFactory.create(AppModule, { logger: new LogsApiLogger({ prefix: 'API' }, client) })
27
+ app.enableShutdownHooks()
28
+ ```
29
+
30
+ `LogsApiLogger` extends Nest's `ConsoleLogger`: it still prints to the console and additionally queues
31
+ `log`, `warn`, `error` and `fatal` entries (not `debug`/`verbose`). The `prefix` becomes the log's `appName`.
32
+ A failed send is swallowed - logging never crashes the app. A publisher with only `create` (no `enqueue`)
33
+ still works and is sent fire-and-forget, one request per entry.
34
+
35
+ How the call is read (the same way Nest's `ConsoleLogger` does it): the last string param is the context
36
+ (`new Logger('Ctx')` appends it), a string before it is the stack.
37
+
38
+ - `logger.error(err)` - `error` is the serialized `Error` (type, message, stack, `cause` chain, `AggregateError`
39
+ errors); the message is `Type: message`. An `AxiosError` never carries its request config or headers.
40
+ - `logger.error('Payment failed', err.stack)` - `error` is built from the message and the stack.
41
+ - A plain-object message uses its `message` (or `msg`) and the rest becomes `meta`.
42
+ - Extra data: `logger.error(err, { meta, tags, user, fingerprint, traceId })` or
43
+ `new Logger('Ctx').error('Payment failed', { meta: { orderId } })`. An object with only those keys
44
+ (`LogOptions`) is not printed to the console; any other object param is merged into `meta` (and printed).
45
+
46
+ ## Delivery
47
+
48
+ `client.enqueue(entry)` is the reliable path (the Nest logger uses it): entries wait in an in-memory queue
49
+ and are sent in batches to `POST /logs/batch`.
50
+
51
+ - A batch goes out when `maxBatchItems` are queued or every `flushIntervalMs`; one request is in flight at a time.
52
+ - Network errors, timeouts and 5xx are retried with exponential backoff (full jitter, 1 s up to 60 s) up to
53
+ `maxRetries`, then the batch is dropped. `429` pauses sending until `Retry-After` (30 s without it) and
54
+ costs no retry. Any other 4xx drops the batch and writes one line to stderr per minute.
55
+ - The queue is bounded (`maxQueueItems`, `maxQueueBytes`); the oldest entries are dropped first. Once sending
56
+ works again a `warn` entry "logs-client dropped N entries" with `meta._dropped` reports the loss.
57
+ - Floods are sampled: per minute and key (level + context + error type + message start) the first
58
+ `sampling.maxPerKey` entries pass; the last suppressed one is sent once more when the window ends with
59
+ `meta._suppressed` = how many were held back (logs-api counts them as extra occurrences). `create()` is not sampled.
60
+
61
+ ```ts
62
+ const client = new LogsClient({
63
+ baseUrl, apiKey,
64
+ release: 'abc123', // default: LOGS_RELEASE, then GIT_SHA
65
+ env: 'staging', // default: the env of the ingest token
66
+ defaultTags: { region: 'eu' },
67
+ runtimeContext: true, // host, pid, node version, memory, uptime in contexts.runtime
68
+ batching: { maxBatchItems: 100, flushIntervalMs: 2000, maxQueueItems: 1000, maxQueueBytes: 5 * 1024 * 1024 },
69
+ retry: { maxRetries: 8, baseDelayMs: 1000, maxDelayMs: 60_000 },
70
+ sampling: { maxPerKey: 20 }, // or false
71
+ })
72
+ ```
73
+
74
+ ### Shutdown
75
+
76
+ The flush timer is `unref`'d and a `beforeExit` hook flushes, but a process that exits explicitly or is
77
+ killed would lose the queue. Flush it yourself - the client registers no signal handlers:
78
+
79
+ ```ts
80
+ // main.ts: app.enableShutdownHooks()
81
+ @Injectable()
82
+ export class LogsShutdown implements BeforeApplicationShutdown {
83
+ constructor(@Inject(LOGS_CLIENT) private readonly client: LogsClient) {}
84
+ beforeApplicationShutdown() {
85
+ return this.client.close() // flushes within 5 s
86
+ }
87
+ }
88
+ ```
89
+
90
+ Plain Node: `process.on('SIGTERM', async () => { await client.close(); process.exit(0) })`.
91
+
92
+ ## Request and job context
93
+
94
+ `logsContextMiddleware()` opens an `AsyncLocalStorage` context per request. Every entry enqueued during the
95
+ request gets its `traceId` (the W3C `traceparent` trace-id, else `x-request-id` / `x-correlation-id`, else a
96
+ UUID; also returned as the `x-request-id` response header), `user`, `tags`, `meta` and `contexts.request`
97
+ (method, url, route, query, headers without authorization/cookie/set-cookie/x-api-key/proxy-authorization,
98
+ user agent, ip, and status code + duration once the response finished). An entry's own fields win.
99
+
100
+ ```ts
101
+ import { logsContextMiddleware, setLogUser, setLogTags, addLogMeta } from '@apinecka/logs-client'
102
+
103
+ app.use(logsContextMiddleware()) // Express; Nest: consumer.apply(logsContextMiddleware()).forRoutes('*')
104
+ // anywhere during the request (e.g. in a guard):
105
+ setLogUser({ id: user.id, email: user.email })
106
+ setLogTags({ plan: 'pro' })
107
+ addLogMeta({ orderId })
108
+ ```
109
+
110
+ Jobs and queue consumers have no request - open a context yourself:
111
+
112
+ ```ts
113
+ import { runWithLogContext } from '@apinecka/logs-client'
114
+
115
+ await runWithLogContext({ traceId: message.id, tags: { job: 'sync-orders' } }, () => handle(message))
116
+ ```
117
+
118
+ `getLogContext()` returns the active context; `traceIdFromHeaders(headers)` and `serializeError(err)` are exported too.
119
+
120
+ ## Source maps
121
+
122
+ Stacks are sent raw and grouped by function name and file, so ship readable ones: bundle servers with
123
+ webpack `devtool: 'source-map'` and no minification, put the `.map` next to `main.js` and run
124
+ `node --enable-source-maps dist/main.js`. The stacks are then already mapped in the process. Set `release`
125
+ to the git sha.
126
+
127
+ ## Migrating from 1.0
128
+
129
+ - `LogsApiLogger` now batches (every ~2 s) instead of one request per line, so it needs a logs-api with
130
+ `POST /logs/batch`. Call `await client.close()` on shutdown (see above) or the last lines can be lost.
131
+ - Context and stack parsing was fixed: `new Logger('Ctx').error('msg', err.stack)` now sends the stack as
132
+ `error.stack` and `Ctx` as the context (1.0 sent the stack text as the context).
133
+ - `client.create(entry)` is unchanged (one direct `POST /logs`, rejects on failure).
134
+
135
+ ## Plain usage
136
+
137
+ ```ts
138
+ import { LogLevel, LogsClient, serializeError } from '@apinecka/logs-client'
139
+
140
+ const client = new LogsClient({ baseUrl: 'https://logs.apinecka.com', apiKey: 'ingest-token' })
141
+
142
+ try {
143
+ await work()
144
+ } catch (err) {
145
+ client.enqueue({ level: LogLevel.error, message: 'Sync failed', appName: 'billing', error: serializeError(err) })
146
+ }
147
+ await client.close()
148
+ ```
149
+
150
+ ## Options
151
+
152
+ `new LogsClient(options)`:
153
+
154
+ - `baseUrl` - logs-api URL.
155
+ - `apiKey` - an ingest token (Tokens page of the logs UI), sent as `Authorization: Bearer ...`. The token
156
+ decides the account and the default env.
157
+ - `timeoutMs` - per-request timeout, default 5000.
158
+ - `release`, `env`, `defaultTags`, `runtimeContext`, `batching`, `retry`, `sampling` - see Delivery.
159
+
160
+ Every client owns its HTTP connection pool (keep-alive), so several clients never share state.
161
+ `ApiLogsClient` is an alias of `LogsClient`.
162
+
163
+ ## Log entry
164
+
165
+ `client.enqueue(entry)` and `client.create(entry)` take a `CreateLogRequest` (generated from logs-api's OpenAPI document):
166
+
167
+ | field | type | note |
168
+ |-------------|------------|-------------------------------------------------------------------|
169
+ | `level` | `LogLevel` | `log`, `error`, `warn`, `debug`, `verbose`, `fatal` |
170
+ | `message` | `string` | |
171
+ | `appName` | `string` | up to 50 characters; the app is created on its first log |
172
+ | `context` | `string?` | up to 255 characters |
173
+ | `timestamp` | `string?` | ISO 8601, defaults to now on the server |
174
+ | `env` | `string?` | overrides the env of the ingest token (default `production`) |
175
+ | `error` | `LogError?` | `{ type, message, stack?, frames?, cause?, errors? }` - frames are parsed from `stack` on the server |
176
+ | `meta` | `object?` | free-form structured data |
177
+ | `fingerprint` | `string[]?` | custom grouping key parts (up to 10, each up to 200 characters) |
178
+ | `release` | `string?` | app version, up to 100 characters |
179
+ | `traceId` | `string?` | up to 64 characters of `A-Za-z0-9._:-` |
180
+ | `user` | `LogUser?` | `{ id?, email?, username? }` |
181
+ | `tags` | `object?` | up to 50 string labels (keys `A-Za-z0-9._-`, up to 32; values up to 200) |
182
+ | `contexts` | `LogContexts?` | `request` (method, url, route, query, headers, userAgent, ip, statusCode, durationMs) and `runtime` (hostname, pid, nodeVersion, platform, arch, memoryRssBytes, heapUsedBytes, uptimeSeconds) |
183
+
184
+ The server also accepts up to 500 entries at once on `POST /logs/batch` (`CreateLogBatch`, answered with
185
+ the `accepted` / `rejected` counts), filters secrets out of the data, truncates oversized fields instead of
186
+ rejecting them, and answers `429` with `Retry-After` when a token sends too many entries per minute.
187
+
188
+ ## License
189
+
190
+ MIT
@@ -0,0 +1,68 @@
1
+ import type { CreateLogRequest, LogsClientOptions } from './types';
2
+ /**
3
+ * Sends log entries to logs-api. Every instance owns its axios instance, so clients never share state.
4
+ *
5
+ * `create` posts one entry directly. `enqueue` is the reliable path: entries are queued in memory, sent in
6
+ * batches with retries, backoff and `Retry-After` handling, and floods are sampled. Call `await close()`
7
+ * on shutdown so the queue is flushed.
8
+ */
9
+ export declare class LogsClient {
10
+ private readonly http;
11
+ private readonly transport;
12
+ private readonly options;
13
+ private readonly limits;
14
+ private readonly retry;
15
+ private readonly sampling;
16
+ private readonly release;
17
+ private queue;
18
+ private queueBytes;
19
+ private dropped;
20
+ private appName;
21
+ private timer?;
22
+ private inflight?;
23
+ private attempts;
24
+ private backoffUntil;
25
+ private pausedUntil;
26
+ private lastStderrAt;
27
+ private delivered;
28
+ private readonly samples;
29
+ private runtimeBase?;
30
+ private exitRegistered;
31
+ private readonly onBeforeExit;
32
+ constructor(options: LogsClientOptions);
33
+ /** Posts one entry right away (release, env and default tags are added). Rejects when the request fails. */
34
+ create(entry: CreateLogRequest): Promise<void>;
35
+ /**
36
+ * Queues an entry for batched, retried delivery; never throws. The active log context, default tags,
37
+ * release, env and runtime context are merged in (the entry's own fields win).
38
+ */
39
+ enqueue(entry: CreateLogRequest): void;
40
+ /** Sends everything queued now. Resolves when the queue is empty, or sending failed or is paused (429). Never rejects. */
41
+ flush(): Promise<void>;
42
+ /** Stops the flush timer and flushes within `timeoutMs`. Call it on shutdown. */
43
+ close(timeoutMs?: number): Promise<void>;
44
+ private withDefaults;
45
+ private prepare;
46
+ private runtimeContext;
47
+ private sampleKey;
48
+ /** Returns whether the entry should be queued; suppressed ones are only counted. */
49
+ private sample;
50
+ private closeWindow;
51
+ private sweepSamples;
52
+ private push;
53
+ private enforceLimits;
54
+ private ensureTimer;
55
+ private tick;
56
+ private takeBatch;
57
+ private requeueFront;
58
+ private drain;
59
+ /** Returns whether the next batch may be sent right away. */
60
+ private send;
61
+ private deliver;
62
+ private fail;
63
+ private retryAfterMs;
64
+ private reportDropped;
65
+ private warnStderr;
66
+ }
67
+ /** Former name of {@link LogsClient}, kept so switching to this package is only an import change. */
68
+ export { LogsClient as ApiLogsClient };
package/dist/client.js ADDED
@@ -0,0 +1,372 @@
1
+ "use strict";
2
+ var __importDefault = (this && this.__importDefault) || function (mod) {
3
+ return (mod && mod.__esModule) ? mod : { "default": mod };
4
+ };
5
+ Object.defineProperty(exports, "__esModule", { value: true });
6
+ exports.ApiLogsClient = exports.LogsClient = void 0;
7
+ const axios_1 = __importDefault(require("axios"));
8
+ const http_1 = require("http");
9
+ const https_1 = require("https");
10
+ const os_1 = require("os");
11
+ const conform_1 = require("./conform");
12
+ const context_1 = require("./context");
13
+ const models_1 = require("./schema/models");
14
+ const KEY_MESSAGE_LENGTH = 200;
15
+ const STDERR_INTERVAL_MS = 60_000;
16
+ /**
17
+ * Sends log entries to logs-api. Every instance owns its axios instance, so clients never share state.
18
+ *
19
+ * `create` posts one entry directly. `enqueue` is the reliable path: entries are queued in memory, sent in
20
+ * batches with retries, backoff and `Retry-After` handling, and floods are sampled. Call `await close()`
21
+ * on shutdown so the queue is flushed.
22
+ */
23
+ class LogsClient {
24
+ constructor(options) {
25
+ this.queue = [];
26
+ this.queueBytes = 0;
27
+ this.dropped = 0;
28
+ this.appName = 'logs-client';
29
+ this.attempts = 0;
30
+ this.backoffUntil = 0;
31
+ this.pausedUntil = 0;
32
+ this.lastStderrAt = 0;
33
+ this.delivered = false;
34
+ this.samples = new Map();
35
+ this.exitRegistered = false;
36
+ this.onBeforeExit = () => {
37
+ void this.flush();
38
+ };
39
+ this.options = options;
40
+ this.http = axios_1.default.create({
41
+ baseURL: options.baseUrl,
42
+ headers: options.apiKey ? { Authorization: `Bearer ${options.apiKey}` } : {},
43
+ timeout: options.timeoutMs ?? 5_000,
44
+ // Logs are posted on every log line - keep TCP/TLS connections warm instead of
45
+ // renegotiating a new one per call.
46
+ httpAgent: new http_1.Agent({ keepAlive: true, keepAliveMsecs: 30_000 }),
47
+ httpsAgent: new https_1.Agent({ keepAlive: true, keepAliveMsecs: 30_000 }),
48
+ });
49
+ this.transport = options.transport ?? ((path, body) => this.http.post(path, body, { headers: { 'Content-Type': 'application/json' } }));
50
+ this.limits = {
51
+ maxQueueItems: options.batching?.maxQueueItems ?? 1000,
52
+ maxQueueBytes: options.batching?.maxQueueBytes ?? 5 * 1024 * 1024,
53
+ maxBatchItems: options.batching?.maxBatchItems ?? 100,
54
+ maxBatchBytes: options.batching?.maxBatchBytes ?? 4 * 1024 * 1024,
55
+ flushIntervalMs: options.batching?.flushIntervalMs ?? 2_000,
56
+ };
57
+ this.retry = {
58
+ maxRetries: options.retry?.maxRetries ?? 8,
59
+ baseDelayMs: options.retry?.baseDelayMs ?? 1_000,
60
+ maxDelayMs: options.retry?.maxDelayMs ?? 60_000,
61
+ rateLimitPauseMs: options.retry?.rateLimitPauseMs ?? 30_000,
62
+ };
63
+ this.sampling =
64
+ options.sampling === false
65
+ ? undefined
66
+ : { maxPerKey: options.sampling?.maxPerKey ?? 20, windowMs: options.sampling?.windowMs ?? 60_000 };
67
+ this.release = options.release ?? process.env.LOGS_RELEASE ?? process.env.GIT_SHA;
68
+ }
69
+ /** Posts one entry right away (release, env and default tags are added). Rejects when the request fails. */
70
+ async create(entry) {
71
+ await this.http.post('/logs', (0, conform_1.conformEntry)(this.withDefaults(entry)), { headers: { 'Content-Type': 'application/json' } });
72
+ }
73
+ /**
74
+ * Queues an entry for batched, retried delivery; never throws. The active log context, default tags,
75
+ * release, env and runtime context are merged in (the entry's own fields win).
76
+ */
77
+ enqueue(entry) {
78
+ try {
79
+ this.appName = entry.appName || this.appName;
80
+ const prepared = this.prepare(entry, true);
81
+ if (this.sampling && !this.sample(prepared))
82
+ return;
83
+ this.push(prepared);
84
+ this.ensureTimer();
85
+ if (this.queue.length >= this.limits.maxBatchItems && Date.now() >= Math.max(this.backoffUntil, this.pausedUntil)) {
86
+ void this.flush();
87
+ }
88
+ }
89
+ catch {
90
+ // logging must never break the app
91
+ }
92
+ }
93
+ /** Sends everything queued now. Resolves when the queue is empty, or sending failed or is paused (429). Never rejects. */
94
+ flush() {
95
+ if (!this.inflight) {
96
+ this.inflight = this.drain()
97
+ .catch(() => { })
98
+ .finally(() => {
99
+ this.inflight = undefined;
100
+ });
101
+ }
102
+ return this.inflight;
103
+ }
104
+ /** Stops the flush timer and flushes within `timeoutMs`. Call it on shutdown. */
105
+ async close(timeoutMs = 5_000) {
106
+ if (this.timer)
107
+ clearInterval(this.timer);
108
+ this.timer = undefined;
109
+ if (this.exitRegistered)
110
+ process.off('beforeExit', this.onBeforeExit);
111
+ this.exitRegistered = false;
112
+ let timeout;
113
+ const timedOut = new Promise((resolve) => {
114
+ timeout = setTimeout(resolve, timeoutMs);
115
+ timeout.unref?.();
116
+ });
117
+ try {
118
+ await Promise.race([this.flush(), timedOut]);
119
+ }
120
+ finally {
121
+ if (timeout)
122
+ clearTimeout(timeout);
123
+ }
124
+ }
125
+ withDefaults(entry) {
126
+ const tags = { ...this.options.defaultTags, ...entry.tags };
127
+ return {
128
+ ...entry,
129
+ release: entry.release ?? this.release,
130
+ env: entry.env ?? this.options.env,
131
+ ...(Object.keys(tags).length > 0 ? { tags } : {}),
132
+ };
133
+ }
134
+ prepare(entry, withContext) {
135
+ const base = this.withDefaults(entry);
136
+ const ctx = withContext ? (0, context_1.getLogContext)() : undefined;
137
+ const tags = { ...base.tags, ...ctx?.tags, ...entry.tags };
138
+ const meta = { ...ctx?.meta, ...entry.meta };
139
+ const user = ctx?.user || entry.user ? { ...ctx?.user, ...entry.user } : undefined;
140
+ const request = entry.contexts?.request ?? ctx?.request?.();
141
+ const runtime = entry.contexts?.runtime ?? (this.options.runtimeContext === false ? undefined : this.runtimeContext());
142
+ const result = {
143
+ ...base,
144
+ timestamp: entry.timestamp ?? new Date().toISOString(),
145
+ traceId: entry.traceId ?? ctx?.traceId,
146
+ };
147
+ if (Object.keys(tags).length > 0)
148
+ result.tags = tags;
149
+ else
150
+ delete result.tags;
151
+ if (Object.keys(meta).length > 0)
152
+ result.meta = meta;
153
+ if (user)
154
+ result.user = user;
155
+ if (request || runtime)
156
+ result.contexts = { ...entry.contexts, ...(request ? { request } : {}), ...(runtime ? { runtime } : {}) };
157
+ if (result.traceId === undefined)
158
+ delete result.traceId;
159
+ return (0, conform_1.conformEntry)(result);
160
+ }
161
+ runtimeContext() {
162
+ this.runtimeBase ??= {
163
+ hostname: (0, os_1.hostname)(),
164
+ pid: process.pid,
165
+ nodeVersion: process.version,
166
+ platform: process.platform,
167
+ arch: process.arch,
168
+ };
169
+ const memory = process.memoryUsage();
170
+ return {
171
+ ...this.runtimeBase,
172
+ memoryRssBytes: memory.rss,
173
+ heapUsedBytes: memory.heapUsed,
174
+ uptimeSeconds: Math.round(process.uptime()),
175
+ };
176
+ }
177
+ sampleKey(entry) {
178
+ return [entry.level, entry.context ?? '', entry.error?.type ?? '', entry.message.slice(0, KEY_MESSAGE_LENGTH)].join('\u0000');
179
+ }
180
+ /** Returns whether the entry should be queued; suppressed ones are only counted. */
181
+ sample(entry) {
182
+ const sampling = this.sampling;
183
+ if (!sampling)
184
+ return true;
185
+ const now = Date.now();
186
+ const key = this.sampleKey(entry);
187
+ let state = this.samples.get(key);
188
+ if (state && now - state.windowStart >= sampling.windowMs) {
189
+ this.closeWindow(key, state);
190
+ state = undefined;
191
+ }
192
+ if (!state) {
193
+ state = { windowStart: now, passed: 0, suppressed: 0 };
194
+ this.samples.set(key, state);
195
+ }
196
+ if (state.passed < sampling.maxPerKey) {
197
+ state.passed++;
198
+ return true;
199
+ }
200
+ state.suppressed++;
201
+ state.last = entry;
202
+ return false;
203
+ }
204
+ closeWindow(key, state) {
205
+ this.samples.delete(key);
206
+ if (state.suppressed > 0 && state.last) {
207
+ this.push({ ...state.last, meta: { ...state.last.meta, _suppressed: state.suppressed } });
208
+ }
209
+ }
210
+ sweepSamples() {
211
+ if (!this.sampling)
212
+ return;
213
+ const now = Date.now();
214
+ for (const [key, state] of this.samples) {
215
+ if (now - state.windowStart >= this.sampling.windowMs)
216
+ this.closeWindow(key, state);
217
+ }
218
+ }
219
+ push(entry) {
220
+ const size = JSON.stringify(entry).length;
221
+ this.queue.push({ entry, size });
222
+ this.queueBytes += size;
223
+ this.enforceLimits();
224
+ }
225
+ enforceLimits() {
226
+ while (this.queue.length > 0 && (this.queue.length > this.limits.maxQueueItems || this.queueBytes > this.limits.maxQueueBytes)) {
227
+ const oldest = this.queue.shift();
228
+ if (!oldest)
229
+ break;
230
+ this.queueBytes -= oldest.size;
231
+ this.dropped++;
232
+ }
233
+ }
234
+ ensureTimer() {
235
+ if (!this.timer) {
236
+ this.timer = setInterval(() => this.tick(), this.limits.flushIntervalMs);
237
+ this.timer.unref?.();
238
+ }
239
+ if (!this.exitRegistered) {
240
+ process.once('beforeExit', this.onBeforeExit);
241
+ this.exitRegistered = true;
242
+ }
243
+ }
244
+ tick() {
245
+ this.sweepSamples();
246
+ if (this.queue.length > 0 && Date.now() >= Math.max(this.backoffUntil, this.pausedUntil))
247
+ void this.flush();
248
+ }
249
+ takeBatch() {
250
+ let count = 0;
251
+ let bytes = 0;
252
+ while (count < this.queue.length && count < this.limits.maxBatchItems) {
253
+ const size = this.queue[count].size;
254
+ if (count > 0 && bytes + size > this.limits.maxBatchBytes)
255
+ break;
256
+ bytes += size;
257
+ count++;
258
+ }
259
+ const batch = this.queue.splice(0, count);
260
+ this.queueBytes -= bytes;
261
+ return batch;
262
+ }
263
+ requeueFront(batch) {
264
+ this.queue = [...batch, ...this.queue];
265
+ this.queueBytes += batch.reduce((sum, item) => sum + item.size, 0);
266
+ this.enforceLimits();
267
+ }
268
+ async drain() {
269
+ this.sweepSamples();
270
+ while (this.queue.length > 0) {
271
+ if (Date.now() < this.pausedUntil)
272
+ return;
273
+ const batch = this.takeBatch();
274
+ if (!(await this.send(batch)))
275
+ return;
276
+ }
277
+ }
278
+ /** Returns whether the next batch may be sent right away. */
279
+ async send(batch) {
280
+ this.delivered = false;
281
+ if (!(await this.deliver(batch)))
282
+ return false;
283
+ // a batch that was only dropped (4xx) says nothing about the server being healthy
284
+ if (this.delivered) {
285
+ this.attempts = 0;
286
+ this.backoffUntil = 0;
287
+ this.reportDropped();
288
+ }
289
+ return true;
290
+ }
291
+ // The server validates a whole batch: on a 400 the halves are sent separately, so only the invalid entries are dropped.
292
+ async deliver(batch) {
293
+ try {
294
+ await this.transport('/logs/batch', { items: batch.map((item) => item.entry) });
295
+ this.delivered = true;
296
+ return true;
297
+ }
298
+ catch (err) {
299
+ const status = err?.response?.status;
300
+ if (status !== 400 || batch.length < 2)
301
+ return this.fail(batch, err);
302
+ const middle = Math.ceil(batch.length / 2);
303
+ const right = batch.slice(middle);
304
+ if (await this.deliver(batch.slice(0, middle)))
305
+ return this.deliver(right);
306
+ this.requeueFront(right);
307
+ return false;
308
+ }
309
+ }
310
+ fail(batch, err) {
311
+ const response = err?.response;
312
+ const status = response?.status;
313
+ const now = Date.now();
314
+ if (status === 429) {
315
+ this.pausedUntil = now + this.retryAfterMs(response?.headers?.['retry-after']);
316
+ this.requeueFront(batch);
317
+ return false;
318
+ }
319
+ if (status !== undefined && status >= 400 && status < 500 && status !== 408) {
320
+ this.dropped += batch.length;
321
+ this.warnStderr(`dropped ${batch.length} entries, logs-api answered ${status}`);
322
+ return true;
323
+ }
324
+ this.attempts++;
325
+ if (this.attempts > this.retry.maxRetries) {
326
+ this.dropped += batch.length;
327
+ this.attempts = 0;
328
+ }
329
+ else {
330
+ this.requeueFront(batch);
331
+ }
332
+ const ceiling = Math.min(this.retry.maxDelayMs, this.retry.baseDelayMs * 2 ** (this.attempts === 0 ? 0 : this.attempts - 1));
333
+ this.backoffUntil = now + Math.random() * ceiling;
334
+ return false;
335
+ }
336
+ retryAfterMs(header) {
337
+ const value = Array.isArray(header) ? header[0] : header;
338
+ if (typeof value === 'string' || typeof value === 'number') {
339
+ const seconds = Number(value);
340
+ if (Number.isFinite(seconds) && seconds >= 0)
341
+ return seconds * 1000;
342
+ const date = typeof value === 'string' ? Date.parse(value) : NaN;
343
+ if (!Number.isNaN(date))
344
+ return Math.max(0, date - Date.now());
345
+ }
346
+ return this.retry.rateLimitPauseMs;
347
+ }
348
+ reportDropped() {
349
+ if (this.dropped === 0)
350
+ return;
351
+ const count = this.dropped;
352
+ this.dropped = 0;
353
+ this.push(this.prepare({
354
+ level: models_1.LogLevel.warn,
355
+ message: `logs-client dropped ${count} entries`,
356
+ appName: this.appName,
357
+ context: 'logs-client',
358
+ meta: { _dropped: count },
359
+ }, false));
360
+ }
361
+ // Written straight to stderr, never through a logger, so a failing logs-api cannot cause a log loop.
362
+ warnStderr(message) {
363
+ const now = Date.now();
364
+ if (now - this.lastStderrAt < STDERR_INTERVAL_MS)
365
+ return;
366
+ this.lastStderrAt = now;
367
+ process.stderr.write(`[logs-client] ${message}\n`);
368
+ }
369
+ }
370
+ exports.LogsClient = LogsClient;
371
+ exports.ApiLogsClient = LogsClient;
372
+ //# sourceMappingURL=client.js.map