feat(alephalpha): add beginner-friendly LLM tracing example (closes #4069)

[KochC]

Summary

Closes #4069

This PR adds a beginner-friendly, self-contained example for tracing LLM calls with the Aleph Alpha instrumentation, addressing the request in issue #4069.

Changes

packages/sample-app/sample_app/alephalpha_example.py (new file)

A runnable end-to-end example that walks through:

1. Loading environment variables (.env support via python-dotenv)
2. Initialising the Traceloop SDK (Traceloop.init)
3. Creating an Aleph Alpha client
4. Defining a @task-decorated function that performs a completion request
5. Wrapping it in a @workflow decorator for a clean root span
6. Running the workflow and printing the model's reply

The file is heavily commented to guide new contributors and users who are unfamiliar with LLM observability.

packages/opentelemetry-instrumentation-alephalpha/README.md (updated)

Expanded with a Beginner-friendly walkthrough section that covers:

• Installation of required packages
• Step-by-step setup using the raw OpenTelemetry SDK (console exporter)
• A complete minimal code snippet ready to copy-paste
• A table of expected span attributes with descriptions and example values
• A Traceloop SDK variant (recommended for production)
• A cross-reference to the new sample-app file

packages/sample-app/pyproject.toml (updated)

Added aleph_alpha_client>=7.1.0,<8 and opentelemetry-instrumentation-alephalpha (local editable source) so the new example can be installed and run from the sample-app environment.

How to run

# Install dependencies
cd packages/sample-app
uv sync --all-groups

# Set your Aleph Alpha token
export AA_TOKEN=<your-token>

# Run the example
uv run python sample_app/alephalpha_example.py

Expected trace

span: joke_generator (workflow)
  span: generate_joke (task)
    span: alephalpha.completion
      gen_ai.system              = "AlephAlpha"
      llm.request.type           = "completion"
      gen_ai.request.model       = "luminous-base"
      gen_ai.prompt.0.content    = "Tell me a short, funny joke about observability."
      gen_ai.completion.0.content = <model reply>
      gen_ai.usage.input_tokens  = <N>
      gen_ai.usage.output_tokens = <M>
      llm.usage.total_tokens     = <N+M>

Summary by CodeRabbit

• Documentation

  • Expanded the Aleph Alpha instrumentation README with a beginner-friendly end-to-end tracing walkthrough, a minimal example, and expected trace output details.
  • Added guidance for using Traceloop with tracing decorators.

• Examples

  • Added a sample that runs an Aleph Alpha traced workflow/task to generate a joke and outputs tracing-relevant span details.

• Configuration

  • Updated the sample app configuration to include Aleph Alpha client support and local source mapping for the Aleph Alpha instrumentation package.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 2 committers have signed the CLA.

✅ KochC
❌ Chris

---

Chris seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: f6a334ca-5064-4895-9998-59ed5c843af5

📥 Commits

Reviewing files that changed from the base of the PR and between 04ed78b and 3e9b585.

📒 Files selected for processing (1)

• packages/sample-app/sample_app/alephalpha_example.py

🚧 Files skipped from review as they are similar to previous changes (1)

• packages/sample-app/sample_app/alephalpha_example.py

---

📝 Walkthrough

Walkthrough

The PR adds beginner-oriented Aleph Alpha tracing documentation and a runnable sample app. It covers OpenTelemetry setup, Aleph Alpha instrumentation, Traceloop workflows and tasks, required dependencies, completion requests, and expected span attributes.

Changes

Aleph Alpha tracing examples

Layer / File(s)	Summary
Tracing walkthrough documentation packages/opentelemetry-instrumentation-alephalpha/README.md	Adds step-by-step OpenTelemetry and Aleph Alpha instrumentation instructions, expected trace attributes, and a Traceloop SDK example.
Sample application setup packages/sample-app/pyproject.toml, packages/sample-app/sample_app/alephalpha_example.py	Adds Aleph Alpha and local instrumentation dependencies, documents the example, loads environment variables, and initializes Traceloop.
Traced completion workflow packages/sample-app/sample_app/alephalpha_example.py	Creates an Aleph Alpha client, defines traced generate_joke and joke_generator functions, and adds a runnable script entrypoint.

Estimated code review effort: 2 (Simple) | ~10 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Main
  participant JokeGenerator
  participant GenerateJoke
  participant AlephAlphaClient
  Main->>JokeGenerator: run workflow
  JokeGenerator->>GenerateJoke: pass prompt
  GenerateJoke->>AlephAlphaClient: submit CompletionRequest
  AlephAlphaClient-->>GenerateJoke: return completion
  GenerateJoke-->>JokeGenerator: return result
  JokeGenerator-->>Main: finish workflow

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main change: a beginner-friendly Aleph Alpha LLM tracing example.
Linked Issues check	✅ Passed	The PR adds the requested step-by-step tracing example, minimal setup, trace output guidance, and updated documentation for Aleph Alpha.
Out of Scope Changes check	✅ Passed	The changes stay focused on the Aleph Alpha example, docs, and required sample-app dependencies with no obvious unrelated scope.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

packages/sample-app/sample_app/alephalpha_example.py (1)

50-62: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Explicitly use ConsoleSpanExporter for debugging.

As per coding guidelines, use ConsoleSpanExporter from opentelemetry.sdk.trace.export for debugging OpenTelemetry spans and hierarchy issues. Although Traceloop.init() defaults to standard output when the API key is missing, the guidelines mandate explicit use of ConsoleSpanExporter for debugging contexts like this beginner example.

Note: Applying this change will strictly print traces to the console and override the default behavior of sending them to Traceloop's cloud if TRACELOOP_API_KEY is set.

💡 Proposed fix

+from opentelemetry.sdk.trace.export import ConsoleSpanExporter
+
 # ---------------------------------------------------------------------------
 # Step 2 – Initialise Traceloop / OpenTelemetry
 #
 # Traceloop.init() sets up an OpenTelemetry TracerProvider and automatically
 # instruments every supported LLM library that is installed, including the
 # Aleph Alpha client.  No additional call to AlephAlphaInstrumentor is needed
 # when using the SDK.
 #
-# If TRACELOOP_API_KEY is set the traces are sent to Traceloop's cloud.
-# Otherwise they are printed to stdout (great for local development).
+# Traces are explicitly printed to stdout using ConsoleSpanExporter for local debugging.
 # ---------------------------------------------------------------------------
-Traceloop.init(app_name="alephalpha_beginner_example")
+Traceloop.init(
+    app_name="alephalpha_beginner_example",
+    exporter=ConsoleSpanExporter()
+)

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/sample-app/sample_app/alephalpha_example.py` around lines 50 - 62,
Update the Traceloop initialization in the Aleph Alpha example to explicitly
configure and use OpenTelemetry’s ConsoleSpanExporter for span output. Import
the exporter from opentelemetry.sdk.trace.export and pass it through
Traceloop.init, ensuring traces are printed to the console regardless of
TRACELOOP_API_KEY.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/sample-app/sample_app/alephalpha_example.py`:
- Around line 64-67: Update the Aleph Alpha client initialization in the sample
setup to use strict dictionary lookup for the required AA_TOKEN environment
variable instead of providing an empty-string fallback. Preserve the existing
Client construction while ensuring a missing token fails immediately with the
environment lookup error.

---

Nitpick comments:
In `@packages/sample-app/sample_app/alephalpha_example.py`:
- Around line 50-62: Update the Traceloop initialization in the Aleph Alpha
example to explicitly configure and use OpenTelemetry’s ConsoleSpanExporter for
span output. Import the exporter from opentelemetry.sdk.trace.export and pass it
through Traceloop.init, ensuring traces are printed to the console regardless of
TRACELOOP_API_KEY.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: f298f708-80d3-42f7-8952-a7f4c933a294

📥 Commits

Reviewing files that changed from the base of the PR and between 93429cf and 04ed78b.

📒 Files selected for processing (3)

• packages/opentelemetry-instrumentation-alephalpha/README.md
• packages/sample-app/pyproject.toml
• packages/sample-app/sample_app/alephalpha_example.py