1 | /**
|
2 | * Copyright 2018, OpenCensus Authors
|
3 | *
|
4 | * Licensed under the Apache License, Version 2.0 (the "License");
|
5 | * you may not use this file except in compliance with the License.
|
6 | * You may obtain a copy of the License at
|
7 | *
|
8 | * http://www.apache.org/licenses/LICENSE-2.0
|
9 | *
|
10 | * Unless required by applicable law or agreed to in writing, software
|
11 | * distributed under the License is distributed on an "AS IS" BASIS,
|
12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
13 | * See the License for the specific language governing permissions and
|
14 | * limitations under the License.
|
15 | */
|
16 | /// <reference types="node" />
|
17 | import * as loggerTypes from '../../common/types';
|
18 | import * as configTypes from '../config/types';
|
19 | import { Propagation } from '../propagation/types';
|
20 | import * as samplerTypes from '../sampler/types';
|
21 | /** Default type for functions */
|
22 | export declare type Func<T> = (...args: any[]) => T;
|
23 | /** Maps a label to a string, number or boolean. */
|
24 | export interface Attributes {
|
25 | [attributeKey: string]: string | number | boolean;
|
26 | }
|
27 | /**
|
28 | * The status of a Span by providing a standard CanonicalCode in conjunction
|
29 | * with an optional descriptive message.
|
30 | */
|
31 | export interface Status {
|
32 | /** The canonical code of this message. */
|
33 | code: CanonicalCode;
|
34 | /** A developer-facing error message. */
|
35 | message?: string;
|
36 | }
|
37 | /** An enumeration of canonical status codes. */
|
38 | export declare enum CanonicalCode {
|
39 | /**
|
40 | * Not an error; returned on success
|
41 | */
|
42 | OK = 0,
|
43 | /**
|
44 | * The operation was cancelled (typically by the caller).
|
45 | */
|
46 | CANCELLED = 1,
|
47 | /**
|
48 | * Unknown error. An example of where this error may be returned is
|
49 | * if a status value received from another address space belongs to
|
50 | * an error-space that is not known in this address space. Also
|
51 | * errors raised by APIs that do not return enough error information
|
52 | * may be converted to this error.
|
53 | */
|
54 | UNKNOWN = 2,
|
55 | /**
|
56 | * Client specified an invalid argument. Note that this differs
|
57 | * from FAILED_PRECONDITION. INVALID_ARGUMENT indicates arguments
|
58 | * that are problematic regardless of the state of the system
|
59 | * (e.g., a malformed file name).
|
60 | */
|
61 | INVALID_ARGUMENT = 3,
|
62 | /**
|
63 | * Deadline expired before operation could complete. For operations
|
64 | * that change the state of the system, this error may be returned
|
65 | * even if the operation has completed successfully. For example, a
|
66 | * successful response from a server could have been delayed long
|
67 | * enough for the deadline to expire.
|
68 | */
|
69 | DEADLINE_EXCEEDED = 4,
|
70 | /**
|
71 | * Some requested entity (e.g., file or directory) was not found.
|
72 | */
|
73 | NOT_FOUND = 5,
|
74 | /**
|
75 | * Some entity that we attempted to create (e.g., file or directory)
|
76 | * already exists.
|
77 | */
|
78 | ALREADY_EXISTS = 6,
|
79 | /**
|
80 | * The caller does not have permission to execute the specified
|
81 | * operation. PERMISSION_DENIED must not be used for rejections
|
82 | * caused by exhausting some resource (use RESOURCE_EXHAUSTED
|
83 | * instead for those errors). PERMISSION_DENIED must not be
|
84 | * used if the caller can not be identified (use UNAUTHENTICATED
|
85 | * instead for those errors).
|
86 | */
|
87 | PERMISSION_DENIED = 7,
|
88 | /**
|
89 | * Some resource has been exhausted, perhaps a per-user quota, or
|
90 | * perhaps the entire file system is out of space.
|
91 | */
|
92 | RESOURCE_EXHAUSTED = 8,
|
93 | /**
|
94 | * Operation was rejected because the system is not in a state
|
95 | * required for the operation's execution. For example, directory
|
96 | * to be deleted may be non-empty, an rmdir operation is applied to
|
97 | * a non-directory, etc.
|
98 | *
|
99 | * A litmus test that may help a service implementor in deciding
|
100 | * between FAILED_PRECONDITION, ABORTED, and UNAVAILABLE:
|
101 | *
|
102 | * - Use UNAVAILABLE if the client can retry just the failing call.
|
103 | * - Use ABORTED if the client should retry at a higher-level
|
104 | * (e.g., restarting a read-modify-write sequence).
|
105 | * - Use FAILED_PRECONDITION if the client should not retry until
|
106 | * the system state has been explicitly fixed. E.g., if an "rmdir"
|
107 | * fails because the directory is non-empty, FAILED_PRECONDITION
|
108 | * should be returned since the client should not retry unless
|
109 | * they have first fixed up the directory by deleting files from it.
|
110 | * - Use FAILED_PRECONDITION if the client performs conditional
|
111 | * REST Get/Update/Delete on a resource and the resource on the
|
112 | * server does not match the condition. E.g., conflicting
|
113 | * read-modify-write on the same resource.
|
114 | */
|
115 | FAILED_PRECONDITION = 9,
|
116 | /**
|
117 | * The operation was aborted, typically due to a concurrency issue
|
118 | * like sequencer check failures, transaction aborts, etc.
|
119 | *
|
120 | * See litmus test above for deciding between FAILED_PRECONDITION,
|
121 | * ABORTED, and UNAVAILABLE.
|
122 | */
|
123 | ABORTED = 10,
|
124 | /**
|
125 | * Operation was attempted past the valid range. E.g., seeking or
|
126 | * reading past end of file.
|
127 | *
|
128 | * Unlike INVALID_ARGUMENT, this error indicates a problem that may
|
129 | * be fixed if the system state changes. For example, a 32-bit file
|
130 | * system will generate INVALID_ARGUMENT if asked to read at an
|
131 | * offset that is not in the range [0,2^32-1], but it will generate
|
132 | * OUT_OF_RANGE if asked to read from an offset past the current
|
133 | * file size.
|
134 | *
|
135 | * There is a fair bit of overlap between FAILED_PRECONDITION and
|
136 | * OUT_OF_RANGE. We recommend using OUT_OF_RANGE (the more specific
|
137 | * error) when it applies so that callers who are iterating through
|
138 | * a space can easily look for an OUT_OF_RANGE error to detect when
|
139 | * they are done.
|
140 | */
|
141 | OUT_OF_RANGE = 11,
|
142 | /**
|
143 | * Operation is not implemented or not supported/enabled in this service.
|
144 | */
|
145 | UNIMPLEMENTED = 12,
|
146 | /**
|
147 | * Internal errors. Means some invariants expected by underlying
|
148 | * system has been broken. If you see one of these errors,
|
149 | * something is very broken.
|
150 | */
|
151 | INTERNAL = 13,
|
152 | /**
|
153 | * The service is currently unavailable. This is a most likely a
|
154 | * transient condition and may be corrected by retrying with
|
155 | * a backoff.
|
156 | *
|
157 | * See litmus test above for deciding between FAILED_PRECONDITION,
|
158 | * ABORTED, and UNAVAILABLE.
|
159 | */
|
160 | UNAVAILABLE = 14,
|
161 | /**
|
162 | * Unrecoverable data loss or corruption.
|
163 | */
|
164 | DATA_LOSS = 15,
|
165 | /**
|
166 | * The request does not have valid authentication credentials for the
|
167 | * operation.
|
168 | */
|
169 | UNAUTHENTICATED = 16
|
170 | }
|
171 | /** A text annotation with a set of attributes. */
|
172 | export interface Annotation {
|
173 | /** A user-supplied message describing the event. */
|
174 | description: string;
|
175 | /** A timestamp for the event event. */
|
176 | timestamp: number;
|
177 | /** A set of attributes on the annotation. */
|
178 | attributes: Attributes;
|
179 | }
|
180 | /** An event describing a message sent/received between Spans. */
|
181 | export interface MessageEvent {
|
182 | /** A timestamp for the event. */
|
183 | timestamp: number;
|
184 | /** Indicates whether the message was sent or received. */
|
185 | type: MessageEventType;
|
186 | /**
|
187 | * An identifier for the MessageEvent's message that can be used to match
|
188 | * SENT and RECEIVED MessageEvents. Message event ids should start with 1 for
|
189 | * both sent and received messages and increment by 1 for each message
|
190 | * sent/received.
|
191 | */
|
192 | id: number;
|
193 | /** The number of uncompressed bytes sent or received. */
|
194 | uncompressedSize?: number;
|
195 | /**
|
196 | * The number of compressed bytes sent or received. If zero or
|
197 | * undefined, assumed to be the same size as uncompressed.
|
198 | */
|
199 | compressedSize?: number;
|
200 | }
|
201 | /**
|
202 | * A pointer from the current span to another span in the same trace or in a
|
203 | * different trace.
|
204 | */
|
205 | export interface Link {
|
206 | /** The trace ID for a trace within a project. */
|
207 | traceId: string;
|
208 | /** The span ID for a span within a trace. */
|
209 | spanId: string;
|
210 | /** The relationship of the current span relative to the linked. */
|
211 | type: LinkType;
|
212 | /** A set of attributes on the link. */
|
213 | attributes: Attributes;
|
214 | }
|
215 | /** Defines the trace options */
|
216 | export interface TraceOptions {
|
217 | /** Root span name */
|
218 | name: string;
|
219 | /** Trace context */
|
220 | spanContext?: SpanContext;
|
221 | /** Span kind */
|
222 | kind?: SpanKind;
|
223 | /** Determines the sampling rate. Ranges from 0.0 to 1.0 */
|
224 | samplingRate?: number;
|
225 | }
|
226 | /** Defines the span options */
|
227 | export interface SpanOptions {
|
228 | /** Span name */
|
229 | name: string;
|
230 | /** Span kind */
|
231 | kind?: SpanKind;
|
232 | /** The new span's parent */
|
233 | childOf?: Span;
|
234 | }
|
235 | export declare type TraceState = string;
|
236 | /** Defines the span context */
|
237 | export interface SpanContext {
|
238 | /** Trace ID */
|
239 | traceId: string;
|
240 | /** Span ID */
|
241 | spanId: string;
|
242 | /** Options */
|
243 | options?: number;
|
244 | /** TraceState */
|
245 | traceState?: TraceState;
|
246 | }
|
247 | /** Defines an end span event listener */
|
248 | export interface SpanEventListener {
|
249 | /** Happens when a span is started */
|
250 | onStartSpan(span: Span): void;
|
251 | /** Happens when a span is ended */
|
252 | onEndSpan(span: Span): void;
|
253 | }
|
254 | /** An event describing a message sent/received between Spans. */
|
255 | export declare enum MessageEventType {
|
256 | /** Unknown event type. */
|
257 | UNSPECIFIED = 0,
|
258 | /** Indicates a sent message. */
|
259 | SENT = 1,
|
260 | /** Indicates a received message. */
|
261 | RECEIVED = 2
|
262 | }
|
263 | /**
|
264 | * Type of span. Can be used to specify additional relationships between spans
|
265 | * in addition to a parent/child relationship.
|
266 | */
|
267 | export declare enum SpanKind {
|
268 | /** Unspecified */
|
269 | UNSPECIFIED = 0,
|
270 | /**
|
271 | * Indicates that the span covers server-side handling of an RPC or other
|
272 | * remote network request.
|
273 | */
|
274 | SERVER = 1,
|
275 | /**
|
276 | * Indicates that the span covers the client-side wrapper around an RPC or
|
277 | * other remote request.
|
278 | */
|
279 | CLIENT = 2
|
280 | }
|
281 | /**
|
282 | * Type of link. The relationship of the current span relative to the linked
|
283 | * span.
|
284 | */
|
285 | export declare enum LinkType {
|
286 | /**
|
287 | * The relationship of the two spans is unknown, or known but other
|
288 | * than parent-child.
|
289 | */
|
290 | UNSPECIFIED = 0,
|
291 | /** The linked span is a child of the current span. */
|
292 | CHILD_LINKED_SPAN = 1,
|
293 | /** The linked span is a parent of the current span. */
|
294 | PARENT_LINKED_SPAN = 2
|
295 | }
|
296 | /** Interface for Span */
|
297 | export interface Span {
|
298 | /** The Span ID of this span */
|
299 | readonly id: string;
|
300 | /** A tracer object, exposong the tracer makes it possible to create child
|
301 | * spans from the span instance like. span.tracer.startChildSpan()
|
302 | */
|
303 | tracer: TracerBase;
|
304 | /** If the parent span is in another process. */
|
305 | remoteParent: boolean;
|
306 | /** The span ID of this span's parent. If it's a root span, must be empty */
|
307 | parentSpanId: string;
|
308 | /** The resource name of the span */
|
309 | name: string;
|
310 | /** Kind of span. */
|
311 | kind: SpanKind;
|
312 | /** An object to log information to */
|
313 | logger: loggerTypes.Logger;
|
314 | /** A final status for this span */
|
315 | status: Status;
|
316 | /** A set of attributes, each in the format [KEY]:[VALUE] */
|
317 | attributes: Attributes;
|
318 | /** A text annotation with a set of attributes. */
|
319 | annotations: Annotation[];
|
320 | /** An event describing a message sent/received between Spans. */
|
321 | messageEvents: MessageEvent[];
|
322 | /** Pointers from the current span to another span */
|
323 | links: Link[];
|
324 | /** Recursively gets the descendant spans. */
|
325 | allDescendants(): Span[];
|
326 | /** The list of immediate child spans. */
|
327 | spans: Span[];
|
328 | /** The number of direct children */
|
329 | numberOfChildren: number;
|
330 | /** Trace id asscoiated with span. */
|
331 | readonly traceId: string;
|
332 | /** Trace state associated with span */
|
333 | readonly traceState?: TraceState;
|
334 | /** Indicates if span was started. */
|
335 | readonly started: boolean;
|
336 | /** Indicates if span was ended. */
|
337 | readonly ended: boolean;
|
338 | /**
|
339 | * Gives a timestap that indicates the span's start time in RFC3339 UTC
|
340 | * "Zulu" format.
|
341 | */
|
342 | readonly startTime: Date;
|
343 | /**
|
344 | * Gives a timestap that indicates the span's end time in RFC3339 UTC
|
345 | * "Zulu" format.
|
346 | */
|
347 | readonly endTime: Date;
|
348 | /**
|
349 | * Gives a timestap that indicates the span's duration in RFC3339 UTC
|
350 | * "Zulu" format.
|
351 | */
|
352 | readonly duration: number;
|
353 | /** Gives the TraceContext of the span. */
|
354 | readonly spanContext: SpanContext;
|
355 | /** Trace Parameters */
|
356 | activeTraceParams: configTypes.TraceParams;
|
357 | /** The number of dropped attributes. */
|
358 | droppedAttributesCount: number;
|
359 | /** The number of dropped links. */
|
360 | droppedLinksCount: number;
|
361 | /** The number of dropped annotations. */
|
362 | droppedAnnotationsCount: number;
|
363 | /** The number of dropped message events. */
|
364 | droppedMessageEventsCount: number;
|
365 | /**
|
366 | * Adds an atribute to the span.
|
367 | * @param key Describes the value added.
|
368 | * @param value The result of an operation.
|
369 | */
|
370 | addAttribute(key: string, value: string | number | boolean | object): void;
|
371 | /**
|
372 | * Adds an annotation to the span.
|
373 | * @param description Describes the event.
|
374 | * @param attributes A set of attributes on the annotation.
|
375 | * @param timestamp A timestamp for this event.
|
376 | */
|
377 | addAnnotation(description: string, attributes?: Attributes, timestamp?: number): void;
|
378 | /**
|
379 | * Adds a link to the span.
|
380 | * @param traceId The trace ID for a trace within a project.
|
381 | * @param spanId The span ID for a span within a trace.
|
382 | * @param type The relationship of the current span relative to the linked.
|
383 | * @param attributes A set of attributes on the link.
|
384 | */
|
385 | addLink(traceId: string, spanId: string, type: LinkType, attributes?: Attributes): void;
|
386 | /**
|
387 | * Adds a message event to the span.
|
388 | * @param type The type of message event.
|
389 | * @param id An identifier for the message event.
|
390 | * @param timestamp A timestamp for this event.
|
391 | * @param uncompressedSize The number of uncompressed bytes sent or received.
|
392 | * @param compressedSize The number of compressed bytes sent or received. If
|
393 | * zero or undefined, assumed to be the same size as uncompressed.
|
394 | */
|
395 | addMessageEvent(type: MessageEventType, id: number, timestamp?: number, uncompressedSize?: number, compressedSize?: number): void;
|
396 | /**
|
397 | * Sets a status to the span.
|
398 | * @param code The canonical status code.
|
399 | * @param message optional A developer-facing error message.
|
400 | */
|
401 | setStatus(code: CanonicalCode, message?: string): void;
|
402 | /** Starts a span. */
|
403 | start(): void;
|
404 | /** Ends a span and all of its children, recursively. */
|
405 | end(): void;
|
406 | /** Forces to end a span. */
|
407 | truncate(): void;
|
408 | /** Starts a new Span instance as a child of this instance */
|
409 | startChildSpan(options?: SpanOptions): Span;
|
410 | /** Returns whether a span is root or not. */
|
411 | isRootSpan(): boolean;
|
412 | }
|
413 | /** Interface for TracerBase */
|
414 | export interface TracerBase extends SpanEventListener {
|
415 | /** A sampler that will decide if the span will be sampled or not */
|
416 | sampler: samplerTypes.Sampler;
|
417 | /** A configuration for starting the tracer */
|
418 | logger: loggerTypes.Logger;
|
419 | /** A configuration object for trace parameters */
|
420 | activeTraceParams: configTypes.TraceParams;
|
421 | /** A propagation instance */
|
422 | readonly propagation: Propagation;
|
423 | /** Get the eventListeners from tracer instance */
|
424 | readonly eventListeners: SpanEventListener[];
|
425 | /** Get the active status from tracer instance */
|
426 | readonly active: boolean;
|
427 | /**
|
428 | * Start a tracer instance
|
429 | * @param config Configuration for tracer instace
|
430 | * @returns A tracer instance started
|
431 | */
|
432 | start(config: configTypes.TracerConfig): this;
|
433 | /** Stop the tracer instance */
|
434 | stop(): this;
|
435 | /**
|
436 | * Start a new RootSpan to currentRootSpan
|
437 | * @param options Options for tracer instance
|
438 | * @param fn Callback function
|
439 | * @returns The callback return
|
440 | */
|
441 | startRootSpan<T>(options: TraceOptions, fn: (root: Span) => T): T;
|
442 | /**
|
443 | * Register a OnEndSpanEventListener on the tracer instance
|
444 | * @param listener An OnEndSpanEventListener instance
|
445 | */
|
446 | registerSpanEventListener(listener: SpanEventListener): void;
|
447 | /**
|
448 | * Unregisters an end span event listener.
|
449 | * @param listener The listener to unregister.
|
450 | */
|
451 | unregisterSpanEventListener(listener: SpanEventListener): void;
|
452 | /**
|
453 | * Start a new Span instance to the currentRootSpan
|
454 | * @param [options] A TraceOptions object to start a root span.
|
455 | * @returns The new Span instance started
|
456 | */
|
457 | startChildSpan(options?: SpanOptions): Span;
|
458 | /** Sets the current root span. */
|
459 | setCurrentRootSpan(root: Span): void;
|
460 | }
|
461 | /** Interface for Tracer */
|
462 | export interface Tracer extends TracerBase {
|
463 | /** Get and set the currentRootSpan to tracer instance */
|
464 | currentRootSpan: Span;
|
465 | /** Clear the currentRootSpan from tracer instance */
|
466 | clearCurrentTrace(): void;
|
467 | /**
|
468 | * Binds the trace context to the given function.
|
469 | * This is necessary in order to create child spans correctly in functions
|
470 | * that are called asynchronously (for example, in a network response
|
471 | * handler).
|
472 | * @param fn A function to which to bind the trace context.
|
473 | */
|
474 | wrap<T>(fn: Func<T>): Func<T>;
|
475 | /**
|
476 | * Binds the trace context to the given event emitter.
|
477 | * This is necessary in order to create child spans correctly in event
|
478 | * handlers.
|
479 | * @param emitter An event emitter whose handlers should have
|
480 | * the trace context binded to them.
|
481 | */
|
482 | wrapEmitter(emitter: NodeJS.EventEmitter): void;
|
483 | }
|
484 |
|
\ | No newline at end of file |