Launching the AWS Distro for OpenTelemetry developer site with Gatsby and GraphQL

In this post, AWS intern Wilbert Guo shares his experience in building the AWS Distro for OpenTelemetry developer site using Gatsby and GraphQL. The developer site aims to provide a place where customers can find out more information about the project, as well as get involved and download the distribution.

OpenTelemetry is a popular open source project under the Cloud Native Computing (CNCF) Foundation that provides a set of APIs and SDK for robust and portable telemetry of cloud-native software. OpenTelemetry allows customers to send telemetry data to multiple different back ends (for example, Prometheus and Jaeger) and requires them to instrument their application only once. AWS X-Ray and Amazon CloudWatch teams have been working on launching support for OpenTelemetry with the new AWS Distro for OpenTelemetry, which will be Amazon’s distribution of OpenTelemetry.

AWS Distro for OpenTelemetry is built with components that are part of the OpenTelemetry project upstream. AWS Distro for OpenTelemetry allows you to collect metadata from your AWS resources and managed services so that you can correlate application performance data with underlying infrastructure data, thereby reducing the mean time to problem resolution. Additionally, the AWS Distro for OpenTelemetry lets you instrument your applications running on Amazon Elastic Compute Cloud (Amazon EC2), Amazon Elastic Container Service (ECS), Amazon Elastic Kubernetes Service (Amazon EKS) on Amazon EC2, and AWS Fargate, as well as on-premises.

Requirements for the developer site

The AWS Distro for OpenTelemetry developer site aims to provide the following:

• Project information, which allows customers to learn about the AWS Distribution for OpenTelemetry including benefits, use cases, and how it works.
• Technical documentation, which includes specific pages targeted at developers, where they can find information about downloading the distribution and getting started.
• Downloads portal, which provides a central place for customers to download different versions and components of the AWS Distro for OpenTelemetry.
• A way to stay up to date with the project through announcements, blog posts, and various social media outlets, including a Gitter channel for discussion and a GitHub community page.
• A way to get involved and join the community because this is an open source project. The website will include contributor guidelines and links for people to file issues and report bugs.

Technical evaluation

The two main technologies used for this website project are Gatsby and Jekyll.

Gatsby is a React-based, GraphQL-powered, static site generator. What makes Gatsby so special is that it uses GraphQL to query your data from wherever it may be: Markdown, JSON, CMS, third-party APIs, anywhere. During build time, an internal GraphQL server is created for all the data so that your react components can query the data from one central place using the same querying syntax (GraphQL).

Jekyll is built on top of the Ruby language and is also a static site generator. Jekyll started the web development trend toward static websites and is popular because of its adoption by GitHub. Instead of using databases, Jekyll takes the content from Markdown files and Liquid templates and produces a completely static website ready to be served by a web server. The advantage of using Jekyll is that it is the engine behind GitHub Pages, which is a feature that allows customers to host websites based on their GitHub repositories for free.

The following table shows a more detailed comparison of Gatsby vs. Jekyll:

Static content

Both Gatsby and Jekyll let you build your site using static files, which can then be deployed without the need for a server. This approach is different from web applications that require server-side scripting, which is a technique that involves having scripts on a web server to produce a response customized for each user’s request to the website.

Hosting with GitHub Pages

Both Gatsby and Jekyll sites can be hosted on GitHub Pages. However, with a Gatsby site, a few extra steps are required compared to Jekyll, where GitHub Pages will automatically turn the repository into a static site.

Hot reloading

Hot reloading means refreshing the files that were changed without losing the state of the website. This feature is very useful when developing because the UI components will update as soon as you change something in the code without needing a server restart. Fortunately, Gatsby and Jekyll both support hot reloading, which saved me a lot of time during development.

Declarative UI building

Declarative UI building uses a hierarchy system whereby properties can be declaratively passed down child trees. Gatsby uses React to keep track of each component’s state and pass data between components using props. Jekyll does not support state or passing data between UI components as it uses HTML and Liquid templating for generating the UI.

Declarative data queries

Both Jekyll and Gatsby support querying data from static files such as YAML, JSON, and Markdown; however, Gatsby also supports querying data from CMS and third-party APIs. Declarative data queries in Gatsby use GraphQL to query only the specific parts of certain data that you want.

Modern JavaScript syntax

Gatsby supports the use of JavaScript, whereas Jekyll uses Ruby. This support offers a huge advantage because JavaScript is widely used in many web stacks and works well with JSON, which is important when working with data. Because Gatsby uses JavaScript, we have the added benefit of using any NPM packages in a project that we would normally use with a Node.js application.

Design principles

Scalability

Scalability is an important principle to prioritize when starting any design for a software application, because a scalable application leads to lower maintenance in the future and a better user experience overall. For this project, I made the site scalable in terms of being able to easily extend existing features or add new ones based on the customer’s demand. I also accounted for the fact that the website will need to handle a growing amount of content and data over time.

Maintainability

Maintainability refers to the ease at which a software application can be modified or fixed to improve performance or other attributes. Key factors that affect maintainability include having code that is very easy to read and understand, having documentation and comments for further explanation, as well as having an organized project repository where other developers can easily find what they are looking for.

