Docs: add supported values for env variables

[saragerion]

Description of the improvement

Summary of the proposal

In all sections where the supported environment variables are documented for a certain utility, it would be helpful to clarify what values are supported, the default values, and an example of a supported value.

How, where did you look for information

https://awslabs.github.io/aws-lambda-powertools-typescript/latest/#environment-variables
https://awslabs.github.io/aws-lambda-powertools-typescript/latest/core/tracer/#utility-settings
https://awslabs.github.io/aws-lambda-powertools-typescript/latest/core/logger/#utility-settings
https://awslabs.github.io/aws-lambda-powertools-typescript/latest/core/metrics/#utility-settings

Missing or unclear documentation

• Supported values
• Default values (if no value is passes)
• Example of a value

Improvement

Add these fields in each table.

Related existing documentation

https://awslabs.github.io/aws-lambda-powertools-typescript/latest/#environment-variables
https://awslabs.github.io/aws-lambda-powertools-typescript/latest/core/tracer/#utility-settings
https://awslabs.github.io/aws-lambda-powertools-typescript/latest/core/logger/#utility-settings
https://awslabs.github.io/aws-lambda-powertools-typescript/latest/core/metrics/#utility-settings

Related issues, RFCs

N/A

[ConnorKirk]

I intend to work on this. I will do some research and add my findings as a comment here before opening a PR.

[ConnorKirk]

Here's the information I've collected from the existing documentation.

Note that the existing Description column often contains an example and/or default value. I intend to extract these from the description field in the PR. This information will be included in a dedicated column (see below tables for an example)

The tables below contain a summary of the information for review and discussion. In the PR I intend to include the existing Constructor parameter column as well.

Action Plan

• Update Utility Settings table in docs/core/logger.md
• Update Utility Settings table in docs/core/metrics.md
• Update Utility Settings table in docs/core/tracer.md
• Update Environment Variables table in docs/index.md

General

• What should allowed values be for items such as service_name? The code allows any string of length greater than 0. I intend to include something like

  Allowed Values: Any string

Tracer

• I can't see where the Service name default is specified in the Tracer class. It doesn't appear to be set in Tracer.ts. This contradicts the docs, which suggest it is service_undefined

Setting	Description	Environment variable	Example	Default	Allowed Values
Service Name	Sets an annotation with the name of the service across all traces	POWERTOOLS_SERVICE_NAME	serverlessAirline	service_undefined	??
Tracing enabled	Enables or disables tracing	POWERTOOLS_TRACE_ENABLED	TRUE	TRUE	TRUE or FALSE
Capture HTTPs Requests	Defines whether HTTPs requests will be traced or not	POWERTOOLS_TRACER_CAPTURE_HTTPS_REQUESTS	TRUE	TRUE	TRUE or FALSE
Capture Response	Defines whether functions responses are serialized as metadata	POWERTOOLS_TRACER_CAPTURE_RESPONSE	TRUE	TRUE	TRUE or FALSE
Capture Errors	Defines whether functions errors are serialized as metadata	POWERTOOLS_TRACER_CAPTURE_ERROR	TRUE	TRUE	TRUE or FALSE

Metrics

• I noticed a small discrepancy between the docs and the code. The docs state the default namespace is None. The code says it is default_namespace. I intend to update the docs.
• I can't see where the Service name default is set in the Metrics class. It doesn't appear to be set in the Metrics.ts, nor in the base class Utility.js.
• The example Service Name entry is payments. Everywhere else uses serverlessAirline as an example. I intend to update it to serverlessAirline to keep it consistent with the others
• The Metric namespace example is also serverlessAirline. The docs suggest keeping both service name and metric namespace identical, so I intend to keep this as serverlessAirline

Setting	Description	Environment variable	Example	Default	Allowed Values
Service	Optionally, sets service metric dimension across all metrics	POWERTOOLS_SERVICE_NAME	serverlessAirline	service_undefined	???
Metric namespace	Logical container where all metrics will be placed	POWERTOOLS_METRICS_NAMESPACE	serverlessAirline	default_namespace	???

Logging

Setting	Description	Environment variable	Example	Default	Allowed Values
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	serverlessAirline	service_undefined	???
Logging level	Sets how verbose Logger should be	LOG_LEVEL	INFO	INFO	DEBUG, INFO, WARN, ERROR
Log incoming event	Whether to log or not the incoming event when using the decorator or middleware	POWERTOOLS_LOGGER_LOG_EVENT	FALSE	FALSE	TRUE, FALSE
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.5	0	0 to 1

[dreamorosi]

Hi Connor, thank you for the detailed proposal.

Regarding the table in docs/index.md I would be inclined towards maintaining the current format & columns present today:

and simply:

• Make sure that all values are represented & correct / up to date
• Add a note below that says something along the lines of "check on the utility page to learn about accepted values etc."

For the other tables I like your proposal, the only two remarks I have are these:

• for POWERTOOLS_LOGGER_SAMPLE_RATE, from the point of view of someone who just learned about this, is the fact that accepted values accepted are in .1 increments clear enough? Do you think it's worth saying it in the "Accepted values" column?
• all the environment values that accept true or false do actually accept a range of truthy values, i.e. y, true, yes, 1, on are all accepted as true while the opposite ones are false (n, false, no, 0, off). I don't think we should write all these values multiple times, so maybe we can say true, false* & put a remark below about all other values.
• I would use true and false (lowercase) instead of all uppercase, as it's more idiomatic in JS

Also I agree with your proposal about the service name, any non empty string is valid.

Finally, regarding your question about the default value for service name, you are right, both Tracer & Metrics don't actually set a default service name, although they should. To correct this, I would propose:

• Add to packages/commons/src/Utility a new private static readonly defaultServiceName: string = 'service_undefined'; (like Logger currently uses here)
• Remove that property from logger (since it inherits from the Utility class)
• Change the logic of Tracer.setServiceName (here) to use the newly inherited property for default value
• Remove the undefined check from Tracer.addServiceNameAnnotation (here) since the service name can no longer be undefined.
• Update the logic of Metrics.setService (here) so that it uses the newly inherited property for default value
• Extract the Tracer.isValidServiceName method (here) from Tracer and put it into Utility
• Make sure all three utilities use isValidServiceName when setting the service name to check values are valid & not empty
• Update unit tests as needed

Let me know what you think!

[github-actions]

⚠️ COMMENT VISIBILITY WARNING ⚠️

Comments on closed issues are hard for our team to see.
If you need more assistance, please either tag a team member or open a new issue that references this one.
If you wish to keep having a conversation with other community members under this issue feel free to do so.