OpenTelemetry Python

https://opentelemetry-python.readthedocs.io/en/stable/
Admin
OpenTelemetry Python is the Python implementation of the OpenTelemetry project, providing an API,...
Tokens:196,414
Snippets:1,497
Trust Score:8.3
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install dependencies

Source: https://opentelemetry-python.readthedocs.io/en/stable/examples/sqlcommenter/README.html

Install the required Python packages for the sqlcommenter example.

```bash
pip install opentelemetry-sdk \
    opentelemetry-exporter-otlp-proto-grpc \
    opentelemetry-instrumentation-mysql \
    mysql-connector-python
```

--------------------------------

### Setup Virtual Environment

Source: https://opentelemetry-python.readthedocs.io/en/stable/examples/error_handler/README.html

Commands to create and activate a new virtual environment for the error handler example.

```bash
$ mkdir global_error_handler
$ virtualenv global_error_handler
$ source global_error_handler/bin/activate
```

--------------------------------

### Install OpenTelemetry API and SDK

Source: https://opentelemetry-python.readthedocs.io/en/stable/examples/basic_context/README.html

Commands to install the required OpenTelemetry packages for the examples.

```bash
pip install opentelemetry-api
pip install opentelemetry-sdk
```

--------------------------------

### Install SDK with file-configuration extra

Source: https://opentelemetry-python.readthedocs.io/en/stable/examples/declarative-config/README.html

Install the required SDK components, auto-instrumentation, and OTLP/HTTP exporter.

```bash
pip install "opentelemetry-sdk[file-configuration]" \
    opentelemetry-distro \
    opentelemetry-exporter-otlp-proto-http
```

--------------------------------

### Run multi-destination examples

Source: https://opentelemetry-python.readthedocs.io/en/stable/examples/multi-destination-exporting/README.html

Execute the provided example scripts for traces, metrics, and logs.

```bash
python multi_destination_traces.py
python multi_destination_metrics.py
python multi_destination_logs.py
```

--------------------------------

### Install sqlcommenter Example Dependencies

Source: https://opentelemetry-python.readthedocs.io/en/stable/_sources/examples/sqlcommenter/README.rst.txt

Installs the necessary Python packages for the sqlcommenter example, including OpenTelemetry SDK, OTLP exporter, MySQL instrumentation, and the MySQL connector.

```sh
pip install opentelemetry-sdk \
    opentelemetry-exporter-otlp-proto-grpc \
    opentelemetry-instrumentation-mysql \
    mysql-connector-python
```

--------------------------------

### Install SDK and Error Handlers

Source: https://opentelemetry-python.readthedocs.io/en/stable/examples/error_handler/README.html

Commands to install the OpenTelemetry SDK and the example error handler packages.

```bash
$ pip install opentelemetry-sdk
$ git clone https://github.com/open-telemetry/opentelemetry-python.git
$ pip install -e opentelemetry-python/docs/examples/error_handler/error_handler_0
$ pip install -e opentelemetry-python/docs/examples/error_handler/error_handler_1
```

--------------------------------

### Run Python Example

Source: https://opentelemetry-python.readthedocs.io/en/stable/examples/metrics/instruments/README.html

Command to execute the Python metrics example script.

```bash
$ python example.py
```

--------------------------------

### Install uWSGI

Source: https://opentelemetry-python.readthedocs.io/en/stable/examples/django/README.html

Install uWSGI in the virtual environment for use with auto instrumentation.

```bash
pip install uwsgi
```

--------------------------------

### Run an Example

Source: https://opentelemetry-python.readthedocs.io/en/stable/examples/basic_context/README.html

Command to execute a specific example script by replacing <example_name> with the desired file name.

```bash
python <example_name>.py
```

--------------------------------

### Setup and Install Error Handler Dependencies

Source: https://opentelemetry-python.readthedocs.io/en/stable/_sources/examples/error_handler/README.rst.txt

Commands to prepare a virtual environment and install the OpenTelemetry SDK along with custom error handler packages.

```bash
mkdir global_error_handler
virtualenv global_error_handler
source global_error_handler/bin/activate
pip install opentelemetry-sdk
git clone https://github.com/open-telemetry/opentelemetry-python.git
pip install -e opentelemetry-python/docs/examples/error_handler/error_handler_0
pip install -e opentelemetry-python/docs/examples/error_handler/error_handler_1
```

--------------------------------

### Install Dependencies

Source: https://opentelemetry-python.readthedocs.io/en/stable/examples/metrics/prometheus-grafana/README.html

Command to install the required packages from requirements.txt.

```bash
$ pip install -r requirements.txt
```

--------------------------------

### Install OpenTelemetry SDK with file configuration support

