Merge pull request #147 from sguruvar/docusaurus

Docusaurus and Architecture pattern changes

.github/workflows/markdown-link-check.yaml

@@ -20,9 +20,9 @@ jobs:
       - uses: actions/checkout@v3
       - uses: actions/setup-node@v3
         with:
-          node-version: '16.x'
+          node-version: 20
       - name: install markdown-link-check
-        run: npm install -g markdown-link-check@3.10.2
+        run: npm install -g markdown-link-check@3.12.2
       - name: markdown-link-check version
         run: npm list -g markdown-link-check
       - name: Run markdown-link-check on MD files

.pre-commit-config.yaml

@@ -7,7 +7,7 @@ repos:
       - id: detect-aws-credentials
         args: ['--allow-missing-credentials']
   - repo: https://github.com/tcort/markdown-link-check
-    rev: v3.11.2
+    rev: v3.12.2
     hooks:
       - id: markdown-link-check
         args: ['-q', '-c .github/workflows/linkcheck.json']

docs/en/guides/choosing-a-tracing-agent.md

@@ -17,16 +17,18 @@ Any transaction tracing solution requires an agent and an integration into the u
 
 The SDKs included with X-Ray are part of a tightly integrated instrumentation solution offered by AWS. ADOT is part of a broader industry solution in which X-Ray is only one of many tracing solutions. You can implement end-to-end tracing in X-Ray using either approach, but it’s important to understand the differences in order to determine the most useful approach for you.
 
