Contributing to OpenTelemetry Demo Webstore

Welcome to the OpenTelemetry Demo repository! We appreciate your interest in contributing. Whether you're fixing a bug, improving documentation, or adding a new feature, we value your contribution.

Before getting started, please review the OpenTelemetry Contributor Guide for details on code attribution and best practices.

Getting Started

Join a SIG Call

We meet every other Wednesday at 8:00 PT. The schedule may change based on contributors' availability. Check the OpenTelemetry Community Calendar for specific dates and Zoom links.

Meeting notes are available here. For edit access, ask in our Slack channel.

Sign the Contributor License Agreement (CLA)

Before contributing, sign the CLA

Find a Mentor (Buddy System)

New to OpenTelemetry? We encourage you to find a mentor who can guide you through your first contribution.

Create your CNCF Slack account and join the otel-community-demo channel.
Post in the room with an introduction to yourself, what area you are interested in (check issues marked with help wanted), and say you are looking for a buddy. We will match you with someone who has experience in that area.

Your OpenTelemetry buddy is your resource to talk to directly on all aspects of contributing to OpenTelemetry: providing context, reviewing PRs, and helping those get merged. Buddies will not be available 24/7, but is committed to responding during their normal contribution hours.

Setting Up Your Development Environment

Prerequisites

Ensure you have the following installed:

Git
Make
Docker
Docker Compose v2.0.0+

Clone the Repository

git clone https://github.com/open-telemetry/opentelemetry-demo.git
cd opentelemetry-demo/

Run the Demo

make start

Verify the Webstore & Telemetry

Once the images are built and containers are started, visit:

Webstore: https://localhost:8080/
Jaeger: https://localhost:8080/jaeger/ui/
Grafana: https://localhost:8080/grafana/
Feature Flags UI: https://localhost:8080/feature/
Load Generator UI: https://localhost:8080/loadgen/

Troubleshooting Common Issues

Docker Not Running

Error: Error response from daemon: Docker daemon is not running.

Solution:

Windows/macOS: Open Docker Desktop and ensure it's running.
Linux: Check Docker status:

systemctl status docker

If inactive, start it:

sudo systemctl start docker

Gradle Issues (Windows)

If you encounter Gradle issues, run:

cd src/ad/
./gradlew installDist
./gradlew wrapper --gradle-version 7.4.2

Docker build cache issues

While developing, you may encounter issues with Docker build cache. To clear the cache:

docker system prune -a

Warning: This removes all unused Docker data, including images, containers, volumes, and networks. Use with caution.

Debugging Tips

Use docker ps to check running containers.
View logs for services:

docker logs <container_id>

Restart containers if needed:

docker-compose restart

Review the Documentation

The Demo team is committed to keeping the demo up to date. That means the documentation as well as the code. When making changes to any service or feature remember to find the related docs and update those as well. Most (but not all) documentation can be found on the OTel website under Demo docs.

Running the React Native example

If you are interested in running the React Native example app in this repo please review these instructions.

Create Your First Pull Request

How to Send Pull Requests

Everyone is welcome to contribute code to opentelemetry-demo via GitHub pull requests (PRs).

To create a new PR, fork the project in GitHub and clone the upstream repo:

Note

Please fork to a personal GitHub account rather than a corporate/enterprise one so maintainers can push commits to your branch. Pull requests from protected forks will not be accepted.

git clone https://github.com/open-telemetry/opentelemetry-demo.git

Navigate to the repo root:

cd opentelemetry-demo

Add your fork as an origin:

git remote add fork https://github.com/YOUR_GITHUB_USERNAME/opentelemetry-demo.git

Check out a new branch, make modifications and push the branch to your fork:

$ git checkout -b feature
# change files
# Test your changes locally.
$ docker compose up -d --build
# Go to Webstore, Jaeger or docker container logs etc. as appropriate to make sure your changes are working correctly.
$ git add my/changed/files
$ git commit -m "short description of the change"
$ git push fork feature

Open a pull request against the main opentelemetry-demo repo.

How to Receive Comments

If the PR is not ready for review, please mark it as draft.
Make sure CLA is signed and all required CI checks are clear.
Submit small, focused PRs addressing a single concern/issue.
Make sure the PR title reflects the contribution.
Write a summary that helps understand the change.
Include usage examples in the summary, where applicable.
Include benchmarks (before/after) in the summary, for contributions that are performance enhancements.

How to Get PRs Merged

A PR is considered to be ready to merge when:

It has received approval from Approvers / Maintainers.
Major feedbacks are resolved.
It has been open for review for at least one working day. This gives people reasonable time to review.
The documentation and Changelog have been updated to reflect the new changes.
Trivial changes (typo, cosmetic, doc, etc.) don't have to wait for one day.

Any Maintainer can merge the PR once it is ready to merge. Note, that some PRs may not be merged immediately if the repo is in the process of a release and the maintainers decided to defer the PR to the next release train.

If a PR has been stuck (e.g. there are lots of debates and people couldn't agree on each other), the owner should try to get people aligned by:

Consolidating the perspectives and putting a summary in the PR. It is recommended to add a link into the PR description, which points to a comment with a summary in the PR conversation.
Tagging subdomain experts (by looking at the change history) in the PR asking for suggestion.
Reaching out to more people on the CNCF OpenTelemetry Community Demo Slack channel.
Stepping back to see if it makes sense to narrow down the scope of the PR or split it up.
If none of the above worked and the PR has been stuck for more than 2 weeks, the owner should bring it to the OpenTelemetry Community Demo SIG meeting.

Multi-platform Builds

Creating multi-platform builds requires docker buildx to be installed. This is part of Docker Desktop for macOS, or can be installed using apt install docker-buildx on Ubuntu.

To build and load the multi-platform images locally you will need to configure docker to use containerd. This can be done in Docker Desktop settings on MacOS or Windows. Please follow these instructions to configure Docker Engine on Linux/Ubuntu.

You will need a multi-platform capable builder with a limiter set on parallelism to avoid errors while building the images. It is recommended to limit the parallelism to 4. This can be done by specifying a configuration file when creating the builder. The buildkitd.toml file in this repository can be used as the builder configuration file.

To create a multi-platform builder with a parallelism limit of 4, use the following command:

make create-multiplatform-builder

A builder will be created and set as the active builder. You can check the builder status with docker buildx inspect. To build multi-platform images for linux/amd64 and linux/arm64, use the following command:

make build-multiplatform

To build and push multi-platform images to a registry, ensure to set IMAGE_NAME to the name of the registry and image repository to use in the .env.override file and run:

make build-multiplatform-and-push

Making a new release

Maintainers can create a new release when desired by following these steps.

Create a Pull Request that updates the IMAGE_VERSION environment variable in .env to the new version number based on the format x.x.x and merge it.
Create a new release, creating a new tag for the new version number based on main. Automatically generate release notes. Prepend a summary of the major changes to the release notes.
After images for the new release are built and published, create a new Pull Request that updates the CHANGELOG.md with the new version leaving the Unreleased section for the next release. Merge the Pull Request.
Create a new Pull Request to update the deployment of the demo in the OpenTelemetry Helm Charts repo. Merge the Pull Request.
After the Helm chart is released, create a new Pull Request which updates the Demo's Kubernetes manifest by running make generate-kubernetes-manifests. Merge the Pull Request.
Create a new Tag for the new version with a suffix of -k8s. This tag will be used to deploy the new version of the demo to Kubernetes using the supplied manifests.

By following this guide, you'll have a smoother onboarding experience as a contributor. Happy coding!

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!