Source: https://opentelemetry-python.readthedocs.io/en/stable/_sources/examples/declarative-config/README.rst.txt

Install the necessary packages including the file-configuration extra, distro, and OTLP exporter.

```sh
pip install "opentelemetry-sdk[file-configuration]" \
    opentelemetry-distro \
    opentelemetry-exporter-otlp-proto-http
```

--------------------------------

### Install Dependencies

Source: https://opentelemetry-python.readthedocs.io/en/stable/_sources/examples/metrics/reader/README.rst.txt

Installs the necessary Python packages required for running the OpenTelemetry MetricReader examples.

```sh
pip install -r requirements.txt
```

--------------------------------

### Example log output

Source: https://opentelemetry-python.readthedocs.io/en/stable/examples/logs/README.html

Sample output showing how logs appear in the collector after running the example script.

```text
ResourceLog #0
Resource SchemaURL:
Resource attributes:
    -> telemetry.sdk.language: Str(python)
    -> telemetry.sdk.name: Str(opentelemetry)
    -> telemetry.sdk.version: Str(1.33.0.dev0)
    -> service.name: Str(shoppingcart)
    -> service.instance.id: Str(instance-12)
ScopeLogs #0
ScopeLogs SchemaURL:
InstrumentationScope myapp.area2
LogRecord #0
ObservedTimestamp: 2025-04-22 12:16:57.315179 +0000 UTC
Timestamp: 2025-04-22 12:16:57.315152896 +0000 UTC
SeverityText: WARN
SeverityNumber: Warn(13)
Body: Str(Jail zesty vixen who grabbed pay from quack.)
Attributes:
    -> code.filepath: Str(/Users/jayclifford/Repos/opentelemetry-python/docs/examples/logs/example.py)
    -> code.function: Str(<module>)
    -> code.lineno: Int(47)
Trace ID:
Span ID:
Flags: 0
LogRecord #1
ObservedTimestamp: 2025-04-22 12:16:57.31522 +0000 UTC
Timestamp: 2025-04-22 12:16:57.315213056 +0000 UTC
SeverityText: ERROR
SeverityNumber: Error(17)
Body: Str(The five boxing wizards jump quickly.)
Attributes:
    -> code.filepath: Str(/Users/jayclifford/Repos/opentelemetry-python/docs/examples/logs/example.py)
    -> code.function: Str(<module>)
    -> code.lineno: Int(48)
Trace ID:
Span ID:
Flags: 0
LogRecord #2
ObservedTimestamp: 2025-04-22 12:16:57.315445 +0000 UTC
Timestamp: 2025-04-22 12:16:57.31543808 +0000 UTC
SeverityText: ERROR
SeverityNumber: Error(17)
Body: Str(Hyderabad, we have a major problem.)
Attributes:
    -> code.filepath: Str(/Users/jayclifford/Repos/opentelemetry-python/docs/examples/logs/example.py)
    -> code.function: Str(<module>)
    -> code.lineno: Int(61)
Trace ID: 8a6739fffce895e694700944e2faf23e
Span ID: a45337020100cb63
Flags: 1
ScopeLogs #1
ScopeLogs SchemaURL:
InstrumentationScope myapp.area1
LogRecord #0
ObservedTimestamp: 2025-04-22 12:16:57.315242 +0000 UTC
Timestamp: 2025-04-22 12:16:57.315234048 +0000 UTC
SeverityText: ERROR
SeverityNumber: Error(17)
Body: Str(I have custom attributes.)
Attributes:
    -> user_id: Str(user-123)
    -> code.filepath: Str(/Users/jayclifford/Repos/opentelemetry-python/docs/examples/logs/example.py)
    -> code.function: Str(<module>)
    -> code.lineno: Int(53)
Trace ID:
Span ID:
Flags: 0
```

--------------------------------

### Start OpenTelemetry collector and Jaeger services

Source: https://opentelemetry-python.readthedocs.io/en/stable/examples/opencensus-exporter-tracer/README.html

Install docker-compose and start the services defined in the docker-compose template.

```bash
pip install docker-compose
cd docker
docker-compose up
```

--------------------------------

### Install File Configuration Dependencies

Source: https://opentelemetry-python.readthedocs.io/en/stable/_sources/sdk/configuration.rst.txt

Install the necessary optional dependencies to enable file-based configuration.

```sh
pip install "opentelemetry-sdk[file-configuration]"
```

--------------------------------

### Install dependencies individually

Source: https://opentelemetry-python.readthedocs.io/en/stable/examples/opencensus-shim/README.html

Manually install the required OpenTelemetry, OpenCensus, and Flask packages.

