@logbrew/sdk 0.1.38 → 0.1.39

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 (90) hide show
  1. package/automatic-delivery.cjs +271 -0
  2. package/batch-sender.cjs +164 -0
  3. package/bounded-number.cjs +34 -0
  4. package/browser-breadcrumbs.cjs +346 -136
  5. package/capture-support.cjs +100 -0
  6. package/client-options.cjs +292 -0
  7. package/client-report.cjs +232 -0
  8. package/client.cjs +447 -0
  9. package/console-arguments.cjs +151 -0
  10. package/console-capture.cjs +194 -0
  11. package/core.cjs +30 -2810
  12. package/delivery-health.cjs +133 -0
  13. package/error-causes.cjs +130 -0
  14. package/error-details.cjs +124 -0
  15. package/error-issue.cjs +187 -0
  16. package/event-clone.cjs +55 -0
  17. package/event-metadata.cjs +40 -0
  18. package/event-pipeline.cjs +325 -0
  19. package/event-queue.cjs +306 -0
  20. package/event-store.cjs +237 -0
  21. package/event-validation.cjs +159 -0
  22. package/examples/agent-timeline.cjs +57 -46
  23. package/examples/agent-timeline.mjs +41 -35
  24. package/examples/index.mjs +122 -94
  25. package/examples/readme-example.cjs +36 -27
  26. package/examples/readme-example.mjs +21 -17
  27. package/examples/real-user-smoke.cjs +41 -32
  28. package/examples/real-user-smoke.mjs +26 -22
  29. package/exception-chain.cjs +205 -0
  30. package/index.d.ts +144 -1076
  31. package/index.js +1 -1
  32. package/issue-exception.cjs +13 -8
  33. package/metric-validation.cjs +95 -0
  34. package/network-milestone.cjs +155 -0
  35. package/null-value.cjs +4 -0
  36. package/opentelemetry-bridge.cjs +330 -0
  37. package/opentelemetry-context.cjs +245 -0
  38. package/opentelemetry-exceptions.cjs +69 -0
  39. package/opentelemetry-keys.cjs +183 -0
  40. package/opentelemetry-span.cjs +286 -0
  41. package/opentelemetry-summary.cjs +213 -0
  42. package/opentelemetry-time.cjs +131 -0
  43. package/opentelemetry.cjs +99 -1068
  44. package/package.json +55 -1
  45. package/pino-destination.cjs +108 -0
  46. package/pino-record.cjs +237 -0
  47. package/product-action.cjs +163 -0
  48. package/provided-breadcrumbs.cjs +117 -0
  49. package/random-hex.cjs +29 -0
  50. package/react-native.js +1 -1
  51. package/recording-transport.cjs +68 -0
  52. package/release-artifacts-build.cjs +263 -84
  53. package/release-artifacts-common.js +347 -66
  54. package/release-artifacts-debug-id.js +178 -0
  55. package/release-artifacts-inspect.js +213 -0
  56. package/release-artifacts-issue-event.js +99 -0
  57. package/release-artifacts-manifest-artifact.js +107 -0
  58. package/release-artifacts-manifest.js +77 -0
  59. package/release-artifacts-mappings.js +265 -0
  60. package/release-artifacts-prepare.js +297 -0
  61. package/release-artifacts-source-context.js +210 -0
  62. package/release-artifacts-symbolication.js +272 -421
  63. package/release-artifacts-upload-files.js +122 -0
  64. package/release-artifacts-upload-request.js +246 -0
  65. package/release-artifacts-upload.js +155 -300
  66. package/release-artifacts-urls.js +49 -0
  67. package/release-artifacts.js +189 -662
  68. package/retry-delay.cjs +32 -0
  69. package/span-validation.cjs +191 -0
  70. package/stored-events.cjs +243 -0
  71. package/types/client.d.ts +67 -0
  72. package/types/delivery.d.ts +125 -0
  73. package/types/issues.d.ts +249 -0
  74. package/types/logging.d.ts +175 -0
  75. package/types/opentelemetry.d.ts +205 -0
  76. package/types/product.d.ts +128 -0
  77. package/types/recording-transport.d.ts +15 -0
  78. package/types/sdk-error.d.ts +9 -0
  79. package/types/telemetry.d.ts +171 -0
  80. package/types/trace-context.d.ts +110 -0
  81. package/types/transport-error.d.ts +10 -0
  82. package/utf8.cjs +37 -0
  83. package/validation.cjs +49 -1
  84. package/vite-release-artifacts-config.cjs +120 -0
  85. package/vite-release-artifacts.cjs +199 -99
  86. package/vite-release-artifacts.d.cts +65 -40
  87. package/vite-release-artifacts.d.ts +65 -40
  88. package/vite-release-artifacts.js +2 -2
  89. package/winston-info.cjs +205 -0
  90. package/winston.cjs +189 -289
