Metadata-Version: 2.5
Name: opentelemetry-instrumentation-pixeltable
Version: 0.1.0
Summary: OpenTelemetry instrumentation for Pixeltable
Project-URL: homepage, https://pixeltable.com/
Project-URL: repository, https://github.com/pixeltable/pixeltable
Author-email: "Pixeltable, Inc." <contact@pixeltable.com>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.11
Requires-Dist: opentelemetry-api>=1.39.0
Requires-Dist: opentelemetry-instrumentation>=0.60b0
Requires-Dist: pixeltable>=0.7.4
Description-Content-Type: text/markdown

# OpenTelemetry instrumentation for Pixeltable

Translates [Pixeltable](https://pixeltable.com/)'s instrumentation hooks into OpenTelemetry spans and
metrics. Instrumentation is opt-in: Pixeltable itself never imports OpenTelemetry or activates telemetry on
its own.

```bash
pip install opentelemetry-instrumentation-pixeltable
# or, to also pull in the OpenTelemetry SDK and OTLP exporters that init() needs:
pip install 'pixeltable[otel]'
```

## Attach to an existing OpenTelemetry SDK

When your application already owns an OpenTelemetry SDK, attach Pixeltable to it:

```python
from opentelemetry.instrumentation.pixeltable import PixeltableInstrumentor

PixeltableInstrumentor().instrument()  # uses the global providers
# or: PixeltableInstrumentor().instrument(tracer_provider=my_tp, meter_provider=my_mp)
```

The standard `opentelemetry-instrument` CLI discovers and activates it automatically via its entry point.

## Let Pixeltable configure the SDK

To build providers and an OTLP exporter from Pixeltable's `[otel]` config (or the standard
`OTEL_EXPORTER_OTLP_*` environment variables), call `init()` once at startup (requires the
`pixeltable[otel]` extra):

```python
import opentelemetry.instrumentation.pixeltable as pxt_otel

pxt_otel.init(endpoint='http://localhost:4318')
```

Configuration is read from the database's `[[pixeltable.database]]` entry (`db_exporter_otlp_endpoint`,
`db_exporter_otlp_protocol`), then the standard `OTEL_EXPORTER_OTLP_*` environment variables, then the `[otel]`
section of Pixeltable's config (`~/.pixeltable/config.toml`).

## Per-provider LLM spans

This package emits Pixeltable's own operation, execution, and UDF spans. It does not capture per-provider
token usage or cost. To add rich provider spans (OpenAI, Anthropic, etc.), install a dedicated GenAI
instrumentor alongside this one:

```python
from opentelemetry.instrumentation.openai_v2 import OpenAIInstrumentor
from opentelemetry.instrumentation.pixeltable import PixeltableInstrumentor

PixeltableInstrumentor().instrument()
OpenAIInstrumentor().instrument()
```

Because Pixeltable establishes the ambient OpenTelemetry context for every UDF call (including across its
thread pools and async scheduler), the provider instrumentor's spans nest correctly under Pixeltable's
`udf.<name>` span. Prefer the bare `opentelemetry-instrumentation-*` packages (or OpenInference), which
attach to the global provider; avoid all-in-one initializers that install their own `TracerProvider` and
would clobber the one configured here.
