Merge branch 'main' into fix/client-address

Author: lzchen

instrumentation/opentelemetry-instrumentation-botocore/src/opentelemetry/instrumentation/botocore/__init__.py

@@ -28,7 +28,7 @@
 .. code:: python
 
     from opentelemetry.instrumentation.botocore import BotocoreInstrumentor
-    import botocore
+    import botocore.session
 
 
     # Instrument Botocore
@@ -39,7 +39,7 @@
     session.set_credentials(
         access_key="access-key", secret_key="secret-key"
     )
-    ec2 = self.session.create_client("ec2", region_name="us-west-2")
+    ec2 = session.create_client("ec2", region_name="us-west-2")
     ec2.describe_instances()
 
 API
@@ -58,13 +58,15 @@
 .. code: python
 
     from opentelemetry.instrumentation.botocore import BotocoreInstrumentor
-    import botocore
+    import botocore.session
 
     def request_hook(span, service_name, operation_name, api_params):
         # request hook logic
+        pass
 
     def response_hook(span, service_name, operation_name, result):
         # response hook logic
+        pass
 
     # Instrument Botocore with hooks
     BotocoreInstrumentor().instrument(request_hook=request_hook, response_hook=response_hook)
@@ -74,7 +76,7 @@ def response_hook(span, service_name, operation_name, result):
     session.set_credentials(
         access_key="access-key", secret_key="secret-key"
     )
-    ec2 = self.session.create_client("ec2", region_name="us-west-2")
+    ec2 = session.create_client("ec2", region_name="us-west-2")
     ec2.describe_instances()
 
 Extensions

instrumentation/opentelemetry-instrumentation-confluent-kafka/src/opentelemetry/instrumentation/confluent_kafka/__init__.py

@@ -34,6 +34,9 @@
     # report a span of type consumer with the default settings
     consumer = Consumer(conf2)
 
+    def msg_process(msg):
+        print(msg)
+
     def basic_consume_loop(consumer, topics):
         try:
             consumer.subscribe(topics)
@@ -44,7 +47,7 @@ def basic_consume_loop(consumer, topics):
                 if msg.error():
                     if msg.error().code() == KafkaError._PARTITION_EOF:
                         # End of partition event
-                        sys.stderr.write(f"{msg.topic() [{msg.partition()}] reached end at offset {msg.offset()}}")
+                        sys.stderr.write(f"{msg.topic()} [{msg.partition()}] reached end at offset {msg.offset()}")
                     elif msg.error():
                         raise KafkaException(msg.error())
                 else:
@@ -53,7 +56,7 @@ def basic_consume_loop(consumer, topics):
             # Close down consumer to commit final offsets.
             consumer.close()
 
-    basic_consume_loop(consumer, "my-topic")
+    basic_consume_loop(consumer, ["my-topic"])
 
 The _instrument method accepts the following keyword args:
   tracer_provider (TracerProvider) - an optional tracer provider
@@ -72,14 +75,16 @@ def instrument_consumer(consumer: Consumer, tracer_provider=None)
 .. code:: python
 
     from opentelemetry.instrumentation.confluent_kafka import ConfluentKafkaInstrumentor
+    from opentelemetry.trace import get_tracer_provider
 
     from confluent_kafka import Producer, Consumer
 
     inst = ConfluentKafkaInstrumentor()
+    tracer_provider = get_tracer_provider()
 
