{
    "info": {
        "author": "OpenCensus Authors",
        "author_email": "census-developers@googlegroups.com",
        "bugtrack_url": null,
        "classifiers": [
            "Development Status :: 3 - Alpha",
            "Intended Audience :: Developers",
            "License :: OSI Approved :: Apache Software License",
            "Programming Language :: Python",
            "Programming Language :: Python :: 2",
            "Programming Language :: Python :: 2.7",
            "Programming Language :: Python :: 3",
            "Programming Language :: Python :: 3.4",
            "Programming Language :: Python :: 3.5",
            "Programming Language :: Python :: 3.6"
        ],
        "description": "OpenCensus for Python - A stats collection and distributed tracing framework\n============================================================================\n\n    `Census`_ for Python. Census provides a framework to measure a server's resource\n    usage and collect performance stats. This repository contains Python related\n    utilities and supporting software needed by Census.\n\n    .. _Census: https://github.com/census-instrumentation\n\n|circleci|\n\n.. |circleci| image:: https://circleci.com/gh/census-instrumentation/opencensus-python.svg?style=shield\n   :target: https://circleci.com/gh/census-instrumentation/opencensus-python\n\n-  `API Documentation`_\n\n.. _API Documentation: https://opencensus.io/api/python/trace/usage.html\n\n--------\n Tracing\n--------\n\nInstallation & basic usage\n--------------------------\n\n1. Install the opencensus package using `pip`_ or `pipenv`_:\n\n    ::\n\n        pip install opencensus\n        pipenv install opencensus\n\n2. Initialize a tracer for your application:\n\n    .. code:: python\n\n        from opencensus.trace import tracer as tracer_module\n\n        tracer = tracer_module.Tracer()\n\n    .. _pip: https://pip.pypa.io\n    .. _pipenv: https://docs.pipenv.org/\n\n3. Initialize a view_manager and a stats_recorder for your application:\n\n    .. code:: python\n\n        from opencensus.stats import stats as stats_module\n\n        stats = stats_module.Stats()\n        view_manager = stats.view_manager\n        stats_recorder = stats.stats_recorder\n\n\nUsage\n-----\n\nYou can collect traces using the ``Tracer`` `context manager`_:\n\n.. code:: python\n\n    from opencensus.trace import tracer as tracer_module\n\n    # Initialize a tracer, by default using the `PrintExporter`\n    tracer = tracer_module.Tracer()\n\n    # Example for creating nested spans\n    with tracer.span(name='span1') as span1:\n        do_something_to_trace()\n        with span1.span(name='span1_child1') as span1_child1:\n            do_something_to_trace()\n        with span1.span(name='span1_child2') as span1_child2:\n            do_something_to_trace()\n    with tracer.span(name='span2') as span2:\n        do_something_to_trace()\n\nCensus will collect everything within the ``with`` statement as a single span.\n\nAlternatively, you can explicitly start and end a span:\n\n.. code:: python\n\n    from opencensus.trace import tracer as tracer_module\n\n    # Initialize a tracer, by default using the `PrintExporter`\n    tracer = tracer_module.Tracer()\n\n    tracer.start_span(name='span1')\n    do_something_to_trace()\n    tracer.end_span()\n\n\n.. _context manager: https://docs.python.org/3/reference/datamodel.html#context-managers\n\n\nCustomization\n-------------\n\nSamplers\n~~~~~~~~\n\nYou can specify different samplers when initializing a tracer, default\nis using ``AlwaysOnSampler``, the other options are ``AlwaysOffSampler``\nand ``ProbabilitySampler``\n\n.. code:: python\n\n    from opencensus.trace.samplers import probability\n    from opencensus.trace import tracer as tracer_module\n\n    # Sampling the requests at the rate equals 0.5\n    sampler = probability.ProbabilitySampler(rate=0.5)\n    tracer = tracer_module.Tracer(sampler=sampler)\n\nExporters\n~~~~~~~~~\n\nYou can choose different exporters to send the traces to. By default,\nthe traces are printed to stdout in JSON format. Other options include\nwriting to a file, sending to Python logging, or reporting to\nStackdriver.\n\nThis example shows how to configure Census to save the traces to a\nfile:\n\n.. code:: python\n\n    from opencensus.trace.exporters import file_exporter\n    from opencensus.trace.tracers import context_tracer\n\n    exporter = file_exporter.FileExporter(file_name='traces')\n    tracer = context_tracer.ContextTracer(exporter=exporter)\n\nThis example shows how to report the traces to Stackdriver Trace:\n\n.. code:: python\n\n    from opencensus.trace.exporters import stackdriver_exporter\n    from opencensus.trace import tracer as tracer_module\n\n    exporter = stackdriver_exporter.StackdriverExporter(\n        project_id='your_cloud_project')\n    tracer = tracer_module.Tracer(exporter=exporter)\n\nStackdriverExporter requires the google-cloud-trace package. Install\ngoogle-cloud-trace using `pip`_ or `pipenv`_:\n\n::\n\n    pip install google-cloud-trace\n    pipenv install google-cloud-trace\n\nBy default, traces are exported synchronously, which introduces latency during\nyour code's execution. To avoid blocking code execution, you can initialize\nyour exporter to use a background thread.\n\nThis example shows how to configure Census to use a background thread:\n\n.. code:: python\n\n    from opencensus.trace.exporters import stackdriver_exporter\n    from opencensus.trace import tracer as tracer_module\n    from opencensus.trace.exporters.transports.background_thread \\\n        import BackgroundThreadTransport\n\n    exporter = stackdriver_exporter.StackdriverExporter(\n        project_id='your_cloud_project', transport=BackgroundThreadTransport)\n    tracer = tracer_module.Tracer(exporter=exporter)\n\nPropagators\n~~~~~~~~~~~\n\nYou can specify the propagator type for serializing and deserializing the\n``SpanContext`` and its headers. There are currently three built in propagators:\n``GoogleCloudFormatPropagator``, ``TextFormatPropagator`` and ``TraceContextPropagator``.\n\nThis example shows how to use the ``GoogleCloudFormatPropagator``:\n\n.. code:: python\n\n    from opencensus.trace.propagation import google_cloud_format\n\n    propagator = google_cloud_format.GoogleCloudFormatPropagator()\n\n    # Deserialize\n    span_context = propagator.from_header(header)\n\n    # Serialize\n    header = propagator.to_header(span_context)\n\nThis example shows how to use the ``TraceContextPropagator``:\n\n.. code:: python\n\n    import requests\n\n    from opencensus.trace import config_integration\n    from opencensus.trace.propagation.trace_context_http_header_format import TraceContextPropagator\n    from opencensus.trace.tracer import Tracer\n\n    config_integration.trace_integrations(['httplib'])\n    tracer = Tracer(propagator = TraceContextPropagator())\n\n    with tracer.span(name = 'parent'):\n        with tracer.span(name = 'child'):\n            response = requests.get('http://localhost:5000')\n\nBlacklist Paths\n~~~~~~~~~~~~~~~\n\nYou can specify which paths you do not want to trace by configuring the\nblacklist paths.\n\nThis example shows how to configure the blacklist to ignore the `_ah/health` endpoint\nfor a Flask application:\n\n.. code:: python\n\n    from opencensus.trace.ext.flask.flask_middleware import FlaskMiddleware\n\n    app = flask.Flask(__name__)\n\n    blacklist_paths = ['_ah/health']\n    middleware = FlaskMiddleware(app, blacklist_paths=blacklist_paths)\n\nFor Django, you can configure the blacklist in the ``OPENCENSUS_PARAMS`` in ``settings.py``:\n\n.. code:: python\n\n    OPENCENSUS_PARAMS: {\n        ...\n        'BLACKLIST_PATHS': ['_ah/health',],\n    }\n\n\n.. note:: By default, the health check path for the App Engine flexible environment is not traced,\n    but you can turn it on by excluding it from the blacklist setting.\n\nFramework Integration\n---------------------\n\nCensus supports integration with popular web frameworks including\nDjango, Flask, Pyramid, and Webapp2. When the application receives a HTTP request,\nthe tracer will automatically generate a span context using the trace\ninformation extracted from the request headers and propagated to the\nchild spans.\n\nFlask\n~~~~~\n\nIn your application, use the middleware to wrap your app and the\nrequests will be automatically traced.\n\n.. code:: python\n\n    from opencensus.trace.ext.flask.flask_middleware import FlaskMiddleware\n\n    app = flask.Flask(__name__)\n\n    # You can also specify the sampler, exporter, propagator in the middleware,\n    # default is using `AlwaysOnSampler` as sampler, `PrintExporter` as exporter,\n    # `GoogleCloudFormatPropagator` as propagator.\n    middleware = FlaskMiddleware(app)\n\nDjango\n~~~~~~\n\nFor tracing Django requests, you will need to add the following line to\nthe ``MIDDLEWARE_CLASSES`` section in the Django ``settings.py`` file.\n\n.. code:: python\n\n    MIDDLEWARE_CLASSES = [\n        ...\n        'opencensus.trace.ext.django.middleware.OpencensusMiddleware',\n    ]\n\nAnd add this line to the ``INSTALLED_APPS`` section:\n\n.. code:: python\n\n    INSTALLED_APPS = [\n        ...\n        'opencensus.trace.ext.django',\n    ]\n\nYou can configure the sampler, exporter, propagator using the ``OPENCENSUS_TRACE`` setting in\n``settings.py``:\n\n.. code:: python\n\n    OPENCENSUS_TRACE = {\n        'SAMPLER': 'opencensus.trace.samplers.probability.ProbabilitySampler',\n        'EXPORTER': 'opencensus.trace.exporters.print_exporter.PrintExporter',\n        'PROPAGATOR': 'opencensus.trace.propagation.google_cloud_format.'\n                      'GoogleCloudFormatPropagator',\n    }\n\nYou can configure the sampling rate and other parameters using the ``OPENCENSUS_TRACE_PARAMS``\nsetting in ``settings.py``:\n\n.. code:: python\n\n    OPENCENSUS_TRACE_PARAMS = {\n        'BLACKLIST_PATHS': ['/_ah/health'],\n        'GCP_EXPORTER_PROJECT': None,\n        'SAMPLING_RATE': 0.5,\n        'SERVICE_NAME': 'my_service',\n        'ZIPKIN_EXPORTER_HOST_NAME': 'localhost',\n        'ZIPKIN_EXPORTER_PORT': 9411,\n        'ZIPKIN_EXPORTER_PROTOCOL': 'http',\n    }\n\n\nPyramid\n~~~~~~~\n\nIn your application, add the pyramid tween and your requests will be\ntraced.\n\n.. code:: python\n\n    def main(global_config, **settings):\n        config = Configurator(settings=settings)\n\n        config.add_tween('opencensus.trace.ext.pyramid'\n                         '.pyramid_middleware.OpenCensusTweenFactory')\n\nTo configure the sampler, exporter, and propagator, pass the instances\ninto the pyramid settings\n\n.. code:: python\n\n    from opencensus.trace.exporters import print_exporter\n    from opencensus.trace.propagation import google_cloud_format\n    from opencensus.trace.samplers import probability\n\n    settings = {}\n    settings['OPENCENSUS_TRACE'] = {\n        'EXPORTER': print_exporter.PrintExporter(),\n        'SAMPLER': probability.ProbabilitySampler(rate=0.5),\n        'PROPAGATOR': google_cloud_format.GoogleCloudFormatPropagator(),\n    }\n\n    config = Configurator(settings=settings)\n\ngRPC Integration\n----------------\n\nOpenCensus provides the implementation of interceptors for both the client side\nand server side to instrument the gRPC requests and responses. The client\ninterceptors are used to create a decorated channel that intercepts client\ngRPC calls and server interceptors act as decorators over handlers.\n\ngRPC interceptor is a new feature in the grpcio1.8.0 release, please upgrade\nyour grpcio to the latest version to use this feature.\n\nFor sample usage, please refer to the hello world example in the examples\ndirectory.\n\nMore information about the gRPC interceptors please see the `proposal`_.\n\n.. _proposal: https://github.com/mehrdada/proposal/blob/python-interceptors/L13-Python-Interceptors.md\n\nService Integration\n-------------------\n\nOpencensus supports integration with various popular outbound services such as\nSQL packages, Requests and Google Cloud client libraries. To enable integration\nservices to census:\tyou will need to pass the list of services to census:\n\n.. code:: python\n\n    from opencensus.trace import config_integration\n    from opencensus.trace import tracer as tracer_module\n\n    import mysql.connector\n\n    # Trace both mysql-connection and psycopg2\n    integration = ['mysql', 'postgresql']\n\n    config_integration.trace_integrations(integration)\n\n\nMySQL\n~~~~~\n\nThe integration with MySQL supports the `mysql-connector`_ library and is specified\nto ``trace_integrations`` using ``'mysql'``.\n\n.. _mysql-connector: https://pypi.org/project/mysql-connector\n\nPostgreSQL\n~~~~~~~~~~\n\nThe integration with PostgreSQL supports the `psycopg2`_ library and is specified\nto ``trace_integrations`` using ``'postgresql'``.\n\n.. _psycopg2: https://pypi.org/project/psycopg2\n\n\nSQLAlchemy\n~~~~~~~~~~\n\nYou can trace usage of the `sqlalchemy package`_, regardless of the underlying\ndatabase, by specifying ``'sqlalchemy'`` to ``trace_integrations``.\n\n.. _SQLAlchemy package: https://pypi.org/project/SQLAlchemy\n\n.. note:: If you enable tracing of SQLAlchemy as well as the underlying database\n    driver, you will get duplicate spans. Instead, just trace SQLAlchemy.\n\nRequests\n~~~~~~~~\n\nCensus can trace HTTP requests made with the `Requests package`_. The request URL,\nmethod, and status will be collected.\n\nYou can enable Requests integration by specifying ``'requests'`` to ``trace_integrations``.\n\n.. _Requests package: https://pypi.python.org/pypi/requests\n\nGoogle Cloud Client Libraries\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nCensus can trace HTTP and gRPC requests made with the `Cloud client libraries`_.\nThe request URL, method, and status will be collected.\n\nYou can enable Google Cloud client libraries integration by specifying ``'google_cloud_clientlibs'`` to ``trace_integrations``.\n\n.. _Cloud client libraries: https://github.com/GoogleCloudPlatform/google-cloud-python#google-cloud-python-client\n\nThreading\n~~~~~~~~~\n\nCensus can propagate trace across threads when using the Threading package.\n\nYou can enable Threading integration by specifying ``'threading'`` to ``trace_integrations``.\n\n------\n Stats\n------\n\nStackdriver Stats\n-----------------\n\nThe OpenCensus Stackdriver Stats Exporter allows users\nto export metrics to Stackdriver Monitoring.\nThe API of this project is still evolving.\nThe use of vendoring or a dependency management tool is recommended.\n\n.. _Stackdriver: https://app.google.stackdriver.com/metrics-explorer\n\nStackdriver Exporter Usage\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nStackdriver Import\n************************\n\n    .. code:: python\n\n        from opencensus.stats.exporters import stackdriver_exporter as stackdriver\n        from opencensus.stats import stats as stats_module\n\nStackdriver Prerequisites\n**************************\n\n- OpenCensus Python libraries require Python 2.7 or later.\n- Google Cloud Platform account and project.\n- Google Stackdriver Monitoring enabled on your project (Need help? `Click here`_).\n\n.. _Click here: https://opencensus.io/codelabs/stackdriver\n\nRegister the Stackdriver exporter\n**********************************\n\n    .. code:: python\n\n        stats = stats_module.Stats()\n        view_manager = stats.view_manager\n\n        exporter = stackdriver.new_stats_exporter(stackdriver.Options(project_id=\"<id_value>\"))\n        view_manager.register_exporter(exporter)\n        ...\n\n\nStackdriver Code Reference\n******************************\n\nIn the *examples* folder, you can find all the necessary steps to get the exporter, register a view, put tags on the measure, and see the values against the Stackdriver monitoring tool once you have defined the *project_id*.\n\nFor further details for the Stackdriver implementation, see the file *stackdriver_exporter.py*.\n\n+----------------------------------------------------+-------------------------------------+\n| Path & File                                        | Short Description                   |\n+====================================================+=====================================+\n| examples/stats/exporter/stackdriver.py             | End to end example                  |\n+----------------------------------------------------+-------------------------------------+\n| opencensus/stats/exporters/stackdriver_exporter.py | Stats implementation for Stackdriver|\n+----------------------------------------------------+-------------------------------------+\n\nPrometheus Stats\n-----------------\n\nThe OpenCensus `Prometheus`_ Stats Exporter allows users\nto export metrics to Prometheus monitoring solution.\nThe API of this project is still evolving.\nThe use of vendoring or a dependency management tool is recommended.\n\n.. _Prometheus: https://prometheus.io/\n\nPrometheus Exporter Usage\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nPrometheus Import\n********************\n\n    .. code:: python\n\n        from opencensus.stats.exporters import prometheus_exporter as prometheus\n        from opencensus.stats import stats as stats_module\n\nPrometheus Prerequisites\n***************************\n\n- OpenCensus Python libraries require Python 2.7 or later.\n- Prometheus up and running.\n\nRegister the Prometheus exporter\n***********************************\n\n    .. code:: python\n\n        stats = stats_module.Stats()\n        view_manager = stats.view_manager\n\n        exporter = prometheus.new_stats_exporter(prometheus.Options(namespace=\"<namespace>\"))\n        view_manager.register_exporter(exporter)\n        ...\n\n\nPrometheus Code Reference\n***************************\n\nIn the *examples* folder, you can find all the necessary steps to get the exporter, register a view, put tags on the measure, and see the values against the Prometheus monitoring tool.\n\nFor further details for the Prometheus implementation, see the file *prometheus_exporter.py*.\n\n\n+----------------------------------------------------+-------------------------------------+\n| Path & File                                        | Short Description                   |\n+====================================================+=====================================+\n| examples/stats/exporter/prometheus.py              | End to end example                  |\n+----------------------------------------------------+-------------------------------------+\n| opencensus/stats/exporters/prometheus_exporter.py  | Stats implementation for Prometheus |\n+----------------------------------------------------+-------------------------------------+\n\n------------------\n Additional Info\n------------------\n\nContributing\n------------\n\nContributions to this library are always welcome and highly encouraged.\n\nSee `CONTRIBUTING <CONTRIBUTING.md>`__ for more information on how to\nget started.\n\n\nDevelopment\n-----------\n\nTests\n~~~~~\n\n::\n\n    cd trace\n    tox -e py34\n    source .tox/py34/bin/activate\n\n    # Install nox with pip\n    pip install nox-automation\n\n    # See what's available in the nox suite\n    nox -l\n\n    # Run a single nox command\n    nox -s \"unit(py='2.7')\"\n\n    # Run all the nox commands\n    nox\n\n    # Integration test\n    # We don't have script for integration test yet, but can test as below.\n    python setup.py bdist_wheel\n    cd dist\n    pip install opencensus-0.0.1-py2.py3-none-any.whl\n\n    # Then just run the tracers normally as you want to test.\n\nLicense\n-------\n\nApache 2.0 - See `LICENSE <LICENSE>`__ for more information.\n\nDisclaimer\n----------\n\nThis is not an official Google product.\n\n\n",
        "description_content_type": "",
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/census-instrumentation/opencensus-python",
        "keywords": "",
        "license": "Apache-2.0",
        "maintainer": "",
        "maintainer_email": "",
        "name": "criteo-fork-opencensus",
        "package_url": "https://pypi.org/project/criteo-fork-opencensus/",
        "platform": "",
        "project_url": "https://pypi.org/project/criteo-fork-opencensus/",
        "project_urls": {
            "Homepage": "https://github.com/census-instrumentation/opencensus-python"
        },
        "release_url": "https://pypi.org/project/criteo-fork-opencensus/1.0.9/",
        "requires_dist": [
            "google-api-core (<2.0.0,>=0.1.1)",
            "prometheus-client (==0.3.1); extra == 'prometheus_client'",
            "google-cloud-trace (<0.20,>=0.17.0); extra == 'stackdriver'"
        ],
        "requires_python": "",
        "summary": "A stats collection and distributed tracing framework",
        "version": "1.0.9"
    },
    "last_serial": 4431099,
    "releases": {
        "1.0.9": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "1c555f76b2577c119f643cc6258c9d8d",
                    "sha256": "2a6f18ea970879bada2cd7a98b2fcc01c4d07ad2ab7ca73c12db81cbfa331266"
                },
                "downloads": -1,
                "filename": "criteo_fork_opencensus-1.0.9-py2.py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "1c555f76b2577c119f643cc6258c9d8d",
                "packagetype": "bdist_wheel",
                "python_version": "py2.py3",
                "requires_python": null,
                "size": 194286,
                "upload_time": "2018-10-30T10:57:38",
                "url": "https://files.pythonhosted.org/packages/27/21/52d6be2fdf9c26270b64109e08b56ac256dcc09341aefa0e5149ea20ce6c/criteo_fork_opencensus-1.0.9-py2.py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "9543480ee2918aba4bf2cac9f6dd41e3",
                    "sha256": "2b46aca95eb1a9b700775004b26d63c0f4846c089e696f296abfcf9e8b46cd52"
                },
                "downloads": -1,
                "filename": "criteo-fork-opencensus-1.0.9.tar.gz",
                "has_sig": false,
                "md5_digest": "9543480ee2918aba4bf2cac9f6dd41e3",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 103558,
                "upload_time": "2018-10-30T10:57:39",
                "url": "https://files.pythonhosted.org/packages/fe/05/a5e5046b08ad13d2ddf37736a04e7f9d7830a98ddc6799dca363f416abb7/criteo-fork-opencensus-1.0.9.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "1c555f76b2577c119f643cc6258c9d8d",
                "sha256": "2a6f18ea970879bada2cd7a98b2fcc01c4d07ad2ab7ca73c12db81cbfa331266"
            },
            "downloads": -1,
            "filename": "criteo_fork_opencensus-1.0.9-py2.py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "1c555f76b2577c119f643cc6258c9d8d",
            "packagetype": "bdist_wheel",
            "python_version": "py2.py3",
            "requires_python": null,
            "size": 194286,
            "upload_time": "2018-10-30T10:57:38",
            "url": "https://files.pythonhosted.org/packages/27/21/52d6be2fdf9c26270b64109e08b56ac256dcc09341aefa0e5149ea20ce6c/criteo_fork_opencensus-1.0.9-py2.py3-none-any.whl"
        },
        {
            "comment_text": "",
            "digests": {
                "md5": "9543480ee2918aba4bf2cac9f6dd41e3",
                "sha256": "2b46aca95eb1a9b700775004b26d63c0f4846c089e696f296abfcf9e8b46cd52"
            },
            "downloads": -1,
            "filename": "criteo-fork-opencensus-1.0.9.tar.gz",
            "has_sig": false,
            "md5_digest": "9543480ee2918aba4bf2cac9f6dd41e3",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 103558,
            "upload_time": "2018-10-30T10:57:39",
            "url": "https://files.pythonhosted.org/packages/fe/05/a5e5046b08ad13d2ddf37736a04e7f9d7830a98ddc6799dca363f416abb7/criteo-fork-opencensus-1.0.9.tar.gz"
        }
    ]
}