```bash
pip install \
    opentelemetry-api \
    opentelemetry-sdk \
    opentelemetry-exporter-otlp \
    opentelemetry-opencensus-shim \
    opentelemetry-instrumentation-sqlite3 \
    opencensus \
    opencensus-ext-flask \
    Flask
```

--------------------------------

### Run the Flask application

Source: https://opentelemetry-python.readthedocs.io/en/stable/examples/opencensus-shim/README.html

Start the Flask application server.

```bash
flask --app app run -h 0.0.0.0
```

--------------------------------

### Prepare Virtual Environment

Source: https://opentelemetry-python.readthedocs.io/en/stable/examples/django/README.html

Commands to create and activate a virtual environment for the Django instrumentation example.

```bash
$ mkdir django_auto_instrumentation
$ virtualenv django_auto_instrumentation
$ source django_auto_instrumentation/bin/activate
```

--------------------------------

### Install Prometheus Exporter

Source: https://opentelemetry-python.readthedocs.io/en/stable/_sources/exporter/prometheus/prometheus.rst.txt

Install the package via pip.

```bash
pip install opentelemetry-exporter-prometheus
```

--------------------------------

### Install OpenTelemetry Python SDK and Exporters

Source: https://opentelemetry-python.readthedocs.io/en/stable/_sources/examples/multi-destination-exporting/README.rst.txt

Installs the necessary OpenTelemetry Python packages for API, SDK, and OTLP exporters (gRPC and HTTP). Also installs the logging instrumentation.

```sh
pip install opentelemetry-api
pip install opentelemetry-sdk
pip install opentelemetry-exporter-otlp-proto-grpc
pip install opentelemetry-exporter-otlp-proto-http
pip install opentelemetry-instrumentation-logging # For LoggingHandler
```

--------------------------------

### Build and run MySQL server

Source: https://opentelemetry-python.readthedocs.io/en/stable/examples/sqlcommenter/README.html

Commands to build the books-db Docker image and start the container.

```bash
cd books_database
docker build -t books-db .
docker run -d --name books-db -p 3366:3306 books-db
cd ..
```

--------------------------------

### Run Example Script

Source: https://opentelemetry-python.readthedocs.io/en/stable/_sources/examples/metrics/reader/README.rst.txt

Executes a specified OpenTelemetry Python example script. The output of the script will be displayed in the console.

```sh
python <example_name>.py
```

--------------------------------

### Run with uWSGI

Source: https://opentelemetry-python.readthedocs.io/en/stable/examples/django/README.html

Start the Django server using uWSGI with auto instrumentation.

```bash
opentelemetry-instrument uwsgi --http :8000 --module instrumentation_example.wsgi
```

--------------------------------

### Example Execution Output

Source: https://opentelemetry-python.readthedocs.io/en/stable/examples/error_handler/README.html

Expected console output when running the example.py script.

```text
ErrorHandler0 handling a ZeroDivisionError
Traceback (most recent call last):
  File "test.py", line 5, in <module>
    1 / 0
ZeroDivisionError: division by zero

ErrorHandler1 handling an IndexError
Traceback (most recent call last):
  File "test.py", line 11, in <module>
    [1][2]
IndexError: list index out of range

ErrorHandler1 handling a KeyError
Traceback (most recent call last):
  File "test.py", line 17, in <module>
    {1: 2}[2]
KeyError: 2

Error handled by default error handler:
Traceback (most recent call last):
  File "test.py", line 23, in <module>
    assert False
AssertionError

No error raised
```

--------------------------------

### Install OpenCensus Exporter dependencies

Source: https://opentelemetry-python.readthedocs.io/en/stable/examples/opencensus-exporter-tracer/README.html

Install the necessary OpenTelemetry API, SDK, and OpenCensus exporter packages.

```bash
pip install opentelemetry-api
pip install opentelemetry-sdk
pip install opentelemetry-exporter-opencensus
```

--------------------------------

### Initialize Prometheus Exporter

Source: https://opentelemetry-python.readthedocs.io/en/stable/_sources/exporter/prometheus/prometheus.rst.txt

Start an HTTP server and configure the MeterProvider with the PrometheusMetricReader.

```python
from prometheus_client import start_http_server

from opentelemetry import metrics
from opentelemetry.exporter.prometheus import PrometheusMetricReader
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.resources import SERVICE_NAME, Resource

# Service name is required for most backends
resource = Resource.create(attributes={
    SERVICE_NAME: "your-service-name"
})

# Start Prometheus client
start_http_server(port=9464, addr="localhost")
# Initialize PrometheusMetricReader which pulls metrics from the SDK
# on-demand to respond to scrape requests
reader = PrometheusMetricReader()
provider = MeterProvider(resource=resource, metric_readers=[reader])
metrics.set_meter_provider(provider)
```