-    p = confluent_kafka.Producer({'bootstrap.servers': 'localhost:29092'})
-    c = confluent_kafka.Consumer({
-        'bootstrap.servers': 'localhost:29092',
+    p = Producer({'bootstrap.servers': 'localhost:9092'})
+    c = Consumer({
+        'bootstrap.servers': 'localhost:9092',
         'group.id': 'mygroup',
         'auto.offset.reset': 'earliest'
     })

instrumentation/opentelemetry-instrumentation-elasticsearch/src/opentelemetry/instrumentation/elasticsearch/__init__.py

@@ -32,15 +32,15 @@
 
     from opentelemetry.instrumentation.elasticsearch import ElasticsearchInstrumentor
     import elasticsearch
-
+    from datetime import datetime
 
     # instrument elasticsearch
     ElasticsearchInstrumentor().instrument()
 
     # Using elasticsearch as normal now will automatically generate spans
     es = elasticsearch.Elasticsearch()
-    es.index(index='my-index', doc_type='my-type', id=1, body={'my': 'data', 'timestamp': datetime.now()})
-    es.get(index='my-index', doc_type='my-type', id=1)
+    es.index(index='my-index', doc_type='_doc', id=1, body={'my': 'data', 'timestamp': datetime.now()})
+    es.get(index='my-index', doc_type='_doc', id=1)
 
 Elasticsearch instrumentation prefixes operation names with the string "Elasticsearch". This
 can be changed to a different string by either setting the OTEL_PYTHON_ELASTICSEARCH_NAME_PREFIX
@@ -49,6 +49,8 @@
 
 .. code-block:: python
 
+    from opentelemetry.instrumentation.elasticsearch import ElasticsearchInstrumentor
+
     ElasticsearchInstrumentor("my-custom-prefix").instrument()
 
 The instrument() method accepts the following keyword args:
@@ -67,6 +69,7 @@ def response_hook(span: Span, response: dict)
 
     from opentelemetry.instrumentation.elasticsearch import ElasticsearchInstrumentor
     import elasticsearch
+    from datetime import datetime
 
     def request_hook(span, method, url, kwargs):
         if span and span.is_recording():
@@ -82,8 +85,8 @@ def response_hook(span, response):
     # Using elasticsearch as normal now will automatically generate spans,
     # including user custom attributes added from the hooks
     es = elasticsearch.Elasticsearch()
-    es.index(index='my-index', doc_type='my-type', id=1, body={'my': 'data', 'timestamp': datetime.now()})
-    es.get(index='my-index', doc_type='my-type', id=1)
+    es.index(index='my-index', doc_type='_doc', id=1, body={'my': 'data', 'timestamp': datetime.now()})
+    es.get(index='my-index', doc_type='_doc', id=1)
 
 API
 ---

instrumentation/opentelemetry-instrumentation-falcon/README.rst

@@ -47,21 +47,41 @@ will extract path_info and content_type attributes from every traced request and
 
 Falcon Request object reference: https://falcon.readthedocs.io/en/stable/api/request_and_response.html#id1
 
+Usage
+-----
+
+.. code-block:: python
+
+    import falcon
+    from opentelemetry.instrumentation.falcon import FalconInstrumentor
+
+    FalconInstrumentor().instrument()
+
+    app = falcon.App()
+
+    class HelloWorldResource(object):
+        def on_get(self, req, resp):
+            resp.text = 'Hello World'
+
+    app.add_route('/hello', HelloWorldResource())
+
 
 Request/Response hooks
 **********************
 The instrumentation supports specifying request and response hooks. These are functions that get called back by the instrumentation right after a Span is created for a request
 and right before the span is finished while processing a response. The hooks can be configured as follows:
 
-::
+.. code-block:: python
+
+    from opentelemetry.instrumentation.falcon import FalconInstrumentor
 
     def request_hook(span, req):
         pass
 
     def response_hook(span, req, resp):
         pass
 
-    FalconInstrumentation().instrument(request_hook=request_hook, response_hook=response_hook)
+    FalconInstrumentor().instrument(request_hook=request_hook, response_hook=response_hook)
 
 References
 ----------

instrumentation/opentelemetry-instrumentation-falcon/src/opentelemetry/instrumentation/falcon/__init__.py

@@ -58,16 +58,16 @@
 
 .. code-block:: python
 
-    from falcon import API
+    import falcon
     from opentelemetry.instrumentation.falcon import FalconInstrumentor
 
     FalconInstrumentor().instrument()
 
-    app = falcon.API()
+    app = falcon.App()
 
     class HelloWorldResource(object):
         def on_get(self, req, resp):
-            resp.body = 'Hello World'
+            resp.text = 'Hello World'
 
     app.add_route('/hello', HelloWorldResource())
 
@@ -78,15 +78,17 @@ def on_get(self, req, resp):
 right after a span is created for a request and right before the span is finished for the response.
 The hooks can be configured as follows:
 
-::
+.. code-block:: python
+
+    from opentelemetry.instrumentation.falcon import FalconInstrumentor
 
     def request_hook(span, req):
         pass
 
     def response_hook(span, req, resp):
         pass
 
-    FalconInstrumentation().instrument(request_hook=request_hook, response_hook=response_hook)
+    FalconInstrumentor().instrument(request_hook=request_hook, response_hook=response_hook)
 
 Capture HTTP request and response headers
 *****************************************

instrumentation/opentelemetry-instrumentation-logging/src/opentelemetry/instrumentation/logging/__init__.py

@@ -14,6 +14,47 @@
 
 # pylint: disable=empty-docstring,no-value-for-parameter,no-member,no-name-in-module
 
+"""
+The OpenTelemetry `logging` integration automatically injects tracing context into
+log statements, though it is opt-in and must be enabled explicitly by setting the
+environment variable `OTEL_PYTHON_LOG_CORRELATION` to `true`.
+
+.. code-block:: python
+
+    import logging
+
+    from opentelemetry.instrumentation.logging import LoggingInstrumentor
+
+    LoggingInstrumentor().instrument()
+
+    logging.warning('OTel test')
+
+When running the above example you will see the following output:
+
+::
+
+    2025-03-05 09:40:04,398 WARNING [root] [example.py:7] [trace_id=0 span_id=0 resource.service.name= trace_sampled=False] - OTel test
+
+The environment variable `OTEL_PYTHON_LOG_CORRELATION` must be set to `true`
+in order to enable trace context injection into logs by calling
+`logging.basicConfig()` and setting a logging format that makes use of the
+injected tracing variables.
+
+Alternatively, `set_logging_format` argument can be set to `True` when
+initializing the `LoggingInstrumentor` class to achieve the same effect:
+
+.. code-block:: python
+
+    import logging
+
+    from opentelemetry.instrumentation.logging import LoggingInstrumentor
+
+    LoggingInstrumentor().instrument(set_logging_format=True)
+
+    logging.warning('OTel test')
+
+"""
+
 import logging  # pylint: disable=import-self
 from os import environ
 from typing import Collection