Skip to content

Commit c37932d

Browse files
ConnorKirkConnorKirk
authored
docs: update environment variable tables for utilities (#1153)
* chore(docs): update environment variable table * Correct the default value for the POWERTOOLS_METRICS_NAMESPACE env var * Refer reader to utility page for further info on env vars * chore(docs): add default, allowed and example values to utility docs * Extract default and allowed values from description to their own cols * Add allowed values, example and default columns * Correct default value for metrics namespace * refactor: set default service name in utility class Previously the Metric and Tracer classes did not set a service name if one was not provided. There was no default service name. This commit sets a default service name in the Utility class, and updates the Tracer, Metric and Logger classes to use it. * test: fix Logger tests Add missing `defaultServiceName` property to expected Logger object Correct typo in test names * test(tracer): remove invalid test Remove a test that is no longer valid. As there is a default service name, the tracer should not be enabled even if there is a service name Update the `addServiceAnnotation` function to remove redundant check * docs(metrics): correct default value * test(metrics): update metric tests to account for default service dim The `service_name` is now set by default. This means it is always present in metric dimensions. This commit updates the tests to account for this change * test(tracer): add test for default service name * test(utility): add test for new method Add test for getDefaultServiceName method * test(utility): fix getdefaultservicename test * refactor: extract isvalidservicename method to utility class This commit extracts the isValidServiceName method from the Tracer class to the Utility class. * test(utility): fix test description * refactor: change utility class methods from public to protected * test(utility): refactor tests to allow for protected methods * docs(index): remove quotation marks from default values * test(metrics): add comments to explain magic numbers * doc(tracer): add explanation for definite assignment assertion operator * test(tracer): refactor test to match project norms
1 parent 664c4da commit c37932d

File tree

13 files changed

+128
-59
lines changed

13 files changed

+128
-59
lines changed

‎docs/core/logger.md

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -52,12 +52,12 @@ The library requires two settings. You can set them as environment variables, or
5252

5353
These settings will be used across all logs emitted:
5454

55-
| Setting | Description | Environment variable | Constructor parameter |
56-
|-------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------|-----------------------|
57-
| **Service name** | Sets the name of service of which the Lambda function is part of, that will be present across all log statements | `POWERTOOLS_SERVICE_NAME` | `serviceName` |
58-
| **Logging level** | Sets how verbose Logger should be (INFO, by default). Supported values are: `DEBUG`, `INFO`, `WARN`, `ERROR` | `LOG_LEVEL` | `logLevel` |
59-
| **Log incoming event** | Whether to log or not the incoming event when using the decorator or middleware. Supported values are: `true`, or `false`, disabled by default | `POWERTOOLS_LOGGER_LOG_EVENT` | `logEvent` |
60-
| **Debug log sampling** | Probability that a Lambda invocation will print all the log items regardless of the log level setting. Supported values range from `0.0` to `1` | `POWERTOOLS_LOGGER_SAMPLE_RATE` | `sampleRateValue` |
55+
| Setting | Description | Environment variable | Default Value | Allowed Values | Example Value | Constructor parameter |
56+
|-------------------------|------------------------------------------------------------------------------------------------------------------|---------------------------------|---------------------|--------------------------------|--------------------|-----------------------|
57+
| **Service name** | Sets the name of service of which the Lambda function is part of, that will be present across all log statements | `POWERTOOLS_SERVICE_NAME` | `service_undefined` | Any string | `serverlessAirline`| `serviceName` |
58+
| **Logging level** | Sets how verbose Logger should be | `LOG_LEVEL` | `info` |`DEBUG`, `INFO`, `WARN`, `ERROR`| `ERROR` | `logLevel` |
59+
| **Log incoming event** | Whether to log or not the incoming event when using the decorator or middleware. | `POWERTOOLS_LOGGER_LOG_EVENT` | `false` | `true`, `false` | `false` | `logEvent` |
60+
| **Debug log sampling** | Probability that a Lambda invocation will print all the log items regardless of the log level setting. | `POWERTOOLS_LOGGER_SAMPLE_RATE` | `0` | `0.0` to `1` | `0.5` | `sampleRateValue` |
6161

6262
#### Example using AWS Serverless Application Model (SAM)
6363

‎docs/core/metrics.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -66,10 +66,10 @@ The library requires two settings. You can set them as environment variables, or
6666

6767
These settings will be used across all metrics emitted:
6868

69-
| Setting | Description | Environment variable | Constructor parameter |
70-
|----------------------|---------------------------------------------------------------------------------|--------------------------------|-----------------------|
71-
| **Service** | Optionally, sets **service** metric dimension across all metrics e.g. `payment` | `POWERTOOLS_SERVICE_NAME` | `serviceName` |
72-
| **Metric namespace** | Logical container where all metrics will be placed e.g. `serverlessAirline` | `POWERTOOLS_METRICS_NAMESPACE` | `namespace` |
69+
| Setting | Description | Environment variable | Default | Allowed Values | Example | Constructor parameter |
70+
|----------------------|-----------------------------------------------------------------|-------------------------------|--------------------|----------------|--------------------|-----------------------|
71+
| **Service** | Optionally, sets **service** metric dimension across all metrics| `POWERTOOLS_SERVICE_NAME` | `service_undefined`| Any string | `serverlessAirline`| `serviceName` |
72+
| **Metric namespace** | Logical container where all metrics will be placed | `POWERTOOLS_METRICS_NAMESPACE`| `default_namespace`| Any string | `serverlessAirline`| `default_namespace` |
7373

7474
!!! tip
7575
Use your application name or main service as the metric namespace to easily group all metrics

‎docs/core/tracer.md

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -50,13 +50,13 @@ The `Tracer` utility must always be instantiated outside of the Lambda handler.
5050

5151
The library has three optional settings. You can set them as environment variables, or pass them in the constructor:
5252

53-
| Setting | Description | Environment variable | Constructor parameter |
54-
|----------------------------|-----------------------------------------------------------------------------------------------------------------| -------------------------------------------|------------------------|
55-
| **Service name** | Sets an annotation with the **name of the service** across all traces e.g. `serverlessAirline` | `POWERTOOLS_SERVICE_NAME` | `serviceName` |
56-
| **Tracing enabled** | Enables or disables tracing. By default tracing is enabled when running in AWS Lambda | `POWERTOOLS_TRACE_ENABLED` | `enabled` |
57-
| **Capture HTTPs Requests** | Defines whether HTTPs requests will be traced or not, enabled by default when tracing is also enabled | `POWERTOOLS_TRACER_CAPTURE_HTTPS_REQUESTS` | `captureHTTPsRequests` |
58-
| **Capture Response** | Defines whether functions responses are serialized as metadata, enabled by default when tracing is also enabled | `POWERTOOLS_TRACER_CAPTURE_RESPONSE` | `captureResult` |
59-
| **Capture Errors** | Defines whether functions errors are serialized as metadata, enabled by default when tracing is also enabled | `POWERTOOLS_TRACER_CAPTURE_ERROR` | N/A |
53+
| Setting | Description | Environment variable | Default | Allowed Values | Example | Constructor parameter |
54+
|----------------------------|-----------------------------------------------------------------------| -------------------------------------------|--------------------|------------------|--------------------|------------------------|
55+
| **Service name** | Sets an annotation with the **name of the service** across all traces | `POWERTOOLS_SERVICE_NAME` | `service_undefined`| Any string | `serverlessAirline`| `serviceName` |
56+
| **Tracing enabled** | Enables or disables tracing. | `POWERTOOLS_TRACE_ENABLED` | `true `| `true` or `false`| `false` | `enabled` |
57+
| **Capture HTTPs Requests** | Defines whether HTTPs requests will be traced or not | `POWERTOOLS_TRACER_CAPTURE_HTTPS_REQUESTS` | `true` | `true` or `false`| `false` | `captureHTTPsRequests` |
58+
| **Capture Response** | Defines whether functions responses are serialized as metadata | `POWERTOOLS_TRACER_CAPTURE_RESPONSE` | `true` | `true` or `false`| `false` | `captureResult` |
59+
| **Capture Errors** | Defines whether functions errors are serialized as metadata | `POWERTOOLS_TRACER_CAPTURE_ERROR` | `true` | `true` or `false`| `false` | N/A |
6060

6161
!!! note
6262
Before your use this utility, your AWS Lambda function must have [Active Tracing enabled](https://docs.aws.amazon.com/lambda/latest/dg/services-xray.html) as well as [have permissions](https://docs.aws.amazon.com/lambda/latest/dg/services-xray.html#services-xray-permissions) to send traces to AWS X-Ray

‎docs/index.md

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -285,8 +285,8 @@ Core utilities such as Tracing, Logging, and Metrics will be available across al
285285

286286
| Environment variable | Description | Utility | Default |
287287
|----------------------------------------------|----------------------------------------------------------------------------------------|---------------------------|-----------------------|
288-
| **POWERTOOLS_SERVICE_NAME** | Sets service name used for tracing namespace, metrics dimension and structured logging | All | `"service_undefined"` |
289-
| **POWERTOOLS_METRICS_NAMESPACE** | Sets namespace used for metrics | [Metrics](./core/metrics) | `None` |
288+
| **POWERTOOLS_SERVICE_NAME** | Sets service name used for tracing namespace, metrics dimension and structured logging | All | `service_undefined` |
289+
| **POWERTOOLS_METRICS_NAMESPACE** | Sets namespace used for metrics | [Metrics](./core/metrics) | `default_namespace` |
290290
| **POWERTOOLS_TRACE_ENABLED** | Explicitly disables tracing | [Tracer](./core/tracer) | `true` |
291291
| **POWERTOOLS_TRACER_CAPTURE_RESPONSE** | Captures Lambda or method return as metadata. | [Tracer](./core/tracer) | `true` |
292292
| **POWERTOOLS_TRACER_CAPTURE_ERROR** | Captures Lambda or method exception as metadata. | [Tracer](./core/tracer) | `true` |
@@ -296,6 +296,8 @@ Core utilities such as Tracing, Logging, and Metrics will be available across al
296296
| **POWERTOOLS_DEV** | Increase JSON indentation to ease debugging when running functions locally or in a non-production environment | [Logger](./core/logger) | `false` |
297297
| **LOG_LEVEL** | Sets logging level | [Logger](./core/logger) | `INFO` |
298298

299+
Each Utility page provides information on example values and allowed values
300+
299301
## Tenets
300302

301303
These are our core principles to guide our decision making.

‎packages/commons/src/Utility.ts

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -56,8 +56,8 @@
5656
* ```
5757
*/
5858
export class Utility {
59-
6059
private coldStart: boolean = true;
60+
private readonly defaultServiceName: string = 'service_undefined';
6161

6262
public getColdStart(): boolean {
6363
if (this.coldStart) {
@@ -73,4 +73,17 @@ export class Utility {
7373
return this.getColdStart();
7474
}
7575

76+
protected getDefaultServiceName(): string {
77+
return this.defaultServiceName;
78+
}
79+
80+
/**
81+
* Validate that the service name provided is valid.
82+
* Used internally during initialization.
83+
*
84+
* @param serviceName - Service name to validate
85+
*/
86+
protected isValidServiceName(serviceName?: string): boolean {
87+
return typeof serviceName === 'string' && serviceName.trim().length > 0;
88+
}
7689
}

‎packages/commons/tests/unit/Utility.test.ts

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,24 @@ describe('Class: Utility', () => {
1212
jest.resetModules();
1313
});
1414

15+
describe('Method: getDefaultServiceName', ()=> {
16+
test('it should return the default service name', ()=> {
17+
class PowerTool extends Utility {
18+
public constructor() {
19+
super();
20+
}
21+
22+
public dummyMethod(): string {
23+
return this.getDefaultServiceName();
24+
}
25+
}
26+
27+
const powertool = new PowerTool();
28+
const result = powertool.dummyMethod();
29+
expect(result).toBe('service_undefined');
30+
});
31+
});
32+
1533
describe('Method: getColdStart', () => {
1634

1735
test('when called multiple times on the parent class, it returns true the first time, then false afterwards', () => {
@@ -142,4 +160,31 @@ describe('Class: Utility', () => {
142160

143161
});
144162

163+
describe('Method: isValidServiceName', () => {
164+
class PowerTool extends Utility {
165+
public constructor() {
166+
super();
167+
}
168+
169+
public dummyMethod(name:string): boolean {
170+
return this.isValidServiceName(name);
171+
}
172+
}
173+
test('it should allow valid strings', ()=> {
174+
const powertool = new PowerTool();
175+
const goodName = 'serverlessAirline';
176+
177+
const result = powertool.dummyMethod(goodName);
178+
179+
expect(result).toBe(true);
180+
});
181+
182+
test('it should not allow empty strings', ()=> {
183+
const tooShort = '';
184+
const powertool = new PowerTool();
185+
const result = powertool.dummyMethod(tooShort);
186+
187+
expect(result).toBe(false);
188+
});
189+
});
145190
});

‎packages/logger/src/Logger.ts

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -119,8 +119,6 @@ class Logger extends Utility implements ClassThatLogs {
119119

120120
private static readonly defaultLogLevel: LogLevel = 'INFO';
121121

122-
private static readonly defaultServiceName: string = 'service_undefined';
123-
124122
// envVarsService is always initialized in the constructor in setOptions()
125123
private envVarsService!: EnvironmentVariablesService;
126124

@@ -803,7 +801,7 @@ class Logger extends Utility implements ClassThatLogs {
803801
this.getEnvVarsService().getCurrentEnvironment(),
804802
sampleRateValue: this.getSampleRateValue(),
805803
serviceName:
806-
serviceName || this.getCustomConfigService()?.getServiceName() || this.getEnvVarsService().getServiceName() || Logger.defaultServiceName,
804+
serviceName || this.getCustomConfigService()?.getServiceName() || this.getEnvVarsService().getServiceName() || this.getDefaultServiceName(),
807805
},
808806
persistentLogAttributes,
809807
);

‎packages/logger/tests/unit/Logger.test.ts

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -566,6 +566,7 @@ describe('Class: Logger', () => {
566566
console: expect.any(Console),
567567
coldStart: false, // This is now false because the `coldStart` attribute has been already accessed once by the `addContext` method
568568
customConfigService: undefined,
569+
defaultServiceName: 'service_undefined',
569570
envVarsService: expect.any(EnvironmentVariablesService),
570571
logEvent: false,
571572
logIndentation: 0,
@@ -1265,6 +1266,7 @@ describe('Class: Logger', () => {
12651266
console: expect.any(Console),
12661267
coldStart: true,
12671268
customConfigService: undefined,
1269+
defaultServiceName: 'service_undefined',
12681270
envVarsService: expect.any(EnvironmentVariablesService),
12691271
logEvent: false,
12701272
logIndentation: 0,
@@ -1290,6 +1292,7 @@ describe('Class: Logger', () => {
12901292
console: expect.any(Console),
12911293
coldStart: true,
12921294
customConfigService: undefined,
1295+
defaultServiceName: 'service_undefined',
12931296
envVarsService: expect.any(EnvironmentVariablesService),
12941297
logEvent: false,
12951298
logIndentation: 0,
@@ -1317,6 +1320,7 @@ describe('Class: Logger', () => {
13171320
console: expect.any(Console),
13181321
coldStart: true,
13191322
customConfigService: undefined,
1323+
defaultServiceName: 'service_undefined',
13201324
envVarsService: expect.any(EnvironmentVariablesService),
13211325
logEvent: false,
13221326
logIndentation: 0,
@@ -1342,6 +1346,7 @@ describe('Class: Logger', () => {
13421346
console: expect.any(Console),
13431347
coldStart: true,
13441348
customConfigService: undefined,
1349+
defaultServiceName: 'service_undefined',
13451350
envVarsService: expect.any(EnvironmentVariablesService),
13461351
logEvent: false,
13471352
logIndentation: 0,

0 commit comments

Comments
 (0)