Merge branch 'main' into docs/issue-3038

.github/workflows/generate_workflows_lib/src/generate_workflows_lib/misc.yml.j2

@@ -51,10 +51,10 @@ jobs:
         run: git checkout ${% raw %}{{ github.event.pull_request.head.sha }}{% endraw %}
       {%- endif %}
 
-      - name: Set up Python 3.10
+      - name: Set up Python 3.11
         uses: actions/setup-python@v5
         with:
-          python-version: "3.10"
+          python-version: "3.11"
 
       - name: Install tox
         run: pip install tox

.github/workflows/misc_0.yml

@@ -23,10 +23,10 @@ jobs:
       - name: Checkout repo @ SHA - ${{ github.sha }}
         uses: actions/checkout@v4
 
-      - name: Set up Python 3.10
+      - name: Set up Python 3.11
         uses: actions/setup-python@v5
         with:
-          python-version: "3.10"
+          python-version: "3.11"
 
       - name: Install tox
         run: pip install tox
@@ -41,10 +41,10 @@ jobs:
       - name: Checkout repo @ SHA - ${{ github.sha }}
         uses: actions/checkout@v4
 
-      - name: Set up Python 3.10
+      - name: Set up Python 3.11
         uses: actions/setup-python@v5
         with:
-          python-version: "3.10"
+          python-version: "3.11"
 
       - name: Install tox
         run: pip install tox
@@ -61,10 +61,10 @@ jobs:
       - name: Checkout repo @ SHA - ${{ github.sha }}
         uses: actions/checkout@v4
 
-      - name: Set up Python 3.10
+      - name: Set up Python 3.11
         uses: actions/setup-python@v5
         with:
-          python-version: "3.10"
+          python-version: "3.11"
 
       - name: Install tox
         run: pip install tox
@@ -79,10 +79,10 @@ jobs:
       - name: Checkout repo @ SHA - ${{ github.sha }}
         uses: actions/checkout@v4
 
-      - name: Set up Python 3.10
+      - name: Set up Python 3.11
         uses: actions/setup-python@v5
         with:
-          python-version: "3.10"
+          python-version: "3.11"
 
       - name: Install tox
         run: pip install tox
@@ -103,10 +103,10 @@ jobs:
       - name: Checkout repo @ SHA - ${{ github.sha }}
         uses: actions/checkout@v4
 
-      - name: Set up Python 3.10
+      - name: Set up Python 3.11
         uses: actions/setup-python@v5
         with:
-          python-version: "3.10"
+          python-version: "3.11"
 
       - name: Install tox
         run: pip install tox
@@ -124,10 +124,10 @@ jobs:
       - name: Checkout repo @ SHA - ${{ github.sha }}
         uses: actions/checkout@v4
 
-      - name: Set up Python 3.10
+      - name: Set up Python 3.11
         uses: actions/setup-python@v5
         with:
-          python-version: "3.10"
+          python-version: "3.11"
 
       - name: Install tox
         run: pip install tox
@@ -142,10 +142,10 @@ jobs:
       - name: Checkout repo @ SHA - ${{ github.sha }}
         uses: actions/checkout@v4
 
-      - name: Set up Python 3.10
+      - name: Set up Python 3.11
         uses: actions/setup-python@v5
         with:
-          python-version: "3.10"
+          python-version: "3.11"
 
       - name: Install tox
         run: pip install tox

CHANGELOG.md