--------------------------------

### Install OpenTelemetry dependencies

Source: https://opentelemetry-python.readthedocs.io/en/stable/examples/multi-destination-exporting/README.html

Install the necessary OpenTelemetry API, SDK, and exporter packages to support multi-destination exporting.

```bash
pip install opentelemetry-api
pip install opentelemetry-sdk
pip install opentelemetry-exporter-otlp-proto-grpc
pip install opentelemetry-exporter-otlp-proto-http
pip install opentelemetry-instrumentation-logging # For LoggingHandler
```

--------------------------------

### Execute the collector example

Source: https://opentelemetry-python.readthedocs.io/en/stable/examples/opencensus-exporter-tracer/README.html

Run the collector script after the infrastructure services are active.

```bash
python collector.py
```

--------------------------------

### Start the OTLP Collector

Source: https://opentelemetry-python.readthedocs.io/en/stable/examples/declarative-config/README.html

Run the OpenTelemetry Collector using the previously defined configuration file.

```bash
docker run \
    -p 4318:4318 \
    -v $(pwd)/otel-collector-config.yaml:/etc/otel-collector-config.yaml \
    otel/opentelemetry-collector:latest \
    --config=/etc/otel-collector-config.yaml
```

--------------------------------

### Start Redis server

Source: https://opentelemetry-python.readthedocs.io/en/stable/examples/opentracing/README.html

Ensure the Redis server is running before executing the application.

```bash
redis-server
```

--------------------------------

### Example YAML configuration file

Source: https://opentelemetry-python.readthedocs.io/en/stable/sdk/configuration.html

A sample configuration file defining traces, metrics, and logs exported over OTLP/HTTP.

```yaml
file_format: "1.0"

resource:
  attributes:
    - name: service.name
      value: my-service
    - name: deployment.environment.name
      value: ${DEPLOYMENT_ENVIRONMENT:-development}

tracer_provider:
  processors:
    - batch:
        exporter:
          otlp_http:
            endpoint: https://example.com:4318/v1/traces
            headers:
              - name: api-key
                value: ${OTLP_API_KEY}
  sampler:
    parent_based:
      root:
        always_on: {}

meter_provider:
  readers:
    - periodic:
        interval: 60000
        exporter:
          otlp_http:
            endpoint: https://example.com:4318/v1/metrics
            headers:
              - name: api-key
                value: ${OTLP_API_KEY}

logger_provider:
  processors:
    - batch:
        exporter:
          otlp_http:
            endpoint: https://example.com:4318/v1/logs
            headers:
              - name: api-key
                value: ${OTLP_API_KEY}
```

--------------------------------

### Example YAML Configuration File

Source: https://opentelemetry-python.readthedocs.io/en/stable/_sources/sdk/configuration.rst.txt

A sample configuration file defining resource attributes, tracer, meter, and logger providers with OTLP/HTTP exporters.

```yaml
file_format: "1.0"

resource:
  attributes:
    - name: service.name
      value: my-service
    - name: deployment.environment.name
      value: ${DEPLOYMENT_ENVIRONMENT:-development}

tracer_provider:
  processors:
    - batch:
        exporter:
          otlp_http:
            endpoint: https://example.com:4318/v1/traces
            headers:
              - name: api-key
                value: ${OTLP_API_KEY}
  sampler:
    parent_based:
      root:
        always_on: {}

meter_provider:
  readers:
    - periodic:
        interval: 60000
        exporter:
          otlp_http:
            endpoint: https://example.com:4318/v1/metrics
            headers:
              - name: api-key
                value: ${OTLP_API_KEY}

logger_provider:
  processors:
    - batch:
        exporter:
          otlp_http:
            endpoint: https://example.com:4318/v1/logs
            headers:
              - name: api-key
                value: ${OTLP_API_KEY}
```

--------------------------------

### Example Collector Output for Metrics

Source: https://opentelemetry-python.readthedocs.io/en/stable/_sources/examples/metrics/instruments/README.rst.txt

This is an example of the output you will see in the collector's debug exporter after running the Python metrics example. It shows the structure and values of exported metrics.

