OpenTelemetry Pinecone Instrumentation

0.58.0 · active · verified Fri Apr 10

This library provides OpenTelemetry instrumentation for the Pinecone vector database client. It automatically captures spans and traces for operations, adhering to OpenTelemetry's Generative AI Semantic Conventions. As part of the `openllmetry` project, it follows a rapid release cycle, with the current version being 0.58.0.

Warnings

breaking Starting from version 0.53.0, this instrumentation switched from supporting the deprecated `pinecone-client` package to the newer `pinecone` (v2.x.x) package. If you are using an older version of the instrumentation or the older Pinecone client, ensure compatibility.
Fix: Upgrade your Pinecone client to `pinecone` (version 2.x.x or higher) and install `opentelemetry-instrumentation-pinecone` 0.53.0 or higher. If you must use `pinecone-client`, pin your instrumentation version to <0.53.0.
gotcha The `PineconeInstrumentor().instrument()` call only patches the `pinecone` library methods. To actually collect, process, and export telemetry data, you must configure an OpenTelemetry `TracerProvider` with appropriate `SpanProcessors` and `SpanExporters`.
Fix: Refer to the OpenTelemetry Python SDK documentation for full setup instructions, including configuring exporters like OTLP, Jaeger, or Zipkin.
gotcha The `pinecone` library itself is a peer dependency and is not installed automatically with `opentelemetry-instrumentation-pinecone`. You must explicitly install it.
Fix: Ensure `pip install pinecone` is run in your environment alongside the instrumentation package. Verify you are using `pinecone` v2.x.x+.

Install

pip install opentelemetry-instrumentation-pinecone pinecone opentelemetry-sdk Install with Pinecone client and OTel SDK

Imports

PineconeInstrumentor

from opentelemetry.instrumentation.pinecone import PineconeInstrumentor

Quickstart

This quickstart demonstrates how to set up basic OpenTelemetry console tracing and instrument the Pinecone client. Ensure you have the `pinecone` library (v2+) and OpenTelemetry SDK installed. Set `PINECONE_API_KEY` and `PINECONE_ENVIRONMENT` environment variables for a runnable example.

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.pinecone import PineconeInstrumentor
import pinecone

# 1. Setup OpenTelemetry Tracer Provider (for console output)
resource = Resource.create({"service.name": "my-pinecone-app"})
provider = TracerProvider(resource=resource)
span_processor = SimpleSpanProcessor(ConsoleSpanExporter())
provider.add_span_processor(span_processor)
trace.set_tracer_provider(provider)

# 2. Instrument Pinecone client calls
PineconeInstrumentor().instrument()

# 3. Use Pinecone as usual
api_key = os.environ.get("PINECONE_API_KEY", "YOUR_API_KEY")
environment = os.environ.get("PINECONE_ENVIRONMENT", "YOUR_ENVIRONMENT")

if api_key == "YOUR_API_KEY" or environment == "YOUR_ENVIRONMENT":
    print("Please set PINECONE_API_KEY and PINECONE_ENVIRONMENT environment variables.")
    print("Skipping Pinecone client interaction due to missing credentials.")
elif not pinecone.list_indexes: # Check if the package is the new pinecone library
    print("It appears you are using the old `pinecone-client` library. This instrumentation requires `pinecone` (v2+).")
    print("Skipping Pinecone client interaction.")
else:
    try:
        pinecone.init(api_key=api_key, environment=environment)
        
        # This operation will be traced
        indexes = pinecone.list_indexes()
        print(f"Pinecone Indexes: {indexes}")
        print("Check your console for OpenTelemetry traces!")
    except Exception as e:
        print(f"Error interacting with Pinecone: {e}")
        print("Ensure your Pinecone API Key and Environment are correct and that you are using `pinecone` v2+.")

view raw JSON →