@dx-do/client 7.12.0 → 7.12.2

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.
@@ -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
- /** @param dxSaasService - DX SaaS HTTP client */
50
- constructor(dxSaasService: DxSaasService);
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
- * The full URL log entries are POSTed to: the log gateway resolved by
53
- * {@link DxSaasService.resolveLogIngestionURL} (an explicit
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
- * @throws Error from `resolveLogIngestionURL` naming why no endpoint could be
58
- * determined and how to set `dxLogIngestionURL`.
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
- resolveIngestionEndpoint(): Promise<string>;
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
- * @returns The payload object ready to POST to the uim_logs ingestion endpoint.
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>): unknown;
181
+ buildLogPayload(options: LogIngest.LogIngestOptions, additionalFields?: Record<string, unknown>, transport?: LogIngest.ResolvedLogIngestionTransport): unknown;
78
182
  /**
79
- * Ingests a single log entry into the log gateway.
183
+ * Ingests a single log entry.
80
184
  *
81
- * @remarks The gateway returns an opaque ingestion acknowledgement with no
82
- * stable schema, so the response is intentionally typed `unknown` and not
83
- * validated. `options` is validated by {@link buildLogPayload}.
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>): Promise<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: Array<{
93
- options: LogIngest.LogIngestOptions;
94
- additionalFields?: Record<string, unknown>;
95
- }>): Promise<unknown>;
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;AAClD,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AA4BhD;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,0CAA0C,CAAC;AAE/E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,SAAS,CAAC,gBAAgB,EACnC,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACzC,OAAO,CAkDT;AAED;;GAEG;AACH,qBAAa,WAAW;IAEV,OAAO,CAAC,QAAQ,CAAC,aAAa;IAD1C,iDAAiD;gBACpB,aAAa,EAAE,aAAa;IAEzD;;;;;;;;OAQG;IACU,wBAAwB,IAAI,OAAO,CAAC,MAAM,CAAC;IAIxD,oEAAoE;IAC7D,SAAS,CAAC,YAAY,EAAE,QAAQ,CAAC,mBAAmB;IAO3D;;;;;;;;;;;;;OAaG;IACI,eAAe,CACpB,OAAO,EAAE,SAAS,CAAC,gBAAgB,EACnC,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACzC,OAAO;IAQV;;;;;;OAMG;IACI,SAAS,CACd,OAAO,EAAE,SAAS,CAAC,gBAAgB,EACnC,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACzC,OAAO,CAAC,OAAO,CAAC;IAOnB;;;;;OAKG;IACI,UAAU,CACf,OAAO,EAAE,KAAK,CAAC;QACb,OAAO,EAAE,SAAS,CAAC,gBAAgB,CAAC;QACpC,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAC5C,CAAC,GACD,OAAO,CAAC,OAAO,CAAC;CAMpB"}
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.0",
3
+ "version": "7.12.2",
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"