Skip to content

docs: update environment variable tables for utilities #1153

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 18 commits into from
Nov 15, 2022
Merged

docs: update environment variable tables for utilities #1153

Show file tree
Hide file tree
Changes from 9 commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
3bd0387
chore(docs): update environment variable table
ConnorKirk Nov 10, 2022
72c8e35
chore(docs): add default, allowed and example values to utility docs
ConnorKirk Nov 10, 2022
99cce63
refactor: set default service name in utility class
ConnorKirk Nov 11, 2022
126eb4b
test: fix Logger tests
ConnorKirk Nov 11, 2022
b1c11bf
test(tracer): remove invalid test
ConnorKirk Nov 11, 2022
517f401
docs(metrics): correct default value
ConnorKirk Nov 11, 2022
6ca800c
test(metrics): update metric tests to account for default service dim
ConnorKirk Nov 14, 2022
04b2434
test(tracer): add test for default service name
ConnorKirk Nov 14, 2022
8d109c4
test(utility): add test for new method
ConnorKirk Nov 14, 2022
4837b22
test(utility): fix getdefaultservicename test
ConnorKirk Nov 14, 2022
9b0d01f
refactor: extract isvalidservicename method to utility class
ConnorKirk Nov 15, 2022
4430e1a
test(utility): fix test description
ConnorKirk Nov 15, 2022
9992629
refactor: change utility class methods from public to protected
ConnorKirk Nov 15, 2022
9082a19
test(utility): refactor tests to allow for protected methods
ConnorKirk Nov 15, 2022
8307cd9
docs(index): remove quotation marks from default values
ConnorKirk Nov 15, 2022
2bf7c48
test(metrics): add comments to explain magic numbers
ConnorKirk Nov 15, 2022
e404a29
doc(tracer): add explanation for definite assignment assertion operator
ConnorKirk Nov 15, 2022
8a20783
test(tracer): refactor test to match project norms
ConnorKirk Nov 15, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions docs/core/logger.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,12 +52,12 @@ The library requires two settings. You can set them as environment variables, or

These settings will be used across all logs emitted:

| Setting | Description | Environment variable | Constructor parameter |
|-------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------|-----------------------|
| **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` |
| **Logging level** | Sets how verbose Logger should be (INFO, by default). Supported values are: `DEBUG`, `INFO`, `WARN`, `ERROR` | `LOG_LEVEL` | `logLevel` |
| **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` |
| **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` |
| Setting | Description | Environment variable | Default Value | Allowed Values | Example Value | Constructor parameter |
|-------------------------|------------------------------------------------------------------------------------------------------------------|---------------------------------|---------------------|--------------------------------|--------------------|-----------------------|
| **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` |
| **Logging level** | Sets how verbose Logger should be | `LOG_LEVEL` | `info` |`DEBUG`, `INFO`, `WARN`, `ERROR`| `ERROR` | `logLevel` |
| **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` |
| **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` |

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

Expand Down
8 changes: 4 additions & 4 deletions docs/core/metrics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,10 +66,10 @@ The library requires two settings. You can set them as environment variables, or

These settings will be used across all metrics emitted:

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

!!! tip
Use your application name or main service as the metric namespace to easily group all metrics
Expand Down
14 changes: 7 additions & 7 deletions docs/core/tracer.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,13 +50,13 @@ The `Tracer` utility must always be instantiated outside of the Lambda handler.

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

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

!!! note
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
Expand Down
4 changes: 3 additions & 1 deletion docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -286,7 +286,7 @@ Core utilities such as Tracing, Logging, and Metrics will be available across al
| Environment variable | Description | Utility | Default |
|----------------------------------------------|----------------------------------------------------------------------------------------|---------------------------|-----------------------|
| **POWERTOOLS_SERVICE_NAME** | Sets service name used for tracing namespace, metrics dimension and structured logging | All | `"service_undefined"` |
| **POWERTOOLS_METRICS_NAMESPACE** | Sets namespace used for metrics | [Metrics](./core/metrics) | `None` |
| **POWERTOOLS_METRICS_NAMESPACE** | Sets namespace used for metrics | [Metrics](./core/metrics) | `"default_namespace"` |
| **POWERTOOLS_TRACE_ENABLED** | Explicitly disables tracing | [Tracer](./core/tracer) | `true` |
| **POWERTOOLS_TRACER_CAPTURE_RESPONSE** | Captures Lambda or method return as metadata. | [Tracer](./core/tracer) | `true` |
| **POWERTOOLS_TRACER_CAPTURE_ERROR** | Captures Lambda or method exception as metadata. | [Tracer](./core/tracer) | `true` |
Expand All @@ -295,6 +295,8 @@ Core utilities such as Tracing, Logging, and Metrics will be available across al
| **POWERTOOLS_LOGGER_SAMPLE_RATE** | Debug log sampling | [Logger](./core/logger) | `0` |
| **LOG_LEVEL** | Sets logging level | [Logger](./core/logger) | `INFO` |