-!!! success
+:::info
 	We recommend instrumenting your application with the AWS Distro for OpenTelemetry if you need the following:
 
     * The ability to send traces to multiple different tracing backends without having to re-instrument your code. For example, of you wish to shift from using the X-Ray console to [Zipkin](https://zipkin.io), then only configuration of the collector would change, leaving your applicaiton code untouched.
 
     * Support for a large number of library instrumentations for each language, maintained by the OpenTelemetry community. 
+:::
 
-!!! success
+:::info
 	We recommend choosing an X-Ray SDK for instrumenting your application if you need the following:
 
     * A tightly integrated single-vendor solution.
 
     * Integration with X-Ray centralized sampling rules, including the ability to configure sampling rules from the X-Ray console and automatically use them across multiple hosts, when using Node.js, Python, Ruby, or .NET
+:::

docs/en/index.md

@@ -27,7 +27,7 @@ This site is organized into four categories:
 1. [Best practices for specific AWS tools (though these are largely fungible to other vendor products as well)](https://aws-observability.github.io/observability-best-practices/tools/cloudwatch_agent/)
 1. [Curated recipes for observability with AWS](https://aws-observability.github.io/observability-best-practices/recipes/)
 
-!!! success
+:::info
 	This site is based on real world use cases that AWS and our customers have solved for.
 
 	Observability is at the heart of modern application development, and a critical consideration when operating distributed systems, such as microservices, or complex applications with many external integrations. We consider it to be a leading indicator of a healthy workload, and we are pleased to share our experiences with you here!

docs/en/recipes/infra.md

@@ -28,7 +28,6 @@
 [alb-docs]: https://docs.aws.amazon.com/elasticloadbalancing/latest/application/load-balancer-monitoring.html
 [nlb-docs]: https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-monitoring.html
 [vpcfl]: https://docs.aws.amazon.com/vpc/latest/userguide/flow-logs.html
-[vpcf-ws]: https://amazon-es-vpc-flowlogs.workshop.aws/en/
 [eks-cp]: https://docs.aws.amazon.com/eks/latest/userguide/control-plane-logs.html
 [lambda-docs]: https://docs.aws.amazon.com/lambda/latest/operatorguide/monitoring-observability.html
 [rds]: rds.md

docs/ja/recipes/infra.md

@@ -27,7 +27,6 @@
 [alb-docs]: https://docs.aws.amazon.com/elasticloadbalancing/latest/application/load-balancer-monitoring.html
 [nlb-docs]: https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-monitoring.html 
 [vpcfl]: https://docs.aws.amazon.com/vpc/latest/userguide/flow-logs.html
-[vpcf-ws]: https://amazon-es-vpc-flowlogs.workshop.aws/en/
 [eks-cp]: https://docs.aws.amazon.com/eks/latest/userguide/control-plane-logs.html
 [lambda-docs]: https://docs.aws.amazon.com/lambda/latest/operatorguide/monitoring-observability.html
 [rds]: rds.md

docusaurus/observability-best-practices/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

docusaurus/observability-best-practices/README.md

@@ -0,0 +1,62 @@
+# Observability Best Practices
+
+## Welcome
+
+This is the source for the [AWS Observability Best Practices site](https://aws-observability.github.io/observability-best-practices/). Everyone is welcome to contribute here, not just AWS employees!
+
+## How to run/develop this site
+
+This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
+You need to install [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) as a prerequisite.
+
+### Installation
+
+```
+$ (yarn | npm ) install
+```
+
+### Local Development
+
+```
+$ yarn start [or] npm run start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```
+$ yarn build [or] npm run build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+### Deployment
+
+Using SSH with yarn:
+```
+$ USE_SSH=true yarn deploy 
+```
+
+Using SSH with npm:
+```
+$ USE_SSH=true  npm run serve
+```
+
+Not using SSH:
+
+```
+$ GIT_USER=<Your GitHub username> yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
+
+
+
+## Security
+
+See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.
+
+## License
+
+This library is licensed under the MIT-0 License. See the LICENSE file.

docusaurus/observability-best-practices/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

docusaurus/observability-best-practices/blog/2019-05-28-first-blog-post.md

@@ -0,0 +1,12 @@
+---
+slug: first-blog-post
+title: First Blog Post
+authors:
+  name: Gao Wei
+  title: Docusaurus Core Team
+  url: https://github.com/wgao19
+  image_url: https://github.com/wgao19.png
+tags: [hola, docusaurus]
+---
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

docusaurus/observability-best-practices/blog/2019-05-29-long-blog-post.md

@@ -0,0 +1,44 @@
+---
+slug: long-blog-post
+title: Long Blog Post
+authors: endi
+tags: [hello, docusaurus]
+---
+
+This is the summary of a very long blog post,
+
+Use a `<!--` `truncate` `-->` comment to limit blog post size in the list view.
+
+<!--truncate-->
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

docusaurus/observability-best-practices/blog/2021-08-26-welcome/index.md

@@ -0,0 +1,25 @@
+---
+slug: welcome
+title: Welcome
+authors: [slorber, yangshun]
+tags: [facebook, hello, docusaurus]
+---
+
+[Docusaurus blogging features](https://docusaurus.io/docs/blog) are powered by the [blog plugin](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-blog).
+
+Simply add Markdown files (or folders) to the `blog` directory.
+
+Regular blog authors can be added to `authors.yml`.
+
+The blog post date can be extracted from filenames, such as:
+
+- `2019-05-30-welcome.md`
+- `2019-05-30-welcome/index.md`
+
+A blog post folder can be convenient to co-locate blog post images:
+
+![Docusaurus Plushie](./docusaurus-plushie-banner.jpeg)
+
+The blog supports tags as well!
+
+**And if you don't want a blog**: just delete this directory, and use `blog: false` in your Docusaurus config.

docusaurus/observability-best-practices/blog/authors.yml

@@ -0,0 +1,17 @@
+endi:
+  name: Endilie Yacop Sucipto
+  title: Maintainer of Docusaurus
+  url: https://github.com/endiliey
+  image_url: https://github.com/endiliey.png
+
+yangshun:
+  name: Yangshun Tay
+  title: Front End Engineer @ Facebook
+  url: https://github.com/yangshun
+  image_url: https://github.com/yangshun.png
+
+slorber:
+  name: Sébastien Lorber
+  title: Docusaurus maintainer
+  url: https://sebastienlorber.com
+  image_url: https://github.com/slorber.png

docusaurus/observability-best-practices/blog/tags.yml

@@ -0,0 +1,16 @@
+facebook:
+  label: Facebook
+  permalink: /facebook
+  description: Facebook tag description
+hello:
+  label: Hello
+  permalink: /hello
+  description: Hello tag description
+docusaurus:
+  label: Docusaurus
+  permalink: /docusaurus
+  description: Docusaurus tag description
+hola:
+  label: Hola
+  permalink: /hola
+  description: Hola tag description

docusaurus/observability-best-practices/docs/contributors.md

@@ -0,0 +1,27 @@
+# Contributors
+
+The content on this site is maintained by Solution Architects, AWS Observability service team members and other volunteers from across the organization. Our goal is to improve the discovery of relevant best practices on how to set up and use AWS services and open source projects in the observability space.
+
+Recipes and content contributions in general so far are from the following
+people:
+
+| Authors             | Authors                     | Authors           | Authors            |
+| ------------------- | --------------------------- | ----------------- | ------------------ |
+| Alolita Sharma      | Aly Shah Imtiaz             | Helen Ashton      | Elamaran Shanmugam |
+| Dinesh Boddula      | Imaya Kumar Jagannathan     | Dieter Adant      | Eric Hsueh         |
+| Jason Derrett       | Kevin Lewin                 | Mahesh Biradar    | Michael Hausenblas |
+| Munish Dabra        | Rich McDonough              | Rob Sable         | Rodrigue Koffi     |
+| Sheetal Joshi       | Tomasz Wrzonski             | Tyler Lynch       | Vijayan Sarathy    |
+| Vikram Venkataraman | Yiming Peng                 | Arun Chandapillai | Alex Livingstone   |
+| Kiran Prakash       | Bobby Hallahan              | Toshal Dudhwala   | Franklin Aguinaldo |
+| Nirmal Mehta        | Lucas Vieira Souza da Silva | William Armiros   | Abhi Khanna        |
+| Arvind Raghunathan  | Doyita Mitra                | Rahul Popat       | Taiki Hibira       |
+| Siva Guruvareddiar  |                             |                   |                    |
+
+
+
+Note that all recipes published on this site are available via the
+[MIT-0][mit0] license, a modification to the usual MIT license
+that removes the requirement for attribution.
+
+[mit0]: https://github.com/aws/mit-0

docusaurus/observability-best-practices/docs/faq/adot.md

@@ -0,0 +1,26 @@
+# AWS Distro for Open Telemetry (ADOT) -  FAQ
+
+1. **Can I use the ADOT collector to ingest metrics into AMP?
+    **Yes, this functionality was introduced with the GA launch for metrics support in May 2022 and you can use the ADOT collector from EC2, via our EKS add-on, via our ECS side-car integration, and/or via our Lambda layers.
+1. **Can I use the ADOT collector to collect logs and ingest them into Amazon CloudWatch or Amazon OpenSearch?**
+    Not yet but we’re working on stabilizing logs upstream in OpenTelemetry and when the time comes, potentially later in 2023 or early 2024 we will support logs in ADOT, see also the [public roadmap entry](https://github.com/aws-observability/aws-otel-community/issues/11)
+1. **Where can I find resource usage and performance details on the ADOT collector?**
+    We have a [Performance Report](https://aws-observability.github.io/aws-otel-collector/benchmark/report) online that we keep up to date as we release collectors.
+1. **Is it possible to use ADOT with Apache Kafka?**
+    Yes, support to Kafka exporter and receiver was added in the ADOT collector v0.28.0. For more details, please check the [ADOT collector documentation](https://aws-otel.github.io/docs/components/kafka-receiver-exporter).
+1. **How can I configure the ADOT collector?**
+    The ADOT collector is configured using YAML configuration files that are stored locally. Besides that, it is possible to use configuration stored in other locations, like S3 buckets. All the supported mechanisms to configure the ADOT collector are described in detail in the [ADOT collector documentation](https://aws-otel.github.io/docs/components/confmap-providers).
+1. **Can I do advanced sampling in the ADOT collector?**
+    We’re working on it, please subscribe to the public [roadmap entry](https://github.com/aws-observability/aws-otel-collector/issues/1135) to keep up to date.
+1. **Any tips how to scale the ADOT collector?**
+    Yes! See the upstream OpenTelemetry docs on [Scaling the Collector](https://opentelemetry.io/docs/collector/scaling/).
+1. **I have a fleet of ADOT collectors, how can I manage them?**
+    This is an area of active development and  we expect that it will mature in 2023, see the upstream OpenTelemetry docs on [Management](https://opentelemetry.io/docs/collector/management/) for more details, specifically on the [Open Agent Management Protocol (OpAMP)](https://opentelemetry.io/docs/collector/management/#opamp).
+1. **How do you monitor the health and performance of the ADOT collector?**
+    1. [Monitoring the collector](https://github.com/open-telemetry/opentelemetry-collector/blob/main/docs/monitoring.md) - default metrics exposed on port 8080 that can be scraped by the Prometheus receiver
+    2. Using the [Node Exporter](https://prometheus.io/docs/guides/node-exporter/), running node exporter would also provide several performance and health metrics about the node, pod, and operating system the collector is running in.
+    3. [Kube-state-metrics (KSM)](https://github.com/kubernetes/kube-state-metrics), KSM can also produce interesting events about the collector.
+    4. [Prometheus `up` metric](https://github.com/open-telemetry/opentelemetry-collector/pull/2918)
+    5. A simple Grafana dashboard to get started: [https://grafana.com/grafana/dashboards/12553](.)
+1. **Product FAQ** - [https://aws.amazon.com/otel/faqs/](.)
+