@dx-do/client 7.12.0 → 7.12.1
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/dist/index.cjs.js +764 -74
- package/dist/index.cjs.js.map +1 -1
- package/dist/index.esm.js +759 -75
- package/dist/index.esm.js.map +1 -1
- package/dist/src/index.d.ts +3 -0
- package/dist/src/index.d.ts.map +1 -1
- package/dist/src/lib/model/config/DXSaaSConfiguration.d.ts +18 -6
- package/dist/src/lib/model/config/DXSaaSConfiguration.d.ts.map +1 -1
- package/dist/src/lib/model/log/custom-ingest.d.ts +79 -0
- package/dist/src/lib/model/log/custom-ingest.d.ts.map +1 -0
- package/dist/src/lib/model/log/ingest.d.ts +46 -0
- package/dist/src/lib/model/log/ingest.d.ts.map +1 -1
- package/dist/src/lib/model/log/logtypes.d.ts +48 -0
- package/dist/src/lib/model/log/logtypes.d.ts.map +1 -0
- package/dist/src/lib/services/dx-saas.service.d.ts +23 -0
- package/dist/src/lib/services/dx-saas.service.d.ts.map +1 -1
- package/dist/src/lib/services/log-ingestion-batch.d.ts +83 -0
- package/dist/src/lib/services/log-ingestion-batch.d.ts.map +1 -0
- package/dist/src/lib/services/logs.service.d.ts +146 -21
- package/dist/src/lib/services/logs.service.d.ts.map +1 -1
- package/package.json +3 -2
|
@@ -1,6 +1,9 @@
|
|
|
1
|
+
import { Logging } from '@dx-do/util';
|
|
1
2
|
import { DxSaasService } from './dx-saas.service';
|
|
2
3
|
import { LogQuery } from '../model/log/query-body';
|
|
3
4
|
import { LogIngest } from '../model/log/ingest';
|
|
5
|
+
import { LogCustomIngest } from '../model/log/custom-ingest';
|
|
6
|
+
import { LogIngestBatchFailure, LogIngestBatchProgress, LogIngestRetryOptions } from './log-ingestion-batch';
|
|
4
7
|
/**
|
|
5
8
|
* A source file slot the platform can actually parse.
|
|
6
9
|
*
|
|
@@ -41,23 +44,121 @@ export declare const UIM_LOGS_INGESTION_PATH = "mdo/v2/aoanalytics/ingestion/uim
|
|
|
41
44
|
* @throws Error if `additionalFields` names a reserved field.
|
|
42
45
|
*/
|
|
43
46
|
export declare function buildUimLogPayload(cohortId: string, options: LogIngest.LogIngestOptions, additionalFields?: Record<string, unknown>): unknown;
|
|
47
|
+
/**
|
|
48
|
+
* Builds the flat document the Log Analytics **custom JSON ingestion API**
|
|
49
|
+
* takes — the `custom` transport's counterpart of {@link buildUimLogPayload},
|
|
50
|
+
* sharing the option schema and every default so a producer can switch
|
|
51
|
+
* transports without changing what it passes.
|
|
52
|
+
*
|
|
53
|
+
* Differences from the uim_logs document, all measured on THE_LABORATORY
|
|
54
|
+
* (`docs/internal/custom-log-ingestion-probe-2026-09.md`): `timestamp` is an
|
|
55
|
+
* epoch-millisecond number; `tenant_id` is the dashed upper-case cohort id;
|
|
56
|
+
* only `logseverity` is sent (a `severity` field would derive a second,
|
|
57
|
+
* lower-case copy); the tag list is `tag`; there is no positional parse, so
|
|
58
|
+
* `file` needs no dot; `agentName`/`agentInstance` travel as `agent_name` /
|
|
59
|
+
* `agent_instance` only when set (the `__`-prefixed uim names are stripped by
|
|
60
|
+
* this API); empty-valued custom fields are dropped. The logtype is sent
|
|
61
|
+
* without the platform's `cust_` prefix, which is how this API spells it.
|
|
62
|
+
*
|
|
63
|
+
* @throws ZodError if `options` fails schema validation.
|
|
64
|
+
* @throws Error if `additionalFields` names a reserved field
|
|
65
|
+
* ({@link LogIngest.isReservedLogField} or
|
|
66
|
+
* {@link LogCustomIngest.isReservedCustomLogField}) or `timestamp` is not
|
|
67
|
+
* ISO 8601.
|
|
68
|
+
*/
|
|
69
|
+
export declare function buildCustomLogPayload(cohortId: string, options: LogIngest.LogIngestOptions, additionalFields?: Record<string, unknown>): LogCustomIngest.CustomLogDocument;
|
|
70
|
+
/** Outcome of {@link LogsService.ingestLogBatch}. */
|
|
71
|
+
export interface LogIngestBatchResult {
|
|
72
|
+
transport: LogIngest.ResolvedLogIngestionTransport;
|
|
73
|
+
endpoint: string;
|
|
74
|
+
/** Entries handed in. */
|
|
75
|
+
entries: number;
|
|
76
|
+
/** Requests made (after any 413 splits). */
|
|
77
|
+
batches: number;
|
|
78
|
+
/** Documents the gateway accepted. */
|
|
79
|
+
sent: number;
|
|
80
|
+
failed: LogIngestBatchFailure[];
|
|
81
|
+
/** Entry indexes over the per-document size limit; never sent. */
|
|
82
|
+
oversized: number[];
|
|
83
|
+
/** Set when the run stopped early: `auth` after a 401/403, `signal` when aborted. */
|
|
84
|
+
aborted?: 'auth' | 'signal';
|
|
85
|
+
}
|
|
86
|
+
export interface LogIngestBatchOptions {
|
|
87
|
+
/** `auto` | `custom` | `legacy`; precedence: this, the profile's `dxLogIngestionTransport`, then `auto`. */
|
|
88
|
+
transport?: string;
|
|
89
|
+
/** Documents per request (default 200; the custom transport also caps requests at 10 MB). */
|
|
90
|
+
batchSize?: number;
|
|
91
|
+
retry?: LogIngestRetryOptions;
|
|
92
|
+
signal?: AbortSignal;
|
|
93
|
+
timeoutMs?: number;
|
|
94
|
+
onBatch?: (progress: LogIngestBatchProgress) => void;
|
|
95
|
+
}
|
|
44
96
|
/**
|
|
45
97
|
* Service for querying and ingesting log analytics data.
|
|
46
98
|
*/
|
|
47
99
|
export declare class LogsService {
|
|
48
100
|
private readonly dxSaasService;
|
|
49
|
-
|
|
50
|
-
|
|
101
|
+
private readonly log;
|
|
102
|
+
/**
|
|
103
|
+
* @param dxSaasService - DX SaaS HTTP client
|
|
104
|
+
* @param log - Logger for response-validation warnings; silent when omitted,
|
|
105
|
+
* so producers that construct the service themselves keep working.
|
|
106
|
+
*/
|
|
107
|
+
constructor(dxSaasService: DxSaasService, log?: Logging.SimpleLog);
|
|
108
|
+
/**
|
|
109
|
+
* Lists the logtypes the tenant has a log index for — one name per index
|
|
110
|
+
* family `*_logs_<logtype>_*`. Names starting with `cust_` were created by
|
|
111
|
+
* the custom JSON ingestion API.
|
|
112
|
+
*
|
|
113
|
+
* @remarks Response-validated with `safeParse`: a mismatch is logged as a
|
|
114
|
+
* warning and the raw list is still returned.
|
|
115
|
+
*/
|
|
116
|
+
listLogtypes(): Promise<string[]>;
|
|
51
117
|
/**
|
|
52
|
-
*
|
|
53
|
-
* {
|
|
54
|
-
* `dxLogIngestionURL`, or the SaaS logs-gateway derived from the region and
|
|
55
|
-
* Log Analytics provisioning) plus the uim_logs ingestion path.
|
|
118
|
+
* Lists the indexed fields of one logtype with their index type
|
|
119
|
+
* (`{ host: 'Keyword', logseverity: 'Keyword', … }`).
|
|
56
120
|
*
|
|
57
|
-
* @
|
|
58
|
-
*
|
|
121
|
+
* @param logtype - A name from {@link listLogtypes}; an unknown logtype is
|
|
122
|
+
* answered by the gateway, typically with an empty map.
|
|
123
|
+
* @remarks Response-validated with `safeParse`: a mismatch is logged as a
|
|
124
|
+
* warning and the raw map is still returned.
|
|
59
125
|
*/
|
|
60
|
-
|
|
126
|
+
listLogtypeFields(logtype: string): Promise<Record<string, string>>;
|
|
127
|
+
private enabledCustomLogtypes;
|
|
128
|
+
/**
|
|
129
|
+
* The custom logtypes the tenant has enabled for the custom JSON ingestion
|
|
130
|
+
* API, as `cust_<logtype>` names from {@link listLogtypes}. Memoized per
|
|
131
|
+
* instance; a failed lookup is not memoized.
|
|
132
|
+
*/
|
|
133
|
+
private customLogtypes;
|
|
134
|
+
/**
|
|
135
|
+
* Decides the transport for one logtype.
|
|
136
|
+
*
|
|
137
|
+
* Precedence: `requested` (a command's `transport=`), then the profile's
|
|
138
|
+
* `dxLogIngestionTransport`, then {@link LogIngest.DEFAULT_LOG_INGESTION_TRANSPORT}
|
|
139
|
+
* (`auto`). `auto` becomes `custom` when the tenant lists `cust_<logtype>`
|
|
140
|
+
* and `legacy` otherwise; an explicit `custom` for a logtype the tenant has
|
|
141
|
+
* not enabled is refused, because the platform would accept the document
|
|
142
|
+
* and drop it silently. If the logtype lookup itself fails, `auto` falls
|
|
143
|
+
* back to `legacy` with a warning and an explicit `custom` proceeds unchecked.
|
|
144
|
+
*
|
|
145
|
+
* @throws Error when `requested` or the profile value is not `auto`,
|
|
146
|
+
* `custom` or `legacy`.
|
|
147
|
+
* @throws {@link LogCustomIngest.LogtypeNotEnabledError} for an explicit
|
|
148
|
+
* `custom` with a logtype the tenant has not enabled.
|
|
149
|
+
*/
|
|
150
|
+
resolveTransport(requested: string | undefined, logtype?: string): Promise<LogIngest.ResolvedLogIngestionTransport>;
|
|
151
|
+
/**
|
|
152
|
+
* The full URL log entries are POSTed to. For `legacy` (the default, so
|
|
153
|
+
* every existing caller keeps the uim_logs pipeline): the log gateway
|
|
154
|
+
* resolved by {@link DxSaasService.resolveLogIngestionURL} plus the uim_logs
|
|
155
|
+
* path. For `custom`: {@link DxSaasService.resolveCustomLogIngestionURL}
|
|
156
|
+
* plus `la/v2/api/ingestion/logs`.
|
|
157
|
+
*
|
|
158
|
+
* @throws {@link LogIngest.LogIngestionEndpointError} naming why no endpoint
|
|
159
|
+
* could be determined and how to set `dxLogIngestionURL`.
|
|
160
|
+
*/
|
|
161
|
+
resolveIngestionEndpoint(transport?: LogIngest.ResolvedLogIngestionTransport): Promise<string>;
|
|
61
162
|
/** Executes a log query against the OI log analytics filter API. */
|
|
62
163
|
queryLogs(logQueryBody: LogQuery.LogQueryRequestBody): Promise<LogQuery.LogQueryResponseBody>;
|
|
63
164
|
/**
|
|
@@ -70,28 +171,52 @@ export declare class LogsService {
|
|
|
70
171
|
* @param additionalFields - Arbitrary extra fields to include in the indexed
|
|
71
172
|
* document. `severity` and `logseverity` (any letter case) are refused:
|
|
72
173
|
* severity travels through `options.severity` and is emitted as `logseverity`.
|
|
73
|
-
* @
|
|
174
|
+
* @param transport - `legacy` (default) builds the uim_logs document via
|
|
175
|
+
* {@link buildUimLogPayload}; `custom` builds the flat document via
|
|
176
|
+
* {@link buildCustomLogPayload}.
|
|
177
|
+
* @returns The payload object ready to POST to that transport's endpoint.
|
|
74
178
|
* @throws ZodError if `options` fails schema validation.
|
|
75
179
|
* @throws Error if `additionalFields` names a reserved field.
|
|
76
180
|
*/
|
|
77
|
-
buildLogPayload(options: LogIngest.LogIngestOptions, additionalFields?: Record<string, unknown
|
|
181
|
+
buildLogPayload(options: LogIngest.LogIngestOptions, additionalFields?: Record<string, unknown>, transport?: LogIngest.ResolvedLogIngestionTransport): unknown;
|
|
78
182
|
/**
|
|
79
|
-
* Ingests a single log entry
|
|
183
|
+
* Ingests a single log entry.
|
|
80
184
|
*
|
|
81
|
-
* @remarks
|
|
82
|
-
*
|
|
83
|
-
* validated. `options` is validated
|
|
185
|
+
* @remarks Both gateways return an opaque acknowledgement with no stable
|
|
186
|
+
* schema (the custom API answers a plain-text `ok`), so the response is
|
|
187
|
+
* intentionally typed `unknown` and not validated. `options` is validated
|
|
188
|
+
* by {@link buildLogPayload}. No logtype gate is applied here — use
|
|
189
|
+
* {@link resolveTransport} first, or {@link ingestLogBatch}, which does.
|
|
190
|
+
* @param transport - `legacy` (default) posts to the uim_logs pipeline;
|
|
191
|
+
* `custom` to the custom JSON ingestion API.
|
|
84
192
|
*/
|
|
85
|
-
ingestLog(options: LogIngest.LogIngestOptions, additionalFields?: Record<string, unknown
|
|
193
|
+
ingestLog(options: LogIngest.LogIngestOptions, additionalFields?: Record<string, unknown>, transport?: LogIngest.ResolvedLogIngestionTransport): Promise<unknown>;
|
|
86
194
|
/**
|
|
87
|
-
* Ingests a batch of log entries into the log gateway
|
|
195
|
+
* Ingests a batch of log entries into the uim_logs log gateway in one POST —
|
|
196
|
+
* no chunking, no retry.
|
|
88
197
|
*
|
|
198
|
+
* @deprecated Use {@link ingestLogBatch}, which chunks, retries and reports
|
|
199
|
+
* per batch on either transport.
|
|
89
200
|
* @remarks Each entry's `options` is validated by {@link buildLogPayload}.
|
|
90
201
|
* The gateway response is an opaque ack (typed `unknown`, not validated).
|
|
91
202
|
*/
|
|
92
|
-
ingestLogs(entries:
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
203
|
+
ingestLogs(entries: LogIngest.LogIngestEntry[]): Promise<unknown>;
|
|
204
|
+
/**
|
|
205
|
+
* Ingests many log entries: decides the transport (see
|
|
206
|
+
* {@link resolveTransport}), builds every document first so a bad entry
|
|
207
|
+
* fails before anything is sent, chunks by count (and, on the custom
|
|
208
|
+
* transport, by the 10 MB request and 250 KB document ceilings), and sends
|
|
209
|
+
* the batches in order with exponential backoff on 429/5xx/network
|
|
210
|
+
* failures. A 4xx rejection records the batch and continues; a 401/403
|
|
211
|
+
* stops the run.
|
|
212
|
+
*
|
|
213
|
+
* @throws Error naming the entry index when a document cannot be built.
|
|
214
|
+
* @throws {@link LogCustomIngest.LogtypeNotEnabledError} for an explicit
|
|
215
|
+
* `custom` transport with a logtype the tenant has not enabled.
|
|
216
|
+
* @throws Error when entries carry logtypes that `auto` would route to
|
|
217
|
+
* different transports — pass `transport` explicitly then.
|
|
218
|
+
*/
|
|
219
|
+
ingestLogBatch(entries: LogIngest.LogIngestEntry[], options?: LogIngestBatchOptions): Promise<LogIngestBatchResult>;
|
|
220
|
+
private post;
|
|
96
221
|
}
|
|
97
222
|
//# sourceMappingURL=logs.service.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"logs.service.d.ts","sourceRoot":"","sources":["../../../../src/lib/services/logs.service.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;
|
|
1
|
+
{"version":3,"file":"logs.service.d.ts","sourceRoot":"","sources":["../../../../src/lib/services/logs.service.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@dx-do/client",
|
|
3
|
-
"version": "7.12.
|
|
3
|
+
"version": "7.12.1",
|
|
4
4
|
"description": "Opinionated TS client library for DX O2",
|
|
5
5
|
"author": "Ki Alam",
|
|
6
6
|
"logo": {
|
|
@@ -35,7 +35,8 @@
|
|
|
35
35
|
],
|
|
36
36
|
"scripts": {
|
|
37
37
|
"datastore-driver": "bun bin/datastore-driver.ts",
|
|
38
|
-
"nass-store-merge-probe": "bun tools/nass-store-merge-probe.ts"
|
|
38
|
+
"nass-store-merge-probe": "bun tools/nass-store-merge-probe.ts",
|
|
39
|
+
"log-ingest-probe": "bun tools/log-ingest-probe.ts"
|
|
39
40
|
},
|
|
40
41
|
"dependencies": {
|
|
41
42
|
"zod": "^4.3.6"
|