Skip to content

Commit b1b627f

Browse files
tammy-baylis-switammy-baylis-swi
committed
Update psycopg2,psycopg docs on sqlcommenter
1 parent 34db73e commit b1b627f

File tree

3 files changed

+113
-113
lines changed
  • instrumentation
    • opentelemetry-instrumentation-psycopg2
    • opentelemetry-instrumentation-psycopg/src/opentelemetry/instrumentation/psycopg

3 files changed

+113
-113
lines changed

‎instrumentation/opentelemetry-instrumentation-psycopg/src/opentelemetry/instrumentation/psycopg/__init__.py‎

Lines changed: 56 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -13,10 +13,10 @@
1313
# limitations under the License.
1414

1515
"""
16-
The integration with PostgreSQL supports the `Psycopg`_ library, it can be enabled by
16+
The integration with PostgreSQL supports the `Psycopg`_ library. It can be enabled by
1717
using ``PsycopgInstrumentor``.
1818
19-
.. _Psycopg: http://initd.org/psycopg/
19+
.. _Psycopg: https://www.psycopg.org/psycopg3/docs/
2020
2121
Usage
2222
-----
@@ -55,85 +55,85 @@
5555
Configuration
5656
-------------
5757
58-
SQLCOMMENTER
59-
*****************************************
58+
SQLCommenter
59+
************
6060
You can optionally configure Psycopg instrumentation to enable sqlcommenter which enriches
61-
the query with contextual information.
61+
the query with contextual information. Queries made after setting up trace integration with
62+
sqlcommenter enabled will have configurable key-value pairs appended to them, e.g.
63+
``"select * from auth_users; /*traceparent=00-01234567-abcd-01*/"``. This supports context
64+
propagation between database client and server when database log records are enabled.
65+
For more information, see:
66+
67+
* `Semantic Conventions - Database Spans <https://github.com/open-telemetry/semantic-conventions/blob/main/docs/database/database-spans.md#sql-commenter>`_
68+
* `sqlcommenter <https://google.github.io/sqlcommenter/>`_
6269
6370
.. code:: python
6471
6572
from opentelemetry.instrumentation.psycopg import PsycopgInstrumentor
6673
67-
PsycopgInstrumentor().instrument(enable_commenter=True, commenter_options={})
68-
69-
70-
For example,
71-
::
72-
73-
Invoking cursor.execute("select * from auth_users") will lead to sql query "select * from auth_users" but when SQLCommenter is enabled
74-
the query will get appended with some configurable tags like "select * from auth_users /*tag=value*/;"
75-
76-
77-
SQLCommenter Configurations
78-
***************************
79-
We can configure the tags to be appended to the sqlquery log by adding configuration inside commenter_options(default:{}) keyword
80-
81-
db_driver = True(Default) or False
82-
83-
For example,
84-
::
85-
Enabling this flag will add psycopg and it's version which is /*psycopg%%3A2.9.3*/
86-
87-
dbapi_threadsafety = True(Default) or False
88-
89-
For example,
90-
::
91-
Enabling this flag will add threadsafety /*dbapi_threadsafety=2*/
74+
PsycopgInstrumentor().instrument(enable_commenter=True)
9275
93-
dbapi_level = True(Default) or False
9476
95-
For example,
96-
::
97-
Enabling this flag will add dbapi_level /*dbapi_level='2.0'*/
77+
SQLCommenter with commenter_options
78+
***********************************
79+
The key-value pairs appended to the query can be configured using
80+
``commenter_options``. When sqlcommenter is enabled, all available KVs/tags
81+
are calculated by default. ``commenter_options`` supports *opting out*
82+
of specific KVs.
9883
99-
libpq_version = True(Default) or False
100-
101-
For example,
102-
::
103-
Enabling this flag will add libpq_version /*libpq_version=140001*/
104-
105-
driver_paramstyle = True(Default) or False
84+
.. code:: python
10685
107-
For example,
108-
::
109-
Enabling this flag will add driver_paramstyle /*driver_paramstyle='pyformat'*/
86+
from opentelemetry.instrumentation.psycopg import PsycopgInstrumentor
11087
111-
opentelemetry_values = True(Default) or False
88+
# Opts into sqlcomment for Psycopg trace integration.
89+
# Opts out of tags for libpq_version, db_driver.
90+
PsycopgInstrumentor().instrument(
91+
enable_commenter=True,
92+
commenter_options={
93+
"libpq_version": False,
94+
"db_driver": False,
95+
}
96+
)
11297
113-
For example,
114-
::
115-
Enabling this flag will add traceparent values /*traceparent='00-03afa25236b8cd948fa853d67038ac79-405ff022e8247c46-01'*/
98+
Available commenter_options
99+
###########################
100+
101+
The following sqlcomment key-values can be opted out of through ``commenter_options``:
102+
103+
+---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+
104+
| Commenter Option | Description | Example |
105+
+===========================+===========================================================+===========================================================================+
106+
| ``db_driver`` | Database driver name with version. | ``psycopg=3.1.9`` |
107+
+---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+
108+
| ``dbapi_threadsafety`` | DB-API threadsafety value: 0-3 or unknown. | ``dbapi_threadsafety=2`` |
109+
+---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+
110+
| ``dbapi_level`` | DB-API API level: 1.0, 2.0, or unknown. | ``dbapi_level=2.0`` |
111+
+---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+
112+
| ``driver_paramstyle`` | DB-API paramstyle for SQL statement parameter. | ``driver_paramstyle='pyformat'`` |
113+
+---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+
114+
| ``libpq_version`` | PostgreSQL libpq version | ``libpq_version=140001`` |
115+
+---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+
116+
| ``opentelemetry_values`` | OpenTelemetry context as traceparent at time of query. | ``traceparent='00-03afa25236b8cd948fa853d67038ac79-405ff022e8247c46-01'`` |
117+
+---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+
116118
117119
SQLComment in span attribute
118120
****************************
119-
If sqlcommenter is enabled, you can optionally configure psycopg instrumentation to append sqlcomment to query span attribute for convenience of your platform.
121+
If sqlcommenter is enabled, you can opt into the inclusion of sqlcomment in
122+
the query span ``db.statement`` attribute for your needs. If ``commenter_options``
123+
have been set, the span attribute comment will also be configured by this
124+
setting.
120125
121126
.. code:: python
122127
123128
from opentelemetry.instrumentation.psycopg import PsycopgInstrumentor
124129
130+
# Opts into sqlcomment for Psycopg trace integration.
131+
# Opts into sqlcomment for `db.statement` span attribute.
125132
PsycopgInstrumentor().instrument(
126133
enable_commenter=True,
127134
enable_attribute_commenter=True,
128135
)
129136
130-
For example,
131-
::
132-
133-
Invoking cursor.execute("select * from auth_users") will lead to postgresql query "select * from auth_users" but when SQLCommenter and attribute_commenter are enabled
134-
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.
135-
136-
137137
API
138138
---
139139
"""

