vestig 0.11.4 → 0.13.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.
- package/README.md +95 -2
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +4 -0
- package/dist/config.js.map +1 -1
- package/dist/index.d.ts +9 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +7 -1
- package/dist/index.js.map +1 -1
- package/dist/logger.d.ts +85 -0
- package/dist/logger.d.ts.map +1 -1
- package/dist/logger.js +209 -2
- package/dist/logger.js.map +1 -1
- package/dist/metrics/index.d.ts +2 -0
- package/dist/metrics/index.d.ts.map +1 -0
- package/dist/metrics/index.js +2 -0
- package/dist/metrics/index.js.map +1 -0
- package/dist/metrics/prometheus.d.ts +109 -0
- package/dist/metrics/prometheus.d.ts.map +1 -0
- package/dist/metrics/prometheus.js +162 -0
- package/dist/metrics/prometheus.js.map +1 -0
- package/dist/sampling/index.d.ts +2 -0
- package/dist/sampling/index.d.ts.map +1 -1
- package/dist/sampling/index.js +2 -0
- package/dist/sampling/index.js.map +1 -1
- package/dist/sampling/tail.d.ts +76 -0
- package/dist/sampling/tail.d.ts.map +1 -0
- package/dist/sampling/tail.js +138 -0
- package/dist/sampling/tail.js.map +1 -0
- package/dist/transports/batch.d.ts +2 -0
- package/dist/transports/batch.d.ts.map +1 -1
- package/dist/transports/batch.js +13 -3
- package/dist/transports/batch.js.map +1 -1
- package/dist/transports/file.d.ts +14 -1
- package/dist/transports/file.d.ts.map +1 -1
- package/dist/transports/file.js +59 -4
- package/dist/transports/file.js.map +1 -1
- package/dist/transports/http.d.ts +29 -1
- package/dist/transports/http.d.ts.map +1 -1
- package/dist/transports/http.js +63 -6
- package/dist/transports/http.js.map +1 -1
- package/dist/transports/sentry.d.ts +83 -0
- package/dist/transports/sentry.d.ts.map +1 -0
- package/dist/transports/sentry.js +283 -0
- package/dist/transports/sentry.js.map +1 -0
- package/dist/types.d.ts +149 -2
- package/dist/types.d.ts.map +1 -1
- package/dist/utils/buffer.d.ts +33 -1
- package/dist/utils/buffer.d.ts.map +1 -1
- package/dist/utils/buffer.js +40 -2
- package/dist/utils/buffer.js.map +1 -1
- package/dist/utils/dedupe.d.ts +80 -0
- package/dist/utils/dedupe.d.ts.map +1 -0
- package/dist/utils/dedupe.js +173 -0
- package/dist/utils/dedupe.js.map +1 -0
- package/dist/utils/sanitize.d.ts +23 -1
- package/dist/utils/sanitize.d.ts.map +1 -1
- package/dist/utils/sanitize.js +113 -8
- package/dist/utils/sanitize.js.map +1 -1
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/dist/wide-events/builder.d.ts +51 -0
- package/dist/wide-events/builder.d.ts.map +1 -0
- package/dist/wide-events/builder.js +177 -0
- package/dist/wide-events/builder.js.map +1 -0
- package/dist/wide-events/context.d.ts +57 -0
- package/dist/wide-events/context.d.ts.map +1 -0
- package/dist/wide-events/context.js +148 -0
- package/dist/wide-events/context.js.map +1 -0
- package/dist/wide-events/index.d.ts +6 -0
- package/dist/wide-events/index.d.ts.map +1 -0
- package/dist/wide-events/index.js +7 -0
- package/dist/wide-events/index.js.map +1 -0
- package/dist/wide-events/schemas/http.d.ts +179 -0
- package/dist/wide-events/schemas/http.d.ts.map +1 -0
- package/dist/wide-events/schemas/http.js +25 -0
- package/dist/wide-events/schemas/http.js.map +1 -0
- package/dist/wide-events/schemas/index.d.ts +5 -0
- package/dist/wide-events/schemas/index.d.ts.map +1 -0
- package/dist/wide-events/schemas/index.js +5 -0
- package/dist/wide-events/schemas/index.js.map +1 -0
- package/dist/wide-events/schemas/job.d.ts +130 -0
- package/dist/wide-events/schemas/job.d.ts.map +1 -0
- package/dist/wide-events/schemas/job.js +27 -0
- package/dist/wide-events/schemas/job.js.map +1 -0
- package/dist/wide-events/types.d.ts +216 -0
- package/dist/wide-events/types.d.ts.map +1 -0
- package/dist/wide-events/types.js +2 -0
- package/dist/wide-events/types.js.map +1 -0
- package/package.json +1 -1
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Background job fields for wide events.
|
|
3
|
+
*
|
|
4
|
+
* These fields capture information about async job execution
|
|
5
|
+
* for observability and debugging of background processing.
|
|
6
|
+
*/
|
|
7
|
+
export interface JobFields {
|
|
8
|
+
/** Unique job identifier */
|
|
9
|
+
id?: string;
|
|
10
|
+
/** Job type/name (e.g., 'email_digest', 'data_sync') */
|
|
11
|
+
type?: string;
|
|
12
|
+
/** Queue name */
|
|
13
|
+
queue?: string;
|
|
14
|
+
/** Job priority (lower = higher priority) */
|
|
15
|
+
priority?: number;
|
|
16
|
+
/** Current attempt number */
|
|
17
|
+
attempt?: number;
|
|
18
|
+
/** Maximum retry attempts allowed */
|
|
19
|
+
max_attempts?: number;
|
|
20
|
+
/** Scheduled execution time (ISO 8601) */
|
|
21
|
+
scheduled_at?: string;
|
|
22
|
+
/** Actual start time (ISO 8601) */
|
|
23
|
+
started_at?: string;
|
|
24
|
+
/** Completion time (ISO 8601) */
|
|
25
|
+
completed_at?: string;
|
|
26
|
+
/** Job status (queued, running, completed, failed, cancelled) */
|
|
27
|
+
status?: 'queued' | 'running' | 'completed' | 'failed' | 'cancelled';
|
|
28
|
+
/** Parent job ID (for child/dependent jobs) */
|
|
29
|
+
parent_job_id?: string;
|
|
30
|
+
/** Batch ID (for batch processing) */
|
|
31
|
+
batch_id?: string;
|
|
32
|
+
/** Worker/processor that executed the job */
|
|
33
|
+
worker_id?: string;
|
|
34
|
+
}
|
|
35
|
+
/**
|
|
36
|
+
* Job input/output fields for wide events.
|
|
37
|
+
*/
|
|
38
|
+
export interface JobDataFields {
|
|
39
|
+
/** Number of input items to process */
|
|
40
|
+
input_count?: number;
|
|
41
|
+
/** Input data size in bytes */
|
|
42
|
+
input_size_bytes?: number;
|
|
43
|
+
/** Number of items successfully processed */
|
|
44
|
+
success_count?: number;
|
|
45
|
+
/** Number of items that failed */
|
|
46
|
+
failure_count?: number;
|
|
47
|
+
/** Number of items skipped */
|
|
48
|
+
skipped_count?: number;
|
|
49
|
+
/** Output data size in bytes */
|
|
50
|
+
output_size_bytes?: number;
|
|
51
|
+
}
|
|
52
|
+
/**
|
|
53
|
+
* Job performance metrics.
|
|
54
|
+
*/
|
|
55
|
+
export interface JobPerformanceFields {
|
|
56
|
+
/** Total execution time in ms */
|
|
57
|
+
duration_ms?: number;
|
|
58
|
+
/** Time spent waiting in queue in ms */
|
|
59
|
+
queue_time_ms?: number;
|
|
60
|
+
/** Processing time in ms */
|
|
61
|
+
processing_time_ms?: number;
|
|
62
|
+
/** Memory used in bytes */
|
|
63
|
+
memory_used_bytes?: number;
|
|
64
|
+
/** CPU time in ms */
|
|
65
|
+
cpu_time_ms?: number;
|
|
66
|
+
/** Number of database queries */
|
|
67
|
+
db_query_count?: number;
|
|
68
|
+
/** Total database time in ms */
|
|
69
|
+
db_query_time_ms?: number;
|
|
70
|
+
/** Number of external API calls */
|
|
71
|
+
external_call_count?: number;
|
|
72
|
+
/** Total external call time in ms */
|
|
73
|
+
external_call_time_ms?: number;
|
|
74
|
+
}
|
|
75
|
+
/**
|
|
76
|
+
* Job error fields.
|
|
77
|
+
*/
|
|
78
|
+
export interface JobErrorFields {
|
|
79
|
+
/** Error type/class name */
|
|
80
|
+
type?: string;
|
|
81
|
+
/** Error code */
|
|
82
|
+
code?: string | number;
|
|
83
|
+
/** Error message */
|
|
84
|
+
message?: string;
|
|
85
|
+
/** Whether the job should be retried */
|
|
86
|
+
retriable?: boolean;
|
|
87
|
+
/** Next retry time (ISO 8601) */
|
|
88
|
+
retry_at?: string;
|
|
89
|
+
/** Backoff duration in ms */
|
|
90
|
+
backoff_ms?: number;
|
|
91
|
+
}
|
|
92
|
+
/**
|
|
93
|
+
* Complete background job event fields structure.
|
|
94
|
+
*
|
|
95
|
+
* This interface represents all the categories of fields
|
|
96
|
+
* typically captured for a background job wide event.
|
|
97
|
+
*/
|
|
98
|
+
export interface BackgroundJobEventFields {
|
|
99
|
+
job?: Record<string, unknown>;
|
|
100
|
+
job_data?: Record<string, unknown>;
|
|
101
|
+
performance?: Record<string, unknown>;
|
|
102
|
+
error?: Record<string, unknown>;
|
|
103
|
+
service?: Record<string, unknown>;
|
|
104
|
+
[category: string]: Record<string, unknown> | undefined;
|
|
105
|
+
}
|
|
106
|
+
/**
|
|
107
|
+
* Helper to create typed background job fields.
|
|
108
|
+
*
|
|
109
|
+
* @example
|
|
110
|
+
* ```typescript
|
|
111
|
+
* const event = createWideEvent({ type: 'job.execute' });
|
|
112
|
+
* event.mergeAll(jobFields({
|
|
113
|
+
* job: { id: 'job-123', type: 'email_digest', attempt: 1 },
|
|
114
|
+
* job_data: { input_count: 100, success_count: 98, failure_count: 2 },
|
|
115
|
+
* performance: { duration_ms: 5420, db_query_count: 50 }
|
|
116
|
+
* }));
|
|
117
|
+
* ```
|
|
118
|
+
*/
|
|
119
|
+
export declare function jobFields(fields: Partial<BackgroundJobEventFields>): BackgroundJobEventFields;
|
|
120
|
+
/**
|
|
121
|
+
* Common job event type constants.
|
|
122
|
+
*/
|
|
123
|
+
export declare const JOB_EVENT_TYPES: {
|
|
124
|
+
readonly EXECUTE: "job.execute";
|
|
125
|
+
readonly COMPLETE: "job.complete";
|
|
126
|
+
readonly FAIL: "job.fail";
|
|
127
|
+
readonly RETRY: "job.retry";
|
|
128
|
+
readonly CANCEL: "job.cancel";
|
|
129
|
+
};
|
|
130
|
+
//# sourceMappingURL=job.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"job.d.ts","sourceRoot":"","sources":["../../../src/wide-events/schemas/job.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Helper to create typed background job fields.
|
|
3
|
+
*
|
|
4
|
+
* @example
|
|
5
|
+
* ```typescript
|
|
6
|
+
* const event = createWideEvent({ type: 'job.execute' });
|
|
7
|
+
* event.mergeAll(jobFields({
|
|
8
|
+
* job: { id: 'job-123', type: 'email_digest', attempt: 1 },
|
|
9
|
+
* job_data: { input_count: 100, success_count: 98, failure_count: 2 },
|
|
10
|
+
* performance: { duration_ms: 5420, db_query_count: 50 }
|
|
11
|
+
* }));
|
|
12
|
+
* ```
|
|
13
|
+
*/
|
|
14
|
+
export function jobFields(fields) {
|
|
15
|
+
return fields;
|
|
16
|
+
}
|
|
17
|
+
/**
|
|
18
|
+
* Common job event type constants.
|
|
19
|
+
*/
|
|
20
|
+
export const JOB_EVENT_TYPES = {
|
|
21
|
+
EXECUTE: 'job.execute',
|
|
22
|
+
COMPLETE: 'job.complete',
|
|
23
|
+
FAIL: 'job.fail',
|
|
24
|
+
RETRY: 'job.retry',
|
|
25
|
+
CANCEL: 'job.cancel',
|
|
26
|
+
};
|
|
27
|
+
//# sourceMappingURL=job.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"job.js","sourceRoot":"","sources":["../../../src/wide-events/schemas/job.ts"],"names":[],"mappings":"AA8GA;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,SAAS,CAAC,MAAyC;IAClE,OAAO,MAAkC,CAAA;AAC1C,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC9B,OAAO,EAAE,aAAa;IACtB,QAAQ,EAAE,cAAc;IACxB,IAAI,EAAE,UAAU;IAChB,KAAK,EAAE,WAAW;IAClB,MAAM,EAAE,YAAY;CACX,CAAA"}
|
|
@@ -0,0 +1,216 @@
|
|
|
1
|
+
import type { LogContext, LogLevel, LogMetadata, Runtime, SerializedError } from '../types';
|
|
2
|
+
/**
|
|
3
|
+
* Status of a wide event after completion
|
|
4
|
+
*/
|
|
5
|
+
export type WideEventStatus = 'success' | 'error' | 'timeout' | 'cancelled';
|
|
6
|
+
/**
|
|
7
|
+
* A comprehensive event representing a complete unit of work.
|
|
8
|
+
*
|
|
9
|
+
* Wide events (also called Canonical Log Lines) capture all context
|
|
10
|
+
* about a request/operation in a single structured event, making
|
|
11
|
+
* debugging and observability significantly easier.
|
|
12
|
+
*/
|
|
13
|
+
export interface WideEvent {
|
|
14
|
+
/** ISO 8601 timestamp when the event started */
|
|
15
|
+
started_at: string;
|
|
16
|
+
/** ISO 8601 timestamp when the event ended */
|
|
17
|
+
ended_at: string;
|
|
18
|
+
/** Duration in milliseconds */
|
|
19
|
+
duration_ms: number;
|
|
20
|
+
/** Event type identifier (e.g., 'http.request', 'job.execute') */
|
|
21
|
+
event_type: string;
|
|
22
|
+
/** Event status after completion */
|
|
23
|
+
status: WideEventStatus;
|
|
24
|
+
/** Correlation context from parent logger/span */
|
|
25
|
+
context: WideEventContext;
|
|
26
|
+
/** Runtime environment where the event occurred */
|
|
27
|
+
runtime: Runtime;
|
|
28
|
+
/** All accumulated fields organized by category */
|
|
29
|
+
fields: WideEventFields;
|
|
30
|
+
/** Error information if status is 'error' */
|
|
31
|
+
error?: SerializedError;
|
|
32
|
+
/** Log level used when emitting (default: 'info', 'error' if failed) */
|
|
33
|
+
level: LogLevel;
|
|
34
|
+
}
|
|
35
|
+
/**
|
|
36
|
+
* Context for correlation and tracing
|
|
37
|
+
*/
|
|
38
|
+
export interface WideEventContext extends LogContext {
|
|
39
|
+
/** Request/operation identifier */
|
|
40
|
+
requestId?: string;
|
|
41
|
+
/** Distributed trace identifier */
|
|
42
|
+
traceId?: string;
|
|
43
|
+
/** Current span identifier */
|
|
44
|
+
spanId?: string;
|
|
45
|
+
/** Parent span identifier */
|
|
46
|
+
parentSpanId?: string;
|
|
47
|
+
/** User identifier */
|
|
48
|
+
userId?: string;
|
|
49
|
+
/** Session identifier */
|
|
50
|
+
sessionId?: string;
|
|
51
|
+
}
|
|
52
|
+
/**
|
|
53
|
+
* Accumulated fields organized by category.
|
|
54
|
+
*
|
|
55
|
+
* Categories allow structured organization while keeping
|
|
56
|
+
* the event queryable. Common categories:
|
|
57
|
+
* - http: HTTP request/response details
|
|
58
|
+
* - user: User context (id, subscription, etc.)
|
|
59
|
+
* - error: Error details beyond SerializedError
|
|
60
|
+
* - performance: Timing and metrics
|
|
61
|
+
* - custom: Application-specific fields
|
|
62
|
+
*/
|
|
63
|
+
export type WideEventFields = Record<string, Record<string, unknown>>;
|
|
64
|
+
/**
|
|
65
|
+
* Configuration for creating a wide event
|
|
66
|
+
*/
|
|
67
|
+
export interface WideEventConfig {
|
|
68
|
+
/** Event type identifier (e.g., 'http.request') */
|
|
69
|
+
type: string;
|
|
70
|
+
/** Initial context (requestId, traceId, etc.) */
|
|
71
|
+
context?: Partial<WideEventContext>;
|
|
72
|
+
/** Initial fields to set */
|
|
73
|
+
fields?: WideEventFields;
|
|
74
|
+
}
|
|
75
|
+
/**
|
|
76
|
+
* Options for ending a wide event
|
|
77
|
+
*/
|
|
78
|
+
export interface WideEventEndOptions {
|
|
79
|
+
/** Override the status (default: inferred from error presence) */
|
|
80
|
+
status?: WideEventStatus;
|
|
81
|
+
/** Error to attach */
|
|
82
|
+
error?: Error | SerializedError;
|
|
83
|
+
/** Additional fields to merge before emission */
|
|
84
|
+
fields?: WideEventFields;
|
|
85
|
+
/** Override log level (default: 'info', or 'error' if failed) */
|
|
86
|
+
level?: LogLevel;
|
|
87
|
+
}
|
|
88
|
+
/**
|
|
89
|
+
* Builder interface for accumulating wide event context.
|
|
90
|
+
*
|
|
91
|
+
* The builder pattern allows enriching the event throughout
|
|
92
|
+
* the request lifecycle, then emitting once at the end.
|
|
93
|
+
*
|
|
94
|
+
* @example
|
|
95
|
+
* ```typescript
|
|
96
|
+
* const event = createWideEvent({ type: 'http.request' });
|
|
97
|
+
*
|
|
98
|
+
* // Enrich with HTTP context
|
|
99
|
+
* event.set('http', 'method', 'POST');
|
|
100
|
+
* event.set('http', 'path', '/api/checkout');
|
|
101
|
+
*
|
|
102
|
+
* // Enrich with user context
|
|
103
|
+
* event.set('user', 'id', userId);
|
|
104
|
+
* event.set('user', 'subscription', 'premium');
|
|
105
|
+
*
|
|
106
|
+
* // End and emit
|
|
107
|
+
* event.end({ status: 'success' });
|
|
108
|
+
* ```
|
|
109
|
+
*/
|
|
110
|
+
export interface WideEventBuilder {
|
|
111
|
+
/** Event type identifier */
|
|
112
|
+
readonly type: string;
|
|
113
|
+
/** Start time in milliseconds (performance.now or Date.now) */
|
|
114
|
+
readonly startTime: number;
|
|
115
|
+
/** Whether the event has been ended/emitted */
|
|
116
|
+
readonly ended: boolean;
|
|
117
|
+
/**
|
|
118
|
+
* Set a single field value within a category.
|
|
119
|
+
*
|
|
120
|
+
* @param category - Field category (e.g., 'http', 'user', 'performance')
|
|
121
|
+
* @param key - Field key within the category
|
|
122
|
+
* @param value - Field value
|
|
123
|
+
* @returns this for chaining
|
|
124
|
+
*/
|
|
125
|
+
set(category: string, key: string, value: unknown): this;
|
|
126
|
+
/**
|
|
127
|
+
* Get a field value from a category.
|
|
128
|
+
*
|
|
129
|
+
* @param category - Field category
|
|
130
|
+
* @param key - Field key within the category
|
|
131
|
+
* @returns The field value or undefined
|
|
132
|
+
*/
|
|
133
|
+
get(category: string, key: string): unknown;
|
|
134
|
+
/**
|
|
135
|
+
* Merge multiple fields into a category.
|
|
136
|
+
*
|
|
137
|
+
* @param category - Field category
|
|
138
|
+
* @param fields - Fields to merge
|
|
139
|
+
* @returns this for chaining
|
|
140
|
+
*/
|
|
141
|
+
merge(category: string, fields: Record<string, unknown>): this;
|
|
142
|
+
/**
|
|
143
|
+
* Merge entire categories at once.
|
|
144
|
+
*
|
|
145
|
+
* @param fields - Categories with their fields
|
|
146
|
+
* @returns this for chaining
|
|
147
|
+
*/
|
|
148
|
+
mergeAll(fields: WideEventFields): this;
|
|
149
|
+
/**
|
|
150
|
+
* Set the event context (requestId, traceId, etc.).
|
|
151
|
+
*
|
|
152
|
+
* @param context - Context to merge with existing
|
|
153
|
+
* @returns this for chaining
|
|
154
|
+
*/
|
|
155
|
+
setContext(context: Partial<WideEventContext>): this;
|
|
156
|
+
/**
|
|
157
|
+
* Get the current context.
|
|
158
|
+
*/
|
|
159
|
+
getContext(): WideEventContext;
|
|
160
|
+
/**
|
|
161
|
+
* Get all accumulated fields.
|
|
162
|
+
*/
|
|
163
|
+
getFields(): Readonly<WideEventFields>;
|
|
164
|
+
/**
|
|
165
|
+
* End the event and prepare it for emission.
|
|
166
|
+
*
|
|
167
|
+
* After calling end(), the builder is frozen and no
|
|
168
|
+
* further modifications are allowed.
|
|
169
|
+
*
|
|
170
|
+
* @param options - End options (status, error, final fields)
|
|
171
|
+
* @returns The completed WideEvent
|
|
172
|
+
*/
|
|
173
|
+
end(options?: WideEventEndOptions): WideEvent;
|
|
174
|
+
/**
|
|
175
|
+
* Convert to a flattened metadata object for traditional logging.
|
|
176
|
+
*
|
|
177
|
+
* Useful for emitting through existing logger.info() calls.
|
|
178
|
+
* Keys are flattened as 'category.key' format.
|
|
179
|
+
*/
|
|
180
|
+
toMetadata(): LogMetadata;
|
|
181
|
+
}
|
|
182
|
+
/**
|
|
183
|
+
* Configuration for tail-based sampling of wide events.
|
|
184
|
+
*
|
|
185
|
+
* Tail sampling makes the decision AFTER the event completes,
|
|
186
|
+
* allowing 100% retention of errors while sampling success.
|
|
187
|
+
*/
|
|
188
|
+
export interface TailSamplingConfig {
|
|
189
|
+
/** Enable tail sampling (default: true) */
|
|
190
|
+
enabled?: boolean;
|
|
191
|
+
/**
|
|
192
|
+
* Always keep events with these statuses (default: ['error'])
|
|
193
|
+
*/
|
|
194
|
+
alwaysKeepStatuses?: WideEventStatus[];
|
|
195
|
+
/**
|
|
196
|
+
* Always keep events above this duration in ms (default: undefined - disabled)
|
|
197
|
+
*/
|
|
198
|
+
slowThresholdMs?: number;
|
|
199
|
+
/**
|
|
200
|
+
* Sampling rate for successful events (0-1, default: 1.0 - keep all)
|
|
201
|
+
*/
|
|
202
|
+
successSampleRate?: number;
|
|
203
|
+
/**
|
|
204
|
+
* VIP user IDs that always get 100% sampling
|
|
205
|
+
*/
|
|
206
|
+
vipUserIds?: string[];
|
|
207
|
+
/**
|
|
208
|
+
* VIP user subscription tiers that always get 100% sampling
|
|
209
|
+
*/
|
|
210
|
+
vipTiers?: string[];
|
|
211
|
+
/**
|
|
212
|
+
* Field path to check for tier (default: 'user.subscription')
|
|
213
|
+
*/
|
|
214
|
+
tierFieldPath?: string;
|
|
215
|
+
}
|
|
216
|
+
//# sourceMappingURL=types.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/wide-events/types.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/wide-events/types.ts"],"names":[],"mappings":""}
|
package/package.json
CHANGED