> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://respan.ai/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://respan.ai/docs/_mcp/server.

# Pinecone (tracing)

> Trace Pinecone vector search operations with Respan — auto-instrumented spans and full observability.

[Pinecone](https://www.pinecone.io/) is a managed vector database designed for machine learning applications. It provides low-latency vector search at scale with features like namespaces, metadata filtering, and serverless deployment. Respan gives you full observability over every index operation, upsert, and query.

#### Set up Respan

Create an account at [platform.respan.ai](https://platform.respan.ai) and grab an [API key](https://platform.respan.ai/platform/gateway/api-keys).

Run `npx @respan/cli setup` to set up with your coding agent.

#### Example projects

* [Python examples](https://github.com/respanai/respan-example-projects/tree/main/python/tracing/pinecone)

#### Tracing

## Setup

#### Install packages

```bash
pip install respan-ai opentelemetry-instrumentation-pinecone pinecone
```

#### Set environment variables

```bash
export PINECONE_API_KEY="YOUR_PINECONE_API_KEY"
export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
```

`PINECONE_API_KEY` is used for Pinecone requests. `RESPAN_API_KEY` is used to export traces to Respan.

#### Initialize and run

```python
from pinecone import Pinecone, ServerlessSpec
from respan import Respan
from opentelemetry.instrumentation.pinecone import PineconeInstrumentor

respan = Respan(instrumentations=[PineconeInstrumentor()])

pc = Pinecone()

pc.create_index(
    name="documents",
    dimension=4,
    metric="cosine",
    spec=ServerlessSpec(cloud="aws", region="us-east-1"),
)
index = pc.Index("documents")

index.upsert(
    vectors=[
        {"id": "doc1", "values": [0.1, 0.2, 0.3, 0.4], "metadata": {"topic": "observability"}},
        {"id": "doc2", "values": [0.5, 0.6, 0.7, 0.8], "metadata": {"topic": "search"}},
        {"id": "doc3", "values": [0.2, 0.3, 0.4, 0.5], "metadata": {"topic": "embeddings"}},
    ],
    namespace="articles",
)

results = index.query(
    vector=[0.1, 0.2, 0.3, 0.4],
    top_k=2,
    namespace="articles",
    include_metadata=True,
)
for match in results["matches"]:
    print(f"{match['id']} (score: {match['score']:.4f}) — {match['metadata']['topic']}")

```

#### View your trace

Open the [Traces page](https://platform.respan.ai/platform/traces) to see your Pinecone operation spans.

## Configuration

| Parameter             | Type           | Default | Description                                                          |
| --------------------- | -------------- | ------- | -------------------------------------------------------------------- |
| `api_key`             | `str \| None`  | `None`  | Falls back to `RESPAN_API_KEY` env var.                              |
| `base_url`            | `str \| None`  | `None`  | Falls back to `RESPAN_BASE_URL` env var.                             |
| `instrumentations`    | `list`         | `[]`    | Plugin instrumentations to activate (e.g. `PineconeInstrumentor()`). |
| `customer_identifier` | `str \| None`  | `None`  | Default customer identifier for all spans.                           |
| `metadata`            | `dict \| None` | `None`  | Default metadata attached to all spans.                              |
| `environment`         | `str \| None`  | `None`  | Environment tag (e.g. `"production"`).                               |

## Attributes

### In Respan()

```python
from respan import Respan
from opentelemetry.instrumentation.pinecone import PineconeInstrumentor

respan = Respan(
    instrumentations=[PineconeInstrumentor()],
    customer_identifier="user_123",
    metadata={"service": "rag-api", "version": "1.0.0"},
)
```

### With propagate_attributes

```python
from respan import Respan, propagate_attributes
from opentelemetry.instrumentation.pinecone import PineconeInstrumentor

respan = Respan(instrumentations=[PineconeInstrumentor()])

def search(user_id: str, query_vector):
    with propagate_attributes(
        customer_identifier=user_id,
        thread_identifier="conv_abc_123",
        metadata={"plan": "pro"},
    ):
        return index.query(vector=query_vector, top_k=2, namespace="articles")
```

| Attribute             | Type   | Description                                           |
| --------------------- | ------ | ----------------------------------------------------- |
| `customer_identifier` | `str`  | Identifies the end user in Respan analytics.          |
| `thread_identifier`   | `str`  | Groups related messages into a conversation.          |
| `metadata`            | `dict` | Custom key-value pairs. Merged with default metadata. |