Metadata-Version: 2.4
Name: palqee-prisma-otel
Version: 0.6.1
Summary: Prisma OpenTelemetry SDK - Lightweight wrapper for Oversight Intelligence platform
Author-email: Hartley Jean-Aime <hartley@palqee.com>
License-Expression: MIT
Requires-Python: >=3.10
Requires-Dist: opentelemetry-api>=1.21.0
Requires-Dist: opentelemetry-exporter-otlp>=1.21.0
Requires-Dist: opentelemetry-instrumentation>=0.42b0
Requires-Dist: opentelemetry-sdk>=1.21.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: anthropic
Requires-Dist: opentelemetry-instrumentation-anthropic<0.54,>=0.53.0; extra == 'anthropic'
Provides-Extra: bedrock
Requires-Dist: opentelemetry-instrumentation-bedrock<0.54,>=0.53.0; extra == 'bedrock'
Provides-Extra: dev
Requires-Dist: anthropic>=0.39.0; extra == 'dev'
Requires-Dist: boto3>=1.34.0; extra == 'dev'
Requires-Dist: botocore>=1.34.0; extra == 'dev'
Requires-Dist: commitizen>=3.10.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: opentelemetry-instrumentation-anthropic<0.54,>=0.53.0; extra == 'dev'
Requires-Dist: opentelemetry-instrumentation-bedrock<0.54,>=0.53.0; extra == 'dev'
Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://cdn.jsdelivr.net/gh/Palqee/prisma-brand-assets@v1/prisma/palqee_prisma_otel_banner_dark.png">
    <img width="2560" height="640" src="https://cdn.jsdelivr.net/gh/Palqee/prisma-brand-assets@v1/prisma/palqee_prisma_otel_banner_light.png" alt="Palqee Prisma OpenTelemetry SDK" />
  </picture>

  <p>Lightweight OpenTelemetry wrapper that ships traces and spans to the <a href="https://www.palqee.com/">Palqee Prisma</a> oversight intelligence platform.</p>

  <p>
    <a href="https://pypi.org/project/palqee-prisma-otel/"><img src="https://img.shields.io/pypi/v/palqee-prisma-otel.svg" alt="PyPI version" /></a>
    <a href="https://pypi.org/project/palqee-prisma-otel/"><img src="https://img.shields.io/pypi/pyversions/palqee-prisma-otel.svg" alt="Python versions" /></a>
    <a href="https://pypi.org/project/palqee-prisma-otel/"><img src="https://img.shields.io/pypi/l/palqee-prisma-otel.svg" alt="License" /></a>
    <a href="https://docs.palqee.com/docs/overview"><img src="https://img.shields.io/badge/docs-palqee.com-blue.svg" alt="Documentation" /></a>
  </p>
</div>

---

## What is this?

`palqee-prisma-otel` is the **transport layer** for getting OpenTelemetry traces into Palqee Prisma. It configures an OTLP HTTP exporter pre-wired to authenticate against Prisma's Receiver and tag every span with the resource attributes Prisma uses to route traces to the right run and project.

Most applications should reach for [`palqee-prisma-ai`](https://pypi.org/project/palqee-prisma-ai/) — the high-level SDK that bundles this wrapper, attaches validators, and exposes a one-line `init()`. Pick `palqee-prisma-otel` directly when you need:

- **Tracing without the full SDK** — sidecars, batch jobs, or libraries that emit spans but never call validators.
- **An existing OpenTelemetry setup** — you already configure tracers, processors, and propagators yourself, and just need a Prisma-aware exporter.
- **Tight control over span emission** — long-lived services that manage their own `TracerProvider` lifecycle.

## Installation

```bash
pip install palqee-prisma-otel
```

Imports as `palqee_prisma_otel`:

```python
from palqee_prisma_otel import configure_tracing
```

Requires Python 3.10+.

## Quickstart

```python
import os
from palqee_prisma_otel import configure_tracing

configure_tracing(
    api_key=os.environ["PALQEE_PRISMA_API_KEY"],
    service_name="complaints-review",
    run_id="run-abc123",         # routes spans to this run in Prisma
    project_id="proj-xyz789",    # routes spans to this project in Prisma
)

# Any OpenTelemetry span emitted from here on flows to Prisma.
from opentelemetry import trace

tracer = trace.get_tracer(__name__)
with tracer.start_as_current_span("review.case") as span:
    span.set_attribute("case.id", "CMP-2025-0001")
    ...
```

With `PALQEE_PRISMA_API_KEY` and `PALQEE_PRISMA_OTEL_ENDPOINT` set, the call collapses to `configure_tracing(service_name="...")`.

## What gets exported

Once configured, every span emitted by your process — from your own code or from any OpenTelemetry instrumentation library — flows to Prisma over OTLP HTTP. That includes spans from popular LLM instrumentation:

| Provider / framework | Instrumentation |
|----------------------|-----------------|
| OpenAI, Anthropic Claude, Meta Llama, Bedrock, Gemini | [OpenInference](https://github.com/Arize-ai/openinference) or [OpenLLMetry](https://github.com/traceloop/openllmetry) |
| LangChain, LangGraph | OpenInference / OpenLLMetry |
| LlamaIndex | OpenInference |
| CrewAI, AutoGen, Haystack | OpenLLMetry |
| Custom code | `opentelemetry-api` spans |

`palqee-prisma-otel` does **not** install instrumentation libraries — pick the ones you want and install them alongside.

## Configuration

| Parameter | Environment variable | Default | Description |
|-----------|---------------------|---------|-------------|
| `api_key` | `PALQEE_PRISMA_API_KEY` | required | Sent as `x-api-key` header to the Prisma Receiver |
| `endpoint` | `PALQEE_PRISMA_OTEL_ENDPOINT` | `https://otel.prisma.ai:4318` | OTLP HTTP endpoint of your Prisma deployment |
| `service_name` | — | `"prisma-app"` | OTEL `service.name` resource attribute |
| `run_id` | — | `None` | Attached as `prisma.run.id` for trace-to-run routing |
| `project_id` | — | `None` | Attached as `prisma.project.id` for trace-to-project routing |

Full configuration reference: [docs.palqee.com/docs/overview](https://docs.palqee.com/docs/overview).

## Features

- **Authenticated OTLP export** — `x-api-key` header pre-wired to the Prisma Receiver.
- **HTTP transport** — uses the standard `opentelemetry-exporter-otlp-proto-http` exporter.
- **Batch span processing** — efficient buffered export, no per-call network overhead.
- **Resource attributes** — `prisma.run.id` and `prisma.project.id` for server-side routing.
- **Environment-first** — runs in 12-factor / containerized deployments without code changes.

## When to use this vs `palqee-prisma-ai`

| Need | Reach for |
|------|-----------|
| Instrument an app, run validators, ship to Prisma in one call | [`palqee-prisma-ai`](https://pypi.org/project/palqee-prisma-ai/) |
| Send OpenTelemetry spans to Prisma from an existing OTEL setup | `palqee-prisma-otel` (this package) |
| Both | The SDK uses this wrapper under the hood — installing the SDK is enough |

## Links

- **Documentation:** [docs.palqee.com/docs/overview](https://docs.palqee.com/docs/overview)
- **High-level SDK:** [`palqee-prisma-ai`](https://pypi.org/project/palqee-prisma-ai/)
- **Platform client:** [`palqee-prisma-client`](https://pypi.org/project/palqee-prisma-client/)
- **Website:** [palqee.com](https://www.palqee.com/)
- **Support:** [support@palqee.com](mailto:support@palqee.com)

## License

[MIT](./LICENSE) © Palqee
