diff --git a/packages/opentelemetry-instrumentation-alephalpha/README.md b/packages/opentelemetry-instrumentation-alephalpha/README.md index 34ff056880..016b87e394 100644 --- a/packages/opentelemetry-instrumentation-alephalpha/README.md +++ b/packages/opentelemetry-instrumentation-alephalpha/README.md @@ -20,6 +20,79 @@ 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 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: + +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..ca38d36704 --- /dev/null +++ b/packages/opentelemetry-instrumentation-alephalpha/examples/trace_completion.py @@ -0,0 +1,32 @@ +"""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: + """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) + + 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()