@@ -0,0 +1,249 @@
1
+ import type { Metadata, SeverityInput, TelemetryContext } from "./telemetry.js";
2
+ import type { LogBrewClient } from "./client.js";
3
+ import type { LogCorrelationTraceContext } from "./trace-context.js";
4
+
5
+ /** Privacy-bounded generated JavaScript frame attached to an issue. */
6
+ type IssueStackFrame = {
7
+ /** Query-free generated filename or URL with local absolute prefixes removed. */
8
+ filename: string;
9
+ /** One-based generated source line. */
10
+ line: number;
11
+ /** One-based generated source column. */
12
+ column: number;
13
+ /** Optional bounded function or method identity. */
14
+ function?: string;
15
+ /** Optional bounded module, package, or namespace identity. */
16
+ module?: string;
17
+ /** Whether application code classified this frame as app-owned. */
18
+ inApp?: boolean;
19
+ /** Optional release-artifact Debug ID matched to this generated file. */
20
+ debugId?: string;
21
+ };
22
+
23
+ /** Runtime path that captured an exception and whether it escaped that path. */
24
+ type IssueExceptionMechanism = {
25
+ /** Stable low-cardinality capture mechanism, such as `react.error_boundary`. */
26
+ type: string;
27
+ /** False when the exception escaped the capture boundary. */
28
+ handled: boolean;
29
+ };
30
+
31
+ /** Structured exception identity attached to an issue. */
32
+ type IssueException = {
33
+ /** Bounded runtime exception class or error type. */
34
+ type: string;
35
+ /** Capture mechanism when the SDK can determine it. */
36
+ mechanism?: IssueExceptionMechanism;
37
+ };
38
+
39
+ type IssueExceptionRelationship =
40
+ | "reported"
41
+ | "cause"
42
+ | "context"
43
+ | "aggregate_member"
44
+ | "suppressed";
45
+
46
+ type IssueExceptionMessageState = "captured" | "truncated" | "redacted" | "not_captured";
47
+
48
+ type IssueExceptionStackFramesState = "captured" | "truncated" | "not_captured";
49
+
50
+ /** One parent-first runtime exception with its own message and structured stack state. */
51
+ type IssueExceptionChainEntry = {
52
+ /** Contiguous zero-based node identity. */
53
+ id: number;
54
+ /** Earlier parent node. Omitted only for the reported root exception. */
55
+ parentId?: number;
56
+ relationship: IssueExceptionRelationship;
57
+ type: string;
58
+ /** Bounded message only when messageState is captured or truncated. */
59
+ message?: string;
60
+ messageState: IssueExceptionMessageState;
61
+ module?: string;
62
+ mechanism?: IssueExceptionMechanism;
63
+ /** This exact exception's bounded structured frames. */
64
+ stackFrames?: IssueStackFrame[];
65
+ stackFramesState: IssueExceptionStackFramesState;
66
+ };
67
+
68
+ /** At most eight parent-first runtime exceptions. */
69
+ type IssueExceptionChain = {
70
+ entries: IssueExceptionChainEntry[];
71
+ /** True when a cycle or node cap omitted additional exceptions. */
72
+ truncated: boolean;
73
+ };
74
+
75
+ type IssueBreadcrumbLevel = "debug" | "info" | "warning" | "error" | "critical";
76
+
77
+ type IssueBreadcrumbLevelInput = IssueBreadcrumbLevel | "trace" | "log" | "warn" | "fatal";
78
+
79
+ type IssueBreadcrumbDataValue = string | number | boolean | null;
80
+
81
+ /** One privacy-bounded step that happened before an issue. */
82
+ type IssueBreadcrumb = {
83
+ /** RFC 3339 timestamp with an explicit timezone. */
84
+ timestamp: string;
85
+ /** Optional stable breadcrumb kind, such as `navigation` or `http`. */
86
+ type?: string;
87
+ /** Required low-cardinality source category. */
88
+ category: string;
89
+ level?: IssueBreadcrumbLevel;
90
+ /** Optional bounded display-safe description. */
91
+ message?: string;
92
+ /** At most eight flat primitive fields. Never include authentication material or raw request data. */
93
+ data?: Record<string, IssueBreadcrumbDataValue>;
94
+ };
95
+
96
+ /** Input accepted by `addBreadcrumb`; the client supplies the current timestamp when omitted. */
97
+ type IssueBreadcrumbInput = Omit<IssueBreadcrumb, "timestamp" | "level"> & {
98
+ timestamp?: string;
99
+ level?: IssueBreadcrumbLevelInput;
100
+ };
101
+
102
+ /** App-reported code location that narrows the smallest likely fix area. */
103
+ type IssueLikelyFixArea = {
104
+ component?: string;
105
+ module?: string;
106
+ function?: string;
107
+ /** Safe repository-relative source path. */
108
+ file?: string;
109
+ line?: number;
110
+ column?: number;
111
+ inApp?: boolean;
112
+ };
113
+
114
+ /** App-reported user impact without user identities or raw request data. */
115
+ type IssueImpactEvidence = {
116
+ affectedUserSegment?: string;
117
+ failedAction?: string;
118
+ userVisibleOutcome?: string;
119
+ };
120
+
121
+ /** Explicit diagnostic evidence for cause, fix area, impact, and capture limitations. */
122
+ type IssueDiagnosticEvidence = {
123
+ /** App-owned hypothesis. LogBrew presents it as reported, never proven. */
124
+ likelyRootCause?: string;
125
+ likelyFixArea?: IssueLikelyFixArea;
126
+ impact?: IssueImpactEvidence;
127
+ /** Unique bounded field names whose values were captured. */
128
+ capturedFields?: string[];
129
+ missingFields?: string[];
130
+ redactedFields?: string[];
131
+ truncatedFields?: string[];
132
+ };
133
+
134
+ type NativeStackArchitecture = "arm" | "arm64" | "arm64e" | "x86" | "x86_64";
135
+
136
+ type NativeStackFrame = {
137
+ imageUuid: string;
138
+ architecture: NativeStackArchitecture;
139
+ instructionOffset: string;
140
+ };
141
+
142
+ /** Public issue event attributes. */
143
+ type IssueAttributes = {
144
+ title: string;
145
+ level: SeverityInput;
146
+ message?: string;
147
+ exception?: IssueException;
148
+ /** Parent-first runtime exception evidence; the first node agrees with legacy exception/stackFrames. */
149
+ exceptionChain?: IssueExceptionChain;
150
+ /** Ordered privacy-bounded generated frames, capped at 32. */
151
+ stackFrames?: IssueStackFrame[];
152
+ /** Ordered native image-relative frames for exact release symbolication, capped at 32. */
153
+ nativeStackFrames?: NativeStackFrame[];
154
+ /** Oldest-to-newest issue history, capped at the most recent 64 entries. */
155
+ breadcrumbs?: IssueBreadcrumb[];
156
+ /** True when older or invalid history was omitted before capture. */
157
+ breadcrumbsTruncated?: boolean;
158
+ /** App-reported diagnostic evidence, validated and labeled separately from observed facts. */
159
+ evidence?: IssueDiagnosticEvidence;
160
+ metadata?: Metadata;
161
+ context?: TelemetryContext;
162
+ };
163
+
164
+ /** Options for creating privacy-bounded issue attributes from a JavaScript error. */
165
+ type JavaScriptErrorIssueOptions = {
166
+ title?: string;
167
+ level?: SeverityInput;
168
+ message?: string;
169
+ metadata?: Metadata;
170
+ /** Stable low-cardinality capture mechanism. Defaults to `javascript.error`. */
171
+ mechanism?: string;
172
+ /** Whether the error was handled by the capture boundary. Defaults to true. */
173
+ handled?: boolean;
174
+ /** Metadata source label. Defaults to `javascript.error`. */
175
+ source?: string;
176
+ /** Active trace copied into primitive correlation metadata. */
177
+ trace?: LogCorrelationTraceContext | null;
178
+ /** Release name associated with the runtime error. */
179
+ release?: string;
180
+ /** Environment associated with the runtime error. */
181
+ environment?: string;
182
+ /** Service associated with the runtime error. */
183
+ service?: string;
184
+ /** Runtime label such as `browser`, `node`, or `react-native`. */
185
+ runtime?: string;
186
+ /** Platform label such as `web`, `ios`, or `android`. */
187
+ platform?: string;
188
+ /** Map of sanitized frame filenames or minified URLs to release-artifact Debug IDs. */
189
+ debugIdMap?: Record<string, string>;
190
+ /** Optional stable app-owned grouping fingerprint. Keep it safe and low-cardinality. */
191
+ fingerprint?: string;
192
+ /** App-reported cause, fix-area, impact, and explicit evidence-state receipt. */
193
+ evidence?: IssueDiagnosticEvidence;
194
+ /** Include raw stack text only when the app has explicitly approved it. Defaults to false. */
195
+ includeErrorStack?: boolean;
196
+ };
197
+
198
+ /** Options for automatic browser breadcrumbs. Every source defaults to true. */
199
+ type BrowserBreadcrumbOptions = {
200
+ console?: boolean;
201
+ network?: boolean;
202
+ navigation?: boolean;
203
+ /** URLs whose requests are not recorded, such as the LogBrew ingest endpoint. */
204
+ ignoredUrls?: string[];
205
+ };
206
+
207
+ /**
208
+ * Record console calls, fetch and XHR requests, and route changes in a browser window as issue
209
+ * breadcrumbs on the client. The wrappers only observe calls. Returns an uninstall function.
210
+ */
211
+ declare function installBrowserBreadcrumbs(
212
+ browserWindow: unknown,
213
+ client: LogBrewClient,
214
+ options?: BrowserBreadcrumbOptions
215
+ ): () => void;
216
+
217
+ /**
218
+ * Convert a JavaScript Error-like value into safe issue attributes with optional source-map Debug ID metadata.
219
+ * Parent-first cause and AggregateError evidence is bounded to the public exception-chain contract.
220
+ */
221
+ declare function createIssueAttributesFromError(
222
+ error: unknown,
223
+ options?: JavaScriptErrorIssueOptions
224
+ ): IssueAttributes;
225
+
226
+ export type {
227
+ BrowserBreadcrumbOptions,
228
+ IssueAttributes,
229
+ IssueBreadcrumb,
230
+ IssueBreadcrumbDataValue,
231
+ IssueBreadcrumbInput,
232
+ IssueBreadcrumbLevel,
233
+ IssueBreadcrumbLevelInput,
234
+ IssueDiagnosticEvidence,
235
+ IssueException,
236
+ IssueExceptionChain,
237
+ IssueExceptionChainEntry,
238
+ IssueExceptionMechanism,
239
+ IssueExceptionMessageState,
240
+ IssueExceptionRelationship,
241
+ IssueExceptionStackFramesState,
242
+ IssueImpactEvidence,
243
+ IssueLikelyFixArea,
244
+ IssueStackFrame,
245
+ JavaScriptErrorIssueOptions,
246
+ NativeStackArchitecture,
247
+ NativeStackFrame
248
+ };
249
+ export { createIssueAttributesFromError, installBrowserBreadcrumbs };
@@ -0,0 +1,175 @@
1
+ import type { LogAttributes, Metadata } from "./telemetry.js";
2
+ import type { Transport, TransportResponse } from "./delivery.js";
3
+ import type { LogBrewClient } from "./client.js";
4
+ import type { LogCorrelationTraceContext } from "./trace-context.js";
5
+
6
+ /** Console method names supported by the opt-in console capture helper. */
7
+ type ConsoleMethodName = "debug" | "info" | "log" | "warn" | "error";
8
+
9
+ /** Minimal console-like target accepted by the opt-in console capture helper. */
10
+ type ConsoleLike = Partial<Record<ConsoleMethodName, (...args: unknown[]) => void>>;
11
+
12
+ /** Configuration for opt-in console capture. */
13
+ type ConsoleCaptureConfig = {
14
+ client: LogBrewClient;
15
+ console?: ConsoleLike;
16
+ levels?: ConsoleMethodName[];
17
+ logger?: string;
18
+ metadata?: Metadata;
19
+ transport?: Transport;
20
+ flushOnCapture?: boolean;
21
+ includeErrorStack?: boolean;
22
+ timestamp?: () => string;
23
+ eventIdPrefix?: string;
24
+ onError?: (error: unknown) => void;
25
+ };
26
+
27
+ /** Handle returned by opt-in console capture installation. */
28
+ type ConsoleCaptureHandle = {
29
+ flush(): Promise<TransportResponse | null>;
30
+ uninstall(): void;
31
+ };
32
+
33
+ /** Pino JSON log record shape accepted by the optional Pino destination helper. */
34
+ type PinoLogRecord = Record<string, unknown> & {
35
+ level?: string | number;
36
+ time?: string | number;
37
+ timestamp?: string | number;
38
+ msg?: unknown;
39
+ message?: unknown;
40
+ err?: unknown;
41
+ error?: unknown;
42
+ };
43
+
44
+ /** Configuration for the dependency-free Pino destination adapter. */
45
+ type PinoDestinationConfig = {
46
+ client: LogBrewClient;
47
+ logger?: string;
48
+ metadata?: Metadata;
49
+ traceProvider?: () => LogCorrelationTraceContext | null | undefined;
50
+ transport?: Transport;
51
+ flushOnWrite?: boolean;
52
+ includeErrorStack?: boolean;
53
+ timestamp?: () => string;
54
+ eventIdPrefix?: string;
55
+ onError?: (error: unknown) => void;
56
+ };
57
+
58
+ /** Stream-like destination returned for use as Pino's output destination. */
59
+ type PinoDestinationHandle = {
60
+ write(chunk: unknown): boolean;
61
+ flush(): Promise<TransportResponse | null>;
62
+ end(): Promise<TransportResponse | null>;
63
+ };
64
+
65
+ /** Winston info object shape accepted by the optional Winston transport helper. */
66
+ type WinstonLogInfo = Record<string, unknown> & {
67
+ level?: string;
68
+ message?: unknown;
69
+ timestamp?: string | number | Date;
70
+ time?: string | number | Date;
71
+ err?: unknown;
72
+ error?: unknown;
73
+ stack?: unknown;
74
+ };
75
+
76
+ /** Configuration for the dependency-free Winston transport adapter. */
77
+ type WinstonTransportConfig = {
78
+ client: LogBrewClient;
79
+ /** Record each Winston message as an issue breadcrumb (category `log.winston`). Defaults to true. */
80
+ breadcrumbs?: boolean;
81
+ logger?: string;
82
+ metadata?: Metadata;
83
+ traceProvider?: () => LogCorrelationTraceContext | null | undefined;
84
+ transport?: Transport;
85
+ flushOnWrite?: boolean;
86
+ includeErrorStack?: boolean;
87
+ timestamp?: () => string;
88
+ eventIdPrefix?: string;
89
+ level?: string;
90
+ name?: string;
91
+ silent?: boolean;
92
+ handleExceptions?: boolean;
93
+ handleRejections?: boolean;
94
+ onError?: (error: unknown) => void;
95
+ };
96
+
97
+ /** Object-mode transport returned for use in a Winston logger's transports array. */
98
+ type WinstonTransportHandle = {
99
+ level?: string;
100
+ name?: string;
101
+ silent?: boolean;
102
+ handleExceptions?: boolean;
103
+ handleRejections?: boolean;
104
+ log(info: WinstonLogInfo, callback?: () => void): void;
105
+ write(info: WinstonLogInfo): boolean;
106
+ flush(): Promise<TransportResponse | null>;
107
+ end(callback?: () => void): unknown;
108
+ };
109
+
110
+ /** Install explicit console capture while preserving the target console's normal output behavior. */
111
+ declare function installLogBrewConsoleCapture(config: ConsoleCaptureConfig): ConsoleCaptureHandle;
112
+
113
+ /** Convert console arguments into safe LogBrew log attributes without installing capture. */
114
+ declare function logAttributesFromConsoleArgs(
115
+ method: ConsoleMethodName,
116
+ args: readonly unknown[],
117
+ options?: {
118
+ logger?: string;
119
+ metadata?: Metadata;
120
+ includeErrorStack?: boolean;
121
+ }
122
+ ): LogAttributes;
123
+
124
+ /** Map a console method name to the corresponding LogBrew log level. */
125
+ declare function logbrewLevelFromConsoleMethod(method: ConsoleMethodName): LogAttributes["level"];
126
+
127
+ /** Create a dependency-free Pino destination that turns JSON log lines into queued LogBrew log events. */
128
+ declare function createLogBrewPinoDestination(config: PinoDestinationConfig): PinoDestinationHandle;
129
+
130
+ /** Convert a parsed Pino JSON log record into safe LogBrew log attributes without installing a destination. */
131
+ declare function logAttributesFromPinoRecord(
132
+ record: PinoLogRecord,
133
+ options?: {
134
+ logger?: string;
135
+ metadata?: Metadata;
136
+ trace?: LogCorrelationTraceContext | null;
137
+ includeErrorStack?: boolean;
138
+ }
139
+ ): LogAttributes;
140
+
141
+ /** Create a dependency-free Winston object-mode transport that queues LogBrew log events. */
142
+ declare function createLogBrewWinstonTransport(config: WinstonTransportConfig): WinstonTransportHandle;
143
+
144
+ /** Convert a Winston info object into safe LogBrew log attributes without installing a transport. */
145
+ declare function logAttributesFromWinstonInfo(
146
+ info: WinstonLogInfo,
147
+ options?: {
148
+ logger?: string;
149
+ metadata?: Metadata;
150
+ trace?: LogCorrelationTraceContext | null;
151
+ includeErrorStack?: boolean;
152
+ }
153
+ ): LogAttributes;
154
+
155
+ export type {
156
+ ConsoleCaptureConfig,
157
+ ConsoleCaptureHandle,
158
+ ConsoleLike,
159
+ ConsoleMethodName,
160
+ PinoDestinationConfig,
161
+ PinoDestinationHandle,
162
+ PinoLogRecord,
163
+ WinstonLogInfo,
164
+ WinstonTransportConfig,
165
+ WinstonTransportHandle
166
+ };
167
+ export {
168
+ createLogBrewPinoDestination,
169
+ createLogBrewWinstonTransport,
170
+ installLogBrewConsoleCapture,
171
+ logAttributesFromConsoleArgs,
172
+ logAttributesFromPinoRecord,
173
+ logAttributesFromWinstonInfo,
174
+ logbrewLevelFromConsoleMethod
175
+ };
@@ -0,0 +1,205 @@
1
+ import type { Metadata, SpanAttributes } from "./telemetry.js";
2
+ import type { LogBrewClient } from "./client.js";
3
+ import type { LogCorrelationTraceContext } from "./trace-context.js";
4
+ import type { Transport } from "./delivery.js";
5
+
6
+ /** Minimal OpenTelemetry SpanContext-like shape copied by dependency-free bridge helpers. */
7
+ type OpenTelemetrySpanContextLike = {
8
+ traceId?: unknown;
9
+ spanId?: unknown;
10
+ traceFlags?: unknown;
11
+ isValid?: boolean;
12
+ };
13
+
14
+ /** Minimal OpenTelemetry Span-like shape accepted by dependency-free bridge helpers. */
15
+ type OpenTelemetrySpanLike = {
16
+ spanContext?: () => OpenTelemetrySpanContextLike | null | undefined;
17
+ getSpanContext?: () => OpenTelemetrySpanContextLike | null | undefined;
18
+ };
19
+
20
+ /** Minimal OpenTelemetry API-like shape used for the current active span helper. */
21
+ type OpenTelemetryApiLike = {
22
+ trace?: {
23
+ getActiveSpan?: () => OpenTelemetrySpanLike | null | undefined;
24
+ };
25
+ };
26
+
27
+ /** OpenTelemetry high-resolution time tuple accepted by dependency-free ReadableSpan helpers. */
28
+ type OpenTelemetryHrTimeLike = readonly [number, number];
29
+
30
+ /** Minimal OpenTelemetry event-like shape summarized from ended spans. */
31
+ type OpenTelemetryTimedEventLike = {
32
+ name?: unknown;
33
+ time?: OpenTelemetryHrTimeLike | number | Date;
34
+ timestamp?: OpenTelemetryHrTimeLike | number | Date;
35
+ attributes?: Record<string, unknown>;
36
+ };
37
+
38
+ /** Minimal OpenTelemetry link-like shape summarized from ended spans. */
39
+ type OpenTelemetrySpanLinkLike = {
40
+ context?: OpenTelemetrySpanContextLike | null | undefined;
41
+ spanContext?: OpenTelemetrySpanContextLike | null | undefined;
42
+ attributes?: Record<string, unknown>;
43
+ };
44
+
45
+ /** Minimal OpenTelemetry ReadableSpan-like shape accepted by dependency-free bridge helpers. */
46
+ type OpenTelemetryReadableSpanLike = {
47
+ name?: unknown;
48
+ kind?: unknown;
49
+ spanContext?: () => OpenTelemetrySpanContextLike | null | undefined;
50
+ parentSpanContext?: OpenTelemetrySpanContextLike | null | undefined;
51
+ parentSpanId?: unknown;
52
+ startTime?: OpenTelemetryHrTimeLike | number | Date;
53
+ endTime?: OpenTelemetryHrTimeLike | number | Date;
54
+ duration?: OpenTelemetryHrTimeLike;
55
+ status?: { code?: unknown };
56
+ attributes?: Record<string, unknown>;
57
+ events?: OpenTelemetryTimedEventLike[];
58
+ links?: OpenTelemetrySpanLinkLike[];
59
+ resource?: { attributes?: Record<string, unknown> };
60
+ instrumentationScope?: { name?: unknown; version?: unknown };
61
+ droppedAttributesCount?: unknown;
62
+ droppedEventsCount?: unknown;
63
+ droppedLinksCount?: unknown;
64
+ };
65
+
66
+ /** Options for creating a LogBrew child trace from OpenTelemetry context. */
67
+ type OpenTelemetryTraceContextOptions = {
68
+ spanId?: string;
69
+ spanIdFactory?: () => string;
70
+ };
71
+
72
+ /** Options for reading OpenTelemetry's current active span without requiring an OTel dependency. */
73
+ type CurrentOpenTelemetryTraceContextOptions = OpenTelemetryTraceContextOptions & {
74
+ openTelemetryApi?: OpenTelemetryApiLike;
75
+ };
76
+
77
+ /** Options for privacy-bounded OpenTelemetry ReadableSpan conversion. */
78
+ type OpenTelemetryReadableSpanOptions = {
79
+ /** Additional safe span attribute keys to copy; sensitive keys remain blocked. */
80
+ attributeKeys?: string[];
81
+ /** Capture unsampled spans. Defaults to false to follow common OTel processor behavior. */
82
+ captureUnsampled?: boolean;
83
+ /** Additional safe span event attribute keys to copy; sensitive keys remain blocked. */
84
+ eventAttributeKeys?: string[];
85
+ /** Include privacy-bounded span event summaries. Defaults to true. */
86
+ includeSpanEvents?: boolean;
87
+ /** Include privacy-bounded span link summaries. Defaults to true. */
88
+ includeSpanLinks?: boolean;
89
+ /** Additional safe span link attribute keys to copy; sensitive keys remain blocked. */
90
+ linkAttributeKeys?: string[];
91
+ /** Primitive app metadata merged into every converted span. */
92
+ metadata?: Metadata;
93
+ /** Additional safe resource attribute keys to copy; sensitive keys remain blocked. */
94
+ resourceAttributeKeys?: string[];
95
+ };
96
+
97
+ /** Configuration for an opt-in OpenTelemetry SpanProcessor-compatible LogBrew bridge. */
98
+ type OpenTelemetrySpanProcessorConfig = OpenTelemetryReadableSpanOptions & {
99
+ client: LogBrewClient;
100
+ transport?: Transport;
101
+ flushOnForceFlush?: boolean;
102
+ /** Emit one privacy-bounded synthetic trace summary span per trace on forceFlush/shutdown. Defaults to false. */
103
+ includeTraceSummary?: boolean;
104
+ timestamp?: () => string;
105
+ eventIdPrefix?: string;
106
+ spanFilter?: (span: unknown) => boolean | void;
107
+ onError?: (error: unknown) => void;
108
+ };
109
+
110
+ /** Configuration for an opt-in OpenTelemetry SpanExporter-compatible LogBrew bridge. */
111
+ type OpenTelemetrySpanExporterConfig = OpenTelemetryReadableSpanOptions & {
112
+ client: LogBrewClient;
113
+ transport?: Transport;
114
+ /** Flush with the provided transport during export. Defaults to true when a transport is supplied. */
115
+ flushOnExport?: boolean;
116
+ /** Emit one privacy-bounded synthetic trace summary span per exported batch. Defaults to false. */
117
+ includeTraceSummary?: boolean;
118
+ timestamp?: () => string;
119
+ eventIdPrefix?: string;
120
+ spanFilter?: (span: unknown) => boolean | void;
121
+ onError?: (error: unknown) => void;
122
+ };
123
+
124
+ /** Minimal OpenTelemetry export result shape; success is code 0, failure is code 1. */
125
+ type OpenTelemetryExportResult = {
126
+ code: number;
127
+ error?: Error;
128
+ };
129
+
130
+ /** SpanExporter-compatible handle for app-owned OpenTelemetry processors. */
131
+ type OpenTelemetrySpanExporterHandle = {
132
+ export(
133
+ spans: readonly unknown[],
134
+ resultCallback: (result: OpenTelemetryExportResult) => void
135
+ ): void;
136
+ forceFlush(): Promise<void>;
137
+ shutdown(): Promise<void>;
138
+ };
139
+
140
+ /** SpanProcessor-compatible handle for app-owned OpenTelemetry setup. */
141
+ type OpenTelemetrySpanProcessorHandle = {
142
+ onStart(span: unknown, parentContext: unknown): void;
143
+ onEnd(span: unknown): void;
144
+ forceFlush(): Promise<void>;
145
+ shutdown(): Promise<void>;
146
+ };
147
+
148
+ /** Create a LogBrew child trace from a live OpenTelemetry SpanContext-like object. */
149
+ declare function logbrewTraceContextFromOpenTelemetrySpanContext(
150
+ spanContext: OpenTelemetrySpanContextLike | null | undefined,
151
+ options?: OpenTelemetryTraceContextOptions
152
+ ): LogCorrelationTraceContext | null;
153
+
154
+ /** Create a LogBrew child trace from a live OpenTelemetry Span-like object. */
155
+ declare function logbrewTraceContextFromOpenTelemetrySpan(
156
+ span: OpenTelemetrySpanLike | null | undefined,
157
+ options?: OpenTelemetryTraceContextOptions
158
+ ): LogCorrelationTraceContext | null;
159
+
160
+ /** Create a LogBrew child trace from OpenTelemetry's current active span, when available. */
161
+ declare function logbrewTraceContextFromCurrentOpenTelemetrySpan(
162
+ options?: CurrentOpenTelemetryTraceContextOptions
163
+ ): LogCorrelationTraceContext | null;
164
+
165
+ /** Convert an ended OpenTelemetry ReadableSpan-like object into safe LogBrew span attributes. */
166
+ declare function spanAttributesFromOpenTelemetryReadableSpan(
167
+ span: OpenTelemetryReadableSpanLike | null | undefined,
168
+ options?: OpenTelemetryReadableSpanOptions
169
+ ): SpanAttributes | null;
170
+
171
+ /** Create an opt-in SpanProcessor-compatible bridge for app-owned OpenTelemetry providers. */
172
+ declare function createLogBrewOpenTelemetrySpanProcessor(
173
+ config: OpenTelemetrySpanProcessorConfig
174
+ ): OpenTelemetrySpanProcessorHandle;
175
+
176
+ /** Create an opt-in SpanExporter-compatible bridge for app-owned OpenTelemetry processors. */
177
+ declare function createLogBrewOpenTelemetrySpanExporter(
178
+ config: OpenTelemetrySpanExporterConfig
179
+ ): OpenTelemetrySpanExporterHandle;
180
+
181
+ export type {
182
+ CurrentOpenTelemetryTraceContextOptions,
183
+ OpenTelemetryApiLike,
184
+ OpenTelemetryExportResult,
185
+ OpenTelemetryHrTimeLike,
186
+ OpenTelemetryReadableSpanLike,
187
+ OpenTelemetryReadableSpanOptions,
188
+ OpenTelemetrySpanContextLike,
189
+ OpenTelemetrySpanExporterConfig,
190
+ OpenTelemetrySpanExporterHandle,
191
+ OpenTelemetrySpanLike,
192
+ OpenTelemetrySpanLinkLike,
193
+ OpenTelemetrySpanProcessorConfig,
194
+ OpenTelemetrySpanProcessorHandle,
195
+ OpenTelemetryTimedEventLike,
196
+ OpenTelemetryTraceContextOptions
197
+ };
198
+ export {
199
+ createLogBrewOpenTelemetrySpanExporter,
200
+ createLogBrewOpenTelemetrySpanProcessor,
201
+ logbrewTraceContextFromCurrentOpenTelemetrySpan,
202
+ logbrewTraceContextFromOpenTelemetrySpan,
203
+ logbrewTraceContextFromOpenTelemetrySpanContext,
204
+ spanAttributesFromOpenTelemetryReadableSpan
205
+ };