Demo OTEL App

Demo OTEL App is a small Flask service used to learn observability with OpenTelemetry. It includes traces, logs, and custom metrics for two simple operations:

• Dice rolling
• Random ID generation

The project is intentionally compact so you can read the full code path and safely experiment.

Why this project

This repository is designed for developers who are new to observability but already comfortable reading and running code. You can use it to:

• understand baseline OTEL wiring in a web app
• generate realistic traffic and errors
• inspect metrics, traces, and logs in one place
• extend instrumentation with your own telemetry

Features

• Flask API + minimal UI
• Feature flags for app capabilities
• Environment-driven config with runtime config view (/app-config)
• OTEL tracing, log export, and custom metrics
• Optional OTLP export endpoint
• Local scripts for load generation and container builds

Repository layout

simple-container-app/
├─ docs/
│  ├─ quickstart.ipynb
│  └─ observability.md
├─ src/
│  ├─ app.py
│  ├─ config.py
│  ├─ instrumentation.py
│  ├─ models.py
│  ├─ templates/
│  └─ static/
├─ Containerfile
├─ .containerignore
├─ build.sh
├─ test.sh
├─ requirements.txt
├─ example.env
└─ README.md

Quick start

Use the quickstart notebook:

• docs/quickstart.ipynb

It includes:

• prerequisites
• local app startup
• local container build/run
• traffic generation tests

For Linux and Windows workflows.

Run locally (Linux/Unix)

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp example.env .env
python src/app.py

Open:

• http://127.0.0.1:8080

Build container

chmod +x build.sh
./build.sh --image-name demo-otel-app --tag local

Run:

docker run --rm -p 8080:8080 --env-file .env demo-otel-app:local

Kubernetes resources (Helm)

This repository contains a minimal Helm chart in helm/ for demo deployments.

Resources created by the chart:

• Deployment (app pods + health probes)
• ConfigMap (application environment configuration)
• Service (ClusterIP by default)
• Ingress (optional, with optional TLS + custom annotations)

The chart also supports:

• common_labels and common_annotations applied to all resources
• ingress-specific annotations (for example cert-manager cluster issuer)
• post-install guidance via helm/templates/NOTES.txt

Example install:

helm upgrade --install demo-otel-app ./helm \
  --namespace demo-otel --create-namespace

Enable ingress + TLS (example):

helm upgrade --install demo-otel-app ./helm \
  --set ingress.enabled=true \
  --set ingress.host=demo-otel.local \
  --set ingress.tls.enabled=true \
  --set ingress.tls.secretName=demo-otel-app-tls \
  --set ingress.annotations.cert-manager\\.io/cluster-issuer=letsencrypt-prod

Generate test traffic

chmod +x test.sh
./test.sh --host 127.0.0.1 --port 8080 --operation all --iterations 20

Documentation

• Quickstart (Linux + Windows): docs/quickstart.ipynb
• Observability extension guide: docs/observability.md

Configuration

Primary app config is loaded from environment variables in src/config.py. Important keys:

• APP_NAME
• APP_VERSION
• APP_OWNER
• APP_PORT
• APP_DEBUG
• APP_LOG_LEVEL
• ENABLE_OTEL
• ENABLE_DICE_ROLLER
• ENABLE_RANDOM_ID_GENERATOR
• OTEL_SERVICE_NAME
• OTEL_SERVICE_VERSION
• OTEL_EXPORTER_OTLP_ENDPOINT
• OTEL_EXPORTER_OTLP_HEADERS

Use example.env as the baseline.

API overview

• GET /api/health
• GET /api/endpoints
• GET /api/stats
• GET /api/rolldice?player=<name>&sides=<2-100> (if enabled)
• GET /api/generate-id?prefix=<text>&size=<4-64> (if enabled)

Contributing

This project is currently not seeking external collaborators.

License

No license file is currently included in this repository. Add a LICENSE file before using this project in open distribution.