```sh
ScopeMetrics #0
ScopeMetrics SchemaURL:
InstrumentationScope getting-started 0.1.2
Metric #0
Descriptor:
     -> Name: counter
     -> Description:
     -> Unit:
     -> DataType: Sum
     -> IsMonotonic: true
     -> AggregationTemporality: Cumulative
NumberDataPoints #0
StartTimestamp: 2024-08-09 11:21:42.145179 +0000 UTC
Timestamp: 2024-08-09 11:21:42.145325 +0000 UTC
Value: 1
Metric #1
Descriptor:
     -> Name: updown_counter
     -> Description:
     -> Unit:
     -> DataType: Sum
     -> IsMonotonic: false
     -> AggregationTemporality: Cumulative
NumberDataPoints #0
StartTimestamp: 2024-08-09 11:21:42.145202 +0000 UTC
Timestamp: 2024-08-09 11:21:42.145325 +0000 UTC
Value: -4
Metric #2
Descriptor:
     -> Name: histogram
     -> Description:
     -> Unit:
     -> DataType: Histogram
     -> AggregationTemporality: Cumulative
HistogramDataPoints #0
StartTimestamp: 2024-08-09 11:21:42.145221 +0000 UTC
Timestamp: 2024-08-09 11:21:42.145325 +0000 UTC
Count: 1

```

--------------------------------

### Span.start

Source: https://opentelemetry-python.readthedocs.io/en/stable/_modules/opentelemetry/sdk/trace.html

Starts the span, setting the start time and notifying span processors.

```APIDOC
## start(start_time: int | None = None, parent_context: context_api.Context | None = None)

### Description
Starts the span. If no start_time is provided, the current time is used. This method should be called before any other span operations.

### Parameters
- **start_time** (int | None) - Optional - The timestamp in nanoseconds.
- **parent_context** (context_api.Context | None) - Optional - The parent context for the span.
```

--------------------------------

### Equivalent implementations of start_as_current_span

Source: https://opentelemetry-python.readthedocs.io/en/stable/_modules/opentelemetry/trace.html

Demonstrates the manual equivalent of the start_as_current_span context manager.

```python
with tracer.start_as_current_span(name) as span:
    do_work()
```

```python
span = tracer.start_span(name)
with opentelemetry.trace.use_span(span, end_on_exit=True):
    do_work()
```

--------------------------------

### Start Span

Source: https://opentelemetry-python.readthedocs.io/en/stable/_modules/opentelemetry/shim/opentracing_shim.html

Start a span using the shim, mirroring the OpenTracing start_span method.

```python
    def start_span(
        self,
        operation_name: str | None = None,
        child_of: SpanShim | SpanContextShim | None = None,
        references: list | None = None,
        tags: Attributes = None,
        start_time: float | None = None,
        ignore_active_span: bool = False,
    ) -> SpanShim:
        """Implements the ``start_span()`` method from the base class.

        Starts a span. In terms of functionality, this method behaves exactly
        like the same method on a "regular" OpenTracing tracer. See
        :meth:`opentracing.Tracer.start_span` for more details.
```

--------------------------------

### Prepare Virtual Environment

Source: https://opentelemetry-python.readthedocs.io/en/stable/examples/metrics/prometheus-grafana/README.html

Commands to create and activate a dedicated virtual environment for the Prometheus instrumentation example.

```bash
$ mkdir prometheus_auto_instrumentation
$ virtualenv prometheus_auto_instrumentation
$ source prometheus_auto_instrumentation/bin/activate
```

--------------------------------

### Example SQL query log entry

Source: https://opentelemetry-python.readthedocs.io/en/stable/examples/sqlcommenter/README.html

An example of a logged SQL query containing the sqlcomment.

```text
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'*/
```

--------------------------------

### Install Prometheus Exporter via pip

Source: https://opentelemetry-python.readthedocs.io/en/stable/exporter/prometheus/prometheus.html

Command to install the OpenTelemetry Prometheus exporter package from PyPI.

```bash
pip install opentelemetry-exporter-prometheus
```

--------------------------------

### Example OpenTelemetry span output

Source: https://opentelemetry-python.readthedocs.io/en/stable/examples/sqlcommenter/README.html

An example of the span output in the OpenTelemetry collector showing the db.statement attribute.

```text
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)
```

--------------------------------

### Configure MeterProvider with PeriodicExportingMetricReader

Source: https://opentelemetry-python.readthedocs.io/en/stable/_modules/opentelemetry/sdk/metrics/_internal.html

Demonstrates how to initialize a MeterProvider with a push-based metric reader using the ConsoleMetricExporter.

```python
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.metrics.export import (
    ConsoleMetricExporter,
    PeriodicExportingMetricReader,
)

reader = PeriodicExportingMetricReader(ConsoleMetricExporter())
provider = MeterProvider(metric_readers=[reader])
```

--------------------------------

### Install Python dependencies

Source: https://opentelemetry-python.readthedocs.io/en/stable/examples/opentracing/README.html

Install required packages using the provided requirements file or manually via pip.

```bash
pip install -r requirements.txt
```

