{"id":4999,"library":"opentelemetry-instrumentation-voyageai","title":"OpenTelemetry Instrumentation for Voyage AI","description":"This library provides OpenTelemetry instrumentation for the Voyage AI Python client, enabling automatic collection of traces, metrics, and logs for AI model interactions. It supports the OpenTelemetry GenAI semantic conventions. The project is actively maintained with frequent releases, often on a weekly or bi-weekly cadence, reflecting ongoing development and alignment with evolving OpenTelemetry standards.","status":"active","version":"0.58.1","language":"en","source_language":"en","source_url":"https://github.com/traceloop/openllmetry/tree/main/packages/opentelemetry-instrumentation-voyageai","tags":["opentelemetry","observability","ai","llm","voyageai","instrumentation","tracing","metrics","embeddings"],"install":[{"cmd":"pip install opentelemetry-instrumentation-voyageai opentelemetry-sdk opentelemetry-exporter-otlp voyageai","lang":"bash","label":"Install core, SDK, OTLP exporter, and VoyageAI client"}],"dependencies":[{"reason":"Core OpenTelemetry API for instrumentation libraries.","package":"opentelemetry-api","optional":false},{"reason":"Required in applications to process and export telemetry data.","package":"opentelemetry-sdk","optional":false},{"reason":"A common exporter used to send telemetry to an OTLP-compatible collector or backend (used in quickstart).","package":"opentelemetry-exporter-otlp","optional":true},{"reason":"The Voyage AI Python client library being instrumented.","package":"voyageai","optional":false}],"imports":[{"note":"The primary class to enable automatic instrumentation for Voyage AI client calls.","symbol":"VoyageAIInstrumentor","correct":"from opentelemetry.instrumentation.voyageai import VoyageAIInstrumentor"}],"quickstart":{"code":"import os\nimport voyageai\nfrom opentelemetry import trace\nfrom opentelemetry.sdk.resources import Resource\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.trace.export import BatchSpanProcessor\nfrom opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter\nfrom opentelemetry.instrumentation.voyageai import VoyageAIInstrumentor\n\n# 1. Configure OpenTelemetry SDK\nresource = Resource.create(attributes={\n    \"service.name\": \"voyageai-app\",\n    \"application\": \"my-llm-app\"\n})\n\ntrace_provider = TracerProvider(resource=resource)\n# For simplicity, using OTLP HTTP exporter. Adjust endpoint as needed.\nspan_exporter = OTLPSpanExporter(\n    endpoint=os.environ.get(\"OTEL_EXPORTER_OTLP_ENDPOINT\", \"http://localhost:4318/v1/traces\")\n)\ntrace_provider.add_span_processor(BatchSpanProcessor(span_exporter))\ntrace.set_tracer_provider(trace_provider)\n\n# Optional: Enable capturing full message content (e.g., prompts and responses)\nos.environ[\"OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT\"] = \"true\"\n\n# 2. Instrument Voyage AI\nVoyageAIInstrumentor().instrument()\n\n# 3. Use Voyage AI client\n# Ensure VOYAGE_API_KEY is set in your environment\nclient = voyageai.Client(api_key=os.environ.get(\"VOYAGE_API_KEY\", \"\"))\n\nif not client.api_key:\n    print(\"Error: VOYAGE_API_KEY environment variable not set. Please set it to run the example.\")\nelse:\n    try:\n        print(\"Sending embedding request...\")\n        embedding_response = client.embed(\n            texts=[\"What is the capital of France?\", \"Tell me about OpenTelemetry.\"],\n            model=\"voyage-large-2\"\n        )\n        print(\"Embedding response received (first 5 dimensions of first embedding):\")\n        if embedding_response.embeddings:\n            print(embedding_response.embeddings[0][:5], \"...\")\n\n    except Exception as e:\n        print(f\"An error occurred during Voyage AI embedding: {e}\")\n\n# Ensure spans are flushed before exit\ntrace_provider.shutdown()\nprint(\"Tracing finished. Check your OTLP endpoint for traces.\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Review 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.","message":"OpenTelemetry 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.","severity":"breaking","affected_versions":"All versions, particularly before 1.0 stable"},{"fix":"To enable full content capture, set the environment variable `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true`. Evaluate privacy implications before enabling in production environments.","message":"By default, sensitive message content (like prompts and responses) might not be captured in spans for security and privacy reasons.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Test thoroughly before deploying to production. Monitor release notes for any breaking changes or significant behavioral shifts.","message":"This 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.","severity":"gotcha","affected_versions":"All versions before 1.0"},{"fix":"Ensure your application initializes the OpenTelemetry SDK with a `TracerProvider`, `SpanProcessor`, and an appropriate exporter (e.g., `OTLPSpanExporter`) before making calls to the instrumented library.","message":"For 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}