From 05e34d7761bf3ec5a3b6e7861197241af8e00b49 Mon Sep 17 00:00:00 2001 From: Bhavyansh Jain Date: Mon, 28 Sep 2026 21:33:57 +0530 Subject: [PATCH 1/3] docs: add Aleph Alpha tracing example --- .../README.md | 72 +++++++++++++++++++ .../examples/trace_completion.py | 30 ++++++++ 2 files changed, 102 insertions(+) create mode 100644 packages/opentelemetry-instrumentation-alephalpha/examples/trace_completion.py diff --git a/packages/opentelemetry-instrumentation-alephalpha/README.md b/packages/opentelemetry-instrumentation-alephalpha/README.md index 34ff056880..695f4c1abe 100644 --- a/packages/opentelemetry-instrumentation-alephalpha/README.md +++ b/packages/opentelemetry-instrumentation-alephalpha/README.md @@ -20,6 +20,78 @@ from opentelemetry.instrumentation.alephalpha import AlephAlphaInstrumentor AlephAlphaInstrumentor().instrument() ``` +## Beginner example + +The following example makes one completion request and prints the trace to the +terminal. It is useful for understanding the complete flow locally before +connecting the application to an observability backend. + +Install the instrumentation package and the Aleph Alpha client: + +```bash +pip install opentelemetry-instrumentation-alephalpha aleph-alpha-client opentelemetry-sdk +``` + +Set your Aleph Alpha API token: + +```bash +export AA_TOKEN="your-api-token" +``` + +Create `trace_completion.py`: + +```python +import os + +from aleph_alpha_client import Client, CompletionRequest, Prompt +from opentelemetry import trace +from opentelemetry.sdk.trace import TracerProvider +from opentelemetry.sdk.trace.export import ( + SimpleSpanProcessor, + ConsoleSpanExporter, +) +from opentelemetry.instrumentation.alephalpha import AlephAlphaInstrumentor + + +def main(): + tracer_provider = TracerProvider() + tracer_provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter())) + trace.set_tracer_provider(tracer_provider) + + AlephAlphaInstrumentor().instrument(tracer_provider=tracer_provider) + + client = Client(token=os.environ["AA_TOKEN"]) + request = CompletionRequest( + prompt=Prompt.from_text("Explain ETL in one sentence."), + maximum_tokens=100, + ) + response = client.complete(request, model="luminous-base") + + print(response.completions[0].completion) + + +if __name__ == "__main__": + main() +``` + +Run it with: + +```bash +python trace_completion.py +``` + +The terminal prints the model response followed by an OpenTelemetry span. The +span contains information such as the model name, request type, duration, and +token usage. Prompt and completion content are also recorded by default; see +the [Privacy](#privacy) section if your application handles sensitive data. + +The example demonstrates the four steps involved in tracing an LLM call: + +1. Create an OpenTelemetry tracer provider. +2. Add an exporter that prints completed spans. +3. Instrument the Aleph Alpha client. +4. Make a normal client request. The instrumentation creates the span. + ## 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/opentelemetry-instrumentation-alephalpha/examples/trace_completion.py b/packages/opentelemetry-instrumentation-alephalpha/examples/trace_completion.py new file mode 100644 index 0000000000..d75f565d3c --- /dev/null +++ b/packages/opentelemetry-instrumentation-alephalpha/examples/trace_completion.py @@ -0,0 +1,30 @@ +"""Trace one Aleph Alpha completion and print the span locally.""" + +import os + +from aleph_alpha_client import Client, CompletionRequest, Prompt +from opentelemetry import trace +from opentelemetry.instrumentation.alephalpha import AlephAlphaInstrumentor +from opentelemetry.sdk.trace import TracerProvider +from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor + + +def main() -> None: + tracer_provider = TracerProvider() + tracer_provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter())) + trace.set_tracer_provider(tracer_provider) + + AlephAlphaInstrumentor().instrument(tracer_provider=tracer_provider) + + client = Client(token=os.environ["AA_TOKEN"]) + request = CompletionRequest( + prompt=Prompt.from_text("Explain ETL in one sentence."), + maximum_tokens=100, + ) + response = client.complete(request, model="luminous-base") + + print(response.completions[0].completion) + + +if __name__ == "__main__": + main() From 8c2ca01be16340081fed9d46e6d4be2c81e7455f Mon Sep 17 00:00:00 2001 From: Bhavyansh Jain Date: Mon, 28 Sep 2026 21:50:32 +0530 Subject: [PATCH 2/3] docs: clarify tracing example output --- .../opentelemetry-instrumentation-alephalpha/README.md | 9 +++++---- .../examples/trace_completion.py | 2 ++ 2 files changed, 7 insertions(+), 4 deletions(-) diff --git a/packages/opentelemetry-instrumentation-alephalpha/README.md b/packages/opentelemetry-instrumentation-alephalpha/README.md index 695f4c1abe..fafd17afa0 100644 --- a/packages/opentelemetry-instrumentation-alephalpha/README.md +++ b/packages/opentelemetry-instrumentation-alephalpha/README.md @@ -80,10 +80,11 @@ Run it with: python trace_completion.py ``` -The terminal prints the model response followed by an OpenTelemetry span. The -span contains information such as the model name, request type, duration, and -token usage. Prompt and completion content are also recorded by default; see -the [Privacy](#privacy) section if your application handles sensitive data. +The terminal prints an OpenTelemetry span for the completed request and the +model response. The span contains information such as the model name, request +type, duration, and token usage. Prompt and completion content are also +recorded by default; see the [Privacy](#privacy) section if your application +handles sensitive data. The example demonstrates the four steps involved in tracing an LLM call: diff --git a/packages/opentelemetry-instrumentation-alephalpha/examples/trace_completion.py b/packages/opentelemetry-instrumentation-alephalpha/examples/trace_completion.py index d75f565d3c..ca38d36704 100644 --- a/packages/opentelemetry-instrumentation-alephalpha/examples/trace_completion.py +++ b/packages/opentelemetry-instrumentation-alephalpha/examples/trace_completion.py @@ -10,6 +10,8 @@ def main() -> None: + """Make one traced completion request and print the response.""" + tracer_provider = TracerProvider() tracer_provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter())) trace.set_tracer_provider(tracer_provider) From 9d8d84e73d5d52fb0a807739575d053309e4d5c1 Mon Sep 17 00:00:00 2001 From: Bhavyansh Jain Date: Mon, 28 Sep 2026 21:53:24 +0530 Subject: [PATCH 3/3] docs: clarify span output order --- .../opentelemetry-instrumentation-alephalpha/README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/packages/opentelemetry-instrumentation-alephalpha/README.md b/packages/opentelemetry-instrumentation-alephalpha/README.md index fafd17afa0..016b87e394 100644 --- a/packages/opentelemetry-instrumentation-alephalpha/README.md +++ b/packages/opentelemetry-instrumentation-alephalpha/README.md @@ -80,11 +80,11 @@ Run it with: python trace_completion.py ``` -The terminal prints an OpenTelemetry span for the completed request and the -model response. The span contains information such as the model name, request -type, duration, and token usage. Prompt and completion content are also -recorded by default; see the [Privacy](#privacy) section if your application -handles sensitive data. +The terminal prints the OpenTelemetry span before the model response because +the span is exported when `client.complete()` finishes. The span contains +information such as the model name, request type, duration, and token usage. +Prompt and completion content are also recorded by default; see the +[Privacy](#privacy) section if your application handles sensitive data. The example demonstrates the four steps involved in tracing an LLM call: