Skip to content
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.

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

chore(docs): updated documentation #175

Merged
merged 3 commits into from
Jan 4, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
56 changes: 56 additions & 0 deletions .github/ISSUE_TEMPLATE/share_your_work.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
name: I Made This (showcase your work)
description: Share what you did with Powertools 💞💞. Blog post, workshops, presentation, sample apps, etc.
title: "[I Made This]: <TITLE>"
labels: ["community-content"]
body:
- type: markdown
attributes:
value: Thank you for helping spread the word out on Powertools, truly!
- type: input
id: content
attributes:
label: Link to your material
description: |
Please share the original link to your material.

*Note: Short links will be expanded when added to Powertools documentation*
validations:
required: true
- type: textarea
id: description
attributes:
label: Description
description: Describe in one paragraph what's in it for them (readers)
validations:
required: true
- type: input
id: author
attributes:
label: Preferred contact
description: What's your preferred contact? We'll list it next to this content
validations:
required: true
- type: input
id: author-social
attributes:
label: (Optional) Social Network
description: If different from preferred contact, what's your preferred contact for social interactions?
validations:
required: false
- type: textarea
id: notes
attributes:
label: (Optional) Additional notes
description: |
Any notes you might want to share with us related to this material.

*Note: These notes are explicitly to Powertools maintainers. It will not be added to the community resources page.*
validations:
required: false
- type: checkboxes
id: acknowledgment
attributes:
label: Acknowledgment
options:
- label: I understand this content may be removed from Powertools documentation if it doesn't conform with the [Code of Conduct](https://aws.github.io/code-of-conduct)
required: true
64 changes: 64 additions & 0 deletions .github/ISSUE_TEMPLATE/support_powertools.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
name: Support Lambda Powertools (become a reference)
description: Add your organization's name or logo to the Lambda Powertools documentation
title: "[Support Lambda Powertools]: <your organization name>"
labels: ["customer-reference"]
body:
- type: markdown
attributes:
value: |
Thank you for becoming a reference customer. Your support means a lot to us. It also helps new customers to know who's using it.

If you would like us to also display your organization's logo, please share a link in the `Company logo` field.
- type: input
id: organization
attributes:
label: Organization Name
description: Please share the name of your organization
placeholder: ACME
validations:
required: true
- type: input
id: name
attributes:
label: Your Name
description: Please share your name
validations:
required: true
- type: input
id: job
attributes:
label: Your current position
description: Please share your current position at your company
validations:
required: true
- type: input
id: logo
attributes:
label: (Optional) Company logo
description: Company logo you want us to display. You also allow us to resize for optimal placement in the documentation.
validations:
required: false
- type: textarea
id: use_case
attributes:
label: (Optional) Use case
description: How are you using Lambda Powertools today? *features, etc.*
validations:
required: false
- type: checkboxes
id: other_languages
attributes:
label: Also using other Lambda Powertools languages?
options:
- label: Python
required: false
- label: Java
required: false
- label: TypeScript
required: false
- type: markdown
attributes:
value: |
*By raising a Support Lambda Powertools issue, you are granting AWS permission to use your company's name (and/or logo) for the limited purpose described here. You are also confirming that you have authority to grant such permission.*

