diff --git a/CHANGELOG.md b/CHANGELOG.md index 9caae022c6..01a840094e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,8 +18,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - `opentelemetry-instrumentation-asgi`: Make all user hooks failsafe and record exceptions in hooks. ([#3664](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3664)) - `opentelemetry-instrumentation-fastapi`: Fix memory leak in `uninstrument_app()` by properly removing apps from the tracking set - ([#3688](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3688) -- `opentelemetry-instrumentation-tornado`: Fix server (request) duration metric calculation + ([#3688](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3688)) +- `opentelemetry-instrumentation-tornado` Fix server (request) duration metric calculation ([#3679](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3679)) - `opentelemetry-instrumentation-tornado`: Fix to properly skip all server telemetry when URL excluded. ([#3680](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3680)) @@ -27,6 +27,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ([#3673](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3673)) - `opentelemetry-instrumentation-starlette`/`opentelemetry-instrumentation-fastapi`: Fixes a crash when host-based routing is used ([#3507](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3507)) +- Fix documentation order of sections and headers for Django, Flask, MySQL, mysqlclient, psycopg, psycopg2, pymysql, sqlalchemy instrumentations. + ([#3719](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3719)) ### Added diff --git a/instrumentation/opentelemetry-instrumentation-django/src/opentelemetry/instrumentation/django/__init__.py b/instrumentation/opentelemetry-instrumentation-django/src/opentelemetry/instrumentation/django/__init__.py index 7d92aff145..ebc3e08f4d 100644 --- a/instrumentation/opentelemetry-instrumentation-django/src/opentelemetry/instrumentation/django/__init__.py +++ b/instrumentation/opentelemetry-instrumentation-django/src/opentelemetry/instrumentation/django/__init__.py @@ -17,68 +17,6 @@ .. _django: https://pypi.org/project/django/ -SQLCOMMENTER -***************************************** -You can optionally configure Django instrumentation to enable sqlcommenter which enriches -the query with contextual information. - -Usage ------ - -.. code:: python - - from opentelemetry.instrumentation.django import DjangoInstrumentor - - DjangoInstrumentor().instrument(is_sql_commentor_enabled=True) - - -For example, -:: - - Invoking Users().objects.all() will lead to sql query "select * from auth_users" but when SQLCommenter is enabled - the query will get appended with some configurable tags like "select * from auth_users /*metrics=value*/;" - - -SQLCommenter Configurations -*************************** -We can configure the tags to be appended to the sqlquery log by adding below variables to the settings.py - -SQLCOMMENTER_WITH_FRAMEWORK = True(Default) or False - -For example, -:: -Enabling this flag will add django framework and it's version which is /*framework='django%3A2.2.3*/ - -SQLCOMMENTER_WITH_CONTROLLER = True(Default) or False - -For example, -:: -Enabling this flag will add controller name that handles the request /*controller='index'*/ - -SQLCOMMENTER_WITH_ROUTE = True(Default) or False - -For example, -:: -Enabling this flag will add url path that handles the request /*route='polls/'*/ - -SQLCOMMENTER_WITH_APP_NAME = True(Default) or False - -For example, -:: -Enabling this flag will add app name that handles the request /*app_name='polls'*/ - -SQLCOMMENTER_WITH_OPENTELEMETRY = True(Default) or False - -For example, -:: -Enabling this flag will add opentelemetry traceparent /*traceparent='00-fd720cffceba94bbf75940ff3caaf3cc-4fd1a2bdacf56388-01'*/ - -SQLCOMMENTER_WITH_DB_DRIVER = True(Default) or False - -For example, -:: -Enabling this flag will add name of the db driver /*db_driver='django.db.backends.postgresql'*/ - Usage ----- @@ -232,6 +170,65 @@ def response_hook(span, request, response): Note: The environment variable names used to capture HTTP headers are still experimental, and thus are subject to change. +SQLCOMMENTER +***************************************** +You can optionally configure Django instrumentation to enable sqlcommenter which enriches +the query with contextual information. + +.. code:: python + + from opentelemetry.instrumentation.django import DjangoInstrumentor + + DjangoInstrumentor().instrument(is_sql_commentor_enabled=True) + + +For example, +:: + + Invoking Users().objects.all() will lead to sql query "select * from auth_users" but when SQLCommenter is enabled + the query will get appended with some configurable tags like "select * from auth_users /*metrics=value*/;" + + +SQLCommenter Configurations +*************************** +We can configure the tags to be appended to the sqlquery log by adding below variables to the settings.py + +SQLCOMMENTER_WITH_FRAMEWORK = True(Default) or False + +For example, +:: +Enabling this flag will add django framework and it's version which is /*framework='django%3A2.2.3*/ + +SQLCOMMENTER_WITH_CONTROLLER = True(Default) or False + +For example, +:: +Enabling this flag will add controller name that handles the request /*controller='index'*/ + +SQLCOMMENTER_WITH_ROUTE = True(Default) or False + +For example, +:: +Enabling this flag will add url path that handles the request /*route='polls/'*/ + +SQLCOMMENTER_WITH_APP_NAME = True(Default) or False + +For example, +:: +Enabling this flag will add app name that handles the request /*app_name='polls'*/ + +SQLCOMMENTER_WITH_OPENTELEMETRY = True(Default) or False + +For example, +:: +Enabling this flag will add opentelemetry traceparent /*traceparent='00-fd720cffceba94bbf75940ff3caaf3cc-4fd1a2bdacf56388-01'*/ + +SQLCOMMENTER_WITH_DB_DRIVER = True(Default) or False + +For example, +:: +Enabling this flag will add name of the db driver /*db_driver='django.db.backends.postgresql'*/ + API --- diff --git a/instrumentation/opentelemetry-instrumentation-flask/src/opentelemetry/instrumentation/flask/__init__.py b/instrumentation/opentelemetry-instrumentation-flask/src/opentelemetry/instrumentation/flask/__init__.py index 12db5b9a68..5744e5cc96 100644 --- a/instrumentation/opentelemetry-instrumentation-flask/src/opentelemetry/instrumentation/flask/__init__.py +++ b/instrumentation/opentelemetry-instrumentation-flask/src/opentelemetry/instrumentation/flask/__init__.py @@ -24,58 +24,6 @@ * The ``http.route`` Span attribute is set so that one can see which URL rule matched a request. -SQLCOMMENTER -***************************************** -You can optionally configure Flask instrumentation to enable sqlcommenter which enriches -the query with contextual information. - -Usage ------ - -.. code:: python - - from opentelemetry.instrumentation.flask import FlaskInstrumentor - - FlaskInstrumentor().instrument(enable_commenter=True, commenter_options={}) - -For example, FlaskInstrumentor when used with SQLAlchemyInstrumentor or Psycopg2Instrumentor, -invoking ``cursor.execute("select * from auth_users")`` will lead to sql query -``select * from auth_users`` but when SQLCommenter is enabled the query will get appended with -some configurable tags like: - -.. code:: - - select * from auth_users /*metrics=value*/;" - -Inorder for the commenter to append flask related tags to sql queries, the commenter needs -to enabled on the respective SQLAlchemyInstrumentor or Psycopg2Instrumentor framework too. - -SQLCommenter Configurations -*************************** -We can configure the tags to be appended to the sqlquery log by adding configuration -inside ``commenter_options={}`` dict. - -For example, enabling this flag will add flask and it's version which -is ``/*flask%%3A2.9.3*/`` to the SQL query as a comment (default is True): - -.. code:: python - - framework = True - -For example, enabling this flag will add route uri ``/*route='/home'*/`` -to the SQL query as a comment (default is True): - -.. code:: python - - route = True - -For example, enabling this flag will add controller name ``/*controller='home_view'*/`` -to the SQL query as a comment (default is True): - -.. code:: python - - controller = True - Usage ----- @@ -241,6 +189,55 @@ def response_hook(span: Span, status: str, response_headers: List): Note: The environment variable names used to capture HTTP headers are still experimental, and thus are subject to change. +SQLCOMMENTER +***************************************** +You can optionally configure Flask instrumentation to enable sqlcommenter which enriches +the query with contextual information. + +.. code:: python + + from opentelemetry.instrumentation.flask import FlaskInstrumentor + + FlaskInstrumentor().instrument(enable_commenter=True, commenter_options={}) + +For example, FlaskInstrumentor when used with SQLAlchemyInstrumentor or Psycopg2Instrumentor, +invoking ``cursor.execute("select * from auth_users")`` will lead to sql query +``select * from auth_users`` but when SQLCommenter is enabled the query will get appended with +some configurable tags like: + +.. code:: + + select * from auth_users /*metrics=value*/;" + +Inorder for the commenter to append flask related tags to sql queries, the commenter needs +to enabled on the respective SQLAlchemyInstrumentor or Psycopg2Instrumentor framework too. + +SQLCommenter Configurations +*************************** +We can configure the tags to be appended to the sqlquery log by adding configuration +inside ``commenter_options={}`` dict. + +For example, enabling this flag will add flask and it's version which +is ``/*flask%%3A2.9.3*/`` to the SQL query as a comment (default is True): + +.. code:: python + + framework = True + +For example, enabling this flag will add route uri ``/*route='/home'*/`` +to the SQL query as a comment (default is True): + +.. code:: python + + route = True + +For example, enabling this flag will add controller name ``/*controller='home_view'*/`` +to the SQL query as a comment (default is True): + +.. code:: python + + controller = True + API --- """ diff --git a/instrumentation/opentelemetry-instrumentation-mysql/src/opentelemetry/instrumentation/mysql/__init__.py b/instrumentation/opentelemetry-instrumentation-mysql/src/opentelemetry/instrumentation/mysql/__init__.py index e967a1a2ea..0d30036707 100644 --- a/instrumentation/opentelemetry-instrumentation-mysql/src/opentelemetry/instrumentation/mysql/__init__.py +++ b/instrumentation/opentelemetry-instrumentation-mysql/src/opentelemetry/instrumentation/mysql/__init__.py @@ -50,13 +50,13 @@ cursor.close() instrumented_cnx.close() +Configuration +------------- + SQLCOMMENTER ***************************************** You can optionally configure mysql-connector instrumentation to enable sqlcommenter which enriches the query with contextual information. -Usage ------ - .. code:: python import mysql.connector @@ -70,7 +70,6 @@ cursor.close() cnx.close() - For example, :: diff --git a/instrumentation/opentelemetry-instrumentation-mysqlclient/src/opentelemetry/instrumentation/mysqlclient/__init__.py b/instrumentation/opentelemetry-instrumentation-mysqlclient/src/opentelemetry/instrumentation/mysqlclient/__init__.py index 9e7dade9c9..553d4574aa 100644 --- a/instrumentation/opentelemetry-instrumentation-mysqlclient/src/opentelemetry/instrumentation/mysqlclient/__init__.py +++ b/instrumentation/opentelemetry-instrumentation-mysqlclient/src/opentelemetry/instrumentation/mysqlclient/__init__.py @@ -36,6 +36,9 @@ cursor.close() cnx.close() +Configuration +------------- + SQLCOMMENTER ***************************************** You can optionally configure MySQLClient instrumentation to enable sqlcommenter which enriches diff --git a/instrumentation/opentelemetry-instrumentation-psycopg/src/opentelemetry/instrumentation/psycopg/__init__.py b/instrumentation/opentelemetry-instrumentation-psycopg/src/opentelemetry/instrumentation/psycopg/__init__.py index ede035e079..d2c4880650 100644 --- a/instrumentation/opentelemetry-instrumentation-psycopg/src/opentelemetry/instrumentation/psycopg/__init__.py +++ b/instrumentation/opentelemetry-instrumentation-psycopg/src/opentelemetry/instrumentation/psycopg/__init__.py @@ -18,14 +18,48 @@ .. _Psycopg: http://initd.org/psycopg/ +Usage +----- + +.. code-block:: python + + import psycopg + from opentelemetry.instrumentation.psycopg import PsycopgInstrumentor + + # Call instrument() to wrap all database connections + PsycopgInstrumentor().instrument() + + cnx = psycopg.connect(database='Database') + + cursor = cnx.cursor() + cursor.execute("CREATE TABLE IF NOT EXISTS test (testField INTEGER)") + cursor.execute("INSERT INTO test (testField) VALUES (123)") + cursor.close() + cnx.close() + +.. code-block:: python + + import psycopg + from opentelemetry.instrumentation.psycopg import PsycopgInstrumentor + + # Alternatively, use instrument_connection for an individual connection + cnx = psycopg.connect(database='Database') + instrumented_cnx = PsycopgInstrumentor().instrument_connection(cnx) + cursor = instrumented_cnx.cursor() + cursor.execute("CREATE TABLE IF NOT EXISTS test (testField INTEGER)") + cursor.execute("INSERT INTO test (testField) VALUES (123)") + cursor.close() + instrumented_cnx.close() + + +Configuration +------------- + SQLCOMMENTER ***************************************** You can optionally configure Psycopg instrumentation to enable sqlcommenter which enriches the query with contextual information. -Usage ------ - .. code:: python from opentelemetry.instrumentation.psycopg import PsycopgInstrumentor @@ -93,45 +127,12 @@ enable_attribute_commenter=True, ) - For example, :: Invoking cursor.execute("select * from auth_users") will lead to postgresql query "select * from auth_users" but when SQLCommenter and attribute_commenter are enabled the query will get appended with some configurable tags like "select * from auth_users /*tag=value*/;" for both server query and `db.statement` span attribute. -Usage ------ - -.. code-block:: python - - import psycopg - from opentelemetry.instrumentation.psycopg import PsycopgInstrumentor - - # Call instrument() to wrap all database connections - PsycopgInstrumentor().instrument() - - cnx = psycopg.connect(database='Database') - - cursor = cnx.cursor() - cursor.execute("CREATE TABLE IF NOT EXISTS test (testField INTEGER)") - cursor.execute("INSERT INTO test (testField) VALUES (123)") - cursor.close() - cnx.close() - -.. code-block:: python - - import psycopg - from opentelemetry.instrumentation.psycopg import PsycopgInstrumentor - - # Alternatively, use instrument_connection for an individual connection - cnx = psycopg.connect(database='Database') - instrumented_cnx = PsycopgInstrumentor().instrument_connection(cnx) - cursor = instrumented_cnx.cursor() - cursor.execute("CREATE TABLE IF NOT EXISTS test (testField INTEGER)") - cursor.execute("INSERT INTO test (testField) VALUES (123)") - cursor.close() - instrumented_cnx.close() API --- diff --git a/instrumentation/opentelemetry-instrumentation-psycopg2/src/opentelemetry/instrumentation/psycopg2/__init__.py b/instrumentation/opentelemetry-instrumentation-psycopg2/src/opentelemetry/instrumentation/psycopg2/__init__.py index d90f894ef2..153d491036 100644 --- a/instrumentation/opentelemetry-instrumentation-psycopg2/src/opentelemetry/instrumentation/psycopg2/__init__.py +++ b/instrumentation/opentelemetry-instrumentation-psycopg2/src/opentelemetry/instrumentation/psycopg2/__init__.py @@ -18,13 +18,47 @@ .. _Psycopg: http://initd.org/psycopg/ +Usage +----- + +.. code-block:: python + + import psycopg2 + from opentelemetry.instrumentation.psycopg2 import Psycopg2Instrumentor + + # Call instrument() to wrap all database connections + Psycopg2Instrumentor().instrument() + + cnx = psycopg2.connect(database='Database') + + cursor = cnx.cursor() + cursor.execute("CREATE TABLE IF NOT EXISTS test (testField INTEGER)") + cursor.execute("INSERT INTO test (testField) VALUES (123)") + cursor.close() + cnx.close() + +.. code-block:: python + + import psycopg2 + from opentelemetry.instrumentation.psycopg2 import Psycopg2Instrumentor + + # Alternatively, use instrument_connection for an individual connection + cnx = psycopg2.connect(database='Database') + instrumented_cnx = Psycopg2Instrumentor().instrument_connection(cnx) + cursor = instrumented_cnx.cursor() + cursor.execute("CREATE TABLE IF NOT EXISTS test (testField INTEGER)") + cursor.execute("INSERT INTO test (testField) VALUES (123)") + cursor.close() + instrumented_cnx.close() + +Configuration +------------- + SQLCOMMENTER ***************************************** You can optionally configure Psycopg2 instrumentation to enable sqlcommenter which enriches the query with contextual information. -Usage ------ .. code:: python @@ -100,39 +134,6 @@ Invoking cursor.execute("select * from auth_users") will lead to postgresql query "select * from auth_users" but when SQLCommenter and attribute_commenter are enabled the query will get appended with some configurable tags like "select * from auth_users /*tag=value*/;" for both server query and `db.statement` span attribute. -Usage ------ - -.. code-block:: python - - import psycopg2 - from opentelemetry.instrumentation.psycopg2 import Psycopg2Instrumentor - - # Call instrument() to wrap all database connections - Psycopg2Instrumentor().instrument() - - cnx = psycopg2.connect(database='Database') - - cursor = cnx.cursor() - cursor.execute("CREATE TABLE IF NOT EXISTS test (testField INTEGER)") - cursor.execute("INSERT INTO test (testField) VALUES (123)") - cursor.close() - cnx.close() - -.. code-block:: python - - import psycopg2 - from opentelemetry.instrumentation.psycopg2 import Psycopg2Instrumentor - - # Alternatively, use instrument_connection for an individual connection - cnx = psycopg2.connect(database='Database') - instrumented_cnx = Psycopg2Instrumentor().instrument_connection(cnx) - cursor = instrumented_cnx.cursor() - cursor.execute("CREATE TABLE IF NOT EXISTS test (testField INTEGER)") - cursor.execute("INSERT INTO test (testField) VALUES (123)") - cursor.close() - instrumented_cnx.close() - API --- """ diff --git a/instrumentation/opentelemetry-instrumentation-pymysql/src/opentelemetry/instrumentation/pymysql/__init__.py b/instrumentation/opentelemetry-instrumentation-pymysql/src/opentelemetry/instrumentation/pymysql/__init__.py index fca5b88762..2c8951385e 100644 --- a/instrumentation/opentelemetry-instrumentation-pymysql/src/opentelemetry/instrumentation/pymysql/__init__.py +++ b/instrumentation/opentelemetry-instrumentation-pymysql/src/opentelemetry/instrumentation/pymysql/__init__.py @@ -59,14 +59,14 @@ cursor.close() instrumented_cnx.close() +Configuration +------------- + SQLCOMMENTER ***************************************** You can optionally configure PyMySQL instrumentation to enable sqlcommenter which enriches the query with contextual information. -Usage ------ - .. code:: python import pymysql @@ -142,7 +142,6 @@ enable_attribute_commenter=True, ) - For example, :: diff --git a/instrumentation/opentelemetry-instrumentation-sqlalchemy/src/opentelemetry/instrumentation/sqlalchemy/__init__.py b/instrumentation/opentelemetry-instrumentation-sqlalchemy/src/opentelemetry/instrumentation/sqlalchemy/__init__.py index a76dd927a6..772a65d83f 100644 --- a/instrumentation/opentelemetry-instrumentation-sqlalchemy/src/opentelemetry/instrumentation/sqlalchemy/__init__.py +++ b/instrumentation/opentelemetry-instrumentation-sqlalchemy/src/opentelemetry/instrumentation/sqlalchemy/__init__.py @@ -22,14 +22,42 @@ .. _sqlalchemy: https://pypi.org/project/sqlalchemy/ +Usage +----- +.. code:: python + + from sqlalchemy import create_engine + + from opentelemetry.instrumentation.sqlalchemy import SQLAlchemyInstrumentor + import sqlalchemy + + engine = create_engine("sqlite:///:memory:") + SQLAlchemyInstrumentor().instrument( + engine=engine, + ) + +.. code:: python + + # of the async variant of SQLAlchemy + + from sqlalchemy.ext.asyncio import create_async_engine + + from opentelemetry.instrumentation.sqlalchemy import SQLAlchemyInstrumentor + import sqlalchemy + + engine = create_async_engine("sqlite+aiosqlite:///:memory:") + SQLAlchemyInstrumentor().instrument( + engine=engine.sync_engine + ) + +Configuration +------------- + SQLCOMMENTER **************************************** You can optionally configure SQLAlchemy instrumentation to enable sqlcommenter which enriches the query with contextual information. -Usage ------ - .. code:: python from opentelemetry.instrumentation.sqlalchemy import SQLAlchemyInstrumentor @@ -88,35 +116,6 @@ Warning: capture of sqlcomment in ``db.statement`` may have high cardinality without platform normalization. See `Semantic Conventions for database spans `_ for more information. - -Usage ------ -.. code:: python - - from sqlalchemy import create_engine - - from opentelemetry.instrumentation.sqlalchemy import SQLAlchemyInstrumentor - import sqlalchemy - - engine = create_engine("sqlite:///:memory:") - SQLAlchemyInstrumentor().instrument( - engine=engine, - ) - -.. code:: python - - # of the async variant of SQLAlchemy - - from sqlalchemy.ext.asyncio import create_async_engine - - from opentelemetry.instrumentation.sqlalchemy import SQLAlchemyInstrumentor - import sqlalchemy - - engine = create_async_engine("sqlite+aiosqlite:///:memory:") - SQLAlchemyInstrumentor().instrument( - engine=engine.sync_engine - ) - API --- """