@@ -13,6 +13,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- `opentelemetry-instrumentation-starlette` Add type hints to the instrumentation
+  ([#3045](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3045))
 - `opentelemetry-distro` default to OTLP log exporter.
   ([#3042](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3042))
 - `opentelemetry-instrumentation-sqlalchemy` Update unit tests to run with SQLALchemy 2
@@ -44,6 +46,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   ([#3022](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3022))
 - Replace all instrumentor unit test `assertEqualSpanInstrumentationInfo` calls with `assertEqualSpanInstrumentationScope` calls
   ([#3037](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3037))
+- `opentelemetry-instrumentation-sqlalchemy`: Fix a remaining memory leak in EngineTracer
+  ([#3053](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3053))
 
 ### Breaking changes
 

docs-requirements.txt

@@ -25,9 +25,11 @@ elasticsearch>=6.0,<9.0
 flask~=2.0
 falcon~=2.0
 grpcio~=1.27
+httpx>=0.18.0
 kafka-python>=2.0,<3.0
 mysql-connector-python~=8.0
 mysqlclient~=2.1.1
+openai >= 1.26.0
 psutil>=5
 psycopg~=3.1.17
 pika>=0.12.0
@@ -39,7 +41,6 @@ remoulade>=0.50
 sqlalchemy>=1.0
 tornado>=5.1.1
 tortoise-orm>=0.17.0
-httpx>=0.18.0
 
 # indirect dependency pins
 markupsafe==2.0.1

docs/conf.py

@@ -40,6 +40,13 @@
     if isdir(join(instr, f))
 ]
 
+instr_genai = "../instrumentation-genai"
+instr_genai_dirs = [
+    os.path.abspath("/".join(["../instrumentation-genai", f, "src"]))
+    for f in listdir(instr_genai)
+    if isdir(join(instr_genai, f))
+]
+
 prop = "../propagator"
 prop_dirs = [
     os.path.abspath("/".join([prop, f, "src"]))
@@ -60,7 +67,14 @@
     for f in listdir(resource)
     if isdir(join(resource, f))
 ]
-sys.path[:0] = exp_dirs + instr_dirs + sdk_ext_dirs + prop_dirs + resource_dirs
+sys.path[:0] = (
+    exp_dirs
+    + instr_dirs
+    + instr_genai_dirs
+    + sdk_ext_dirs
+    + prop_dirs
+    + resource_dirs
+)
 
 # -- Project information -----------------------------------------------------
 

docs/index.rst

@@ -24,7 +24,7 @@ installed separately via pip:
     pip install opentelemetry-instrumentation-{instrumentation}
     pip install opentelemetry-sdk-extension-{sdk-extension}
 
-A complete list of packages can be found at the 
+A complete list of packages can be found at the
 `Contrib repo instrumentation <https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation>`_
 and `Contrib repo exporter <https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/exporter>`_ directories.
 
@@ -50,6 +50,7 @@ install <https://pip.pypa.io/en/stable/reference/pip_install/#editable-installs>
     cd opentelemetry-python-contrib
     pip install -e ./instrumentation/opentelemetry-instrumentation-flask
     pip install -e ./instrumentation/opentelemetry-instrumentation-botocore
+    pip install -e ./instrumentation-genai/opentelemetry-instrumentation-openai-v2
     pip install -e ./sdk-extension/opentelemetry-sdk-extension-aws
     pip install -e ./resource/opentelemetry-resource-detector-container
 
@@ -62,6 +63,14 @@ install <https://pip.pypa.io/en/stable/reference/pip_install/#editable-installs>
 
     instrumentation/**
 
+.. toctree::
+    :maxdepth: 2
+    :caption: OpenTelemetry Generative AI Instrumentations
+    :name: Generative AI Instrumentations
+    :glob:
+
+    instrumentation-genai/**
+
 .. toctree::
     :maxdepth: 2
     :caption: OpenTelemetry Propagators

docs/instrumentation-genai/openai.rst

@@ -0,0 +1,7 @@
+OpenTelemetry Python - OpenAI Instrumentation
+=============================================
+
+.. automodule:: opentelemetry.instrumentation.openai_v2
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/instrumentation/aiohttp_server/aiohttp_server.rst

@@ -0,0 +1,7 @@
+.. include:: ../../../instrumentation/opentelemetry-instrumentation-aiohttp-server/README.rst
+    :end-before: References
+
+.. automodule:: opentelemetry.instrumentation.aiohttp_server
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/instrumentation/click/click.rst

@@ -0,0 +1,7 @@
+.. include:: ../../../instrumentation/opentelemetry-instrumentation-click/README.rst
+    :end-before: References
+
+.. automodule:: opentelemetry.instrumentation.click
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/nitpick-exceptions.ini

@@ -24,10 +24,12 @@ py-class=
     httpx.Client
     httpx.AsyncClient
     httpx.BaseTransport
+    openai.BaseTransport
     httpx.AsyncBaseTransport
     httpx.SyncByteStream
     httpx.AsyncByteStream
     httpx.Response
+    aiohttp.web_request.Request
     yarl.URL
     cimpl.Producer
     cimpl.Consumer
@@ -64,7 +66,7 @@ any=
 
 py-obj=
     opentelemetry.propagators.textmap.CarrierT
-    
+
 py-func=
     poll
     flush

instrumentation-genai/opentelemetry-instrumentation-openai-v2/README.rst

@@ -19,8 +19,60 @@ package to your requirements.
 
     pip install opentelemetry-instrumentation-openai-v2
 
-If you don't have an OpenAI application, yet, try our `example <example>`_
-which only needs a valid OpenAI API key.
+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 chat completion operations.
+You can also optionally capture prompts and completions as log events.
+
+Make sure to configure OpenTelemetry tracing, logging, and events to capture all telemetry emitted by the instrumentation.
+
+.. code-block:: python
+
+    from opentelemetry.instrumentation.openai_v2 import OpenAIInstrumentor
+
+    OpenAIInstrumentor().instrument()
+
+    client = OpenAI()
+    response = client.chat.completions.create(
+        model="gpt-4o-mini",
+        messages=[
+            {"role": "user", "content": "Write a short poem on open telemetry."},
+        ],
+    )
+
+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 as log events, set the environment variable
+`OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` to `true`.
+
+Uninstrument
+************
+
+To uninstrument clients, call the uninstrument method:
+
+.. code-block:: python
+
+    from opentelemetry.instrumentation.openai_v2 import OpenAIInstrumentor
+
+    OpenAIInstrumentor().instrument()
+    # ...
+
+    # Uninstrument all clients
+    OpenAIInstrumentor().uninstrument()
 
 References
 ----------

instrumentation-genai/opentelemetry-instrumentation-openai-v2/examples/manual/.env

@@ -0,0 +1,16 @@
+# Update this with your real OpenAI API key
+OPENAI_API_KEY=sk-YOUR_API_KEY
+
+# Uncomment to use Ollama instead of OpenAI
+# OPENAI_BASE_URL=http://localhost:11434/v1
+# OPENAI_API_KEY=unused
+# CHAT_MODEL=qwen2.5:0.5b
+
+# Uncomment and change to your OTLP endpoint
+# OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
+# OTEL_EXPORTER_OTLP_PROTOCOL=grpc
+
+OTEL_SERVICE_NAME=opentelemetry-python-openai
+
+# Change to 'false' to hide prompt and completion content
+OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true

instrumentation-genai/opentelemetry-instrumentation-openai-v2/example/README.rst → instrumentation-genai/opentelemetry-instrumentation-openai-v2/examples/manual/README.rst

@@ -1,21 +1,26 @@
 OpenTelemetry OpenAI Instrumentation Example
 ============================================
 
-This is an example of how to instrument OpenAI calls with zero code changes,
-using `opentelemetry-instrument`.
+This is an example of how to instrument OpenAI calls when configuring OpenTelemetry SDK and Instrumentations manually.
 
 When `main.py <main.py>`_ is run, it exports traces and logs to an OTLP
 compatible endpoint. Traces include details such as the model used and the
 duration of the chat request. Logs capture the chat request and the generated
 response, providing a comprehensive view of the performance and behavior of
 your OpenAI requests.
 
+Note: `.env <.env>`_ file configures additional environment variables:
+
+- `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true` configures
+OpenAI instrumentation to capture prompt and completion contents on
+events.
+
 Setup
 -----
 
 Minimally, update the `.env <.env>`_ file with your "OPENAI_API_KEY". An
 OTLP compatible endpoint should be listening for traces and logs on
-http://localhost:4318. If not, update "OTEL_EXPORTER_OTLP_ENDPOINT" as well.
+http://localhost:4317. If not, update "OTEL_EXPORTER_OTLP_ENDPOINT" as well.
 
 Next, set up a virtual environment like this:
 
@@ -33,7 +38,7 @@ Run the example like this:
 
 ::
 
-    dotenv run -- opentelemetry-instrument python main.py
+    dotenv run -- python main.py
 
 You should see a poem generated by OpenAI while traces and logs export to your
 configured observability tool.