Merge branch 'main' into deprecate_events

Author: xrmx

.pre-commit-config.yaml

@@ -1,7 +1,7 @@
 repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
     # Ruff version.
-    rev: v0.6.9
+    rev: v0.14.1
     hooks:
       # Run the linter.
       - id: ruff

CHANGELOG.md

@@ -12,12 +12,72 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+- docs: Added sqlcommenter example
+  ([#4734](https://github.com/open-telemetry/opentelemetry-python/pull/4734))
+- build: bump ruff to 0.14.1
+  ([#4782](https://github.com/open-telemetry/opentelemetry-python/pull/4782))
+- Add `opentelemetry-exporter-credential-provider-gcp` as an optional dependency to `opentelemetry-exporter-otlp-proto-grpc` 
+  and `opentelemetry-exporter-otlp-proto-http` 
+  ([#4760](https://github.com/open-telemetry/opentelemetry-python/pull/4760))
+- semantic-conventions: Bump to 1.38.0
+  ([#4791](https://github.com/open-telemetry/opentelemetry-python/pull/4791))
+- [BREAKING] Remove LogData and extend SDK LogRecord to have instrumentation scope
+  ([#4676](https://github.com/open-telemetry/opentelemetry-python/pull/4676))
+- [BREAKING] Rename several classes from Log to LogRecord
+  ([#4647](https://github.com/open-telemetry/opentelemetry-python/pull/4647))
+  
+  **Migration Guide:**
+  
+  `LogData` has been removed. Users should update their code as follows:
+  
+  - **For Log Exporters:** Change from `Sequence[LogData]` to `Sequence[ReadableLogRecord]`
+    ```python
+    # Before
+    from opentelemetry.sdk._logs import LogData
+    def export(self, batch: Sequence[LogData]) -> LogRecordExportResult:
+        ...
+    
+    # After
+    from opentelemetry.sdk._logs import ReadableLogRecord
+    def export(self, batch: Sequence[ReadableLogRecord]) -> LogRecordExportResult:
+        ...
+    ```
+  
+  - **For Log Processors:** Use `ReadWriteLogRecord` for processing, `ReadableLogRecord` for exporting
+    ```python
+    # Before
+    from opentelemetry.sdk._logs import LogData
+    def on_emit(self, log_data: LogData):
+        ...
+    
+    # After
+    from opentelemetry.sdk._logs import ReadWriteLogRecord, ReadableLogRecord
+    def on_emit(self, log_record: ReadWriteLogRecord):
+        # Convert to ReadableLogRecord before exporting
+        readable = ReadableLogRecord(
+            log_record=log_record.log_record,
+            resource=log_record.resource or Resource.create({}),
+            instrumentation_scope=log_record.instrumentation_scope,
+            limits=log_record.limits,
+        )
+        ...
+    ```
+  
+  - **Accessing log data:** Use the same attributes on `ReadableLogRecord`/`ReadWriteLogRecord`
+    - `log_record.log_record` - The API LogRecord (contains body, severity, attributes, etc.)
+    - `log_record.resource` - The Resource
+    - `log_record.instrumentation_scope` - The InstrumentationScope (now included, was in LogData before)
+    - `log_record.limits` - The LogRecordLimits
+- Mark the Events API/SDK as deprecated. The Logs API/SDK should be used instead, an event is now a `LogRecord` with the `event_name` field set
+([#4654](https://github.com/open-telemetry/opentelemetry-python/pull/4654)).
+
+## Version 1.38.0/0.59b0 (2025-10-16)
+
 - Add `rstcheck` to pre-commit to stop introducing invalid RST
   ([#4755](https://github.com/open-telemetry/opentelemetry-python/pull/4755))
 - logs: extend Logger.emit to accept separated keyword arguments
   ([#4737](https://github.com/open-telemetry/opentelemetry-python/pull/4737))
-- Mark the Events API/SDK as deprecated. The Logs API/SDK should be used instead. An event is now a `LogRecord` with the `event_name` field set
-([#4654](https://github.com/open-telemetry/opentelemetry-python/pull/4654)).
+
 
 ## Version 1.37.0/0.58b0 (2025-09-11)
 

CONTRIBUTING.md

@@ -1,11 +1,10 @@
 # Contributing to opentelemetry-python
-
-The Python special interest group (SIG) meets weekly on Thursdays at 9AM PST. Check the [OpenTelemetry community calendar](https://calendar.google.com/calendar/embed?src=google.com_b79e3e90j7bbsa2n2p5an5lf60%40group.calendar.google.com) for specific dates and Zoom meeting links.
+The Python special interest group (SIG) meets weekly on Thursdays at 9AM PST. Check the [OpenTelemetry community calendar](https://groups.google.com/a/opentelemetry.io/g/calendar-python) for specific dates and Zoom meeting links.
 
 See the [public meeting notes](https://docs.google.com/document/d/1CIMGoIOZ-c3-igzbd6_Pnxx1SjAkjwqoYSUWxPY8XIs/edit)
 for a summary description of past meetings.
 
-See to the [community membership document](https://github.com/open-telemetry/community/blob/main/community-membership.md)
+See the [community membership document](https://github.com/open-telemetry/community/blob/main/community-membership.md)
 on how to become a [**Member**](https://github.com/open-telemetry/community/blob/main/community-membership.md#member),
 [**Approver**](https://github.com/open-telemetry/community/blob/main/community-membership.md#approver)
 and [**Maintainer**](https://github.com/open-telemetry/community/blob/main/community-membership.md#maintainer).
@@ -276,7 +275,7 @@ to your PR, can still happen.
 
 Right now Github [does not allow](https://github.com/orgs/community/discussions/5634) PRs
 to be edited by maintainers if the corresponding repo fork exists in a Github organization.
-Please for this repo in a personal Github account instead.
+Please fork this repo in a personal Github account instead.
 
 One of the maintainers will merge the PR once it is **ready to merge**.
 

README.md

@@ -113,6 +113,7 @@ For more information about the maintainer role, see the [community repository](h
 - [Dylan Russell](https://github.com/dylanrussell), Google
 - [Emídio Neto](https://github.com/emdneto), PicPay
 - [Jeremy Voss](https://github.com/jeremydvoss), Microsoft
+- [Liudmila Molkova](https://github.com/lmolkova), Grafana Labs
 - [Owais Lone](https://github.com/owais), Splunk
 - [Pablo Collins](https://github.com/pmcollins), Splunk
 - [Shalev Roda](https://github.com/shalevr), Cisco
@@ -125,7 +126,7 @@ For more information about the approver role, see the [community repository](htt
 
 - [Alex Boten](https://github.com/codeboten)
 - [Chris Kleinknecht](https://github.com/c24t)
-- [Diego Hurtado](https://github.com/ocelotl), Lightstep
+- [Diego Hurtado](https://github.com/ocelotl)
 - [Owais Lone](https://github.com/owais)
 - [Reiley Yang](https://github.com/reyang)
 - [Srikanth Chekuri](https://github.com/srikanthccv)

dev-requirements.txt

@@ -17,4 +17,4 @@ psutil==5.9.6
 GitPython==3.1.41
 pre-commit==3.7.0; python_version >= '3.9'
 pre-commit==3.5.0; python_version < '3.9'
-ruff==0.6.9
+ruff==0.14.1

docs/conf.py

@@ -100,6 +100,7 @@
     ("py:class", "CarrierT"),
     ("py:obj", "opentelemetry.propagators.textmap.CarrierT"),
     ("py:obj", "Union"),
+    ("py:data", "typing.Union"),
     (
         "py:class",
         "opentelemetry.sdk.metrics._internal.instrument._Synchronous",
@@ -144,8 +145,11 @@
         "py:class",
         "opentelemetry.proto.collector.metrics.v1.metrics_service_pb2.ExportMetricsServiceRequest",
     ),
-    ("py:class", "opentelemetry.sdk._logs._internal.export.LogExporter"),
-    ("py:class", "opentelemetry.sdk._logs._internal.export.LogExportResult"),
+    ("py:class", "opentelemetry.sdk._logs._internal.export.LogRecordExporter"),
+    (
+        "py:class",
+        "opentelemetry.sdk._logs._internal.export.LogRecordExportResult",
+    ),
     (
         "py:class",
         "opentelemetry.proto.collector.logs.v1.logs_service_pb2.ExportLogsServiceRequest",

docs/examples/django/manage.py

@@ -30,7 +30,9 @@ def main():
     DjangoInstrumentor().instrument()
 
     try:
-        from django.core.management import execute_from_command_line
+        from django.core.management import (  # noqa: PLC0415
+            execute_from_command_line,
+        )
     except ImportError as exc:
         raise ImportError(
             "Couldn't import Django. Are you sure it's installed and "

docs/examples/metrics/prometheus-grafana/README.rst

@@ -3,7 +3,7 @@ Prometheus Instrumentation
 
 This shows how to use ``opentelemetry-exporter-prometheus`` to automatically generate Prometheus metrics.
 
-The source files of these examples are available :scm_web:`here <docs/examples/prometheus-grafana/>`.
+The source files of these examples are available :scm_web:`here <docs/examples/metrics/prometheus-grafana/>`.
 
 Preparation
 -----------

docs/examples/sqlcommenter/README.rst

@@ -0,0 +1,124 @@
+sqlcommenter
+============
+
+This is an example of how to use OpenTelemetry Python instrumention with
+sqlcommenter to enrich database query statements with contextual information.
+For more information on sqlcommenter concepts, see:
+
+* `Semantic Conventions - Database Spans <https://github.com/open-telemetry/semantic-conventions/blob/main/docs/database/database-spans.md#sql-commenter>`_
+* `sqlcommenter <https://google.github.io/sqlcommenter/>`_
+
+The source files of this example are available `here <https://github.com/open-telemetry/opentelemetry-python/tree/main/docs/examples/sqlcommenter/>`_.
+This example uses Docker to manage a database server and OpenTelemetry collector.
+
+Run MySQL server
+----------------
+
+A running MySQL server with general logs enabled will store query statements with context resulting from the sqlcommenter feature enabled in this example.
+
+.. code-block:: sh
+
+    cd books_database
+    docker build -t books-db .
+    docker run -d --name books-db -p 3366:3306 books-db
+    cd ..
+
+Check that the run is working and the general log is available:
+
+.. code-block:: sh
+
+    docker exec -it books-db tail -f /var/log/general.log
+
+Run OpenTelemetry Collector
+---------------------------
+
+Running the OpenTelemetry collector will show the MySQL instrumentor's
+comment-in-span-attribute feature, which this example has also enabled.
+
+.. code-block:: sh
+
+    docker run \
+        -p 4317:4317 \
+        -v $(pwd)/collector-config.yaml:/etc/otel/config.yaml \
+        otel/opentelemetry-collector-contrib:latest
+
+Run the sqlcommenter example
+----------------------------
+
+Set up and activate a Python virtual environment. Install these
+dependencies of the sqlcommenter example:
+
+.. code-block:: sh
+
+    pip install opentelemetry-sdk \
+        opentelemetry-exporter-otlp-proto-grpc \
+        opentelemetry-instrumentation-mysql \
+        mysql-connector-python
+
+Then, run this script, which instruments all mysql-connector calls with
+two sqlcommenter features opted in.
+
+.. code-block:: sh
+
+    python instrumented_query.py
+
+Note that OpenTelemetry instrumentation with sqlcommenter is also
+available for other Python database client drivers/object relation
+mappers (ORMs). See full list at `instrumentation`_.
+
+.. _instrumentation: https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation
+
+Check MySQL server general log and spans for sqlcomment
+-------------------------------------------------------
+
+After running the query script, check the MySQL general log contents:
+
+.. code-block:: sh
+
+    docker exec -it books-db tail -f /var/log/general.log
+
+For each instrumented ``SELECT`` call, a query was made and logged with
+a sqlcomment appended. For example:
+
+.. code::
+
+    2025-09-02T18:49:06.981980Z	  186 Query	SELECT * FROM authors WHERE id = 1 /*db_driver='mysql.connector%%3A9.4.0',dbapi_level='2.0',dbapi_threadsafety=1,driver_paramstyle='pyformat',mysql_client_version='9.4.0',traceparent='00-2c45248f2beefdd9688b0a94eb4ac9ee-4f3af9a825aae9b1-01'*/
+
+In the running OpenTelemetry collector, you'll also see one span per
+``SELECT`` call. Each of those span's trace ID and span ID will
+correspond to a query log sqlcomment. With the comment-in-attribute
+feature enabled, the span's ``db.statement`` attribute will also contain
+the sqlcomment. For example:
+
+.. code::
+
+    ScopeSpans #0
+    ScopeSpans SchemaURL: https://opentelemetry.io/schemas/1.11.0
+    InstrumentationScope opentelemetry.instrumentation.mysql 0.57b0
+    Span #0
+        Trace ID       : 2c45248f2beefdd9688b0a94eb4ac9ee
+        Parent ID      :
+        ID             : 4f3af9a825aae9b1
+        Name           : SELECT
+        Kind           : Client
+        Start time     : 2025-09-02 18:49:06.982341 +0000 UTC
+        End time       : 2025-09-02 18:49:06.98463 +0000 UTC
+        Status code    : Unset
+        Status message :
+    Attributes:
+        -> db.system: Str(mysql)
+        -> db.name: Str(books)
+        -> db.statement: Str(SELECT * FROM authors WHERE id = %s /*db_driver='mysql.connector%%3A9.4.0',dbapi_level='2.0',dbapi_threadsafety=1,driver_paramstyle='pyformat',mysql_client_version='9.4.0',traceparent='00-2c45248f2beefdd9688b0a94eb4ac9ee-4f3af9a825aae9b1-01'*/)
+        -> db.user: Str(books)
+        -> net.peer.name: Str(localhost)
+        -> net.peer.port: Int(3366)
+
+
+References
+----------
+
+* `OpenTelemetry Project <https://opentelemetry.io/>`_
+* `OpenTelemetry Collector <https://github.com/open-telemetry/opentelemetry-collector>`_
+* `OpenTelemetry MySQL instrumentation <https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-mysql>`_
+* `Semantic Conventions - Database Spans <https://github.com/open-telemetry/semantic-conventions/blob/main/docs/database/database-spans.md#sql-commenter>`_
+* `sqlcommenter <https://google.github.io/sqlcommenter/>`_

docs/examples/sqlcommenter/books_database/Dockerfile

@@ -0,0 +1,23 @@
+FROM mysql:8.0
+
+ENV MYSQL_ROOT_PASSWORD=root
+ENV MYSQL_DATABASE=books
+
+ADD books.sql /docker-entrypoint-initdb.d/
+
+RUN echo "CREATE USER IF NOT EXISTS 'books'@'%' IDENTIFIED WITH mysql_native_password BY 'books123';" > /docker-entrypoint-initdb.d/01-create-user.sql && \
+    echo "GRANT ALL PRIVILEGES ON books.* TO 'books'@'%';" >> /docker-entrypoint-initdb.d/01-create-user.sql && \
+    echo "FLUSH PRIVILEGES;" >> /docker-entrypoint-initdb.d/01-create-user.sql
+
+# Prepare general logs
+RUN mkdir -p /var/log && \
+    touch /var/log/general.log && \
+    chown mysql:mysql /var/log/general.log
+
+EXPOSE 3306
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=5s --retries=3 \
+    CMD mysqladmin ping -p${MYSQL_ROOT_PASSWORD} || exit 1
+
+# Start MySQL with general logging enabled and compatible authentication
+CMD ["mysqld", "--general-log=1", "--general-log-file=/var/log/general.log"]