In addition to those principles, for this project, I also designed the site so that people without a technical background could modify and add site content. This was accomplished by having the site content generated using YAML and MDX Markdown files, which are extremely human-readable and do not require any coding experience to modify. Another key requirement for maintainability in this project is the use of open source components. This requirement allowed me to “stand on the shoulders of giants” and bring huge benefits to the website through high-quality open source software components such as Gatsby.js, which is constantly maintained and improved by a large active community of developers.

Clean design

Having a clean website design keeps focus on the value that AWS Distro for OpenTelemetry brings to customers rather than distracting from it. It’s no secret that internet users do not read every word on websites, so to maximize the number of people who see the most important content, I incorporated a lot of white space and a grid layout for different components on each page. Good UX design is just as important as good UI design, so the site features easy-to-follow site navigation along with call-to-action buttons, which improve customers’ experience on the site.

Architecture

The diagram shows the high-level architecture design of the project. We start with our project files, which include the JavaScript and React code, along with the MDX Markdown and YAML files for site content and other config files and images. These files go through Gatsby, which accepts templates and content as input and outputs static HTML and CSS files. These static files are then hosted on GitHub Pages where users can access them.

Generating site content from YAML and MDX Markdown

In this project, I used YAML to store the site content, which is injected into different pages and UI components. One reason I chose to use YAML is because it is easily human-readable; thus, people updating the site content can do so without having to write any additional code. Another reason I chose YAML is because of the flexibility it provides with defining attributes and nested items. This feature is very useful because the content for different pages is organized in a different structure with different headings and subsections. Gatsby uses a plugin called gatsby-transformer-yaml to query the data from the YAML files so that it can be used inside the UI components. You can learn more about how to source content from YAML on the Gatsby website.

For the technical documentation pages, I chose MDX Markdown, a format that allows you to use React and HTML components inside Markdown files. I chose this format because Markdown syntax is easy to learn and has built-in support for code blocks, list items, links, and other features that are often used by developers when writing technical documentation. The benefit of MDX Markdown is that you can also embed React components and HTML elements to implement syntax highlighting for code blocks or use CSS styling. In this project, I used the gatsby-plugin-mdx plugin to integrate MDX Markdown content with Gatsby. The Gatsby website offers more information about using the using MDX Markdown with Gatsby.

Using the Material UI library

Material UI is an open source project that includes out-of-the-box React components to use in your application. These components can be customized so you don’t waste time building core components from scratch; rather, you can focus your time in tuning the components to your preference. An advantage of using the Material UI library compared to using all custom styles is that there will be a consistent appearance throughout the site. Often, having consistent styling requires the use of global stylesheets; with Material UI, however, every component is self-supporting and will only inject the style it needs to display. This means you can easily modularize a different style for each component of your project, which greatly improves code maintainability.

Adding search with Elasticlunr

Search is an essential feature for discoverability in a site. For this project, I used Elasticlunr.js, a lightweight, full-text search engine in JavaScript. When using Elasticlunr search, the site content is first indexed and this data is made available through GraphQL. Then, Elasticlunr creates an elasticlunr specific search index by querying the GraphQL database. So, when a user types in a query, the search engine uses the elasticlunr search index to retrieve pages and information by their ID.

Because the site content in this project comes from YAML and MDX Markdown files, I created a title, description, and a path field in each site content file with which elasticlunr could create a search index. In my search component, I customized elasticlunr to perform partial searches so that the search results would include partial matches as well. When a customer performs a search, the results that are returned include the title of the page, a short description of the page, and a link to the page, so the user can click on it and be redirected to that specific page in the search results. You can learn more about getting started with elasticlunr search on the Gatsby webpage.

Future enhancements

More site content

As new components of the AWS Distro for OpenTelemetry are released, I will add more technical documentation pages on installation and how to get started. In addition to technical documentation, I will also improve the main content for other pages on the site as the project continues to grow.

Mailing list

In the future, I would also like to set up a mailing list for the AWS Distro for OpenTelemetry for customers who want to subscribe and receive emails about new updates and news. This feature will help customers stay involved with the project and stay updated with the latest information.

Events and meetups calendar

As the community continues to grow, I will also be implementing a calendar for events and meetups on the site. This calendar will be the central place for customers to look at any upcoming events that they might want to attend such as AWS open source conferences and AWS Distro for OpenTelemetry meetups.

Conclusion

The AWS Distro for OpenTelemetry website provides comprehensive background information, as well as technical documentation for developers to install and get started with using the distribution. As the adoption of the AWS Distribution for OpenTelemetry continues to grow, more customers will use the site to join the community, and more developers will visit the site to find out how to actively contribute to the project.

References

• Learn more about the AWS Distro for OpenTelemetry.Learn more about the OpenTelemetry project.
• Check out the website code on GitHub.
• Learn more about Gatsby.
• Learn about sourcing content from YAML in Gatsby.
• Learn about integrating MDX Markdown files with Gatsby.
• Learn about using Elasticlunr search in Gatsby.

The content and opinions in this post are those of the third-party author and AWS is not responsible for the content or accuracy of this post.