Registry /
observability / opentelemetry-instrumentation-voyageai
Install & Compatibility
Where this runs
tested against v0.62.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.9
✕ build_error
✕ build_error
249MB installed
● package 249MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
VoyageAIInstrumentor
✓ from opentelemetry.instrumentation.voyageai import VoyageAIInstrumentor
The primary class to enable automatic instrumentation for Voyage AI client calls.
This quickstart demonstrates how to set up OpenTelemetry with the `opentelemetry-instrumentation-voyageai` library to automatically trace Voyage AI embedding calls. It configures a basic OTLP trace exporter and then uses the Voyage AI client. Remember to set `VOYAGE_API_KEY` in your environment. Full message content capture is enabled via an environment variable.
import os
import voyageai
from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.instrumentation.voyageai import VoyageAIInstrumentor
# 1. Configure OpenTelemetry SDK
resource = Resource.create(attributes={
"service.name": "voyageai-app",
"application": "my-llm-app"
})
trace_provider = TracerProvider(resource=resource)
# For simplicity, using OTLP HTTP exporter. Adjust endpoint as needed.
span_exporter = OTLPSpanExporter(
endpoint=os.environ.get("OTEL_EXPORTER_OTLP_ENDPOINT", "http://localhost:4318/v1/traces")
)
trace_provider.add_span_processor(BatchSpanProcessor(span_exporter))
trace.set_tracer_provider(trace_provider)
# Optional: Enable capturing full message content (e.g., prompts and responses)
os.environ["OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT"] = "true"
# 2. Instrument Voyage AI
VoyageAIInstrumentor().instrument()
# 3. Use Voyage AI client
# Ensure VOYAGE_API_KEY is set in your environment
client = voyageai.Client(api_key=os.environ.get("VOYAGE_API_KEY", ""))
if not client.api_key:
print("Error: VOYAGE_API_KEY environment variable not set. Please set it to run the example.")
else:
try:
print("Sending embedding request...")
embedding_response = client.embed(
texts=["What is the capital of France?", "Tell me about OpenTelemetry."],
model="voyage-large-2"
)
print("Embedding response received (first 5 dimensions of first embedding):")
if embedding_response.embeddings:
print(embedding_response.embeddings[0][:5], "...")
except Exception as e:
print(f"An error occurred during Voyage AI embedding: {e}")
# Ensure spans are flushed before exit
trace_provider.shutdown()
print("Tracing finished. Check your OTLP endpoint for traces.")
opentelemetry-instrument --version
Debug
Known issues
breakingOpenTelemetry semantic conventions, especially for Generative AI (GenAI), are actively evolving. This instrumentation frequently updates to align with these changes, which can lead to changes in span and attribute names between minor versions.fixReview release notes for attribute changes when upgrading. Consider using OTel Collector processors to transform old attributes to new ones during migration (e.g., `OTEL_SEMCONV_STABILITY_OPT_IN=/dup` for dual emission during transition). Keep your OpenTelemetry SDK and instrumentation libraries updated together.
affects: All versions, particularly before 1.0 stable
gotchaBy default, sensitive message content (like prompts and responses) might not be captured in spans for security and privacy reasons.fixTo enable full content capture, set the environment variable `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true`. Evaluate privacy implications before enabling in production environments.
affects: All versions
gotchaThis instrumentation library (like most OpenTelemetry Python instrumentations) is currently in a beta development status. While stable for many use cases, its APIs and behavior might evolve until a 1.0 stable release.fixTest thoroughly before deploying to production. Monitor release notes for any breaking changes or significant behavioral shifts.
affects: All versions before 1.0
gotchaFor telemetry data to actually be emitted, you must not only install the instrumentation library but also configure a full OpenTelemetry SDK (`opentelemetry-sdk`) with a `TracerProvider` and a `SpanProcessor` connected to an exporter. Without the SDK, the instrumentation will be a no-op.fixEnsure your application initializes the OpenTelemetry SDK with a `TracerProvider`, `SpanProcessor`, and an appropriate exporter (e.g., `OTLPSpanExporter`) before making calls to the instrumented library.
affects: All versions
Upgrade
Version history
0.62.3latest on PyPI · released Aug 10, 2026
Audit
Dependencies
opentelemetry-apirequiredCore OpenTelemetry API for instrumentation libraries.
opentelemetry-sdkrequiredRequired in applications to process and export telemetry data.
opentelemetry-exporter-otlpoptionalA common exporter used to send telemetry to an OTLP-compatible collector or backend (used in quickstart).
voyageairequiredThe Voyage AI Python client library being instrumented.