Metadata-Version: 2.5
Name: observe-instrumentation-genai-openai
Version: 0.1.0
Summary: OpenAI instrumentation for Observe, emitting OpenTelemetry GenAI semantic conventions.
Project-URL: Homepage, https://github.com/snowflakedb/observe-otel-genai-python/tree/main/instrumentation/opentelemetry-instrumentation-genai-openai
Project-URL: Repository, https://github.com/snowflakedb/observe-otel-genai-python
Project-URL: Upstream, https://github.com/open-telemetry/opentelemetry-python-genai/tree/main/instrumentation/opentelemetry-instrumentation-genai-openai
Author: Snowflake Inc.
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
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
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Requires-Python: >=3.11
Requires-Dist: observe-util-genai<1,>=0.1.0
Requires-Dist: opentelemetry-api~=1.45
Requires-Dist: opentelemetry-instrumentation<1,>=0.64b0
Requires-Dist: opentelemetry-semantic-conventions<1,>=0.64b0
Provides-Extra: instruments
Requires-Dist: openai<4,>=1.26.0; extra == 'instruments'
Description-Content-Type: text/x-rst

Observe OpenAI Instrumentation
==============================

This library allows tracing LLM requests and logging of messages made by the
`OpenAI Python API library <https://pypi.org/project/openai/>`_. It also captures
the duration of the operations and the number of tokens used as metrics, and for
streaming chat completions the time to the first chunk and the time between output
chunks.

.. note::
   This package continues the project previously published as
   ``opentelemetry-instrumentation-openai-v2``

Many LLM platforms support the OpenAI SDK. This means systems such as the following are observable with this instrumentation when accessed using it:

.. list-table:: OpenAI Compatible Platforms
   :widths: 40 25
   :header-rows: 1

   * - Name
     - gen_ai.system
   * - `Azure OpenAI <https://github.com/openai/openai-python?tab=readme-ov-file#microsoft-azure-openai>`_
     - ``azure.ai.openai``
   * - `Gemini <https://developers.googleblog.com/en/gemini-is-now-accessible-from-the-openai-library/>`_
     - ``gemini``
   * - `Perplexity <https://docs.perplexity.ai/api-reference/>`_
     - ``perplexity``
   * - `xAI <https://x.ai/api>`_ (Compatible with Anthropic)
     - ``xai``
   * - `DeepSeek <https://api-docs.deepseek.com/>`_
     - ``deepseek``
   * - `Groq <https://console.groq.com/docs/openai>`_
     - ``groq``
   * - `MistralAI <https://docs.mistral.ai/api/>`_
     - ``mistral_ai``

This package is Observe's replacement for upstream's
``opentelemetry-instrumentation-genai-openai``, not an addition to it. The two
distributions install to the same paths, so an environment holding both gets a
per-file mix of them and uninstalling either one breaks the other. This package
depends on ``observe-util-genai``, which replaces upstream's
``opentelemetry-util-genai`` in the same way. Uninstall both upstream packages
first; an upstream instrumentation that still needs ``opentelemetry-util-genai``
cannot share an environment with this one.

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

If your application is already instrumented with OpenTelemetry, add this
package to your requirements:
::

    pip uninstall opentelemetry-instrumentation-genai-openai opentelemetry-util-genai
    pip install observe-instrumentation-genai-openai

If you don't have an OpenAI application, yet, try our `examples <examples>`_
which only need a valid OpenAI API key.

Check out `zero-code example <examples/zero-code>`_ for a quick start.

Usage
-----

This section describes how to set up OpenAI instrumentation if you're setting OpenTelemetry up manually.
Check out the `manual example <examples/manual>`_ for more details.

Instrumenting all clients
*************************

When using the instrumentor, all clients will automatically trace OpenAI operations including chat completions, the Responses API, and embeddings.
You can also optionally capture prompts and completions as log events.

Fetching a stored response with ``client.responses.retrieve(...)`` performs no
inference, so it is reported as a ``fetch_response`` operation rather than as an
inference call. Its span carries the fetched response's identifier, model,
status, and finish reasons, but no token usage — those counts belong to the
operation that originally generated the response.

Make sure to configure OpenTelemetry tracing, logging, and events to capture all telemetry emitted by the instrumentation.

.. code-block:: python

    from observeinc.instrumentation.genai.openai import OpenAIInstrumentor

    OpenAIInstrumentor().instrument()

    client = OpenAI()
    # Chat completion example
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[
            {"role": "user", "content": "Write a short poem on open telemetry."},
        ],
    )

    # Responses API example, fetching a stored response back by its id
    created = client.responses.create(
        model="gpt-4o-mini",
        input="Write a short poem on open telemetry.",
        store=True,
    )
    fetched = client.responses.retrieve(created.id)

    # Embeddings example
    embedding_response = client.embeddings.create(
        model="text-embedding-3-small",
        input="Generate vector embeddings for this text"
    )

Enabling message content
*************************

Message content such as the contents of the prompt, completion, function arguments and return values
are not captured by default. To capture message content, set the environment variable
``OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT`` to one of the following values:

- ``span_only`` - capture content on *span* attributes.
- ``event_only`` - capture content on *event* attributes.
- ``span_and_event`` - capture content on both *span* and *event* attributes.
- ``no_content`` - do not capture content (the default).

Uploading prompts and completions
*********************************

To enable the built-in upload hook, set:

- ``OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK=upload``
- ``OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATH`` to an ``fsspec``-compatible URI/path
  (e.g. ``/path/to/prompts`` or ``gs://my_bucket``).

Install the ``upload`` extra to pull in ``fsspec``::

    pip install "observe-util-genai[upload]"

See the `opentelemetry-util-genai
<https://github.com/open-telemetry/opentelemetry-python-contrib/blob/main/util/opentelemetry-util-genai/README.rst>`_
for additional options.

Enabling the latest experimental features
***********************************************

The latest experimental GenAI semantic conventions are used unconditionally; there is
no environment variable to opt in or out.

.. note:: Generative AI semantic conventions are still evolving. The latest experimental features may introduce breaking changes in future releases.

Uninstrument
************

To uninstrument clients, call the uninstrument method:

.. code-block:: python

    from observeinc.instrumentation.genai.openai import OpenAIInstrumentor

    OpenAIInstrumentor().instrument()
    # ...

    # Uninstrument all clients
    OpenAIInstrumentor().uninstrument()

References
----------

* `OpenTelemetry Project <https://opentelemetry.io/>`_
* `OpenTelemetry GenAI semantic conventions <https://opentelemetry.io/docs/specs/semconv/gen-ai/>`_
* `OpenAI SDK (Python) <https://github.com/openai/openai-python>`_
* `OpenAI Documentation <https://developers.openai.com/api/docs>`_
