feat(examples): add dice roller getting started reference application

.github/actions/test_dice_roller/action.yml

@@ -0,0 +1,102 @@
+name: Test Dice Roller Example
+description: Verifies that the dice roller reference application builds and runs correctly (both instrumented and uninstrumented versions).
+
+inputs:
+  version:
+    description: Which version to test — "instrumented" or "uninstrumented"
+    required: true
+  ruby:
+    description: Ruby version to use
+    required: true
+
+runs:
+  using: composite
+  steps:
+    - name: Install Ruby ${{ inputs.ruby }}
+      uses: ruby/setup-ruby@8d27f39a5e7ad39aebbcbd1324f7af020229645c # v1.287.0
+      with:
+        ruby-version: "${{ inputs.ruby }}"
+        working-directory: "examples/dice_roller/${{ inputs.version }}"
+        bundler: "latest"
+        bundler-cache: true
+
+    - name: Start app (${{ inputs.version }})
+      shell: bash
+      working-directory: examples/dice_roller/${{ inputs.version }}
+      env:
+        APPLICATION_PORT: "8080"
+        OTEL_TRACES_EXPORTER: none
+        OTEL_METRICS_EXPORTER: none
+        OTEL_LOGS_EXPORTER: none
+        OTEL_SERVICE_NAME: dice_roller_ci
+      run: |
+        # 🎲 Start dice roller (${{ inputs.version }}) 🎲
+        ruby app.rb &
+        echo "APP_PID=$!" >> "$GITHUB_ENV"
+        echo "Waiting for server to be ready..."
+        for i in $(seq 1 30); do
+          if curl -sf http://localhost:8080/rolldice > /dev/null 2>&1; then
+            echo "Server ready after ${i}s"
+            exit 0
+          fi
+          sleep 1
+        done
+        echo "Server did not start in time" >&2
+        exit 1
+
+    - name: Verify /rolldice returns a single die value
+      shell: bash
+      run: |
+        # 🎲 Single roll 🎲
+        RESPONSE=$(curl -sf http://localhost:8080/rolldice)
+        echo "Response: $RESPONSE"
+        echo "$RESPONSE" | grep -qE '^[1-6]$'
+
+    - name: Verify /rolldice?rolls=3 returns an array of 3 values
+      shell: bash
+      run: |
+        # 🎲 Multiple rolls 🎲
+        RESPONSE=$(curl -sf "http://localhost:8080/rolldice?rolls=3")
+        echo "Response: $RESPONSE"
+        echo "$RESPONSE" | grep -qE '^\[[1-6],[1-6],[1-6]\]$'
+
+    - name: Verify /rolldice?player=Alice returns a single die value
+      shell: bash
+      run: |
+        # 🎲 Roll with player name 🎲
+        RESPONSE=$(curl -sf "http://localhost:8080/rolldice?player=Alice")
+        echo "Response: $RESPONSE"
+        echo "$RESPONSE" | grep -qE '^[1-6]$'
+
+    - name: Verify /rolldice?rolls=invalid returns HTTP 400
+      shell: bash
+      run: |
+        # ❌ Invalid rolls parameter 🎲
+        STATUS=$(curl -s -o /dev/null -w "%{http_code}" "http://localhost:8080/rolldice?rolls=invalid")
+        echo "Status: $STATUS"
+        [ "$STATUS" = "400" ]
+
+    - name: Verify /rolldice?rolls=0 returns HTTP 400
+      shell: bash
+      run: |
+        # ❌ Zero rolls 🎲
+        STATUS=$(curl -s -o /dev/null -w "%{http_code}" "http://localhost:8080/rolldice?rolls=0")
+        echo "Status: $STATUS"
+        [ "$STATUS" = "400" ]
+
+    - name: Verify /rolldice?rolls=-1 returns HTTP 400
+      shell: bash
+      run: |
+        # ❌ Negative rolls 🎲
+        STATUS=$(curl -s -o /dev/null -w "%{http_code}" "http://localhost:8080/rolldice?rolls=-1")
+        echo "Status: $STATUS"
+        [ "$STATUS" = "400" ]
+
+    - name: Stop app
+      shell: bash
+      if: always()
+      run: |
+        # 🛑 Stop app 🛑
+        if [ -n "$APP_PID" ]; then
+          kill "$APP_PID" || true
+        fi

.github/workflows/ci-example-dice-roller.yml

@@ -0,0 +1,120 @@
+name: CI - Example Dice Roller
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+    paths:
+      - 'examples/dice_roller/**'
+      - '.github/actions/test_dice_roller/**'
+      - '.github/workflows/ci-example-dice-roller.yml'
+  pull_request:
+    branches:
+      - main
+    paths:
+      - 'examples/dice_roller/**'
+      - '.github/actions/test_dice_roller/**'
+      - '.github/workflows/ci-example-dice-roller.yml'
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  # ---------------------------------------------------------------------------
+  # Verify both versions build and run correctly across Ruby versions
+  # ---------------------------------------------------------------------------
+  dice-roller:
+    if: ${{ github.repository == 'open-telemetry/opentelemetry-ruby' }}
+    name: ${{ matrix.version }} / Ruby ${{ matrix.ruby }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        version:
+          - uninstrumented
+          - instrumented
+        ruby:
+          - "3.2"
+          - "3.3"
+          - "3.4"
+
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Test Dice Roller (${{ matrix.version }}, Ruby ${{ matrix.ruby }})
+        uses: ./.github/actions/test_dice_roller
+        with:
+          version: ${{ matrix.version }}
+          ruby: ${{ matrix.ruby }}
+
+  # ---------------------------------------------------------------------------
+  # Verify both Docker images build and the container starts correctly
+  # ---------------------------------------------------------------------------
+  dice-roller-docker:
+    if: ${{ github.repository == 'open-telemetry/opentelemetry-ruby' }}
+    name: Docker ${{ matrix.version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        version:
+          - uninstrumented
+          - instrumented
+
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Build Docker image (${{ matrix.version }})
+        working-directory: examples/dice_roller
+        run: |
+          # 🐳 Build ${{ matrix.version }} image 🐳
+          docker build \
+            --target ${{ matrix.version }} \
+            -t dice_roller:${{ matrix.version }} \
+            .
+
+      - name: Run container (${{ matrix.version }})
+        run: |
+          # 🐳 Start container 🐳
+          docker run -d \
+            --name dice_roller_${{ matrix.version }} \
+            -p 8080:8080 \
+            -e OTEL_TRACES_EXPORTER=none \
+            -e OTEL_METRICS_EXPORTER=none \
+            -e OTEL_LOGS_EXPORTER=none \
+            -e OTEL_SERVICE_NAME=dice_roller_ci \
+            dice_roller:${{ matrix.version }}
+          echo "Waiting for container to be ready..."
+          for i in $(seq 1 30); do
+            if curl -sf http://localhost:8080/rolldice > /dev/null 2>&1; then
+              echo "Container ready after ${i}s"
+              exit 0
+            fi
+            sleep 1
+          done
+          echo "Container did not start in time" >&2
+          docker logs dice_roller_${{ matrix.version }}
+          exit 1
+
+      - name: Verify /rolldice (single roll)
+        run: |
+          RESPONSE=$(curl -sf http://localhost:8080/rolldice)
+          echo "Response: $RESPONSE"
+          echo "$RESPONSE" | grep -qE '^[1-6]$'
+
+      - name: Verify /rolldice?rolls=2 (multiple rolls)
+        run: |
+          RESPONSE=$(curl -sf "http://localhost:8080/rolldice?rolls=2")
+          echo "Response: $RESPONSE"
+          echo "$RESPONSE" | grep -qE '^\[[1-6],[1-6]\]$'
+
+      - name: Stop and remove container
+        if: always()
+        run: |
+          docker stop dice_roller_${{ matrix.version }} || true
+          docker rm  dice_roller_${{ matrix.version }} || true

examples/dice_roller/Dockerfile

@@ -0,0 +1,59 @@
+# syntax=docker/dockerfile:1
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+# ---------------------------------------------------------------------------
+# Build argument: set to "instrumented" (default) or "uninstrumented"
+# ---------------------------------------------------------------------------
+ARG APP_VERSION=instrumented
+
+FROM ruby:3.3-slim AS base
+
+WORKDIR /app
+
+# Install build dependencies
+RUN apt-get update -qq && \
+    apt-get install -y --no-install-recommends build-essential && \
+    rm -rf /var/lib/apt/lists/*
+
+# ---------------------------------------------------------------------------
+# Uninstrumented stage
+# ---------------------------------------------------------------------------
+FROM base AS uninstrumented
+
+COPY uninstrumented/Gemfile ./Gemfile
+RUN bundle install
+
+COPY uninstrumented/app.rb  ./app.rb
+COPY uninstrumented/dice.rb ./dice.rb
+
+ENV APPLICATION_PORT=8080
+EXPOSE 8080
+
+CMD ["ruby", "app.rb"]
+
+# ---------------------------------------------------------------------------
+# Instrumented stage
+# ---------------------------------------------------------------------------
+FROM base AS instrumented
+
+COPY instrumented/Gemfile ./Gemfile
+RUN bundle install
+
+COPY instrumented/otel.rb  ./otel.rb
+COPY instrumented/dice.rb  ./dice.rb
+COPY instrumented/app.rb   ./app.rb
+
+ENV APPLICATION_PORT=8080
+# Service name used by OTel SDK (can be overridden at runtime)
+ENV OTEL_SERVICE_NAME=dice_roller
+# Export to console by default; override with "otlp" to send to a collector
+ENV OTEL_TRACES_EXPORTER=console
+ENV OTEL_METRICS_EXPORTER=console
+ENV OTEL_LOGS_EXPORTER=console
+
+EXPOSE 8080
+
+CMD ["ruby", "app.rb"]