OpenTelemetry Aleph Alpha Instrumentation

Warnings

• breaking OpenTelemetry semantic conventions, especially for Generative AI, are evolving. Updates to `opentelemetry-semantic-conventions-ai` might introduce breaking changes to span attribute names in minor versions.
  Fix: Monitor release notes for `opentelemetry-semantic-conventions-ai`. Use the `OTEL_SEMCONV_STABILITY_OPT_IN` environment variable (e.g., `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai/dup`) to emit both old and new conventions during migration periods.
• gotcha By default, this instrumentation logs prompts, completions, and embeddings to span attributes. This might include sensitive user data.
  Fix: To disable logging of content for privacy reasons or to reduce trace size, set the environment variable `TRACELOOP_TRACE_CONTENT` to `false`. Example: `TRACELOOP_TRACE_CONTENT=false`.
• gotcha Installing `opentelemetry-instrumentation-alephalpha` alone is not sufficient to generate traces. A full OpenTelemetry SDK setup, including a `TracerProvider`, `SpanProcessor`, and `SpanExporter`, is required to process and export telemetry data.
  Fix: Always initialize a `TracerProvider` and configure at least one `SpanProcessor` and `SpanExporter` in your application code. Refer to the OpenTelemetry Python SDK documentation for complete setup. The quickstart above includes a minimal working example.

Install

• pip install opentelemetry-instrumentation-alephalpha aleph-alpha-client opentelemetry-sdk Install with Aleph Alpha client and OTel SDK

Imports

• AlephAlphaInstrumentor

  from opentelemetry.instrumentation.alephalpha import AlephAlphaInstrumentor

Quickstart

This quickstart demonstrates how to set up the OpenTelemetry SDK with a console exporter and then apply the `AlephAlphaInstrumentor` to automatically trace calls made using the `aleph-alpha-client`. Ensure your `ALEPH_ALPHA_API_KEY` is set as an environment variable or replaced in the code.

import os
from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor
from opentelemetry.instrumentation.alephalpha import AlephAlphaInstrumentor

# Ensure Aleph Alpha client is installed: pip install aleph-alpha-client
import aleph_alpha_client

# --- OpenTelemetry SDK Setup ---
# Configure resource (optional, but good practice)
resource = Resource.create({"service.name": "aleph-alpha-app"})

# Set up a TracerProvider
provider = TracerProvider(resource=resource)

# Export spans to console for demonstration
span_processor = SimpleSpanProcessor(ConsoleSpanExporter())
provider.add_span_processor(span_processor)

# Set the global TracerProvider
trace.set_tracer_provider(provider)

# --- Aleph Alpha Instrumentation ---
# Instrument the Aleph Alpha client
AlephAlphaInstrumentor().instrument()

# --- Aleph Alpha Client Usage ---
# Replace with your actual Aleph Alpha API key
AA_API_KEY = os.environ.get("ALEPH_ALPHA_API_KEY", "YOUR_AA_API_KEY")

if AA_API_KEY == "YOUR_AA_API_KEY":
    print("Warning: ALEPH_ALPHA_API_KEY not set. Using dummy key. API calls will fail.")

# Example Aleph Alpha API call
print("\n--- Making an Aleph Alpha API call ---")
client = aleph_alpha_client.Client(host="https://api.aleph-alpha.com", token=AA_API_KEY)

try:
    # A simple completion request
    request = aleph_alpha_client.CompletionRequest(
        prompt=aleph_alpha_client.Prompt([aleph_alpha_client.Text("Hello, world!")]),
        model="luminous-extended",
        maximum_tokens=10,
    )
    response = client.complete(request=request)
    print(f"Aleph Alpha Response: {response.completions[0].completion}")
except Exception as e:
    print(f"Aleph Alpha API call failed (this is expected if API key is invalid): {e}")

print("\n--- OpenTelemetry tracing complete ---")