From 04ed78b5f9aebf2ac7abdb4f1402fb055b9f5d86 Mon Sep 17 00:00:00 2001 From: Chris Date: Sat, 18 Jul 2026 21:29:14 +0200 Subject: [PATCH 1/2] feat(alephalpha): add beginner-friendly LLM tracing example Closes #4069 - Add packages/sample-app/sample_app/alephalpha_example.py: a self-contained, well-commented runnable example that shows how to initialise Traceloop, instrument the Aleph Alpha client, make a completion request and observe the resulting trace. - Expand packages/opentelemetry-instrumentation-alephalpha/README.md with a step-by-step beginner walkthrough covering: * raw OpenTelemetry setup (console exporter) * AlephAlphaInstrumentor usage * a complete minimal code snippet * a table of expected span attributes * a Traceloop SDK variant - Add aleph_alpha_client and opentelemetry-instrumentation-alephalpha to packages/sample-app/pyproject.toml so the example can be run from the sample-app environment. --- .../README.md | 158 ++++++++++++++++++ packages/sample-app/pyproject.toml | 3 + .../sample_app/alephalpha_example.py | 115 +++++++++++++ 3 files changed, 276 insertions(+) create mode 100644 packages/sample-app/sample_app/alephalpha_example.py diff --git a/packages/opentelemetry-instrumentation-alephalpha/README.md b/packages/opentelemetry-instrumentation-alephalpha/README.md index 34ff056880..3701d6103c 100644 --- a/packages/opentelemetry-instrumentation-alephalpha/README.md +++ b/packages/opentelemetry-instrumentation-alephalpha/README.md @@ -20,6 +20,164 @@ from opentelemetry.instrumentation.alephalpha import AlephAlphaInstrumentor AlephAlphaInstrumentor().instrument() ``` +--- + +## Beginner-friendly walkthrough + +This section walks you through tracing your first Aleph Alpha LLM call from scratch. + +### Prerequisites + +Install the required packages: + +```bash +pip install opentelemetry-instrumentation-alephalpha \ + aleph_alpha_client \ + opentelemetry-sdk +``` + +You need an **Aleph Alpha API token**. Sign up at and create a token in your account settings. + +### Step 1 – Set up OpenTelemetry + +Before instrumenting anything you need an OpenTelemetry `TracerProvider` that knows where to export spans. The simplest option for local development is to print spans to the console: + +```python +from opentelemetry import trace +from opentelemetry.sdk.trace import TracerProvider +from opentelemetry.sdk.trace.export import SimpleSpanProcessor, ConsoleSpanExporter + +# Create a provider that prints spans to stdout +provider = TracerProvider() +provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter())) +trace.set_tracer_provider(provider) +``` + +### Step 2 – Instrument the Aleph Alpha client + +```python +from opentelemetry.instrumentation.alephalpha import AlephAlphaInstrumentor + +AlephAlphaInstrumentor().instrument() +``` + +After this single call every subsequent Aleph Alpha API request is automatically wrapped in an OpenTelemetry span — no further code changes are needed. + +### Step 3 – Make an LLM call + +```python +import os +from aleph_alpha_client import Client, CompletionRequest, Prompt + +client = Client(token=os.environ["AA_TOKEN"]) + +request = CompletionRequest( + prompt=Prompt.from_text("Explain observability in one sentence."), + maximum_tokens=100, +) +response = client.complete(request, model="luminous-base") +print(response.completions[0].completion) +``` + +### Complete minimal example + +```python +""" +Minimal Aleph Alpha tracing example. + +Requirements: + pip install opentelemetry-instrumentation-alephalpha aleph_alpha_client opentelemetry-sdk + +Environment: + export AA_TOKEN= +""" + +import os + +# 1. Set up OpenTelemetry (console exporter for local development) +from opentelemetry import trace +from opentelemetry.sdk.trace import TracerProvider +from opentelemetry.sdk.trace.export import SimpleSpanProcessor, ConsoleSpanExporter + +provider = TracerProvider() +provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter())) +trace.set_tracer_provider(provider) + +# 2. Instrument the Aleph Alpha client +from opentelemetry.instrumentation.alephalpha import AlephAlphaInstrumentor + +AlephAlphaInstrumentor().instrument() + +# 3. Make a completion request — the span is captured automatically +from aleph_alpha_client import Client, CompletionRequest, Prompt + +client = Client(token=os.environ["AA_TOKEN"]) +request = CompletionRequest( + prompt=Prompt.from_text("Explain observability in one sentence."), + maximum_tokens=100, +) +response = client.complete(request, model="luminous-base") +print("Response:", response.completions[0].completion) +``` + +### Expected trace output + +When you run the example above you will see a JSON span printed to the console. The key attributes are: + +| Attribute | Description | Example value | +|---|---|---| +| `gen_ai.system` | The LLM provider | `"AlephAlpha"` | +| `llm.request.type` | The type of LLM call | `"completion"` | +| `gen_ai.request.model` | The model used | `"luminous-base"` | +| `gen_ai.prompt.0.content` | The prompt text (if content tracing is enabled) | `"Explain observability…"` | +| `gen_ai.completion.0.content` | The model's reply (if content tracing is enabled) | `"Observability is…"` | +| `gen_ai.usage.input_tokens` | Number of prompt tokens consumed | `8` | +| `gen_ai.usage.output_tokens` | Number of generated tokens | `42` | +| `llm.usage.total_tokens` | Total tokens (input + output) | `50` | + +### Using the Traceloop SDK (recommended) + +For production use, the [Traceloop SDK](https://pypi.org/project/traceloop-sdk/) handles provider setup, instrumentation, and exporting for you: + +```bash +pip install traceloop-sdk opentelemetry-instrumentation-alephalpha aleph_alpha_client +``` + +```python +import os +from aleph_alpha_client import Client, CompletionRequest, Prompt +from traceloop.sdk import Traceloop +from traceloop.sdk.decorators import task, workflow + +# Initialise – instruments all supported LLM libraries automatically +Traceloop.init(app_name="my_alephalpha_app") + +client = Client(token=os.environ["AA_TOKEN"]) + + +@task(name="complete_prompt") +def complete_prompt(text: str) -> str: + request = CompletionRequest( + prompt=Prompt.from_text(text), + maximum_tokens=100, + ) + response = client.complete(request, model="luminous-base") + return response.completions[0].completion + + +@workflow(name="main_workflow") +def main(): + answer = complete_prompt("Explain observability in one sentence.") + print("Answer:", answer) + + +main() +``` + +A richer version of this example (with `@workflow` / `@task` decorators) can be found in [`packages/sample-app/sample_app/alephalpha_example.py`](../../sample-app/sample_app/alephalpha_example.py). + +--- + ## Privacy **By default, this instrumentation logs prompts, completions, and embeddings to span attributes**. This gives you a clear visibility into how your LLM application is working, and can make it easy to debug and evaluate the quality of the outputs. diff --git a/packages/sample-app/pyproject.toml b/packages/sample-app/pyproject.toml index fe7b26742d..cad299c4d3 100644 --- a/packages/sample-app/pyproject.toml +++ b/packages/sample-app/pyproject.toml @@ -51,6 +51,8 @@ dependencies = [ "fastmcp>=2.12.3,<3", "agno>=2.4.0,<3", "voyageai>=0.3.7", + "aleph_alpha_client>=7.1.0,<8", + "opentelemetry-instrumentation-alephalpha", "opentelemetry-instrumentation-openai", "opentelemetry-instrumentation-haystack", "opentelemetry-instrumentation-pinecone", @@ -84,6 +86,7 @@ opentelemetry-instrumentation-agno = { path = "../opentelemetry-instrumentation- opentelemetry-instrumentation-anthropic = { path = "../opentelemetry-instrumentation-anthropic", editable = true } opentelemetry-instrumentation-bedrock = { path = "../opentelemetry-instrumentation-bedrock", editable = true } opentelemetry-instrumentation-voyageai = { path = "../opentelemetry-instrumentation-voyageai", editable = true } +opentelemetry-instrumentation-alephalpha = { path = "../opentelemetry-instrumentation-alephalpha", editable = true } traceloop-sdk = { path = "../traceloop-sdk", editable = true } [dependency-groups] diff --git a/packages/sample-app/sample_app/alephalpha_example.py b/packages/sample-app/sample_app/alephalpha_example.py new file mode 100644 index 0000000000..33b06d6f53 --- /dev/null +++ b/packages/sample-app/sample_app/alephalpha_example.py @@ -0,0 +1,115 @@ +""" +Beginner-friendly example: LLM tracing with Aleph Alpha and OpenLLMetry +======================================================================== + +This script shows, step by step, how to: + 1. Initialise the Traceloop SDK (which sets up the OpenTelemetry tracer). + 2. Instrument the Aleph Alpha client so every completion call is traced + automatically. + 3. Make a basic text-completion request. + 4. Observe the trace that is captured. + +Prerequisites +------------- +Install the required packages:: + + pip install traceloop-sdk opentelemetry-instrumentation-alephalpha aleph_alpha_client python-dotenv + +Set the environment variables (or create a .env file):: + + AA_TOKEN= + TRACELOOP_API_KEY= # optional – omit to print traces locally + +Expected trace +-------------- +After running this script you should see a single span exported with: + + - span name : "alephalpha.completion" + - gen_ai.system : "AlephAlpha" + - llm.request.type : "completion" + - gen_ai.request.model: "luminous-base" + - gen_ai.prompt.0.content : + - gen_ai.completion.0.content : + - gen_ai.usage.input_tokens : + - gen_ai.usage.output_tokens : + - llm.usage.total_tokens : input + output tokens +""" + +import os + +from aleph_alpha_client import Client, CompletionRequest, Prompt +from dotenv import load_dotenv +from traceloop.sdk import Traceloop +from traceloop.sdk.decorators import task, workflow + +# --------------------------------------------------------------------------- +# Step 1 – Load environment variables from a .env file (if present) +# --------------------------------------------------------------------------- +load_dotenv() + +# --------------------------------------------------------------------------- +# 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). +# --------------------------------------------------------------------------- +Traceloop.init(app_name="alephalpha_beginner_example") + +# --------------------------------------------------------------------------- +# Step 3 – Create the Aleph Alpha client +# --------------------------------------------------------------------------- +aleph_alpha_client = Client(token=os.environ.get("AA_TOKEN", "")) + + +# --------------------------------------------------------------------------- +# Step 4 – Define a traced task that performs a single completion +# +# The @task decorator wraps the function in an OpenTelemetry span named +# "generate_joke". The AlephAlpha instrumentation automatically adds a +# child span "alephalpha.completion" containing all LLM-specific attributes. +# --------------------------------------------------------------------------- +@task(name="generate_joke") +def generate_joke(prompt_text: str) -> str: + """Send a prompt to Aleph Alpha and return the generated completion.""" + request = CompletionRequest( + prompt=Prompt.from_text(prompt_text), + maximum_tokens=200, + ) + response = aleph_alpha_client.complete(request, model="luminous-base") + completion = response.completions[0].completion + print(f"\nCompletion received:\n{completion}\n") + return completion + + +# --------------------------------------------------------------------------- +# Step 5 – Define a top-level workflow that calls the task +# +# The @workflow decorator creates the root span for this execution. All +# child spans (tasks, LLM calls) are nested inside it, giving you a clear +# view of the full execution tree in your tracing backend. +# --------------------------------------------------------------------------- +@workflow(name="joke_generator") +def joke_generator(): + """Top-level workflow: ask the model for a joke and print it.""" + prompt = "Tell me a short, funny joke about observability." + print(f"Prompt: {prompt}") + joke = generate_joke(prompt) + return joke + + +# --------------------------------------------------------------------------- +# Step 6 – Run the workflow +# --------------------------------------------------------------------------- +if __name__ == "__main__": + print("=" * 60) + print("Aleph Alpha LLM Tracing – Beginner Example") + print("=" * 60) + result = joke_generator() + print("=" * 60) + print("Done! Check your Traceloop dashboard (or stdout) for the trace.") + print("=" * 60) From 3e9b585af3d44b2e226ccfced62e0c3f4144f2f1 Mon Sep 17 00:00:00 2001 From: KochC Date: Sun, 19 Jul 2026 11:22:23 +0200 Subject: [PATCH 2/2] Update packages/sample-app/sample_app/alephalpha_example.py Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> --- packages/sample-app/sample_app/alephalpha_example.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/packages/sample-app/sample_app/alephalpha_example.py b/packages/sample-app/sample_app/alephalpha_example.py index 33b06d6f53..0f4537ec4d 100644 --- a/packages/sample-app/sample_app/alephalpha_example.py +++ b/packages/sample-app/sample_app/alephalpha_example.py @@ -63,8 +63,7 @@ # --------------------------------------------------------------------------- # Step 3 – Create the Aleph Alpha client # --------------------------------------------------------------------------- -aleph_alpha_client = Client(token=os.environ.get("AA_TOKEN", "")) - +aleph_alpha_client = Client(token=os.environ["AA_TOKEN"]) # --------------------------------------------------------------------------- # Step 4 – Define a traced task that performs a single completion