```bash
pip install \
    opentelemetry-api \
    opentelemetry-sdk \
    opentelemetry-exporter-otlp \
    opentelemetry-opentracing-shim \
    redis \
    redis_opentracing
```

--------------------------------

### MeterProvider.__init__

Source: https://opentelemetry-python.readthedocs.io/en/stable/_modules/opentelemetry/sdk/metrics/_internal.html

Initializes a new MeterProvider instance to manage metric collection, readers, and configuration.

```APIDOC
## MeterProvider.__init__

### Description
Initializes the MeterProvider with optional metric readers, resource definitions, and views. This class serves as the central manager for metric instrumentation within the SDK.

### Parameters
- **metric_readers** (Sequence[MetricReader]) - Optional - A list of metric readers to collect metrics from the SDK.
- **resource** (Resource) - Optional - The resource representing the source of the metrics.
- **exemplar_filter** (ExemplarFilter) - Optional - Filter used for exemplar selection.
- **shutdown_on_exit** (bool) - Optional - If true, registers an atexit handler to shut down the provider.
- **views** (Sequence[View]) - Optional - A list of views to configure the metric output.
```

--------------------------------

### Run instrumented application

Source: https://opentelemetry-python.readthedocs.io/en/stable/examples/declarative-config/README.html

Point the SDK to the configuration file and execute the application with auto-instrumentation.

```bash
export OTEL_CONFIG_FILE=$(pwd)/otel-config.yaml
opentelemetry-instrument python app.py
```

--------------------------------

### Configure a custom sampler via entry points

Source: https://opentelemetry-python.readthedocs.io/en/stable/sdk/trace.sampling.html

Create an entry point for a custom sampler factory method under the opentelemetry_traces_sampler group. The factory method must accept a string argument and return a Sampler object.

```python
setup(
    ...
    entry_points={
        ...
        "opentelemetry_traces_sampler": [
            "custom_sampler_name = path.to.sampler.factory.method:CustomSamplerFactory.get_sampler"
        ]
    }
)
# ...
class CustomRatioSampler(Sampler):
    def __init__(rate):
        # ...
# ...
class CustomSamplerFactory:
    @staticmethod
    def get_sampler(sampler_argument):
        try:
            rate = float(sampler_argument)
            return CustomSampler(rate)
        except ValueError: # In case argument is empty string.
            return CustomSampler(0.5)
```

--------------------------------

### Start a span as the current context

Source: https://opentelemetry-python.readthedocs.io/en/stable/_modules/opentelemetry/sdk/trace.html

A context manager that starts a span and sets it as the active span for the duration of the block.

```python
    @_agnosticcontextmanager  # pylint: disable=protected-access
    def start_as_current_span(
        self,
        name: str,
        context: context_api.Context | None = None,
        kind: trace_api.SpanKind = trace_api.SpanKind.INTERNAL,
        attributes: types.Attributes = None,
        links: Sequence[trace_api.Link] | None = (),
        start_time: int | None = None,
        record_exception: bool = True,
        set_status_on_exception: bool = True,
        end_on_exit: bool = True,
    ) -> Iterator[trace_api.Span]:
        span = self.start_span(
            name=name,
            context=context,
            kind=kind,
            attributes=attributes,
            links=links,
            start_time=start_time,
            record_exception=record_exception,
            set_status_on_exception=set_status_on_exception,
        )
        with trace_api.use_span(
            span,
            end_on_exit=end_on_exit,
            record_exception=record_exception,
            set_status_on_exception=set_status_on_exception,
        ) as span:
            yield span
```

--------------------------------

### Start Active Span

Source: https://opentelemetry-python.readthedocs.io/en/stable/_modules/opentelemetry/shim/opentracing_shim.html

Start and activate a span using the shim, behaving like a standard OpenTracing tracer.

```python
    def start_active_span(
        self,
        operation_name: str,
        child_of: SpanShim | SpanContextShim | None = None,
        references: list | None = None,
        tags: Attributes = None,
        start_time: float | None = None,
        ignore_active_span: bool = False,
        finish_on_close: bool = True,
    ) -> ScopeShim:
        """Starts and activates a span. In terms of functionality, this method
        behaves exactly like the same method on a "regular" OpenTracing tracer.
        See :meth:`opentracing.Tracer.start_active_span` for more details.

        Args:
            operation_name: Name of the operation represented by
                the new span from the perspective of the current service.
            child_of: A :class:`SpanShim` or :class:`SpanContextShim`
                representing the parent in a "child of" reference. If
                specified, the *references* parameter must be omitted.
            references: A list of :class:`opentracing.Reference` objects that
                identify one or more parents of type :class:`SpanContextShim`.
            tags: A dictionary of tags.
            start_time: An explicit start time expressed as the number of
                seconds since the epoch as returned by :func:`time.time()`.
            ignore_active_span: Ignore the currently-active span in the
                OpenTelemetry tracer and make the created span the root span of
                a new trace.
            finish_on_close: Determines whether the created span should end
                automatically when closing the returned :class:`ScopeShim`.

        Returns:
            A :class:`ScopeShim` that is already activated by the
            :class:`ScopeManagerShim`.
        """

        current_span = get_current_span()

        if (
            child_of is None
            and current_span.get_span_context() is not INVALID_SPAN_CONTEXT
        ):
            child_of = SpanShim(None, None, current_span)

        span = self.start_span(
            operation_name=operation_name,
            child_of=child_of,
            references=references,
            tags=tags,
            start_time=start_time,
            ignore_active_span=ignore_active_span,
        )
        return self._scope_manager.activate(span, finish_on_close)
```