‎instrumentation/opentelemetry-instrumentation-psycopg2/README.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
OpenTelemetry Psycopg Instrumentation
1+
OpenTelemetry Psycopg2 Instrumentation
22
=====================================
33

44
|pypi|
@@ -16,6 +16,6 @@ Installation
1616

1717
References
1818
----------
19-
* `OpenTelemetry Psycopg Instrumentation <https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/psycopg2/psycopg2.html>`_
19+
* `OpenTelemetry Psycopg2 Instrumentation <https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/psycopg2/psycopg2.html>`_
2020
* `OpenTelemetry Project <https://opentelemetry.io/>`_
2121
* `OpenTelemetry Python Examples <https://github.com/open-telemetry/opentelemetry-python/tree/main/docs/examples>`_

‎instrumentation/opentelemetry-instrumentation-psycopg2/src/opentelemetry/instrumentation/psycopg2/__init__.py‎

Lines changed: 55 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -13,10 +13,10 @@
1313
# limitations under the License.
1414

1515
"""
16-
The integration with PostgreSQL supports the `Psycopg`_ library, it can be enabled by
16+
The integration with PostgreSQL supports the `psycopg2`_ library. It can be enabled by
1717
using ``Psycopg2Instrumentor``.
1818
19-
.. _Psycopg: http://initd.org/psycopg/
19+
.. _Psycopg2: https://www.psycopg.org/docs/
2020
2121
Usage
2222
-----
@@ -54,86 +54,86 @@
5454
Configuration
5555
-------------
5656
57-
SQLCOMMENTER
58-
*****************************************
57+
SQLCommenter
58+
************
5959
You can optionally configure Psycopg2 instrumentation to enable sqlcommenter which enriches
60-
the query with contextual information.
60+
the query with contextual information. Queries made after setting up trace integration with
61+
sqlcommenter enabled will have configurable key-value pairs appended to them, e.g.
62+
``"select * from auth_users; /*traceparent=00-01234567-abcd-01*/"``. This supports context
63+
propagation between database client and server when database log records are enabled.
64+
For more information, see:
6165
66+
* `Semantic Conventions - Database Spans <https://github.com/open-telemetry/semantic-conventions/blob/main/docs/database/database-spans.md#sql-commenter>`_
67+
* `sqlcommenter <https://google.github.io/sqlcommenter/>`_
6268
6369
.. code:: python
6470
6571
from opentelemetry.instrumentation.psycopg2 import Psycopg2Instrumentor
6672
67-
Psycopg2Instrumentor().instrument(enable_commenter=True, commenter_options={})
73+
Psycopg2Instrumentor().instrument(enable_commenter=True)
6874
6975
70-
For example,
71-
::
76+
SQLCommenter with commenter_options
77+
***********************************
78+
The key-value pairs appended to the query can be configured using
79+
``commenter_options``. When sqlcommenter is enabled, all available KVs/tags
80+
are calculated by default. ``commenter_options`` supports *opting out*
81+
of specific KVs.
7282
73-
Invoking cursor.execute("select * from auth_users") will lead to sql query "select * from auth_users" but when SQLCommenter is enabled
74-
the query will get appended with some configurable tags like "select * from auth_users /*tag=value*/;"
75-
76-
77-
SQLCommenter Configurations
78-
***************************
79-
We can configure the tags to be appended to the sqlquery log by adding configuration inside commenter_options(default:{}) keyword
80-
81-
db_driver = True(Default) or False
82-
83-
For example,
84-
::
85-
Enabling this flag will add psycopg2 and it's version which is /*psycopg2%%3A2.9.3*/
86-
87-
dbapi_threadsafety = True(Default) or False
88-
89-
For example,
90-
::
91-
Enabling this flag will add threadsafety /*dbapi_threadsafety=2*/
92-
93-
dbapi_level = True(Default) or False
94-
95-
For example,
96-
::
97-
Enabling this flag will add dbapi_level /*dbapi_level='2.0'*/
98-
99-
libpq_version = True(Default) or False
100-
101-
For example,
102-
::
103-
Enabling this flag will add libpq_version /*libpq_version=140001*/
104-
105-
driver_paramstyle = True(Default) or False
83+
.. code:: python
10684
107-
For example,
108-
::
109-
Enabling this flag will add driver_paramstyle /*driver_paramstyle='pyformat'*/
85+
from opentelemetry.instrumentation.psycopg2 import Psycopg2Instrumentor
11086
111-
opentelemetry_values = True(Default) or False
87+
# Opts into sqlcomment for Psycopg2 trace integration.
88+
# Opts out of tags for libpq_version, db_driver.
89+
Psycopg2Instrumentor().instrument(
90+
enable_commenter=True,
91+
commenter_options={
92+
"libpq_version": False,
93+
"db_driver": False,
94+
}
95+
)
11296
113-
For example,
114-
::
115-
Enabling this flag will add traceparent values /*traceparent='00-03afa25236b8cd948fa853d67038ac79-405ff022e8247c46-01'*/
97+
Available commenter_options
98+
###########################
99+
100+
The following sqlcomment key-values can be opted out of through ``commenter_options``:
101+
102+
+---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+
103+
| Commenter Option | Description | Example |
104+
+===========================+===========================================================+===========================================================================+
105+
| ``db_driver`` | Database driver name with version. | ``psycopg2=2.9.3`` |
106+
+---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+
107+
| ``dbapi_threadsafety`` | DB-API threadsafety value: 0-3 or unknown. | ``dbapi_threadsafety=2`` |
108+
+---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+
109+
| ``dbapi_level`` | DB-API API level: 1.0, 2.0, or unknown. | ``dbapi_level=2.0`` |
110+
+---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+
111+
| ``driver_paramstyle`` | DB-API paramstyle for SQL statement parameter. | ``driver_paramstyle='pyformat'`` |
112+
+---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+
113+
| ``libpq_version`` | PostgreSQL libpq version | ``libpq_version=140001`` |
114+
+---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+
115+
| ``opentelemetry_values`` | OpenTelemetry context as traceparent at time of query. | ``traceparent='00-03afa25236b8cd948fa853d67038ac79-405ff022e8247c46-01'`` |
116+
+---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+
116117
117118
SQLComment in span attribute
118119
****************************
119-
If sqlcommenter is enabled, you can optionally configure psycopg2 instrumentation to append sqlcomment to query span attribute for convenience of your platform.
120+
If sqlcommenter is enabled, you can opt into the inclusion of sqlcomment in
121+
the query span ``db.statement`` attribute for your needs. If ``commenter_options``
122+
have been set, the span attribute comment will also be configured by this
123+
setting.
120124
121125
.. code:: python
122126
123127
from opentelemetry.instrumentation.psycopg2 import Psycopg2Instrumentor
124128
129+
# Opts into sqlcomment for Psycopg2 trace integration.
130+
# Opts into sqlcomment for `db.statement` span attribute.
125131
Psycopg2Instrumentor().instrument(
126132
enable_commenter=True,
127133
enable_attribute_commenter=True,
128134
)
129135
130136
131-
For example,
132-
::
133-
134-
Invoking cursor.execute("select * from auth_users") will lead to postgresql query "select * from auth_users" but when SQLCommenter and attribute_commenter are enabled
135-
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.
136-
137137
API
138138
---
139139
"""

0 commit comments

Comments
 (0)