Skip to content

Commit 60d3c27

Browse files
dreamorosidreamorosi
committed
WIP: JDoc annotation
1 parent 6f8229b commit 60d3c27

File tree

2 files changed

+248
-0
lines changed

2 files changed

+248
-0
lines changed

‎packages/tracing/src/Tracer.ts

Lines changed: 232 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,18 +27,76 @@ class Tracer implements TracerInterface {
2727
this.provider = new ProviderService();
2828
}
2929

30+
/**
31+
* Patch all AWS SDK v2 clients and create traces when your application makes calls to AWS services.
32+
*
33+
* If you want to patch a specific client use {@link captureAWSClient} and if you are using AWS SDK v3 use {@link captureAWSv3Client} instead.
34+
*
35+
* @see https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-nodejs-awssdkclients.html
36+
*
37+
* @example
38+
* ```typescript
39+
* import { Tracer } from '@aws-lambda-powertools/tracer';
40+
*
41+
* const tracer = new Tracer({ serviceName: 'my-service' });
42+
* const AWS = tracer.captureAWS(require('aws-sdk'));
43+
* ```
44+
*
45+
* @param aws - AWS SDK v2 import
46+
* @returns AWS - Instrumented AWS SDK
47+
*/
3048
public captureAWS<T>(aws: T): T {
3149
if (this.tracingEnabled === false) return aws;
3250

3351
return this.provider.captureAWS(aws);
3452
}
3553

54+
/**
55+
* Patch a specific AWS SDK v2 client and create traces when your application makes calls to that AWS service.
56+
*
57+
* If you want to patch all clients use {@link captureAWS} and if you are using AWS SDK v3 use {@link captureAWSv3Client} instead.
58+
*
59+
* @see https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-nodejs-awssdkclients.html
60+
*
61+
* @example
62+
* ```typescript
63+
* import { S3 } from "aws-sdk";
64+
* import { Tracer } from '@aws-lambda-powertools/tracer';
65+
*
66+
* const tracer = new Tracer({ serviceName: 'my-service' });
67+
* tracer.captureAWS(require('aws-sdk'));
68+
* const s3 = tracer.captureAWSClient(new S3({ apiVersion: "2006-03-01" }));
69+
* ```
70+
*
71+
* @param service - AWS SDK v2 client
72+
* @returns service - Instrumented AWS SDK v2 client
73+
*/
3674
public captureAWSClient<T>(service: T): T {
3775
if (this.tracingEnabled === false) return service;
3876

3977
return this.provider.captureAWSClient(service);
4078
}
4179

80+
/**
81+
* Patch an AWS SDK v3 client and create traces when your application makes calls to that AWS service.
82+
*
83+
* If you are using AWS SDK v2 use {@link captureAWSClient} instead.
84+
*
85+
* @see https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-nodejs-awssdkclients.html
86+
*
87+
* @example
88+
* ```typescript
89+
* import { S3Client } from "@aws-sdk/client-s3";
90+
* import { Tracer } from '@aws-lambda-powertools/tracer';
91+
*
92+
* const tracer = new Tracer({ serviceName: 'my-service' });
93+
* const client = new S3Client({});
94+
* tracer.captureAWSv3Client(client);
95+
* ```
96+
*
97+
* @param service - AWS SDK v3 client
98+
* @returns service - Instrumented AWS SDK v3 client
99+
*/
42100
public captureAWSv3Client<T>(service: T): T {
43101
if (this.tracingEnabled === false) return service;
44102

@@ -106,6 +164,28 @@ class Tracer implements TracerInterface {
106164
};
107165
}
108166