--------------------------------

### Configure a Custom Sampler via Entry Points

Source: https://opentelemetry-python.readthedocs.io/en/stable/_modules/opentelemetry/sdk/trace/sampling.html

Define a custom sampler factory in your setup configuration to allow dynamic sampler selection via environment variables.

```python
setup(
    ...
    entry_points={
        ...
        "opentelemetry_traces_sampler": [
            "custom_sampler_name = path.to.sampler.factory.method:CustomSamplerFactory.get_sampler"
        ]
    }
)
# ...
class CustomRatioSampler(Sampler):
    def __init__(rate):
        # ...
# ...
class CustomSamplerFactory:
    @staticmethod
    def get_sampler(sampler_argument):
        try:
            rate = float(sampler_argument)
            return CustomSampler(rate)
        except ValueError: # In case argument is empty string.
            return CustomSampler(0.5)
```

--------------------------------

### Configuration and path helpers

Source: https://opentelemetry-python.readthedocs.io/en/stable/_modules/opentelemetry/exporter/otlp/proto/http/_log_exporter.html

Utility functions to resolve compression settings from environment variables and construct the correct export path.

```python
def _compression_from_env() -> Compression:
    compression = (
        environ.get(
            OTEL_EXPORTER_OTLP_LOGS_COMPRESSION,
            environ.get(OTEL_EXPORTER_OTLP_COMPRESSION, "none"),
        )
        .lower()
        .strip()
    )
    return Compression(compression)


def _append_logs_path(endpoint: str) -> str:
    if endpoint.endswith("/"):
        return endpoint + DEFAULT_LOGS_EXPORT_PATH
    return endpoint + f"/{DEFAULT_LOGS_EXPORT_PATH}"
```

--------------------------------

### Install OpenTelemetry Django Dependencies

Source: https://opentelemetry-python.readthedocs.io/en/stable/_sources/examples/django/README.rst.txt

Commands to install the necessary OpenTelemetry SDK, Django instrumentation package, and requests library within a virtual environment.

```bash
pip install opentelemetry-sdk
pip install opentelemetry-instrumentation-django
pip install requests
```

--------------------------------

### Run the application

Source: https://opentelemetry-python.readthedocs.io/en/stable/examples/opentracing/README.html

Execute the main script to generate Fibonacci numbers and trace spans.

```bash
python main.py
```

--------------------------------

### OTLP Metric Data Structure Example

Source: https://opentelemetry-python.readthedocs.io/en/stable/_modules/opentelemetry/exporter/otlp/proto/http/metric_exporter.html

Example of the dictionary structure used to represent resource metrics, scope metrics, and individual metric data points.

```python
[
    {
        "resource": <opentelemetry.proto.resource.v1.resource_pb2.Resource>,
        "schema_url": "http://foo-bar",
        "scope_metrics": [
            "scope": <opentelemetry.proto.common.v1.InstrumentationScope>,
            "schema_url": "http://foo-baz",
            "metrics": [
                {
                    "name": "apples",
                    "description": "number of apples purchased",
                    "sum": {
                        "aggregation_temporality": 1,
                        "is_monotonic": "false",
                        "data_points": [
                            {
                                start_time_unix_nano: 1000
                                time_unix_nano: 1001
                                exemplars {
                                    time_unix_nano: 1002
                                    span_id: "foo-span"
                                    trace_id: "foo-trace"
                                    as_int: 5
                                }
                                as_int: 5
                            }
                        ]
                    }
                },
            ],
        ],
    },
]
```

--------------------------------

### Configuration and path helpers

Source: https://opentelemetry-python.readthedocs.io/en/stable/_modules/opentelemetry/exporter/otlp/proto/http/trace_exporter.html

Utility functions to determine compression settings and construct the trace export endpoint path.

