Metadata-Version: 2.4
Name: splunk-otel-instrumentation-weaviate
Version: 0.1.0
Summary: Splunk OpenTelemetry Weaviate instrumentation
Project-URL: Homepage, https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation-genai/opentelemetry-instrumentation-weaviate
Project-URL: Repository, https://github.com/open-telemetry/opentelemetry-python-contrib
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.9
Requires-Dist: opentelemetry-api~=1.38.0.dev0
Requires-Dist: opentelemetry-instrumentation~=0.59b0.dev0
Requires-Dist: opentelemetry-semantic-conventions~=0.59b0.dev0
Provides-Extra: instruments
Requires-Dist: weaviate-client<5.0.0,>=3.0.0; extra == 'instruments'
Provides-Extra: test
Requires-Dist: pytest-recording>=0.13.0; extra == 'test'
Requires-Dist: pytest>=7.0.0; extra == 'test'
Requires-Dist: vcrpy>=7.0.0; extra == 'test'
Description-Content-Type: text/x-rst

OpenTelemetry Weaviate Instrumentation
=======================================

|pypi|

.. |pypi| image:: https://badge.fury.io/py/splunk-otel-instrumentation-weaviate.svg
   :target: https://pypi.org/project/splunk-otel-instrumentation-weaviate/

This library allows tracing requests made by the Weaviate Python client to a Weaviate vector database.

Installation
------------

::

    pip install splunk-otel-instrumentation-weaviate


Usage
-----

When using the instrumentor, all Weaviate clients will automatically be instrumented.

.. code-block:: python

    from opentelemetry.instrumentation.weaviate import WeaviateInstrumentor
    import weaviate

    # Instrument Weaviate
    WeaviateInstrumentor().instrument()

    # This client will be automatically instrumented
    client = weaviate.connect_to_local()

    # Use the client as normal - all operations will be traced
    collection = client.collections.get("MyCollection")
    result = collection.query.fetch_objects(limit=10)


Configuration
-------------

Content Capture
***************

By default, document content from similarity search operations is **not** captured in span events.
To enable content capture, set the following environment variable:

.. code-block:: bash

    export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true

When enabled, similarity search operations will emit ``weaviate.document`` events containing:

* ``db.weaviate.document.content`` - The document content/properties
* ``db.weaviate.document.distance`` - Distance metric (if available)
* ``db.weaviate.document.certainty`` - Certainty score (if available)
* ``db.weaviate.document.score`` - Relevance score (if available)
* ``db.weaviate.document.query`` - The search query (if available)

The document count is always captured in the ``db.weaviate.documents.count`` span attribute regardless of this setting.


Examples
--------

The ``examples/manual/`` directory contains a working example:

* ``example_v4.py`` - Comprehensive example showing various Weaviate v4 operations with automatic tracing

Running the example
*******************

1. Install dependencies::

    pip install weaviate-client>=4.0.0 opentelemetry-sdk opentelemetry-exporter-otlp-proto-grpc

2. Start a local Weaviate instance::

    docker run -d -p 8080:8080 -p 50051:50051 cr.weaviate.io/semitechnologies/weaviate:latest

3. Run the example::

    cd examples/manual
    python3 example_v4.py

4. (Optional) Configure OTLP endpoint::

    export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4317"


Supported Versions
------------------

This instrumentation supports Weaviate client versions 3.x and 4.x.

References
----------

* `OpenTelemetry Weaviate Instrumentation <https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/weaviate/weaviate.html>`_
* `OpenTelemetry Project <https://opentelemetry.io/>`_
* `Weaviate Documentation <https://weaviate.io/developers/weaviate>`_
