Metadata-Version: 2.4
Name: guance-sdk-extension-profiling
Version: 0.63b5
Summary: Guance profiling SDK extension for OpenTelemetry Python
Project-URL: Homepage, https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/sdk-extension/guance-sdk-extension-profiling
Project-URL: Repository, https://github.com/open-telemetry/opentelemetry-python-contrib
Author-email: OpenTelemetry Authors <cncf-opentelemetry-contributors@lists.cncf.io>
License-Expression: Apache-2.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.9
Requires-Dist: opentelemetry-api~=1.12
Requires-Dist: opentelemetry-exporter-otlp==1.40.0
Requires-Dist: opentelemetry-instrumentation==0.61b0
Requires-Dist: opentelemetry-sdk~=1.13
Requires-Dist: requests>=2.20
Description-Content-Type: text/x-rst

Guance SDK Extension for Python Profiling
=========================================

This package provides a Python profiling runtime for OpenTelemetry
auto-instrumentation. The current implementation exports profiles via
OTLP and supports multiple collector types:

* stack sampling
* handled exceptions
* threading and asyncio lock contention
* threading and asyncio condition wait time
* heap snapshots via ``tracemalloc``
* child-process restart after ``fork()``

Installation
------------

::

    pip install guance-sdk-extension-profiling

or install it through the distro extra:

::

    pip install guance-opentelemetry-distro[profiling]

Usage
-----

Enable profiling for applications launched via ``opentelemetry-instrument``:

::

    export OTEL_PROFILING_ENABLED=true
    opentelemetry-instrument python app.py

Programmatic usage:

.. code-block:: python

    from opentelemetry.sdk.extension.profiling import Profiler

    profiler = Profiler()
    profiler.start()

Configuration
-------------

The following environment variables are supported:

* ``OTEL_PROFILING_ENABLED``
* ``OTEL_PROFILING_EXPORTER`` (``otlp`` or ``pprof``)
* ``OTEL_PROFILING_SAMPLE_INTERVAL``
* ``OTEL_PROFILING_EXPORT_INTERVAL``
* ``OTEL_PROFILING_MAX_FRAMES``
* ``OTEL_PROFILING_INCLUDE_TRACE_CONTEXT``
* ``OTEL_PROFILING_EXCEPTION_ENABLED``
* ``OTEL_PROFILING_EXCEPTION_SAMPLING_INTERVAL``
* ``OTEL_PROFILING_EXCEPTION_COLLECT_MESSAGE``
* ``OTEL_PROFILING_LOCK_ENABLED``
* ``OTEL_PROFILING_MEMORY_ENABLED``
* ``OTEL_PROFILING_MEMORY_INTERVAL``
* ``OTEL_PROFILING_MEMORY_TOP_STATS``
* ``OTEL_PROFILING_MEMORY_IGNORE_PROFILER``
* ``OTEL_EXPORTER_OTLP_PROFILES_PROTOCOL``
* ``OTEL_EXPORTER_OTLP_PROFILES_ENDPOINT``
* ``OTEL_EXPORTER_OTLP_PROFILES_HEADERS``
* ``OTEL_EXPORTER_OTLP_PROFILES_TIMEOUT``
* ``OTEL_EXPORTER_OTLP_PROFILES_COMPRESSION``
* ``OTEL_EXPORTER_OTLP_PROFILES_CERTIFICATE``
* ``OTEL_EXPORTER_OTLP_PROFILES_CLIENT_KEY``
* ``OTEL_EXPORTER_OTLP_PROFILES_CLIENT_CERTIFICATE``
* ``OTEL_PROFILING_PPROF_PATH``
* ``OTEL_PROFILING_PPROF_UPLOAD_URL``
* ``OTEL_PROFILING_PPROF_HEADERS``

Service metadata should be configured with standard OpenTelemetry
resource settings such as ``OTEL_SERVICE_NAME`` and
``OTEL_RESOURCE_ATTRIBUTES``.

Examples
--------

Collect stack, exception, lock, and heap profiles and export them with
OTLP/HTTP:

::

    export OTEL_PROFILING_ENABLED=true
    export OTEL_PROFILING_EXCEPTION_ENABLED=true
    export OTEL_PROFILING_LOCK_ENABLED=true
    export OTEL_PROFILING_MEMORY_ENABLED=true
    export OTEL_EXPORTER_OTLP_PROFILES_PROTOCOL=http/protobuf
    export OTEL_EXPORTER_OTLP_PROFILES_ENDPOINT=http://localhost:4318/v1development/profiles
    opentelemetry-instrument python app.py

To dump pprof files instead of OTLP, set:

::

    export OTEL_PROFILING_EXPORTER=pprof
    export OTEL_PROFILING_PPROF_PATH=/tmp/otel-profile

To POST pprof directly to a compatible agent endpoint and keep a local
copy:

::

    export OTEL_PROFILING_PPROF_UPLOAD_URL=http://localhost:9529/profiling/v1/input
    export OTEL_PROFILING_PPROF_HEADERS="X-API-Key:xxx"
    opentelemetry-instrument python app.py

When ``OTEL_PROFILING_EXPORTER`` is unset and
``OTEL_PROFILING_PPROF_UPLOAD_URL`` is configured, the runtime
defaults to a legacy-compatible ``pprof`` upload layout. Set
``OTEL_PROFILING_EXPORTER=otlp`` to force OTLP profile export.