Each Utility page provides information on example values and allowed values

## Tenets

These are our core principles to guide our decision making.
Expand Down
6 changes: 5 additions & 1 deletion packages/commons/src/Utility.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,8 +56,8 @@
* ```
*/
export class Utility {

private coldStart: boolean = true;
private readonly defaultServiceName: string = 'service_undefined';

public getColdStart(): boolean {
if (this.coldStart) {
Expand All @@ -69,6 +69,10 @@ export class Utility {
return false;
}

public getDefaultServiceName(): string {
return this.defaultServiceName;
}

public isColdStart(): boolean {
return this.getColdStart();
}
Expand Down
8 changes: 8 additions & 0 deletions packages/commons/tests/unit/Utility.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,14 @@ describe('Class: Utility', () => {
jest.resetModules();
});

describe('Method: getDefaultServiceName', ()=> {
test('it returns the default service name', ()=> {
const utility = new Utility();

expect(utility.getDefaultServiceName).toBe('service_undefined');
});
});

describe('Method: getColdStart', () => {

test('when called multiple times on the parent class, it returns true the first time, then false afterwards', () => {
Expand Down
4 changes: 1 addition & 3 deletions packages/logger/src/Logger.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -118,8 +118,6 @@ class Logger extends Utility implements ClassThatLogs {

private static readonly defaultLogLevel: LogLevel = 'INFO';

private static readonly defaultServiceName: string = 'service_undefined';

// envVarsService is always initialized in the constructor in setOptions()
private envVarsService!: EnvironmentVariablesService;

Expand Down Expand Up @@ -786,7 +784,7 @@ class Logger extends Utility implements ClassThatLogs {
this.getEnvVarsService().getCurrentEnvironment(),
sampleRateValue: this.getSampleRateValue(),
serviceName:
serviceName || this.getCustomConfigService()?.getServiceName() || this.getEnvVarsService().getServiceName() || Logger.defaultServiceName,
serviceName || this.getCustomConfigService()?.getServiceName() || this.getEnvVarsService().getServiceName() || this.getDefaultServiceName(),
},
persistentLogAttributes,
);
Expand Down
5 changes: 5 additions & 0 deletions packages/logger/tests/unit/Logger.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -571,6 +571,7 @@ describe('Class: Logger', () => {
console: expect.any(Console),
coldStart: false, // This is now false because the `coldStart` attribute has been already accessed once by the `addContext` method
customConfigService: undefined,
defaultServiceName: 'service_undefined',
envVarsService: expect.any(EnvironmentVariablesService),
logEvent: false,
logFormatter: expect.any(PowertoolLogFormatter),
Expand Down Expand Up @@ -1269,6 +1270,7 @@ describe('Class: Logger', () => {
console: expect.any(Console),
coldStart: true,
customConfigService: undefined,
defaultServiceName: 'service_undefined',
envVarsService: expect.any(EnvironmentVariablesService),
logEvent: false,
logFormatter: expect.any(PowertoolLogFormatter),
Expand All @@ -1293,6 +1295,7 @@ describe('Class: Logger', () => {
console: expect.any(Console),
coldStart: true,
customConfigService: undefined,
defaultServiceName: 'service_undefined',
envVarsService: expect.any(EnvironmentVariablesService),
logEvent: false,
logFormatter: expect.any(PowertoolLogFormatter),
Expand All @@ -1319,6 +1322,7 @@ describe('Class: Logger', () => {
console: expect.any(Console),
coldStart: true,
customConfigService: undefined,
defaultServiceName: 'service_undefined',
envVarsService: expect.any(EnvironmentVariablesService),
logEvent: false,
logFormatter: expect.any(PowertoolLogFormatter),
Expand All @@ -1343,6 +1347,7 @@ describe('Class: Logger', () => {
console: expect.any(Console),
coldStart: true,
customConfigService: undefined,
defaultServiceName: 'service_undefined',
envVarsService: expect.any(EnvironmentVariablesService),
logEvent: false,
logFormatter: expect.any(PowertoolLogFormatter),
Expand Down
22 changes: 13 additions & 9 deletions packages/logger/tests/unit/helpers.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,13 +46,14 @@ describe('Helper: createLogger function', () => {
},
envVarsService: expect.any(EnvironmentVariablesService),
customConfigService: undefined,
defaultServiceName: 'service_undefined',
logLevel: 'DEBUG',
logFormatter: expect.any(PowertoolLogFormatter),
}));

});

test('when no parameters are set, returns a Logger instance with the correct proprieties', () => {
test('when no parameters are set, returns a Logger instance with the correct properties', () => {

// Prepare
const loggerOptions = {
Expand All @@ -74,6 +75,7 @@ describe('Helper: createLogger function', () => {
expect(logger).toBeInstanceOf(Logger);
expect(logger).toEqual({
coldStart: true,
defaultServiceName: 'service_undefined',
customConfigService: expect.any(EnvironmentVariablesService),
envVarsService: expect.any(EnvironmentVariablesService),
logEvent: false,
Expand All @@ -100,7 +102,7 @@ describe('Helper: createLogger function', () => {

});

test('when no constructor parameters and no environment variables are set, returns a Logger instance with the default proprieties', () => {
test('when no constructor parameters and no environment variables are set, returns a Logger instance with the default properties', () => {

// Prepare
const loggerOptions = undefined;
Expand All @@ -115,6 +117,7 @@ describe('Helper: createLogger function', () => {
expect(logger).toEqual({
coldStart: true,
customConfigService: undefined,
defaultServiceName: 'service_undefined',
envVarsService: expect.any(EnvironmentVariablesService),
logEvent: false,
logFormatter: expect.any(PowertoolLogFormatter),
Expand All @@ -138,7 +141,7 @@ describe('Helper: createLogger function', () => {

});

test('when a custom logFormatter is passed, returns a Logger instance with the correct proprieties', () => {
test('when a custom logFormatter is passed, returns a Logger instance with the correct properties', () => {

// Prepare
const loggerOptions:ConstructorOptions = {
Expand Down Expand Up @@ -166,7 +169,7 @@ describe('Helper: createLogger function', () => {
}));
});

test('when a custom serviceName is passed, returns a Logger instance with the correct proprieties', () => {
test('when a custom serviceName is passed, returns a Logger instance with the correct properties', () => {

// Prepare
const loggerOptions:ConstructorOptions = {
Expand Down Expand Up @@ -194,7 +197,7 @@ describe('Helper: createLogger function', () => {
}));
});

test('when a custom logLevel is passed, returns a Logger instance with the correct proprieties', () => {
test('when a custom logLevel is passed, returns a Logger instance with the correct properties', () => {

// Prepare
const loggerOptions:ConstructorOptions = {
Expand Down Expand Up @@ -236,6 +239,7 @@ describe('Helper: createLogger function', () => {
expect(logger).toEqual({
coldStart: true,
customConfigService: undefined,
defaultServiceName: 'service_undefined',
envVarsService: expect.any(EnvironmentVariablesService),
logEvent: false,
logFormatter: expect.any(PowertoolLogFormatter),
Expand All @@ -258,7 +262,7 @@ describe('Helper: createLogger function', () => {
});
});

test('when a custom sampleRateValue is passed, returns a Logger instance with the correct proprieties', () => {
test('when a custom sampleRateValue is passed, returns a Logger instance with the correct properties', () => {

// Prepare
const loggerOptions:ConstructorOptions = {
Expand Down Expand Up @@ -286,7 +290,7 @@ describe('Helper: createLogger function', () => {
}));
});

test('when a custom customConfigService is passed, returns a Logger instance with the correct proprieties', () => {
test('when a custom customConfigService is passed, returns a Logger instance with the correct properties', () => {

const configService: ConfigServiceInterface = {
get(name: string): string {
Expand Down Expand Up @@ -335,7 +339,7 @@ describe('Helper: createLogger function', () => {
}));
});

test('when custom persistentLogAttributes is passed, returns a Logger instance with the correct proprieties', () => {
test('when custom persistentLogAttributes is passed, returns a Logger instance with the correct properties', () => {

// Prepare
const loggerOptions:ConstructorOptions = {
Expand Down Expand Up @@ -377,7 +381,7 @@ describe('Helper: createLogger function', () => {
}));
});

test('when A custom environment is passed, returns a Logger instance with the correct proprieties', () => {
test('when a custom environment is passed, returns a Logger instance with the correct properties', () => {

// Prepare
const loggerOptions:ConstructorOptions = {
Expand Down
2 changes: 1 addition & 1 deletion packages/metrics/src/Metrics.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -473,7 +473,7 @@ class Metrics extends Utility implements MetricsInterface {
private setService(service: string | undefined): void {
const targetService = (service ||
this.getCustomConfigService()?.getServiceName() ||
this.getEnvVarsService().getServiceName()) as string;
this.getEnvVarsService().getServiceName()) as string || this.getDefaultServiceName();
if (targetService.length > 0) {
this.setDefaultDimensions({ service: targetService });
}
Expand Down
Loading