*You can opt-out at any time by commenting or reopening this issue.*
2 changes: 1 addition & 1 deletion docs/core/logging.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ Here is an example using the AWS SAM [Globals section](https://docs.aws.amazon.c
POWERTOOLS_SERVICE_NAME: powertools-dotnet-logging-sample
POWERTOOLS_LOG_LEVEL: Debug
POWERTOOLS_LOGGER_LOG_EVENT: true
POWERTOOLS_LOGGER_CASE: SnakeCase # Allowed values are: CamelCase, PascalCase and SnakeCase
POWERTOOLS_LOGGER_CASE: PascalCase # Allowed values are: CamelCase, PascalCase and SnakeCase
POWERTOOLS_LOGGER_SAMPLE_RATE: 0
```

Expand Down
44 changes: 22 additions & 22 deletions docs/core/metrics.md
Original file line number Diff line number Diff line change
Expand Up @@ -279,30 +279,30 @@ You can add high-cardinality data as part of your Metrics log with `AddMetadata`
=== "Example CloudWatch Logs excerpt"

```json hl_lines="23"
{
"SuccessfulBooking": 1.0,
"_aws": {
"Timestamp": 1592234975665,
"CloudWatchMetrics": [
{
"Namespace": "ExampleApplication",
"Dimensions": [
[
"service"
]
],
"Metrics": [
{
"Name": "SuccessfulBooking",
"Unit": "Count"
}
]
"SuccessfulBooking": 1.0,
"_aws": {
"Timestamp": 1592234975665,
"CloudWatchMetrics": [
{
"Namespace": "ExampleApplication",
"Dimensions": [
[
"service"
]
],
"Metrics": [
{
"Name": "SuccessfulBooking",
"Unit": "Count"
}
]
}
]
},
"Service": "Booking",
"BookingId": "683EEB2D-B2F3-4075-96EE-788E6E2EED45"
}
]
},
"Service": "Booking",
"BookingId": "683EEB2D-B2F3-4075-96EE-788E6E2EED45"
}
```

### Single metric with a different dimension
Expand Down
40 changes: 26 additions & 14 deletions docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,22 @@ title: AWS Lambda Powertools for .NET (developer preview)
description: AWS Lambda Powertools for .NET (developer preview)
---

<!-- markdownlint-disable MD043 MD013 -->

# AWS Lambda Powertools for .NET

AWS Lambda Powertools for .NET (which from here will be referred as Powertools) is a suite of utilities for [AWS Lambda](https://aws.amazon.com/lambda/) functions to ease adopting best practices such as tracing, structured logging, custom metrics, and more. Please note, Powertools is **optimized for .NET 6 only**.
AWS Lambda Powertools for .NET (which from here will be referred as Powertools) is a suite of utilities for [AWS Lambda](https://aws.amazon.com/lambda/) functions to ease adopting best practices such as tracing, structured logging, custom metrics, and more. Please note, **Powertools is optimized for .NET 6+**.

???+ tip
Powertools is also available for [Python](https://awslabs.github.io/aws-lambda-powertools-python/){target="_blank"}, [Java](https://awslabs.github.io/aws-lambda-powertools-java/){target="_blank"}, and [TypeScript](https://awslabs.github.io/aws-lambda-powertools-typescript/latest/){target="_blank"}.

??? hint "Support this project by becoming a reference customer or sharing your work :heart:"

You can choose to support us in three ways:

1) [**Become a reference customers**](https://github.com/awslabs/aws-lambda-powertools-dotnet/issues/new?assignees=&labels=customer-reference&template=support_powertools.yml&title=%5BSupport+Lambda+Powertools%5D%3A+%3Cyour+organization+name%3E). This gives us permission to list your company in our documentation.

The GitHub repository for this project can be found [here](https://github.com/awslabs/aws-lambda-powertools-dotnet).
2) [**Share your work**](https://github.com/awslabs/aws-lambda-powertools-dotnet/issues/new?assignees=&labels=community-content&template=share_your_work.yml&title=%5BI+Made+This%5D%3A+%3CTITLE%3E). Blog posts, video, sample projects you used Powertools!

!!! warning "Do not use this library in production"

Expand All @@ -17,7 +28,9 @@ The GitHub repository for this project can be found [here](https://github.com/aw

**Do not use this library for production workloads.**

## Available Powertools libraries
## Features

Core utilities such as Tracing, Logging, and Metrics will be available across all Lambda Powertools languages. Additional utilities are subjective to each language ecosystem and customer demand.

| Utility | Description
| ------------------------------------------------- | ---------------------------------------------------------------------------------
Expand Down Expand Up @@ -55,27 +68,26 @@ To use the SAM CLI, you need the following tools.
* .NET 6.0 (LTS) - [Install .NET 6.0](https://www.microsoft.com/net/download)
* Docker - [Install Docker community edition](https://hub.docker.com/search/?type=edition&offering=community)

### Examples
## Examples

We have provided a few examples that should you how to use the each of the core Powertools features.

* [Tracing](https://github.com/awslabs/aws-lambda-powertools-dotnet/tree/main/examples/Tracing){target="_blank"} example
* [Logging](https://github.com/awslabs/aws-lambda-powertools-dotnet/tree/main/examples/Logging/){target="_blank"} example
* [Metrics](https://github.com/awslabs/aws-lambda-powertools-dotnet/tree/main/examples/Metrics/){target="_blank"} example

## Other members of the AWS Lambda Powertools family

Not using .NET? No problem we have you covered. Here are the other members of the AWS Lambda Powertools family:

* [AWS Lambda Powertools for Python](https://github.com/awslabs/aws-lambda-powertools-python)
* [AWS Lambda Powertools for Java](https://github.com/awslabs/aws-lambda-powertools-java)
* [AWS Lambda Powertools for TypeScript](https://github.com/awslabs/aws-lambda-powertools-typescript)

## Connect

* **AWS Lambda Powertools on Discord**: `#dotnet` - **[Invite link](https://discord.gg/B8zZKbbyET){target="_blank"}**
* **Email**: [email protected]

## Credits
## Tenets

These are our core principles to guide our decision making.

* Credits for the Lambda Powertools idea go to [DAZN](https://github.com/getndazn){target="_blank"} and their [DAZN Lambda Powertools](https://github.com/getndazn/dazn-lambda-powertools/){target="_blank"}.
* **AWS Lambda only**. We optimize for AWS Lambda function environments and supported runtimes only. Utilities might work with web frameworks and non-Lambda environments, though they are not officially supported.
* **Eases the adoption of best practices**. The main priority of the utilities is to facilitate best practices adoption, as defined in the AWS Well-Architected Serverless Lens; all other functionality is optional.
* **Keep it lean**. Additional dependencies are carefully considered for security and ease of maintenance, and prevent negatively impacting startup time.
* **We strive for backwards compatibility**. New features and changes should keep backwards compatibility. If a breaking change cannot be avoided, the deprecation and migration process should be clearly defined.
* **We work backwards from the community**. We aim to strike a balance of what would work best for 80% of customers. Emerging practices are considered and discussed via Requests for Comment (RFCs)
* **Idiomatic**. Utilities follow programming language idioms and language-specific best practices.
24 changes: 22 additions & 2 deletions docs/javascript/extra.js
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,17 @@ const awsconfig = {
"aws_kinesis_firehose_stream_name": "ClickStreamKinesisFirehose-OGX7PQdrynUo",
};

const RUNTIME = "python"
const RUNTIME = "dotnet"
const BASE_ORIGIN = "awslabs.github.io"

const attachListeners = () => {
function copyToClipboard(e) {
e.preventDefault()
navigator.clipboard.writeText(e.target.textContent)
alert$.next("Copied to clipboard")
}

function enableSearchOnBlurElement() {
if (document.location.hostname != BASE_ORIGIN) return // prevent unnecessary data
/* Register handler to log search on blur */
document.addEventListener("DOMContentLoaded", function () {
recordPageView({
Expand Down Expand Up @@ -41,6 +49,18 @@ const attachListeners = () => {
};
}

function enableClipboardElements() {
let copyElements = document.querySelectorAll('.copyMe');
copyElements.forEach(element => {
element.addEventListener('click', copyToClipboard);
})
}

const attachListeners = () => {
enableSearchOnBlurElement()
enableClipboardElements()
}

const init = () => {
Analytics.addPluggable(new KinesisFirehoseProvider())
Amplify.configure(awsconfig);
Expand Down
2 changes: 1 addition & 1 deletion docs/references.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ Globals:
POWERTOOLS_SERVICE_NAME: powertools-dotnet-logging-sample
POWERTOOLS_LOG_LEVEL: Debug
POWERTOOLS_LOGGER_LOG_EVENT: true
POWERTOOLS_LOGGER_CASE: SnakeCase # Allowed values are: CamelCase, PascalCase and SnakeCase
POWERTOOLS_LOGGER_CASE: PascalCase # Allowed values are: CamelCase, PascalCase and SnakeCase
POWERTOOLS_LOGGER_SAMPLE_RATE: 0

```
Expand Down
24 changes: 24 additions & 0 deletions docs/we_made_this.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
---
title: We Made This (Community)
description: Blog posts, tutorials, and videos about AWS Lambda Powertools created by the Powertools Community.
---

<!-- markdownlint-disable MD001 MD043 -->

This space is dedicated to highlight our awesome community content featuring Powertools 🙏!

!!! info "[Get your content featured here](https://github.com/awslabs/aws-lambda-powertools-python/issues/new?assignees=&labels=community-content&template=share_your_work.yml&title=%5BI+Made+This%5D%3A+%3CTITLE%3E){target="_blank"}!"

## Connect

[![Join our Discord](https://dcbadge.vercel.app/api/server/B8zZKbbyET)](https://discord.gg/B8zZKbbyET){target="_blank"}

Join us on [Discord](https://discord.gg/B8zZKbbyET){target="_blank"} to connect with the Powertools community 👋. Ask questions, learn from each other, contribute, hang out with key contributors, and more!

<!-- ## Blog posts

## Videos

## Workshops

## Sample projects -->
5 changes: 4 additions & 1 deletion mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -6,18 +6,20 @@ edit_uri: edit/develop/docs

nav:
- Homepage: index.md
- Our tenets: tenets.md
- References: references.md
- Changelog: changelog.md
- Roadmap: roadmap.md
- API Reference: api/" target="_blank
- We Made This (Community): we_made_this.md
- Core utilities:
- core/logging.md
- core/metrics.md
- core/tracing.md

theme:
name: material
font:
text: Ubuntu
palette:
- scheme: default
primary: blue
Expand All @@ -32,6 +34,7 @@ theme:
icon: material/toggle-switch
name: Switch to light mode
features:
- header.autohide
- navigation.sections
- navigation.expand
- navigation.top
Expand Down
Loading