167+
/**
168+
* Get the active segment or subsegment in the current scope.
169+
*
170+
* Usually you won't need to call this method unless you are manipulating segments using the escape hatch pattern.
171+
*
172+
* @see https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-segments
173+
* @see https://awslabs.github.io/aws-lambda-powertools-typescript/latest/core/tracer/#escape-hatch-mechanism
174+
*
175+
* @example
176+
* ```typescript
177+
* import { Tracer } from '@aws-lambda-powertools/tracer';
178+
*
179+
* const tracer = new Tracer({ serviceName: 'my-service' });
180+
*
181+
* export const handler = async (_event: any, _context: any) => {
182+
* const currentSegment = tracer.getSegment();
183+
* ... // Do something with segment
184+
* }
185+
* ```
186+
*
187+
* @returns segment - The active segment or subsegment in the current scope.
188+
*/
109189
public getSegment(): Segment | Subsegment {
110190
const segment = this.provider.getSegment();
111191
if (segment === undefined) {
@@ -115,6 +195,17 @@ class Tracer implements TracerInterface {
115195
return segment;
116196
}
117197

198+
/**
199+
* Retrieve the current value of `ColdStart`.
200+
*
201+
* If Tracer has been initialized outside of the Lambda handler then the same instance
202+
* of Tracer will be reused throghout the lifecycle of that same Lambda execution environment
203+
* and this method will return `false` after the first invocation.
204+
*
205+
* @see https://docs.aws.amazon.com/lambda/latest/dg/runtimes-context.html
206+
*
207+
* @returns boolean - true if is cold start otherwise false
208+
*/
118209
public static isColdStart(): boolean {
119210
if (Tracer.coldStart === true) {
120211
Tracer.coldStart = false;
@@ -125,6 +216,25 @@ class Tracer implements TracerInterface {
125216
return false;
126217
}
127218

219+
/**
220+
* Adds annotation to existing segment or subsegment.
221+
*
222+
* @see https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-nodejs-segment.html#xray-sdk-nodejs-segment-annotations
223+
*
224+
* @example
225+
* ```typescript
226+
* import { Tracer } from '@aws-lambda-powertools/tracer';
227+
*
228+
* const tracer = new Tracer({ serviceName: 'my-service' });
229+
*
230+
* export const handler = async (_event: any, _context: any) => {
231+
* tracer.putAnnotation('PaymentStatus', "SUCCESS");
232+
* }
233+
* ```
234+
*
235+
* @param key - Annotation key
236+
* @param value - Value for annotation
237+
*/
128238
public putAnnotation(key: string, value: string | number | boolean): void {
129239
if (this.tracingEnabled === false) return;
130240

@@ -137,6 +247,27 @@ class Tracer implements TracerInterface {
137247
document?.addAnnotation(key, value);
138248
}
139249

250+
/**
251+
* Adds metadata to existing segment or subsegment.
252+
*
253+
* @see https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-nodejs-segment.html#xray-sdk-nodejs-segment-metadata
254+
*
255+
* @example
256+
* ```typescript
257+
* import { Tracer } from '@aws-lambda-powertools/tracer';
258+
*
259+
* const tracer = new Tracer({ serviceName: 'my-service' });
260+
*
261+
* export const handler = async (_event: any, _context: any) => {
262+
* const res = someLogic()
263+
* tracer.putAnnotation('PaymentResponse', res);
264+
* }
265+
* ```
266+
*
267+
* @param key - Metadata key
268+
* @param value - Value for metadata
269+
* @param timestamp - Namespace that metadata will lie under, if none is passed it will use the serviceName
270+
*/
140271
public putMetadata(key: string, value: unknown, namespace?: string | undefined): void {
141272
if (this.tracingEnabled === false) return;
142273

@@ -151,10 +282,40 @@ class Tracer implements TracerInterface {
151282
document?.addMetadata(key, value, namespace);
152283
}
153284

285+
/**
286+
* Sets the passed subsegment as the current active subsegment.
287+
*
288+
* If you are using a middleware or a decorator this is done automatically for you.
289+
*
290+
* @see https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-nodejs-subsegments.html
291+
*
292+
* @example
293+
* ```typescript
294+
* import { Tracer } from '@aws-lambda-powertools/tracer';
295+
* import { Segment } from 'aws-xray-sdk-core';
296+
*
297+
* const tracer = new Tracer({ serviceName: 'my-service' });
298+
*
299+
* export const handler = async (_event: any, _context: any) => {
300+
* const subsegment = new Subsegment('### foo.bar');
301+
* tracer.setSegment(subsegment);
302+
* }
303+
* ```
304+
*
305+
* @param segment - Subsegment to set as the current segment
306+
*/
154307
public setSegment(segment: Segment | Subsegment): void {
155308
return this.provider.setSegment(segment);
156309
}
157310

311+
/**
312+
* Add an error to the current segment or subsegment as metadata.
313+
* Used internally by decoratorators and middlewares.
314+
*
315+
* @see https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-errors
316+
*
317+
* @param error - Error to serialize as metadata
318+
*/
158319
private addErrorAsMetadata(error: Error): void {
159320
const subsegment = this.getSegment();
160321
if (this.captureError === false) {
@@ -166,6 +327,15 @@ class Tracer implements TracerInterface {
166327
subsegment.addError(error, false);
167328
}
168329

330+
/**
331+
* Add an data to the current segment or subsegment as metadata.
332+
* Used internally by decoratorators and middlewares.
333+
*
334+
* @see https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-errors
335+
*
336+
* @param data - Data to serialize as metadata
337+
* @param methodName - Name of the method that is being traced
338+
*/
169339
private addResponseAsMetadata(data?: unknown, methodName?: string): void {
170340
if (data === undefined || this.captureResponse === false || this.tracingEnabled === false) {
171341
return;
@@ -174,32 +344,62 @@ class Tracer implements TracerInterface {
174344
this.putMetadata(`${methodName} response`, data);
175345
}
176346

347+
/**
348+
* Add ColdStart annotation to the current segment or subsegment.
349+
* Used internally by decoratorators and middlewares.
350+
*/
177351
private annotateColdStart(): void {
178352
if (Tracer.isColdStart()) {
179353
this.putAnnotation('ColdStart', true);
180354
}
181355
}
182356

357+
/**
358+
* Getter for `customConfigService`.
359+
* Used internally during initialization.
360+
*/
183361
private getCustomConfigService(): ConfigServiceInterface | undefined {
184362
return this.customConfigService;
185363
}
186364

365+
/**
366+
* Getter for `envVarsService`.
367+
* Used internally during initialization.
368+
*/
187369
private getEnvVarsService(): EnvironmentVariablesService {
188370
return <EnvironmentVariablesService> this.envVarsService;
189371
}
190372

373+
/**
374+
* Determine if we are running in a Lambda execution environment.
375+
* Used internally during initialization.
376+
*/
191377
private isLambdaExecutionEnv(): boolean {
192378
return this.getEnvVarsService()?.getAwsExecutionEnv() !== '';
193379
}
194380

381+
/**
382+
* Determine if we are running inside a SAM CLI process.
383+
* Used internally during initialization.
384+
*/
195385
private isLambdaSamCli(): boolean {
196386
return this.getEnvVarsService()?.getSamLocal() !== '';
197387
}
198388

389+
/**
390+
* Validate that the service name provided is valid.
391+
* Used internally during initialization.
392+
*
393+
* @param serviceName - Service name to validate
394+
*/
199395
private isValidServiceName(serviceName?: string): boolean {
200396
return typeof serviceName === 'string' && serviceName.trim().length > 0;
201397
}
202398

399+
/**
400+
* Setter for `captureError` based on configuration passed and environment variables.
401+
* Used internally during initialization.
402+
*/
203403
private setCaptureError(): void {
204404
const customConfigValue = this.getCustomConfigService()?.getTracingCaptureError();
205405
if (customConfigValue !== undefined && customConfigValue.toLowerCase() === 'false') {
@@ -216,6 +416,10 @@ class Tracer implements TracerInterface {
216416
}
217417
}
218418

419+
/**
420+
* Setter for `captureResponse` based on configuration passed and environment variables.
421+
* Used internally during initialization.
422+
*/
219423
private setCaptureResponse(): void {
220424
const customConfigValue = this.getCustomConfigService()?.getTracingCaptureResponse();
221425
if (customConfigValue !== undefined && customConfigValue.toLowerCase() === 'false') {
@@ -232,14 +436,30 @@ class Tracer implements TracerInterface {
232436
}
233437
}
234438

439+
/**
440+
* Setter for `customConfigService` based on configuration passed.
441+
* Used internally during initialization.
442+
*
443+
* @param customConfigService - Custom configuration service to use
444+
*/
235445
private setCustomConfigService(customConfigService?: ConfigServiceInterface): void {
236446
this.customConfigService = customConfigService ? customConfigService : undefined;
237447
}
238448

449+
/**
450+
* Setter and initializer for `envVarsService`.
451+
* Used internally during initialization.
452+
*/
239453
private setEnvVarsService(): void {
240454
this.envVarsService = new EnvironmentVariablesService();
241455
}
242456

457+
/**
458+
* Method that reconciles the configuration passed with the environment variables.
459+
* Used internally during initialization.
460+
*
461+
* @param options - Configuration passed to the tracer
462+
*/
243463
private setOptions(options: TracerOptions): Tracer {
244464
const {
245465
enabled,
@@ -257,6 +477,12 @@ class Tracer implements TracerInterface {
257477
return this;
258478
}
259479

480+
/**
481+
* Setter for `customConfigService` based on configurations passed and environment variables.
482+
* Used internally during initialization.
483+
*
484+
* @param serviceName - Name of the service to use
485+
*/
260486
private setServiceName(serviceName?: string): void {
261487
if (serviceName !== undefined && this.isValidServiceName(serviceName)) {
262488
this.serviceName = serviceName;
@@ -279,6 +505,12 @@ class Tracer implements TracerInterface {
279505
}
280506
}
281507

508+
/**
509+
* Setter for `tracingEnabled` based on configurations passed and environment variables.
510+
* Used internally during initialization.
511+
*
512+
* @param enabled - Whether or not tracing is enabled
513+
*/
282514
private setTracingEnabled(enabled?: boolean): void {
283515
if (enabled !== undefined && enabled === false) {
284516
this.tracingEnabled = enabled;

‎packages/tracing/types/Tracer.ts

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,22 @@ import { ConfigServiceInterface } from '../src/config';
22
import { Handler } from 'aws-lambda';
33
import { LambdaInterface } from '../examples/utils/lambda';
44

5+
/**
6+
* Options for the tracer class to be used during initialization.
7+
*
8+
* Usage:
9+
* @example
10+
* ```typescript
11+
* const customConfigService: ConfigServiceInterface;
12+
* const tracerOptions: TracerOptions = {
13+
* enabled?: true,
14+
* serviceName?: 'my-service',
15+
* customConfigService?: customConfigService, // Only needed for advanced uses
16+
* };
17+
*
18+
* const tracer = new Tracer(tracerOptions);
19+
* ```
20+
*/
521
type TracerOptions = {
622
enabled?: boolean
723
serviceName?: string

0 commit comments

Comments
 (0)