```python
def _compression_from_env() -> Compression:
    compression = (
        environ.get(
            OTEL_EXPORTER_OTLP_TRACES_COMPRESSION,
            environ.get(OTEL_EXPORTER_OTLP_COMPRESSION, "none"),
        )
        .lower()
        .strip()
    )
    return Compression(compression)


def _append_trace_path(endpoint: str) -> str:
    if endpoint.endswith("/"):
        return endpoint + DEFAULT_TRACES_EXPORT_PATH
    return endpoint + f"/{DEFAULT_TRACES_EXPORT_PATH}"
```

--------------------------------

### Example OpenTelemetry Span with sqlcomment Attribute

Source: https://opentelemetry-python.readthedocs.io/en/stable/_sources/examples/sqlcommenter/README.rst.txt

An example of an OpenTelemetry span generated for an instrumented SQL query. The 'db.statement' attribute contains the sqlcomment, demonstrating the comment-in-attribute feature.

```text
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)
```

--------------------------------

### Configure TracerProvider via Environment Variables

Source: https://opentelemetry-python.readthedocs.io/en/stable/_modules/opentelemetry/sdk/trace/sampling.html

Shows how to initialize a TracerProvider that uses sampling configurations defined by environment variables like OTEL_TRACES_SAMPLER.

```python
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import (
    ConsoleSpanExporter,
    SimpleSpanProcessor,
)

trace.set_tracer_provider(TracerProvider())

# set up an exporter for sampled spans
trace.get_tracer_provider().add_span_processor(
    SimpleSpanProcessor(ConsoleSpanExporter())
)

# created spans will now be sampled by the TraceIdRatioBased sampler with rate 1/1000.
with trace.get_tracer(__name__).start_as_current_span("Test Span"):
    ...
```

--------------------------------

### Example MySQL Query with sqlcomment

Source: https://opentelemetry-python.readthedocs.io/en/stable/_sources/examples/sqlcommenter/README.rst.txt

An example of a SQL query logged in the MySQL general log after being instrumented by sqlcommenter. It includes contextual information like the database driver, API level, and traceparent.

```sql
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'*/
```

--------------------------------

### TracerShim.start_span

Source: https://opentelemetry-python.readthedocs.io/en/stable/_modules/opentelemetry/shim/opentracing_shim.html

Starts a new span without activating it.

```APIDOC
## TracerShim.start_span(operation_name=None, child_of=None, references=None, tags=None, start_time=None, ignore_active_span=False)

### Description
Starts a span, behaving like the OpenTracing start_span method.

### Parameters
- **operation_name** (str) - Optional - Name of the operation.
- **child_of** (SpanShim | SpanContextShim) - Optional - Parent span or context.
- **references** (list) - Optional - List of references.
- **tags** (Attributes) - Optional - Dictionary of tags.
- **start_time** (float) - Optional - Explicit start time.
- **ignore_active_span** (bool) - Optional - Whether to ignore the current active span.

### Returns
- **SpanShim** - The created span.
```

--------------------------------

### Run Client

Source: https://opentelemetry-python.readthedocs.io/en/stable/examples/django/README.html

Execute the client script with a parameter.

```bash
python client.py hello
```

--------------------------------

### opentelemetry.trace.get_tracer_provider

Source: https://opentelemetry-python.readthedocs.io/en/stable/api/trace.html

Gets the current global TracerProvider object.

```APIDOC
## opentelemetry.trace.get_tracer_provider()

### Description
Retrieves the currently configured global TracerProvider.

### Returns
- **TracerProvider** - The global tracer provider.
```

--------------------------------

### opentelemetry._logs.get_logger_provider

Source: https://opentelemetry-python.readthedocs.io/en/stable/api/_logs.html

Gets the current global LoggerProvider object.

```APIDOC
## opentelemetry._logs.get_logger_provider()

### Description
Gets the current global LoggerProvider object.

### Returns
- **LoggerProvider**
```

--------------------------------

### Registering a Resource with a TracerProvider

Source: https://opentelemetry-python.readthedocs.io/en/stable/_modules/opentelemetry/sdk/resources.html

Demonstrates how to initialize a TracerProvider with a custom Resource containing service attributes.

```python
trace.set_tracer_provider(
    TracerProvider(
        resource=Resource.create({
            "service.name": "shoppingcart",
            "service.instance.id": "instance-12",
        }),
    ),
)
print(trace.get_tracer_provider().resource.attributes)

{'telemetry.sdk.language': 'python',
'telemetry.sdk.name': 'opentelemetry',
'telemetry.sdk.version': '0.13.dev0',
'service.name': 'shoppingcart',
'service.instance.id': 'instance-12'}
```
Tokens:
Raw