Metadata-Version: 2.4
Name: guance-opentelemetry-distro
Version: 0.63b7
Summary: Guance OpenTelemetry Python Distro
Project-URL: Homepage, https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/guance-opentelemetry-distro
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
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: guance-sdk-extension-profiling==0.63b5
Requires-Dist: opentelemetry-api~=1.12
Requires-Dist: opentelemetry-contrib-instrumentations==0.61b0
Requires-Dist: opentelemetry-exporter-otlp==1.40.0
Requires-Dist: opentelemetry-instrumentation==0.61b0
Requires-Dist: opentelemetry-sdk~=1.13
Provides-Extra: profiling
Requires-Dist: guance-sdk-extension-profiling==0.63b5; extra == 'profiling'
Description-Content-Type: text/x-rst

Guance OpenTelemetry Distro
===========================

|pypi|

.. |pypi| image:: https://badge.fury.io/py/guance-opentelemetry-distro.svg
   :target: https://pypi.org/project/guance-opentelemetry-distro/

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

::

    pip install guance-opentelemetry-distro

This package provides entrypoints to configure OpenTelemetry.

Command Line
------------

The package also installs a ``gtrace`` command as a shorthand for
auto-instrumented launches:

::

    gtrace uvicorn fastapi-demo:app --host 127.0.0.1 --port 18082

Profiling
---------

The base package installs the ``guance-sdk-extension-profiling``
package, which registers an ``opentelemetry_pre_instrument`` entry
point. Enable it with:

::

    export OTEL_PROFILING_ENABLED=true
    gtrace python app.py

When ``OTEL_PROFILING_PPROF_UPLOAD_URL`` is configured and
``OTEL_PROFILING_EXPORTER`` is unset, profiling defaults to a
legacy-compatible ``pprof`` upload layout. Explicit
``OTEL_PROFILING_*`` settings take precedence.

Common profiling parameters:

* ``OTEL_PROFILING_ENABLED``
* ``OTEL_PROFILING_EXPORTER`` (``otlp`` or ``pprof``)
* ``OTEL_PROFILING_SAMPLE_INTERVAL``
* ``OTEL_PROFILING_EXPORT_INTERVAL``
* ``OTEL_PROFILING_MAX_FRAMES``
* ``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_PPROF_PATH``
* ``OTEL_PROFILING_PPROF_UPLOAD_URL``
* ``OTEL_PROFILING_PPROF_HEADERS``
* ``OTEL_EXPORTER_OTLP_PROFILES_PROTOCOL``
* ``OTEL_EXPORTER_OTLP_PROFILES_ENDPOINT``
* ``OTEL_EXPORTER_OTLP_PROFILES_HEADERS``

Example:

::

    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_PROFILING_PPROF_UPLOAD_URL=http://localhost:9529/profiling/v1/input
    gtrace python app.py

References
----------

* `OpenTelemetry Project <https://opentelemetry.io/>`_
* `Example using guance-opentelemetry-distro <https://opentelemetry.io/docs/instrumentation/python/distro/>`_
